構建卓越 HTML API 的關鍵步驟详情 - 前端,javascript,前端工程化,api,程序員 Apifox 日志

作為 JavaScript 開發者，我們經常忘記並不是所有人都像我們一樣瞭解 JavaScript，這被稱為知識的詛咒：當我們精通某個內容的時候，我們就不記得自己作為新人的時候有多麼困惑。我們總是對其他人的能力估計過高，因此我們覺得，自己寫的類庫需要一些 JavaScript 代碼去初始化和配置也很正常。然而，一些用户卻在使用過程中大費周折，他們瘋狂地從文檔中複製粘貼例子並隨機組合這些代碼，直到它們生效為止。

你或許會想：“所有寫 HTML 和 CSS 的人都會 JavaScript，對吧？”

你錯了。來看看我的調查結果吧，這是我所知道的唯一相關數據了。

根據投票結果來看，每兩個寫 HTML 和 CSS 的人中，就有一個對 JavaScript 沒有好感。 這是個值得讓人深思的數據結果。

舉個例子，以下的代碼用來初始化一個 jQuery UI 自動完成庫。

<div class="ui-widget">
    <label for="tags">Tags: </label>
    <input id="tags">
</div>

$( function() {
    var availableTags = [
        "ActionScript",
        "AppleScript",
        "Asp",
        "BASIC",
        "C"
    ];
    $( "#tags" ).autocomplete({
        source: availableTags
    });
} );

你覺得這很簡單，甚至覺得即使那些根本不會 JavaScript 的人也會覺得簡單，對吧？

錯！非程序員在文檔中看到這個例子的時候，腦子裏會閃過各種問題：“我該把這段代碼放哪兒呢？”“這些花括號、冒號和方括號都是什麼意思？”“我要用這些嗎？”“如果我的元素沒有 ID 怎麼辦？”等等。所以即使這段極其簡短的代碼也要求人們瞭解對象字面量、數組、變量、字符串、如何獲取 DOM 元素的引用、事件、 DOM 樹何時構建完畢等等更多知識。這些對於程序員來説微不足道的事情，對於不會 JavaScript 、只會寫 HTML 的人來説都是一場艱難的攻堅戰。

現在來看一下 HTML5 中的等效聲明性代碼：

<div class="ui-widget">
    <label for="tags">Tags: </label>
    <input id="tags" list="languages">
    <datalist id="languages">
        <option>ActionScript</option>
        <option>AppleScript</option>
        <option>Asp</option>
        <option>BASIC</option>
        <option>C</option>
    </datalist>
    </div>

這不僅讓寫 HTML 的人看得更清楚更明白，也對程序員來説更為簡單。我們看到所有的內容都同時被設置好，不必關心什麼時候初始化、如何獲取元素的引用以及如何設置每個內容，無需知道哪個函數是用來初始化或者它需要什麼參數。在更高級的使用情況中，還會添加一個 JavaScript API 來允許動態創建屬性和元素。這遵循了一條最基本的 API 設計原則：讓簡單的內容變得更簡單，讓複雜的內容得以簡單實現。

這給我們上了一堂關於 HTML API 的重要一課：HTML API 不光要給那些瞭解 JavaScript 但水平有限的人帶來福音，還要讓我們程序員在普通的工作中也要不惜犧牲程序的靈活性來換取更高的表述性。然而不知道為什麼，我們在寫自己的類庫的時卻總忘記這些原則。

那麼什麼是 HTML API 呢？根據維基百科的定義，API（也就是應用程序接口）是“用於構建應用程序軟件的一組子程序定義、協議和工具”。在 HTML API 中，定義和協議就是 HTML ，工具在 HTML 中配置。HTML API 通常由可用於現有 HTML 內容的類和屬性模式組成。通過 Web 組件，甚至可以像玩遊戲一般自定義元素名稱和 Shadow DOM，HTML API 甚至能擁有完整的內部結構，並且對頁面其餘部分隱藏實現細節。但是這並不是一篇關於 Web 組件的文章，Web 組件給予了 HTML API 設計者更多的能力和選擇，但是良好的（HTML）API 設計原則都是可以舉一反三的。

HTML API 加強了設計師和工程師之間的合作，減輕工程師肩上的工作負擔，還能讓設計師創造更具還原度的原型。在類庫中引入 HTML API 不僅讓社區更具包容性，最終還能造福程序員。

並不是每個類庫都需要 HTML API。 HTML API 在使用了 UI 元素的類庫中非常有用，比如 galleries、drag-and-drop、accordions、tabs、carousels 等等。經驗表明，如果一個非程序員不能理解該類庫的功能，它就不需要 HTML API。比如，那些簡化代碼或者幫助管理代碼的庫就不需要 HTML API。那 MVC 框架或者 DOM 助手之類的庫又怎會需要 HTML API 呢？

目前為止，我們只討論了 HTML API 的定義、功能和用處，文章剩下的部分是關於如何設計一個好的 HTML API。

初始化選擇器

在 JavaScript API 中，初始化是被類庫的用户嚴格控制的：因為他們必須手動調用函數或者創建對象，精確地控制着其運行的時間和基礎。在 HTML API 中，我們要幫用户選擇，同時也要確保不會妨礙那些仍然使用 JavaScript 的用户，因為他們可能希望得到完全控制。

最常見的兼容兩種使用場景的辦法是：只有匹配到給定選擇器（通常是一個特定的類）時才會自動初始化。Awesomplete 就是採用的這種方法，只選取具有 class="awesomplete" 的 input 元素進行初始化。

有時候，簡化自動初始化比做顯式選擇初始化更重要。當你的類庫需要運行在眾多元素之上時，避免手動給每個元素單獨添加類比顯式選擇初始化更加重要。比如，Prism 自動高亮任何包含 language-xxx 類的 <code> 元素（HTML5 的説明中建議指定代碼段的語言）及其包含languate-xxx 類的元素內部的 <code> 元素。這是因為 Prism 可能會用在一個有着成千上萬代碼段的博客系統中，回過頭去給每一個元素添加類將會是一項非常巨大的工程。

在可以自由地使用 init 選擇器的情況下，最好的做法是允許選擇是否自動化。比如，Stretchy 默認自動調整每個 <input>、<select> 和 <textarea>的尺寸，但是也允許通過 data-stretchy-filter 屬性自定義指定其他元素為 init 選擇器。Prism 支持 <script> 元素的 data-manual 屬性來完全取消自動初始化。良好的實踐應該允許 HTML 和 JavaScript 都能設置這個選項，來適應 HTML 和 JavaScript 兩種類庫的用户。

最小化初始標記

那麼，對於 init 選擇器的每個元素，你的類庫都需要有一個封包、三個內部的按鈕和兩個相鄰的 div 該怎麼辦呢？小問題，自己生成就好了。但是這種瑣碎的工作更適合機器，而不是人。不要期望每個使用類庫的人都同時使用了模板系統：許多人還在使用手動添加標記，他們會發現這樣建造系統太過複雜。因此，我們應該讓他們更輕鬆些。

這種做法也最小化了錯誤風險：如果一個用户僅僅引入了用來初始化的類卻沒有引入所有需要的標記怎麼辦？如果不需要添加額外的標記，就不會產生錯誤。

這條規則中有一個例外：優雅地退化並漸進地增強。比如，即使單個具有 data- * 屬性的元素並在 data-* 中添加所有選項就可以實現，在嵌入推文的時候也還是會涉及很多標記。這樣做是為了在 JavaScript 加載和運行之前推文就可讀。一個良好的經驗法則就是捫心自問“即使在沒有 JavaScript ，多餘的標記能否給終端用户帶來好處？”如果是，那麼就引入；如果不是，那就要用類庫生成。

便於用户使用還是讓用户自定義也是一組經典的矛盾：自動生成所有的標記會易於用户使用，讓用户自定義又顯得更加靈活。在你需要的時候，靈活性如雪中送炭，在不需要的時候卻適得其反，因為你不得不手動設置所有的參數。為了平衡這兩種需要，你可以生成那些需要但不存在的標記。比如，假設你需要給所有的 .foo 元素外層添加一個 .foo-container 元素。首先，通過element.closest(".foo-container") 檢查 .foo 元素的父元素或者任何的祖先元素（這樣最好了）是否含有 foo-container 類，如果有的話，你就不用生成新的元素，直接使用就可以了。

設置

通常，設置應該通過在恰當的元素上使用 data-* 屬性來實現。如果你的類庫中添加了成千上萬的屬性，然後你希望給它們添加命名空間來避免和其他類庫混淆，比如這樣 data-foo-*（foo 是基於類庫名字的一到三個字母長度的前綴）。如果名字顯得太長，你可以使用 foo-*，但你要知道，這種方式會打破 HTML 驗證並且會使得一些勤奮的 HTML 作者因此而棄用你的類庫。理想情況下，只要代碼不會太臃腫，以上兩種情況都應該支持。目前還沒有完美的解決辦法，因此在 WHATWG 中展開了一場如火如荼的討論：是否應該讓自定義的屬性前綴合法化。

儘可能地遵從 HTML 的慣例。比如，你使用了一個屬性來做布爾類型的設置，當該屬性出現時無論其值如何都被視為 true，若不出現則被視為 false，不要期望可以用 data-foo="true" 或者 data-foo="false" 來代替。

你也可以使用類進行布爾值設置。一般情況下它的語法和布爾屬性類似：類存在的時候是 true 不出現的時候就是 false。如果你想反過來設置，那就用一個 no- 前綴（比如，no-line-number）。但是要記住，類名可不像屬性一樣只有 data-*，因此這種方式很可能會和用户現存的類名衝突，因此你可以考慮一下在類名中使用 foo- 這樣的前綴來避免衝突。但也有可能在後期的維護中發現這些類並未被 CSS 使用所以誤刪，這又是另一個隱患。

當你需要設置一組相關的布爾值時，使用空格區分會比使用多個分隔符的方式好很多。

<!-- 第一種-->
<div data-permissions="read add edit delete save logout">

<!-- 第二種-->
<div data-read data-add data-edit data-delete data-save data-logout">

 <!-- 第三種-->
 <div class="read add edit delete save logout">

比如，第一種當時就比後面兩種好得多，因為後者可能會造成很多的衝突。你還可以使用 ~= 屬性選擇器來定位單個元素，比如 element.matches("[data-permissions~=read]") 可以檢查該元素是否有 read 權限。

如果設置內容的類型是數組（array）或者對象（object） ，那麼你就可以使用 data-* 屬性來關聯到另一個元素。比如， HTML5 中的自動完成：因為自動完成需要一個建議列表，你可以使用 data-* 屬性並通過 ID 聯繫到包含建議內容的 <datalist> 元素。

HTML 有一個慣例很讓人頭痛：在 HTML 中，用屬性聯繫到另一個元素通常是靠引用其 ID 實現的（試想一下 <label for="...">）。然而，這種方法相當受限制：如果能夠允許使用選擇器或者甚至允許嵌套將更為方便，其效果將會極大地依賴於你的使用情況。要記住，穩定性重要，但實用性更加重要。

即使有些設置內容不能在 HTML 中指定也沒關係。在 JavaScript 中以函數為設置值的部分被稱作“高級自定義”。試想一下 Awesomplete：所有數字、布爾值、字符串和對象都可以通過 data-* 屬性（list、minChars、maxItems、autoFirst）設置，所有的函數設置只能通過 JavaScript 使用（filter、sort、item、replace、data），這樣會寫 JavaScript 函數來配置類庫的人就可以使用 JavaScript API 了。

正則表達式（regex）處在灰色地帶：通常只有程序員才知道正則表達式（甚至程序員在使用的時候也會有問題！）；那麼，乍看之下，在 HTML API 中引入正則表達式類型的設置並沒有意義。然而，HTML5 確實引入了這樣的設置（<input pattern="regex">），並且我覺得很成功，因為非程序員能在正則詞典中找到他們的用例並複製粘貼。

繼承

如果你的 UI 庫在每個頁面只會調用一兩次，繼承可能不是很重要。然而，如果要應用於多個元素，通過類或者屬性給每個元素做相同的配置將會非常令人頭疼。咱要記住並不是每個人都用了構建系統，尤其是非程序員。在這些情況下，定義能夠從祖先元素繼承設置將會變得非常有用，那樣多個實例就可以被批量設置了。

還拿 Smashing Magazine 中使用的時下流行的語法高亮類庫 —— Prism 來舉例。高亮語句是通過 language-xxx 形式的類來配置的。如你所見，這違反了我們在前文中談過的規則，但這只是一種主觀決策，因為 HTML5 手冊中建議如此。在有許多代碼段的頁面上（想象一下，在博客文章中使用內聯 <code> 元素的頻率！），在每個 <code> 元素中指定代碼語句將會非常煩人。為了減輕這種痛苦，Prism 支持繼承這些類：如果一個 <code> 元素自己沒有 language-xxx 類，那麼將會使用其最近的祖先元素的 language-xxx 類。這使得用户可以設置全局的代碼語句（通過在 <body> 或者 <html> 元素上設置類）或者設置區塊的代碼語句，並且可以在擁有不同語句的元素或者區塊上重寫設置。

現在 CSS 變量已經被所有的瀏覽器支持，它們可以用於以下設置：他們默認可以被繼承，並且可以以內聯的方式通過 style 屬性設置，也可以通過 CSS 或者 JavaScript 設置。在代碼中，你可以通過getComputedStyle(element).getPropertyValue("--variablename") 獲取它們。除了瀏覽器支持，其主要的劣勢就是開發者們還沒習慣使用它們，但是那已經發生改變了。並且，你不能像監視元素和屬性的一般通過 MutationObserver 來監視其改變。

全局設置

大多數 UI 類庫都有兩組設置：定義每個組件表現形式的設置和定義整個類庫表現形式的全局設置。目前為止，我們主要討論了前者，你現在可能好奇全局設置該在設置在哪裏。

進行全局設置的一個好地方就引入類庫的 <script> 元素。你可以通過 document.currentScript 獲取該元素，這有着非常好的瀏覽器支持。好處就是，這對於設置的作用域非常清楚，因此它們的名字可以起的更短（比如 data-filter 而不是 data-stretchy-filter）。

然而，你不能只在 <script> 元素中進行設置，因為一些用户可能會在 CMS 中使用你的類庫，而 CMS 中不允許用户自定義 <script> 元素。你也可以在 <html> 和 <body> 元素或者甚至任何地方設置，只要你清楚地聲明瞭屬性值重複的時候哪個會生效。

文檔

那麼，你已經掌握瞭如何在類庫中設置一個漂亮的聲明性的 API，那自然很好，然而，如果你所有的文檔都寫得只有會 JavaScript 的用户才看得懂，那麼就只有很少人能使用了。我記得曾經看過一個很酷的類庫，基於 URL 並通過切換元素的 HTML 屬性來切換元素的表現形式。然而，這漂亮的 HTML API 並不能被其目標人羣所使用，因為整篇文檔中都充滿了 JavaScript 引用。最開始的例子開頭就是“這和 location.href.match(/foo/)等價”。非程序員哪能看懂這個呀？

同時要記得許多人並不會任何編程語言而不僅僅是 JavaScript。你希望用户能夠讀懂並理解的文中的模型、視圖、控制器或者其他軟件工程觀念，但結果無非是讓他們感到迷惑。

當然，你應該在文檔中寫 API 裏 JavaScript 的內容，你可以寫在“高級使用”部分。然而，如果你在文檔一開頭就引用 JavaScript 對象和函數或者軟件工程的觀念，那麼你實質上就是在告訴非程序員這個類庫不是給他們用的，因此你就排除了一大批潛在用户。不幸的是，大部分的 HTML API 類庫文檔都受這些問題困擾着，因為 HTML API 經常被視為是程序員的捷徑，而並不是給非程序員使用的。慶幸的是，這種狀況在未來可以有改變。

Web 組件

在不遠的未來，Web 組件百分之百將會徹底改變 HTML API。<template> 元素將會允許作者提供惰性加載的腳本。自定義元素將使得用户可以像原生的 HTML 一樣使用更多優雅的 init 標記。引入 HTML 也將使得作者能夠僅引入一個文件來替代三個樣式表、五個腳本和十個模板（如果瀏覽器能夠同時獲取並且不再認為 ES6 模塊是一種競爭技術）。Shadow DOM 使得類庫可以將複雜的 DOM 結構適當壓縮並且不會影響用户自己的標記。

然而除了 <template>，瀏覽器對其他三個特徵的支持目前受限。因此他們需要更高的聚合度，以此來減少對類庫的影響。這將會是我們在未來一段時間裏需要不斷關注的東西。