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

入门

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

// 位于 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' // 调用 __dangerousOptInToUnstableAPIsOnlyForCoreModules 的软件包名称，
        // （不是你想要访问其 API 的软件包名称）
    );

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

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

  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 隐藏在直接可见范围之外：

// 假设这个对象是从某个软件包导出的：
export const publicObject = {};

// 然而，这个字符串是内部内容，不应公开提供：
const __experimentalString = '__experimental information';

// 解决方案：将字符串“锁定”在对象“内部”：
lock( publicObject, __experimentalString );

// 该字符串不会嵌套在对象中，也无法从对象中提取：
console.log( publicObject );
// {}

// 访问该字符串的唯一方式是“解锁”该对象：
console.log( unlock( publicObject ) );
// "__experimental information"

// lock() 接受所有数据类型，而不仅仅是字符串：
export const anotherObject = {};
lock( anotherObject, function __experimentalFn() {} );
console.log( unlock( anotherObject ) );
// function __experimentalFn() {}

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

// 位于 packages/package1/index.js：
import { lock } from './lock-unlock';

export const privateApis = {};
/* 将私有数据附加到导出的对象 */
lock( privateApis, {
    __experimentalFunction: function () {},
} );

// 位于 packages/package2/index.js：
import { privateApis } from '@wordpress/package1';
import { unlock } from './lock-unlock';

const { __experimentalFunction } = unlock( privateApis );

发布实验性 API

参阅 编码指南中的实验性和不稳定 API 章节，了解 lock() 和 unlock() 如何
帮助你发布私有的实验性函数、参数、组件、属性、操作和选择器。

技术限制

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

  • 意识到存在私有导入系统
  • 阅读用大写字母明确列出风险的代码
  • 明确输入自己已知晓后果
  • 假装注册一个 @wordpress 软件包（并在真正的软件包加载时立即触发错误）

不建议主题和插件开发者以危险方式选择加入并使用这些 API。此外，WordPress Core 努力为第三方开发者保持向后兼容的理念不适用于通过此软件包注册的实验性 API。

用于选择加入这些 API 的同意字符串可能随时更改，且不会另行通知。此更改将破坏现有第三方代码。此类更改可能发生在主版本或次版本发布中。

为此软件包做贡献

这是一个独立软件包，属于 Gutenberg 项目。该项目以 monorepo 形式组织，由多个自包含的软件包组成，每个软件包都有特定用途。此 monorepo 中的软件包会发布到 npm，并被 WordPress 以及其他软件项目使用。

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

代码即诗。

更新同意字符串

用于解锁私有 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.