107 lines
3.4 KiB
Markdown
107 lines
3.4 KiB
Markdown
|
# 功能标志
|
|||
|
|
|
|||
|
|
「功能标志」是允许您阻止 Gutenberg 项目中的特定代码被发布到 WordPress 核心，并仅在插件中运行某些实验性功能的变量。
|
|||
|
|
|
|||
|
|
## 介绍 `globalThis.IS_GUTENBERG_PLUGIN`
|
|||
|
|
|
|||
|
|
`globalThis.IS_GUTENBERG_PLUGIN` 是一个环境变量，其值用于「标志」代码是否在 Gutenberg 插件内运行。
|
|||
|
|
|
|||
|
|
当代码库为插件构建时，此变量将被设为 `true`。当为 WordPress 核心构建时，它将被设为 `false` 或 `undefined`。
|
|||
|
|
|
|||
|
|
## 基本用法
|
|||
|
|
|
|||
|
|
### 导出功能
|
|||
|
|
|
|||
|
|
仅限插件使用的函数或常量应使用以下三元语法导出：
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
function myPluginOnlyFeature() {
|
|||
|
|
// 具体实现
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export const pluginOnlyFeature = globalThis.IS_GUTENBERG_PLUGIN
|
|||
|
|
? myPluginOnlyFeature
|
|||
|
|
: undefined;
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
在上面的示例中，`pluginOnlyFeature` 导出在非插件环境（例如 WordPress 核心）中将是 `undefined`。
|
|||
|
|
|
|||
|
|
### 导入功能
|
|||
|
|
|
|||
|
|
如果您尝试导入并调用仅限插件使用的功能，请务必将函数调用包装在 `if` 语句中以避免错误：
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
import { pluginOnlyFeature } from '@wordpress/foo';
|
|||
|
|
|
|||
|
|
if ( globalThis.IS_GUTENBERG_PLUGIN ) {
|
|||
|
|
pluginOnlyFeature();
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 工作原理
|
|||
|
|
|
|||
|
|
在 webpack 构建过程中，`globalThis.IS_GUTENBERG_PLUGIN` 的实例将使用 webpack 的 [define 插件](https://webpack.js.org/plugins/define-plugin/)进行替换。
|
|||
|
|
|
|||
|
|
例如，在以下代码中 –
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
if ( globalThis.IS_GUTENBERG_PLUGIN ) {
|
|||
|
|
pluginOnlyFeature();
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
– 变量 `globalThis.IS_GUTENBERG_PLUGIN` 将在仅限插件的构建过程中被替换为布尔值 `true`：
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
if ( true ) {
|
|||
|
|
// Webpack 已将 `globalThis.IS_GUTENBERG_PLUGIN` 替换为 `true`
|
|||
|
|
pluginOnlyFeature();
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
这确保了 `if` 语句体内的代码将始终被执行。
|
|||
|
|
|
|||
|
|
在 WordPress 核心中，`globalThis.IS_GUTENBERG_PLUGIN` 变量被替换为 `undefined`。构建后的代码如下所示：
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
if ( undefined ) {
|
|||
|
|
// Webpack 已将 `globalThis.IS_GUTENBERG_PLUGIN` 替换为 `undefined`
|
|||
|
|
pluginOnlyFeature();
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
`undefined` 会被判定为 `false`，因此仅限插件的功能将不会被执行。
|
|||
|
|
|
|||
|
|
### 死代码消除
|
|||
|
|
|
|||
|
|
对于生产构建，webpack 会对代码进行[「压缩」](https://en.wikipedia.org/wiki/Minification_(programming))，尽可能移除不必要的 JavaScript。
|
|||
|
|
|
|||
|
|
其中一个步骤涉及称为「死代码消除」的过程。例如，当遇到以下代码时，webpack 会判定周围的 `if` 语句是不必要的：
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
if ( true ) {
|
|||
|
|
pluginOnlyFeature();
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
该条件将始终判定为 `true`，因此 webpack 会移除它，仅保留原本在体内的代码：
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
pluginOnlyFeature(); // `if` 条件块已被移除，仅保留体内的代码。
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
类似地，在为 WordPress 核心构建时，以下 `if` 语句中的条件始终解析为 false：
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
if ( undefined ) {
|
|||
|
|
pluginOnlyFeature();
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
在这种情况下，压缩过程将移除整个 `if` 语句（包括其体内的代码），确保仅限插件的代码不会包含在 WordPress 核心构建中。
|
|||
|
|
|
|||
|
|
## 常见问题解答
|
|||
|
|
|
|||
|
|
### 为什么我不应该将涉及 `IS_GUTENBERG_PLUGIN` 的表达式结果赋值给变量，例如 `const isMyFeatureActive = ! Object.is( undefined, globalThis.IS_GUTENBERG_PLUGIN )`？
|
|||
|
|
|
|||
|
|
引入复杂性可能会阻止 webpack 的压缩器识别并因此消除死代码。因此，建议使用本文档中的示例，以确保您的功能标志按预期工作。更多详细信息，请参阅[死代码消除](#死代码消除)部分。
|