@wordpress/private-apis 允许在 @wordpress 包之间共享私有的 __experimental API，而无需
向 WordPress 扩展者公开暴露它们。

入门指南

每个希望私有访问或暴露实验性 API 的 @wordpress 包都必须选择加入 @wordpress/private-apis：

// In packages/block-editor/private-apis.js:
import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/private-apis';
export const { lock, unlock } =
    __dangerousOptInToUnstableAPIsOnlyForCoreModules(
        'I acknowledge private features are not for use in themes or plugins and doing so will break in the next version of WordPress.',
        '@wordpress/block-editor' // Name of the package calling __dangerousOptInToUnstableAPIsOnlyForCoreModules,
        // (not the name of the package whose APIs you want to access)
    );

每个包只能选择加入一次。该函数名意在表明插件不应使用它。

如果未满足以下条件，该函数将抛出错误：

  1. 第一个参数必须与所需的同意字符串完全匹配：'I acknowledge private features are not for use in themes or plugins and doing so will break in the next version of WordPress.'。
  2. 第二个参数必须是尚未选择加入 @wordpress/private-apis 的已知 @wordpress 包。

一旦完成选择加入，获得的 lock() 和 unlock() 工具即可隐藏 __experimental API，使其对普通用户不可见：

// Say this object is exported from a package:
export const publicObject = {};

// However, this string is internal and should not be publicly available:
const __experimentalString = '__experimental information';

// Solution: lock the string "inside" of the object:
lock( publicObject, __experimentalString );

// The string is not nested in the object and cannot be extracted from it:
console.log( publicObject );
// {}

// The only way to access the string is by "unlocking" the object:
console.log( unlock( publicObject ) );
// "__experimental information"

// lock() accepts all data types, not just strings:
export const anotherObject = {};
lock( anotherObject, function __experimentalFn() {} );
console.log( unlock( anotherObject ) );
// function __experimentalFn() {}

使用 lock() 和 unlock() 在 @wordpress 包之间私有分发 __experimental API：

// In packages/package1/index.js:
import { lock } from './lock-unlock';

export const privateApis = {};
/* Attach private data to the exported object */
lock( privateApis, {
    __experimentalFunction: function () {},
} );

// In packages/package2/index.js:
import { privateApis } from '@wordpress/package1';
import { unlock } from './lock-unlock';

const { __experimentalFunction } = unlock( privateApis );

发布实验性 API

请参阅《编码指南》中的Experimental and Unstable APIs 章节，了解 lock() 和 unlock() 如何帮助您
发布私有的实验性函数、参数、组件、属性、动作和选择器。

技术限制

一个决心不惜一切代价使用私有实验性 API 的开发者必须：

  • 意识到存在私有导入系统
  • 阅读代码中用大写字母明确指出的风险说明
  • 显式键入他或她知道后果
  • 假装注册一个 @wordpress 包（并在加载真实包时立即触发错误）

不推荐主题和插件开发者冒险选择使用这些 API。此外，WordPress Core 致力于为第三方开发人员保持向后兼容性的哲学不适用于通过此包注册的实验性 API。

选择使用这些 API 的同意字符串可能会随时更改且无需另行通知。这种更改会破坏现有的第三方代码。此类更改可能发生在主要版本或次要版本中。

为此包做出贡献

这是 Gutenberg 项目的一部分个人包。该项目组织为一个单体仓库（monorepo）。它由多个自包含的软件包组成，每个包都有特定的用途。此单体仓库中的包发布到 npm，并被 WordPress 以及其他软件项目使用。

要了解有关为此包或整个 Gutenberg 做出贡献的更多信息，请阅读项目的主要贡献者指南。

Code is Poetry.

更新同意字符串

用于解锁私有 API 的同意字符串旨在定期更改。要更新同意字符串：

  1. 想出一个新的同意字符串，该字符串应提及选择加入不稳定和私有特性的主题或插件将在未来版本的 WordPress 中失效。
  2. 确保该同意字符串此前未被使用过。
  3. 将新字符串追加到下方的历史列表中。
  4. 在以下位置替换同意字符串：
    • 上面的文档中出现两次的位置
    • 本包的 src/implementation.js 文件
    • 位于消耗私有 API 的包中的 src/lock-unlock.js 文件
    • 在整个代码库中搜索任何其他出现的地方

注意：同意字符串不用于面向用户的内容，因此不应通过 WordPress 的国际化工具使其可翻译。

更新同意字符串被视为一项任务，可以在 WordPress 发布的后期阶段进行。

同意字符串历史

列表中的最后一个字符串是当前版本。

  1. I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.
  2. I know using unstable features means my theme or plugin will inevitably break in the next version of WordPress.
  3. I acknowledge private features are not for use in themes or plugins and doing so will break in the next version of WordPress.