# 功能标志

「功能标志」是允许您阻止 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 的压缩器识别并因此消除死代码。因此，建议使用本文档中的示例，以确保您的功能标志按预期工作。更多详细信息，请参阅[死代码消除](#死代码消除)部分。