始めに

すべての @wordpress パッケージが実験的な API にプライベートにアクセスまたは公開するには、@wordpress/private-apis にオプトインする必要があります: 

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

各パッケージは一度だけオプトインできます。関数名は、プラグインがこれを使用すべきではないことを伝えています。

次の条件が満たされない場合、関数はエラーをスローします:

  • 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. 2 番目の引数は、@wordpress パッケージであり、まだ @wordpress/private-apis にオプトインしていない必要があります。

オプトインが完了すると、取得した lock() および unlock() ユーティリティにより、experimental API を目に見えないように隠すことができます: 

  1. // Say this object is exported from a package:
  2. export const publicObject = {};
  4. // However, this string is internal and should not be publicly available:
  5. const __experimentalString = '__experimental information';
  7. // Solution: lock the string "inside" of the object:
  8. lock( publicObject, __experimentalString );
  10. // The string is not nested in the object and cannot be extracted from it:
  11. console.log( publicObject );
  12. // {}
  14. // The only way to access the string is by "unlocking" the object:
  15. console.log( unlock( publicObject ) );
  16. // "__experimental information"
  18. // lock() accepts all data types, not just strings:
  19. export const anotherObject = {};
  20. lock( anotherObject, function __experimentalFn() {} );
  21. console.log( unlock( anotherObject ) );
  22. // function __experimentalFn() {}

lock() および unlock() を使用して、@wordpress パッケージ間で experimental API をプライベートに配布します: 

  1. // In packages/package1/index.js:
  2. import { lock } from './lock-unlock';
  4. export const privateApis = {};
  5. /* Attach private data to the exported object */
  6. lock( privateApis, {
  7.    __experimentalFunction: function () {},
  8. } );
  10. // In packages/package2/index.js:
  11. import { privateApis } from '@wordpress/package1';
  12. import { unlock } from './lock-unlock';
  14. const { __experimentalFunction } = unlock( privateApis );

実験的 API の配信

プライベートな実験的機能、引数、コンポーネント、プロパティ、アクション、セレクタを出荷する方法を学ぶには、コーディングガイドラインの実験的および不安定な API の章を参照してください。

技術的制限

プライベートな実験的 API をあらゆるコストで使用したいと考える開発者は、次のことを行う必要があります:

  • プライベートインポートシステムが存在することを認識する
  • リスクが大文字で明記されているコードを読む
  • 結果を認識していることを明示的に記述する
  • @wordpress パッケージを登録するふりをする（実際のパッケージが読み込まれるとすぐにエラーが発生します）

テーマやプラグインの開発者がこれらの API を危険にさらしてオプトインすることは推奨されません。さらに、WordPress コアの哲学は、サードパーティの開発者のために後方互換性を維持することを目指していますが、このパッケージを介して登録された実験的 API には適用されません。

これらの API にオプトインするための同意文字列は、いつでも予告なしに変更される可能性があります。この変更は、既存のサードパーティコードを壊すことになります。このような変更は、メジャーリリースまたはマイナーリリースのいずれかで発生する可能性があります。

このパッケージへの貢献

これは Gutenberg プロジェクトの一部である個別のパッケージです。このプロジェクトはモノレポとして整理されています。特定の目的を持つ複数の自己完結型ソフトウェアパッケージで構成されています。このモノレポ内のパッケージは、npm に公開され、WordPress や他のソフトウェアプロジェクトで使用されています。

このパッケージや Gutenberg 全体への貢献について詳しく知りたい場合は、プロジェクトの主要な 貢献者ガイド をお読みください。

コードは詩です。

同意文字列の更新

プライベート API を解除するための同意文字列は、定期的に変更されることを意図しています。同意文字列を更新するには:

  • 1. 新しい同意文字列を考案します。この文字列は、安定していないプライベート機能にオプトインするテーマやプラグインが、将来の WordPress バージョンで壊れることを示す必要があります。
  • 2. 同意文字列が以前に使用されていないことを確認します。
  • 3. 新しい文字列を以下の履歴リストに追加します。
  • 4. 次の場所で同意文字列を置き換えます:
    • 上記のドキュメントで 2 回
    • このパッケージの src/implementation.js ファイルで
    • プライベート API を消費するパッケージにある src/lock-unlock.js ファイルで
    • コードベース全体で他の出現を検索します

注意: 同意文字列はユーザー向けのコンテンツには使用されず、そのため WordPress の国際化機能を介して 翻訳可能 であってはなりません。

同意文字列の更新はタスクと見なされ、WordPress リリースの後期段階で行うことができます。

同意文字列の履歴

このリストの最後の文字列が現在のバージョンです。

  • 1. 不安定な機能を使用することは、私のプラグインやテーマが次の WordPress リリースで必然的に壊れることを意味することを知っています。
  • 2. 不安定な機能を使用することは、私のテーマやプラグインが次の WordPress バージョンで必然的に壊れることを意味することを知っています。
  • 3. プライベート機能はテーマやプラグインで使用するためのものでないことを認識しており、それを行うと次の WordPress バージョンで壊れることになります。