棄用您的 Web 元件 API

棄用 Web 元件 API 是向使用者傳達某個功能將在軟體包的下一個主要版本中刪除的好方法。如果您使用自訂元素清單來記錄元件 API，這可能比看起來更棘手。 Web 元件通常比框架元件擁有更多的公共 API：

• CSS 變數
• CSS 部分
• 老虎機
• 活動
• 方法
• 屬性
• 屬性。

在本文中，我將示範如何記錄 API 棄用並添加替換功能，而不引入重大變更。

文件

棄用過程中最棘手的部分之一是文件。對於屬性、方法，甚至您的元件，這可以像在元件類別中的 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 {}

解決方案

為了解決這個問題，我創建了一個工具（custom-elements-manifest-deprecator），它允許您在 JSDoc 中標記項目，以便它們在自訂元素清單中進行適當更新。

使用此工具，您可以使用替代標籤來識別已棄用的 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（從右到左）語言中更有意義。我們想要做的一件事是更新我們的插槽，該插槽旨在從左側開始在按鈕文字之前顯示一個圖標，而不會破壞已經使用左側插槽的項目的體驗。

我們可以透過將已棄用的插槽嵌套在新插槽中來實現此目的。如果新插槽沒有被使用，它將「回退」到舊插槽。

--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 元素。

我們要做的第一件事是棄用舊屬性並新增屬性。

/**
 * @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 {}

現在，我們希望避免每次需要確定元件是否已停用時都必須檢查這兩個屬性。為了簡化這一點，我們可以將已棄用的屬性轉換為 getter/setter，並使用新屬性作為事實來源。

/**
 * @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中文網其他相關文章！