Web コンポーネント API の非推奨化

Web コンポーネント API を非推奨にすることは、パッケージの次のメジャー リリースで機能が削除されることをユーザーに伝えるための優れた方法です。コンポーネント API を文書化するためにカスタム要素マニフェストを使用している場合、これは思っているよりも難しい場合があります。 Web コンポーネントには通常、フレームワーク コンポーネントよりも多くのパブリック API があります:

• CSS 変数
• CSS パーツ
• スロット
• イベント
• メソッド
• 属性
• プロパティ。

この記事では、重大な変更を導入せずに API の非推奨を文書化し、代替機能を追加する方法を説明します。

ドキュメント

非推奨プロセスで最も注意が必要な部分の 1 つはドキュメントです。プロパティ、メソッド、さらにはコンポーネントの場合、コンポーネントのクラスの JSDoc コメントに @deprecated タグを追加するだけで簡単に行うことができます。

/**
  * @deprecated This component is going away. Use ... instead.
  */
class MyElement extends HTMLElement {
  /** @deprecated This property is being removed. Use ... instead. */
  myProp;

  /** @deprecated This method is going away. Use ... instead. */
  myMethod() {
  }
}

CSS 変数、CSS パーツ、スロット、イベント、属性は通常、クラスの JSDoc に文書化されます。

カスタム要素 JSDoc で文書化できる内容の例を次に示します。

/**
 * @attr {boolean} disabled - disables the element
 * @attribute {string} foo - description for foo
 *
 * @csspart bar - Styles the bar element in the shadow DOM
 *
 * @slot - This is a default/unnamed slot
 * @slot container - You can put some elements here
 *
 * @cssprop --text-color - Controls the color of foo
 * @cssproperty [--background-color=red] - Controls the background color of bar
 *
 * @prop {boolean} prop1 - some description
 * @property {number} prop2 - some description
 *
 * @fires custom-event - some description for custom-event
 * @fires {MyType} typed-event - some description for typed-event
 * @event {MyType} typed-custom-event - some description for typed-custom-event
 *
 * @summary This is MyElement
 *
 * @tag my-element
 * @tagname my-element
 */
class MyElement extends HTMLElement {}

問題

課題は、JSDoc タグを二重に使用したり、@deprecated タグを使用してこれらの項目が非推奨であることを示すことができないことです。それ以外の場合は、クラス全体が非推奨であると解釈されます。

/**
 * @cssprop --text-color - @deprecated I dub thee "deprecated" ❌
 */
class MyElement extends HTMLElement {}

解決策

これを回避するために、JSDoc 内の項目にタグを付けて、カスタム要素マニフェスト内で項目が適切に更新されるようにするツール (custom-elements-manifest-deprecator) を作成しました。

このツールを使用すると、代替タグを使用して非推奨の API を識別できます。デフォルトでは、括弧で囲まれた @deprecated タグが識別子として使用されます (今日はこれを使用します) が、必要に応じてカスタマイズできます。

/**
 * @cssprop --text-color - (@deprecated) I dub thee "deprecated" ?
 */
class MyElement extends HTMLElement {}

API の更新

私たちのチームにとって重要なことは、API を削除または変更する場合、チームが早期に移行できるように、次のメジャー リリースの前に新機能を導入するように努めていることです。そうすることで、最新の状態を維持していれば、新しいバージョンへのアップグレードの影響を最小限に抑えることができます。

この次のセクションでは、古い API を壊さずに新しい機能を導入する方法と、それらの機能が互いに競合せずに共存できる方法について説明します。シンプルなボタン コンポーネントのいくつかの API を更新する予定です。

この例では Lit を使用しますが、これらの機能と原則はどの環境にも適用できます。

CSS変数

VS Code や JetBrains などのエディターでオートコンプリートと説明を改善するには、コンポーネント固有の CSS 変数名を指定する必要があります。

/**
  * @deprecated This component is going away. Use ... instead.
  */
class MyElement extends HTMLElement {
  /** @deprecated This property is being removed. Use ... instead. */
  myProp;

  /** @deprecated This method is going away. Use ... instead. */
  myMethod() {
  }
}

難しいのは、チームがすでに古い変数を使用しているため、両方が機能する必要があるということです。これを行うには、非推奨の変数を新しい変数にマッピングし、その変数のみを使用するようにボタン コードを更新します。そうすることで、ユーザーが非推奨の変数を使用してスタイルを設定している場合、その変数は新しい変数に適用されるか、ユーザーは値を新しい変数に直接適用できます。

/**
 * @attr {boolean} disabled - disables the element
 * @attribute {string} foo - description for foo
 *
 * @csspart bar - Styles the bar element in the shadow DOM
 *
 * @slot - This is a default/unnamed slot
 * @slot container - You can put some elements here
 *
 * @cssprop --text-color - Controls the color of foo
 * @cssproperty [--background-color=red] - Controls the background color of bar
 *
 * @prop {boolean} prop1 - some description
 * @property {number} prop2 - some description
 *
 * @fires custom-event - some description for custom-event
 * @fires {MyType} typed-event - some description for typed-event
 * @event {MyType} typed-custom-event - some description for typed-custom-event
 *
 * @summary This is MyElement
 *
 * @tag my-element
 * @tagname my-element
 */
class MyElement extends HTMLElement {}

これで、新しい CSS 変数で JSDoc 情報を更新し、更新された説明を含む古い変数に (@deprecated) を追加できるようになりました。

/**
 * @cssprop --text-color - @deprecated I dub thee "deprecated" ❌
 */
class MyElement extends HTMLElement {}

CSSパーツ

CSS 変数と同様に、ツールのサポートを向上させるためにパーツに名前空間付きの名前を提供したいため、コントロールをボタン コントロールに置き換えます。 CSS クラスのように複数のパーツを要素に適用できるため、CSS パーツは非常に簡単です。そのため、新しいパーツ名を他の要素と並べて要素に適用しましょう。

/**
 * @cssprop --text-color - (@deprecated) I dub thee "deprecated" ?
 */
class MyElement extends HTMLElement {}

これで、新しい部分で JSDoc を更新し、(@deprecated) で古い部分を非推奨にし、説明を更新できます。

/* old variables */
--bg-color: #ccc;
--fg-color: black;

/* new variables */
--button-bg-color: #ccc;
--button-fg-color: black;

スロット

コンポーネントが国際化 (i18n) をサポートするための新しい取り組みに伴い、一部の API を RTL (右から左) 言語でより意味のあるものに更新しています。私たちがやりたいことの 1 つは、すでに左側のスロットを使用しているプロジェクトのエクスペリエンスを損なうことなく、左からのボタン テキストの前にアイコンを表示するスロットを更新することです。

これは、非推奨のスロットを新しいスロット内にネストすることで実現できます。新しいスロットが使用されていない場合は、古いスロットに「フォールバック」します。

--bg-color: #ccc;
--fg-color: black;
--button-bg-color: var(--bg-color);
--button-fg-color: var(--fg-color);

button {
  background-color: var(--button-bg-color);
  border: solid 1px var(--button-fg-color);
  color: var(--button-fg-color);
}

これで、新しいスロットで JSDoc を更新し、(@deprecated) で古いスロットを非推奨にし、説明を更新できます。

/**
 * An example button element.
 *
 * @tag my-button
 * 
 * @cssprop [--bg-color=#ccc] - (@deprecated) (use `--button-bg-color` instead) controls the background color of the button
 * @cssprop [--fg-color=black] - (@deprecated) (use `--button-fg-color` instead) controls the foreground/text color of the button
 * @cssprop [--button-bg-color=#ccc] - controls the background color of the button
 * @cssprop [--button-fg-color=black] - controls the foreground/text color of the button
 *
 */

イベント

この例では、カスタム フォーカス イベントを生成していますが、チームにとってはわかりにくくなっているため、名前空間イベント (my-focus) を追加したいと考えています。両方のイベントを発行でき、開発者は機会があれば新しいイベントに移行できるため、イベントは非常に簡単です。

<button part="control button-control">
  <slot></slot>
</button>

これで、新しいイベントで JSDoc を更新し、(@deprecated) で古いイベントを非推奨にし、説明を更新できます。

/**
 * An example button element.
 *
 * @tag my-button
 *
 * @csspart control - (@deprecated) (use `button-control` instead) provides a hook to style internal button element
 * @csspart button-control - provides a hook to style internal button element
 */

注: ほとんどのツールは、イベントの文書化に @event と @fires を受け入れます。それらの間に実際の違いはありません。

メソッド

メソッドは相互に並行して追加するのが非常に簡単で、メソッドの説明で標準の @deprecated タグを使用して、メソッドが非推奨であることを伝えることができます。

/**
  * @deprecated This component is going away. Use ... instead.
  */
class MyElement extends HTMLElement {
  /** @deprecated This property is being removed. Use ... instead. */
  myProp;

  /** @deprecated This method is going away. Use ... instead. */
  myMethod() {
  }
}

プロパティと属性

プロパティと属性は、@attr/@attribute タグと @prop/@property タグを使用してクラスの JSDoc に文書化できます。これらを使用している場合は、カスタム要素マニフェストで (@deprecated) タグを使用して非推奨にすることができますが、通常は、独自の JSDoc コメントを使用してプロパティを直接文書化することをお勧めします。これにより、型やその他のツールが非推奨の API を適切に識別できるようになります。

良い点は、ほとんどのアナライザーは、コンポーネント クラスでデコレーターやその他の構成を使用して定義されているプロパティと属性の関連付けに非常に優れているため、プロパティを非推奨にすると、関連付けられた属性も非推奨になります。

デモ コンポーネントには、ネイティブ HTML 要素とより一致するように無効に更新する disable 属性があります。

最初に行うことは、古いプロパティを廃止し、新しいプロパティを追加することです。

/**
 * @attr {boolean} disabled - disables the element
 * @attribute {string} foo - description for foo
 *
 * @csspart bar - Styles the bar element in the shadow DOM
 *
 * @slot - This is a default/unnamed slot
 * @slot container - You can put some elements here
 *
 * @cssprop --text-color - Controls the color of foo
 * @cssproperty [--background-color=red] - Controls the background color of bar
 *
 * @prop {boolean} prop1 - some description
 * @property {number} prop2 - some description
 *
 * @fires custom-event - some description for custom-event
 * @fires {MyType} typed-event - some description for typed-event
 * @event {MyType} typed-custom-event - some description for typed-custom-event
 *
 * @summary This is MyElement
 *
 * @tag my-element
 * @tagname my-element
 */
class MyElement extends HTMLElement {}

ここで、コンポーネントが無効になっているかどうかを判断する必要があるたびに両方のプロパティをチェックする必要を避けたいと考えています。これを単純化するために、非推奨のプロパティをゲッター/セッターに変換し、新しいプロパティを信頼できるソースとして使用できます。

/**
 * @cssprop --text-color - @deprecated I dub thee "deprecated" ❌
 */
class MyElement extends HTMLElement {}

古い値が更新されるたびに、新しい値も自動的に更新されるため、新しいプロパティをチェックしてコンポーネントが無効になっているかどうかを確認するだけで済みます。

/**
 * @cssprop --text-color - (@deprecated) I dub thee "deprecated" ?
 */
class MyElement extends HTMLElement {}

完成した例をチェックしてください!

結論

API を変更すると複雑な問題が生じる可能性がありますが、破壊的な変更が含まれる可能性があるため、新機能の作成をやめる必要があるというわけではありません。新機能を早期に導入し、古い機能を非推奨にすることは、優れた開発者エクスペリエンス (DX) を提供する方法となります。これにより、新機能を活用するためにチームが待たされたり、一度に大規模な変更を加えたりするのではなく、段階的に強化する道が提供されます。

以上がWeb コンポーネント API の非推奨化の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。