本頁面由 Cloud Translation API 翻譯而成。

操作說明元件 – 操作分頁

Ewa Gasperowicz

Rob Dodson

Surma

摘要

<howto-tabs> 將可見內容分割成多個面板，以便限制顯示的內容。一次只能顯示一個面板，但所有對應的分頁一律會顯示。如要從一個面板切換到其他面板，請選取對應的分頁。

使用者可以點選或使用方向鍵，變更使用中分頁的選取項目。

如果停用 JavaScript，所有面板都會與個別分頁交錯顯示。分頁現在會做為標題使用。

參考資料

示範

在 GitHub 上查看實際操作示範

使用案例：

<style>
  howto-tab {
    border: 1px solid black;
    padding: 20px;
  }
  howto-panel {
    padding: 20px;
    background-color: lightgray;
  }
  howto-tab[selected] {
    background-color: bisque;
  }

如果 JavaScript 未執行，元素就不會與 :defined 相符。在這種情況下，這個樣式會在分頁和上一個面板之間加入間距。

  howto-tabs:not(:defined), howto-tab:not(:defined), howto-panel:not(:defined) {
    display: block;
  }
</style>

<howto-tabs>
  <howto-tab role="heading" slot="tab">Tab 1</howto-tab>
  <howto-panel role="region" slot="panel">Content 1</howto-panel>
  <howto-tab role="heading" slot="tab">Tab 2</howto-tab>
  <howto-panel role="region" slot="panel">Content 2</howto-panel>
  <howto-tab role="heading" slot="tab">Tab 3</howto-tab>
  <howto-panel role="region" slot="panel">Content 3</howto-panel>
</howto-tabs>

程式碼

(function() {

定義按鍵代碼，協助處理鍵盤事件。

  const KEYCODE = {
    DOWN: 40,
    LEFT: 37,
    RIGHT: 39,
    UP: 38,
    HOME: 36,
    END: 35,
  };

為避免針對每個新執行個體使用 .innerHTML 叫用剖析器，所有 <howto-tabs> 例項都會共用陰影 DOM 內容的範本。

  const template = document.createElement('template');
  template.innerHTML = `
    <style>
      :host {
        display: flex;
        flex-wrap: wrap;
      }
      ::slotted(howto-panel) {
        flex-basis: 100%;
      }
    </style>
    <slot name="tab"></slot>
    <slot name="panel"></slot>
  `;

HowtoTabs 是分頁和面板的容器元素。

<howto-tabs> 的所有子項都應為 <howto-tab> 或 <howto-tabpanel>。這個元素是無狀態，代表系統不會快取任何值，因此會在執行階段工作期間發生變更。

  class HowtoTabs extends HTMLElement {
    constructor() {
      super();

如果事件處理常式需要存取 this，就必須綁定至此元素。

      this._onSlotChange = this._onSlotChange.bind(this);

如要採用漸進式增強效果，標記應在分頁和麵板之間來回切換。重新排序子項的元素通常無法與架構搭配運作。而是使用 shadow DOM 透過版位重新排序元素。

      this.attachShadow({ mode: 'open' });

匯入共用範本，建立分頁和面板的空格。

      this.shadowRoot.appendChild(template.content.cloneNode(true));

      this._tabSlot = this.shadowRoot.querySelector('slot[name=tab]');
      this._panelSlot = this.shadowRoot.querySelector('slot[name=panel]');

這個元素需要使用 aria-labelledby 和 aria-controls，以語意方式連結分頁和麵板，因此必須回應新的子項。新的子項會自動插入，並觸發 slotchange，因此不需要 MutationObserver。

      this._tabSlot.addEventListener('slotchange', this._onSlotChange);
      this._panelSlot.addEventListener('slotchange', this._onSlotChange);
    }

connectedCallback() 會重新排序分頁和面板，並確保只有一個分頁處於啟用狀態。

    connectedCallback() {

元素需要進行一些手動輸入事件處理，才能使用方向鍵和 Home/End 鍵切換。

      this.addEventListener('keydown', this._onKeyDown);
      this.addEventListener('click', this._onClick);

      if (!this.hasAttribute('role'))
        this.setAttribute('role', 'tablist');

直到最近，當剖析器升級元素時，slotchange 事件才會觸發。因此，元素會手動叫用處理常式。新行為在所有瀏覽器中推出後，您就可以移除下方的程式碼。

      Promise.all([
        customElements.whenDefined('howto-tab'),
        customElements.whenDefined('howto-panel'),
      ])
        .then(() => this._linkPanels());
    }

disconnectedCallback() 會移除 connectedCallback() 新增的事件監聽器。

    disconnectedCallback() {
      this.removeEventListener('keydown', this._onKeyDown);
      this.removeEventListener('click', this._onClick);
    }

每當元素從其中一個陰影 DOM 插槽新增或移除時，系統就會呼叫 _onSlotChange()。

    _onSlotChange() {
      this._linkPanels();
    }

_linkPanels() 會使用 aria-controls 和 aria-labelledby 將分頁連結至相鄰的面板。此外，這個方法可確保只有一個分頁處於啟用狀態。

    _linkPanels() {
      const tabs = this._allTabs();

為每個面板提供 aria-labelledby 屬性，以便參照控制該面板的分頁。

      tabs.forEach((tab) => {
        const panel = tab.nextElementSibling;
        if (panel.tagName.toLowerCase() !== 'howto-panel') {
          console.error(`Tab #${tab.id} is not a` +
            `sibling of a <howto-panel>`);
          return;
        }

        tab.setAttribute('aria-controls', panel.id);
        panel.setAttribute('aria-labelledby', tab.id);
      });

元素會檢查是否有任何分頁標籤已標示為已選取。如果不是，則會選取第一個分頁。

      const selectedTab =
        tabs.find((tab) => tab.selected) || tabs[0];

接著，切換至所選分頁。_selectTab() 會負責將所有其他分頁標示為取消選取，並隱藏所有其他面板。

      this._selectTab(selectedTab);
    }

_allPanels() 會傳回分頁面板中的所有面板。如果 DOM 查詢曾經發生效能問題，這個函式就能記住結果。記憶功能的缺點是，系統不會處理動態新增的分頁和面板。

這是方法，而非 getter，因為 getter 表示讀取的成本低廉。

    _allPanels() {
      return Array.from(this.querySelectorAll('howto-panel'));
    }

_allTabs() 會傳回分頁面板的所有分頁。

    _allTabs() {
      return Array.from(this.querySelectorAll('howto-tab'));
    }

_panelForTab() 會傳回指定分頁控制項的面板。

    _panelForTab(tab) {
      const panelId = tab.getAttribute('aria-controls');
      return this.querySelector(`#${panelId}`);
    }

_prevTab() 會傳回目前所選分頁之前的分頁，並在到達第一個分頁時循環。

    _prevTab() {
      const tabs = this._allTabs();

使用 findIndex() 找出目前所選元素的索引，減去一個，即可取得前一個元素的索引。

      let newIdx = tabs.findIndex((tab) => tab.selected) - 1;

新增 tabs.length 可確保索引為正數，並在必要時取得模數以便迴繞。

      return tabs[(newIdx + tabs.length) % tabs.length];
    }

_firstTab() 會傳回第一個分頁。

    _firstTab() {
      const tabs = this._allTabs();
      return tabs[0];
    }

_lastTab() 會傳回最後一個分頁。

    _lastTab() {
      const tabs = this._allTabs();
      return tabs[tabs.length - 1];
    }

_nextTab() 會取得目前選取的分頁，並在到達最後一個分頁時換行。

    _nextTab() {
      const tabs = this._allTabs();
      let newIdx = tabs.findIndex((tab) => tab.selected) + 1;
      return tabs[newIdx % tabs.length];
    }

reset() 會將所有分頁標示為未選取，並隱藏所有面板。

    reset() {
      const tabs = this._allTabs();
      const panels = this._allPanels();

      tabs.forEach((tab) => tab.selected = false);
      panels.forEach((panel) => panel.hidden = true);
    }

_selectTab() 會將指定的分頁標示為已選取。此外，它會將對應至指定分頁的面板取消隱藏。

    _selectTab(newTab) {

取消選取所有分頁並隱藏所有面板。

      this.reset();

取得 newTab 相關聯的面板。

      const newPanel = this._panelForTab(newTab);

如果該面板不存在，請中止。

      if (!newPanel)
        throw new Error(`No panel with id ${newPanelId}`);
      newTab.selected = true;
      newPanel.hidden = false;
      newTab.focus();
    }

_onKeyDown() 會處理分頁面板內的按鍵按下動作。

    _onKeyDown(event) {

如果按鍵並非來自分頁元素本身，表示按鍵是在面板內或空白處按下。無須採取任何行動。

      if (event.target.getAttribute('role') !== 'tab')
        return;

請勿處理輔助技術通常使用的修飾符捷徑。

      if (event.altKey)
        return;

切換方塊會根據按下的按鍵，決定應將哪個分頁標示為使用中。

      let newTab;
      switch (event.keyCode) {
        case KEYCODE.LEFT:
        case KEYCODE.UP:
          newTab = this._prevTab();
          break;

        case KEYCODE.RIGHT:
        case KEYCODE.DOWN:
          newTab = this._nextTab();
          break;

        case KEYCODE.HOME:
          newTab = this._firstTab();
          break;

        case KEYCODE.END:
          newTab = this._lastTab();
          break;

系統會忽略任何其他按鍵，並將按鍵動作傳回瀏覽器。

        default:
          return;
      }

瀏覽器可能會提供與方向鍵、Home 或 End 繫結的原生功能。元素會呼叫 preventDefault()，防止瀏覽器執行任何動作。

      event.preventDefault();

選取經過切換的情況下所決定的新分頁。

      this._selectTab(newTab);
    }

_onClick() 會處理分頁面板中的點擊事件。

    _onClick(event) {

如果點擊並非針對分頁元素本身，而是在面板內或空白處點選，無須採取任何行動。

      if (event.target.getAttribute('role') !== 'tab')
        return;

如果是分頁元素，請選取該分頁。

      this._selectTab(event.target);
    }
  }

  customElements.define('howto-tabs', HowtoTabs);

howtoTabCounter 會計算已建立的 <howto-tab> 執行個體數量。這組號碼會用來產生新的專屬 ID。

  let howtoTabCounter = 0;

HowtoTab 是 <howto-tabs> 分頁面板的分頁。在標記中，<howto-tab> 一律應搭配 role="heading" 使用，以便在 JavaScript 發生錯誤時，仍可使用語意。

<howto-tab> 會使用該面板的 ID 做為 aria-controls 屬性的值，宣告自己屬於哪個 <howto-panel>。

如果未指定 ID，<howto-tab> 會自動產生專屬 ID。

  class HowtoTab extends HTMLElement {

    static get observedAttributes() {
      return ['selected'];
    }

    constructor() {
      super();
    }

    connectedCallback() {

如果執行這項操作，JavaScript 就會運作，且元素的角色會變更為 tab。

      this.setAttribute('role', 'tab');
      if (!this.id)
        this.id = `howto-tab-generated-${howtoTabCounter++}`;

設定明確的初始狀態。

      this.setAttribute('aria-selected', 'false');
      this.setAttribute('tabindex', -1);
      this._upgradeProperty('selected');
    }

檢查屬性是否含有執行個體值。如果是，請複製該值，並刪除執行個體屬性，以免遮蔽類別屬性設定器。最後，將值傳遞至類別屬性 setter，以便觸發任何副作用。這項功能可避免發生下列情況：架構可能已將元素新增至網頁，並為其中一個屬性設定值，但延後載入定義。如果沒有這個防護機制，升級的元素就會遺漏該屬性，而例項屬性會防止類別屬性設定器永遠不會呼叫。

    _upgradeProperty(prop) {
      if (this.hasOwnProperty(prop)) {
        let value = this[prop];
        delete this[prop];
        this[prop] = value;
      }
    }

房源和對應的屬性應互相對應。為達到這個效果，selected 的屬性設定器會處理真值/假值，並將這些值反映至屬性的狀態。請特別注意，屬性 setter 中並未套用任何副作用。例如，setter 並未設定 aria-selected。相反地，這項工作會在 attributeChangedCallback 中執行。一般來說，請讓屬性設定器盡可能簡單，如果設定屬性或屬性會導致副作用 (例如設定對應的 ARIA 屬性)，請在 attributeChangedCallback() 中執行這項工作。這樣一來，您就無須管理複雜的屬性/資源重入情境。

    attributeChangedCallback() {
      const value = this.hasAttribute('selected');
      this.setAttribute('aria-selected', value);
      this.setAttribute('tabindex', value ? 0 : -1);
    }

    set selected(value) {
      value = Boolean(value);
      if (value)
        this.setAttribute('selected', '');
      else
        this.removeAttribute('selected');
    }

    get selected() {
      return this.hasAttribute('selected');
    }
  }

  customElements.define('howto-tab', HowtoTab);

  let howtoPanelCounter = 0;

HowtoPanel 是 <howto-tabs> 分頁面板的面板。

  class HowtoPanel extends HTMLElement {

    constructor() {
      super();
    }

    connectedCallback() {
      this.setAttribute('role', 'tabpanel');
      if (!this.id)
        this.id = `howto-panel-generated-${howtoPanelCounter++}`;
    }
  }

  customElements.define('howto-panel', HowtoPanel);
})();