# 功能开关

"功能开关"是变量，允许您阻止 Gutenberg 项目中的特定代码发布到 WordPress 核心，并仅在插件中运行某些实验性功能。

## 介绍 `globalThis.IS_GUTENBERG_PLUGIN`

`globalThis.IS_GUTENBERG_PLUGIN` 是一个环境变量，其值用于“标记”代码是否在 Gutenberg 插件内运行。

当代码库为插件构建时，此变量将被设置为 `true`。当为 WordPress 核心构建时，它将被设置为 `false` 或 `undefined`。

## Basic usage

### Exporting features

A plugin-only function or constant should be exported using the following ternary syntax:

```js
function myPluginOnlyFeature() {
	// implementation
}

export const pluginOnlyFeature = globalThis.IS_GUTENBERG_PLUGIN
	? myPluginOnlyFeature
	: undefined;
```

In the above example, the `pluginOnlyFeature` export will be `undefined` in non-plugin environments such as WordPress core.

### 导入功能特性

若需导入并调用仅限插件使用的功能特性，请务必将函数调用包裹在 `if` 语句中以避免错误：

```js
import { pluginOnlyFeature } from '@wordpress/foo';

if ( globalThis.IS_GUTENBERG_PLUGIN ) {
	pluginOnlyFeature();
}
```

## How it works

During the webpack build, instances of `globalThis.IS_GUTENBERG_PLUGIN` will be replaced using webpack's [define plugin](https://webpack.js.org/plugins/define-plugin/).

For example, in the following code –

```js
if ( globalThis.IS_GUTENBERG_PLUGIN ) {
	pluginOnlyFeature();
}
```

– the variable `globalThis.IS_GUTENBERG_PLUGIN` will be replaced with the boolean `true` during the plugin-only build:

```js
if ( true ) {
	// Webpack has replaced `globalThis.IS_GUTENBERG_PLUGIN` with `true`
	pluginOnlyFeature();
}
```

This ensures that code within the body of the `if` statement will always be executed.

In WordPress core, the `globalThis.IS_GUTENBERG_PLUGIN` variable is replaced with `undefined`. The built code looks like this:

```js
if ( undefined ) {
	// Webpack has replaced `globalThis.IS_GUTENBERG_PLUGIN` with `undefined`
	pluginOnlyFeature();
}
```

`undefined` evaluates to `false` so the plugin-only feature will not be executed.

### 死代码消除

对于生产环境构建，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 的压缩工具识别并因此消除死代码。因此，建议使用本文档中的示例，以确保您的功能标志按预期工作。更多详细信息，请参阅[死代码消除](#dead-code-elimination)部分。