[譯] 用 Shadow DOM v1 和 Custom Elements v1 實現一個原生 Web Component

newraina發表於2018-12-19
Web

[譯] 用 Shadow DOM v1 和 Custom Elements v1 實現一個原生 Web Component

假如你有一個小表單或者元件要在網站的好幾個地方或者好幾個專案裡用，你希望它們都能有統一的樣式和行為，但是，你也希望它們能有些靈活性：也許你的表單需要根據容器元素的不同有各種大小，或者元件要在不同的專案裡顯示不同的文字和圖示。你知道你需要什麼嗎？你需要一個 web component！

Web components 是可以重用和共享的自定義 HTML 元素。和原生 HTML 元素一樣，它們有屬性，有方法，有事件監聽器，能巢狀，能相容各種 JavaScript 框架。

怎麼樣，是不是很厲害？沒有 jQuery，沒有難以維護的麵條程式碼，它就是一個良好封裝過的帶 UI 和功能的元件了。

介紹一下 Mini-Form 元件

我們要實現一個叫 “mini-form” 的 web component。（Custom element 的名字必須用小寫字母開頭，並且至少有一個連字元。要了解更多可以閱讀相關標準。）它是一個很簡單的表單元件：讓使用者提交投訴意見，並且能確認是否收到了使用者的輸入（實際上並不真的幹什麼）。這個元件能自適應它容器元素的大小和標題的長度。它有一個基本的 material design 樣式；你可以給每個元件例項指定顏色主題。元件的程式碼託管在 github.com/pearlbea/mi…，線上示例請見這裡。

定義 Custom Element

Web components 可以用一些新的 web 標準來實現。其中最重要的是最新修訂過的 Custom Elements 標準。（要了解更多關於新的 Custom Elements V1 標準，可以閱讀 Eric Bidelman 的文章）要建立一個 custom element，我們需要兩個東西：一個定義元素行為的類，以及一個告訴瀏覽器如何關聯 DOM 元素標籤和剛才那個類的定義。新建一個叫 mini-form.js 的檔案，把下面的類和定義程式碼放進去：

class MiniForm extends HTMLElement {
  constructor() {
    super();
  }
}
window.customElements.define('mini-form', MiniForm);
複製程式碼

constructor 裡，對 super() 不帶引數的呼叫必須放在第一行。它會為元件設定正確的原型鏈和 this 的值。（更多資訊可以參考 Mozilla Developer Network 關於 super 的文章。）

其他準備工作

新建檔案的時候，還要建立：一個 index.html，用來實際引用元件；一個 mini-form-test.html，用來寫測試用例，因為元件是你寫的。先在這兩個檔案裡寫上基本的 HTML5 樣板程式碼。

你還需要一些 polyfill。我們使用的 web 標準非常新，還沒被所有瀏覽器支援，至少到目前為止，polyfill 是必須的。對於我們這個簡單的元件，只需要兩個 polyfill：custom elements 和 shadydom，可以用 Bower 安裝：

bower install --save webcomponents/custom-elements
bower install --save webcomponents/shadydom
複製程式碼

把這兩個 polyfills 放在 index.html 和 mini-form-test.html 的 head 裡，（或者用你習慣的構建工具打包在一起，都行，無所謂。）同時，也要把 mini-form.js 引用進每一個 HTML 檔案裡。index.html 現在差不多是下面的樣子：

<!doctype html>
<html lang="eng">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, minimum-scale=1, initial-scale=1, user-scalable=yes">
    <script src="bower_components/shadydom/shadydom.min.js"></script>
    <script src="bower_components/custom-elements/custom-elements.min.js"></script>
    <script src="mini-form.js"></script>
  </head>
  <body></body>
</html>
複製程式碼

注意：shadydom polyfill 要放在 custom elements polyfill 前面。不然，你可能會看到 Element#attachShadow 不存在的報錯。（猜猜我是怎麼知道的。）shadow DOM 的其他內容後面再說。

編寫測試用例

在真的開始寫元件之前，我們先寫一些測試。我們要測試這個元件能不能在 DOM 中渲染出一個 div，現在它還通不過測試，畢竟我們的元件還幾乎不存在。不過，一旦我們渲染出了一個 div 元素，我們就能體會到目睹測試通過的樂趣。

測試差不多是這個樣子：

suite('<mini-form>', () => {
  let component = document.querySelector('mini-form');
  test('renders div', () => {
    assert.isOk(component.querySelector('div'));
  });
});
複製程式碼

為了執行測試，我們要用到 Polymer Project 建立的 web component tester 工具。用 NPM 安裝好 web-component-tester 之後，在 mini-form-test.html 檔案的 head 標籤里加上 node_modules/web-component-tester/browser.js，polyfills 和 mini-form.js 也應該在頁面上了。

你還要在 body 里加上 mini-form 的例項，就像這樣：

<body>
  <mini-form></mini-form>
  <script>
    suite('<mini-form>', function() {
      let component = document.querySelector('mini-form');
      test('renders div', () => {
        assert.isOk(component.shadowRoot.querySelector('div'));
      });
    });
  </script>
</body>
複製程式碼

好了，跑測試吧！在命令列中輸入 wct，web component tester 會啟動你安裝的所有瀏覽器執行測試。然後，你會看到一個測試失敗的提示：

✖ test/mini-form-test.html » <mini-form> » renders div expected null to be truthy
複製程式碼

如果你遇到了其他問題，可以在這裡看看到這一步，你的程式碼應該是什麼樣子。

編寫模版

現在我們可以來擴充元件的實現並讓測試通過了。

class MiniForm extends HTMLElement {

  constructor() {
    super();
  }

  connectedCallback() {
    this.innerHTML = this.template;
  }

  get template() {
    return `
      <div>This is a div</div>
    `;
  }
}
複製程式碼

上面的程式碼新增了一個返回最簡單模板的 getter。然後，在 connectedCallback 中，模板賦給了元件的 innerHTML。connectedCallback 方法是custom element 生命週期的一部分，當元件插入到 DOM 中時會被呼叫。

再跑一遍測試，噢耶！這次肯定能通過！當然，這個元件最後不會僅僅只顯示一個 div。我們要寫更多的測試，看著它們測試失敗，再靠程式碼實現讓它們最終都能通過。

// mini-form-test.html
test('renders input', function() {
  assert.isOk(component.querySelector('input[type="text"]'));
});

test('renders button', function() {
  assert.isOk(component.querySelector('button'));
});

// mini-form.js
get template() {
  return `
    <div>
      <input type="text" name="complaint" />
      <button>Submit</button>
    </div>
  `;
}
複製程式碼

增加樣式和 Shadow DOM

到目前為止，mini-form 元件還不是很好看，是時候加一點樣式了。不管用在哪裡，元件的樣式都應該在所有的例項間保持統一。我們並不希望元件所在頁面的 CSS 或者 JS 會影響到元件，也不希望元件的樣式或行為影響到了它所處的頁面。可以通過把元件的內容封裝在 Shadow DOM 裡來實現這一點。

Shadow DOM 和你早已熟悉和喜愛的 DOM 很像。它有相同的樹形結構和工作方式，只是：它不會和父級 DOM 相互影響；也不會成為它所附屬元素的子元素。

我們要修改 mini-form 來讓它支援 Shadow DOM。

connectedCallback() {
  this.initShadowDom();
}

initShadowDom() {
  let shadowRoot = this.attachShadow({mode: 'open'});
  shadowRoot.innerHTML = this.template;
}
複製程式碼

我們不再把模板內容直接賦給元件自身的 innerHTML，而是建立一個 shadowRoot 作為中介：給元件關聯上一個 Shadow DOM，然後把模板內容賦給這個 Shadow DOM 的 innerHTML。

這樣做會破壞掉所有的測試，不過，改起來也很簡單，只要在 DOM 查詢上加上剛定義過的 shadowRoot 即可。

test('renders div', () => {
  assert.isOk(component.shadowRoot.querySelector('div'));
});
test('renders input', () => {
  assert.isOk(component.shadowRoot.querySelector('input'));
});
test('render button', () => {
  assert.isOk(component.shadowRoot.querySelector('button'));
});
複製程式碼

跑一遍測試，確保全都通過之後，我們來加上 Material Design 的樣式。

<style>
  @import 'https://fonts.googleapis.com/icon?family=Material+Icons';
  @import 'https://code.getmdl.io/1.3.0/material.indigo-pink.min.css';
  @import 'http://fonts.googleapis.com/css?family=Roboto:300,400,500,700';
  .mdl-card {
    width: 100%;
  }
  .mdl-button {
    margin-top: 10px;
  }
  i {
    margin-right: 5px;
  }
</style>
<div class="mdl-card mdl-shadow--2dp">
  <header class="mdl-layout__header">
    <div class="mdl-layout__header-row">
      <i class="material-icons">mood_bad</i>
      <div class="mdl-layout-title">complaint box</div>
    </div>
  </header>
  <div class="mdl-card__supporting-text">
    <input type="text" class="mdl-textfield__input" />
  </div>
  <div class="mdl-card__actions">
    <button class="mdl-button mdl-button--raised mdl-button--accent">Submit</button>
  </div>
</div>
複製程式碼

在瀏覽器裡開啟元件的 index.html 看一下，頁面雖然還需要打磨，但是已經有一個好看的輸入框和一個漂亮的粉色按鈕了。

（沒看到粉色按鈕？可以來這裡看下到這一步，程式碼應該是什麼樣子。）

在內部 DOM 中建立 <slot>

Shadow DOM 有個很棒的特性：<slot> 元素，它讓元件可以把它實際的子元素插入到內部結構中。這個能力讓 web components 變得異常靈活。<slot> 元素扮演了一個佔位符的角色，使用元件的人可以自己填充內容。對於我們這個元件來說，我們將用 slot 讓我們自己（或者元件未來的使用者）有能力為表單每一個例項提供不同的文字提示或者問題。第一步，先寫好測試：

<body>
  <mini-form>What?!</mini-form>
  <script>
    suite('<mini-form>', function() {
      let component = document.querySelector('mini-form');
      ...
      test('renders prompt', () => {
        let index = component.innerText.indexOf('What?!');
        assert.isAtLeast(index, 0);
      });
    });
  </script>
</body>
複製程式碼

上面的測試檢查了 <mini-form> 標籤之間的文字內容是不是在元件中顯示出來了。執行一下測試，可以看到測試失敗了。

為了讓測試通過，在模板中加一個 <slot>。

<div class="mdl-card mdl-shadow--2dp">
 <div class="mdl-card__supporting-text">
   <h4><slot></slot></h4>
   <input type="text" rows="3" class="mdl-textfield__input" name="prompt" />
 </div>
 ...
</div>
複製程式碼

再跑一遍測試，這次通過了！試試在 index.html 的 mini-form 標籤之間寫點東西，然後在瀏覽器裡看一下效果。到這一步的程式碼在這裡。

實現主題化

元件需要能允許我們為每一個例項指定一個顏色主題。為了讓主題化和我們在用的 material design CSS 配合得好，使用者能用的主題會被限制在這裡列出的幾種裡。我們給元件新增一個 theme 屬性，使用者設定一個字串值來指定主題。

給這個新特性寫點測試。

<body>
  <mini-form theme="blue-green">What?!</mini-form>
  <script>
    suite('<mini-form>', function() {
      let component = document.querySelector('mini-form');
      ...
      test('applies color theme to button', () => {
        let button = component.shadowRoot.querySelector('button');
        let buttonColor = window.getComputedStyle(button).getPropertyValue('background-color');
        assert.equal(buttonColor, 'rgb(105, 240, 174)');
      });
      test('applies color theme to header', () => {
        let header = component.shadowRoot.querySelector('header');
        let headerColor = window.getComputedStyle(header).getPropertyValue('background-color');
        assert.equal(headerColor, 'rgb(33, 150, 243)');
      });
    });
  </script>
</body>
複製程式碼

跑一遍測試，確定一下它們通過沒有。沒通過吧？很好。修改元件的程式碼來獲取和使用 theme 屬性。

get theme() {
  return this.getAttribute('theme') || 'indigo-pink';
}

get template() {
  return `
    <style>
      @import 'https://code.getmdl.io/1.3.0/material.${this.theme}.min.css';
      ...
    </style>
    ...
  `;
}
複製程式碼

我們從 <mini-form> 標籤上獲取 theme 屬性，把它或者它的預設值 indigo-pink 用在 CSS 的地址裡。如果我們給 theme 屬性賦了這個 CSS 類庫實際並沒有的主題值，CSS 的地址就不會生效，元件就會很難看。解決這個問題需要寫的程式碼（和它的測試用例！），我打算交給你自己來完成。

跑一下測試，哎呀，並沒有全部通過。因為 Firefox 不支援 Shadow DOM，在 Firefox 裡跑的測試失敗了。我們已經用上了 shadydom polyfill，但它並不支援 CSS 封裝，有另一個叫 shadycss 的 polyfill 能解決這個問題。跟上面一樣，之後你自己完成。

在 index.html 裡，給 mini-form 標籤增加一個 theme 屬性。然後你就能在瀏覽器裡看到你的藝術創作了。

處理事件

元件已經很好看了，但還什麼都幹不了。我們要乾的最後一件事情，是給它加上事件處理的邏輯。當使用者點選“Submit”按鈕的時候，得發生點什麼事情。程式碼要獲取輸入，顯示一個成功或失敗（如果輸入為空）的提示。當使用者接著聚焦進輸入框的時候，錯誤資訊需要消失掉。

給這些事件邏輯寫上測試。

let input = component.shadowRoot.querySelector('input[type="text"]');
let button = component.shadowRoot.querySelector('button');
let errorMsg = component.shadowRoot.querySelector('.error');

test('displays an error message on submit', () => {
  button.click();
  let index = errorMsg.innerText.indexOf('Don\'t you have something to say?');
  assert.isAtLeast(index, 0);
});
test('clears error message on focus', () => {
  input.focus();
  let index = errorMsg.innerText.indexOf('Don\'t you have something to say?');
  assert.isAtLeast(index, -1);
});
test('displays a success message on submit', () => {
  input.value = 'Some text';
  button.click();
  let index = component.shadowRoot.querySelector('.mdl-card').innerText.indexOf('Thank you.');
  assert.isAtLeast(index, 0);
});
複製程式碼

在元件程式碼裡，給使用者會與之發生互動的兩個元素：輸入框和按鈕繫結事件監聽器。

當使用者聚焦進輸入框，我們希望清空可能在顯示的任何錯誤提示。首先，在模板裡新增一個錯誤提示，並且建立一個帶有 visibility: hidden 屬性的 CSS 類 hide。

<div class="mdl-card__supporting-text">
  <h4><slot></slot></h4>
  <input type="text" rows="3" class="mdl-textfield__input" name="question" />
  <div class="error hide">Don't you have something to say?</div>
</div>
複製程式碼

給輸入框繫結一個事件監聽器，處理它的聚焦事件。

connectedCallback() {
  this.initShadowDom();
  this.addFocusListener();
}
get input() {
  return this.shadowRoot.querySelector('input');
}
get errorMessage() {
  return this.shadowRoot.querySelector('.error');
}
addFocusListener() {
  this.input.addEventListener('focus', e => {
    this.hideErrorMessage();
  });
}
hideErrorMessage() {
  this.errorMessage.className = 'error hide';
}
複製程式碼

上面的程式碼給輸入框元素建立了一個 getter、一個在 connectedCallback 裡呼叫的繫結聚焦事件監聽的方法、還有一個在事件監聽中用來隱藏錯誤提示的方法。

接著，給按鈕增加點選事件的事件監聽和處理點選的邏輯。

connectedCallback() {
  this.initShadowDom();
  this.addFocusListener();
  this.addClickListener();
}
get button() {
  return this.shadowRoot.querySelector('button');
}
get card() {
  return this.shadowRoot.querySelector('.mdl-card');
}
get message() {
  // this could be a separate component and probably should be if you make it more complicated
  return `
    <div>
      <div class="mdl-card__title">
        <h4>Thank you.</h4>
      </div>
      <div class="mdl-card__supporting-text">We have received your complaint.</div>
      <div class="mdl-card__actions"></div>
    </div>
  `;
}
addClickListener() {
  this.button.addEventListener('click', e => {
    this.getUserInput();
  });
}
getUserInput() {
  this.input.value.length > 0 ? this.handleSuccess() : this.displayErrorMessage();
}
handleSuccess() {
  // You could call a method to save the user's answer here
  this.displaySuccessMessage();
}
displaySuccessMessage() {
  this.card.innerHTML = this.message;
}
displayErrorMessage() {
  this.errorMessage.className = 'error';
}
複製程式碼

跑一遍測試，看它們是不是全都通過！也有可能只是大部分通過：在 Firefox 裡，樣式的測試用例依然會失敗。恭喜，你有一個能工作的 web component 了！

全部的程式碼在這裡。

還可以做很多很多事情來完善和擴充套件這個元件。除了我早就提到過的，你還可以給頭部標題的文字、圖示加上 slot，或者美化、儲存使用者的輸入內容。

覺得還不夠的話，可以寫一個你自己的元件，在 Twitter 上私信給我。祝程式設計愉快！

相關連結

有任何問題或想法，都可以在 twitter @bendyworks 或者 Facebook 上聯絡我們。

如果發現譯文存在錯誤或其他需要改進的地方，歡迎到 掘金翻譯計劃 對譯文進行修改並 PR，也可獲得相應獎勵積分。文章開頭的 本文永久連結 即為本文在 GitHub 上的 MarkDown 連結。

掘金翻譯計劃 是一個翻譯優質網際網路技術文章的社群，文章來源為 掘金 上的英文分享文章。內容覆蓋 Android、iOS、前端、後端、區塊鏈、產品、設計、人工智慧等領域，想要檢視更多優質譯文請持續關注 掘金翻譯計劃、官方微博、知乎專欄。

相關文章