storybook-addon-a11y

這個 Storybook 擴充套件有助於讓你的 UI 元件更具無障礙性。

框架支援

開始使用

首先，安裝此擴充套件。

$ yarn add @storybook/addon-a11y --dev

將此行新增到你的 main.js 檔案 (如果需要，請在你的 Storybook 設定目錄中建立此檔案)。

export default {
  addons: ['@storybook/addon-a11y'],
};

這是一個測試擴充套件的範例 story 檔案

import React from 'react';

export default {
  title: 'button',
};

export const Accessible = () => <button>Accessible button</button>;

export const Inaccessible = () => (
  <button style={{ backgroundColor: 'red', color: 'darkRed' }}>Inaccessible button</button>
);

處理失敗的規則

當 Axe 在 stories 中報告無障礙性違規時，有多種方法可以根據您的需求處理這些失敗。

Story 層級覆寫

在 Story 層級，使用 parameters.a11y.config.rules 覆寫規則。

export const InputWithoutAutofill = () => <input type="text" autocomplete="nope" />;

InputWithoutAutofill.parameters = {
  a11y: {
    // Avoid doing this, as it will fully disable all accessibility checks for this story.
    disable: true,

    // Instead, override rules 👇
    // axe-core configurationOptions (https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#parameters-1)
    config: {
      rules: [
        {
          // You can exclude some elements from failing a specific rule:
          id: 'autocomplete-valid',
          selector: '*:not([autocomplete="nope"])',
        },
        {
          // You can also signify that a violation will need to be fixed in the future
          // by overriding the result of a rule to return "Needs Review"
          // rather than "Violation" if the rule fails:
          id: 'landmark-complementary-is-top-level',
          reviewOnFail: true,
        },
      ],
    },
  },
};

或者，您可以在 Story 中停用特定規則

export const Inaccessible = () => (
  <button style={{ backgroundColor: 'red', color: 'darkRed' }}>Inaccessible button</button>
);
Inaccessible.parameters = {
  a11y: {
    config: {
      rules: [{ id: 'color-contrast', enabled: false }],
    },
  },
};

提示：請在註解中清楚說明為何覆寫某個規則，這有助於您和您的團隊追溯為何某些違規未被報告或需要解決。例如

MyStory.parameters = {
  a11y: {
    config: {
      rules: [
        {
          // Allow `autocomplete="nope"` on form elements,
          // a workaround to disable autofill in Chrome.
          // @link https://bugs.chromium.org/p/chromium/issues/detail?id=468153
          id: 'autocomplete-valid',
          selector: '*:not([autocomplete="nope"])',
        },
        {
          // @fixme Color contrast of subdued text fails, as raised in issue #123.
          id: 'color-contrast',
          reviewOnFail: true,
        },
      ],
    },
  },
};

全域覆寫

當您想要忽略無障礙規則或變更其在所有 stories 中的設定時，請在您 Storybook 的 preview.ts 檔案中設定 parameters.a11y.config.rules。這對於忽略 Axe 常報告的誤判特別有用。

// .storybook/preview.ts

export const parameters = {
  a11y: {
    config: {
      rules: [
        {
          // This tells Axe to run the 'autocomplete-valid' rule on selectors
          // that match '*:not([autocomplete="nope"])' (all elements except [autocomplete="nope"]).
          // This is the safest way of ignoring a violation across all stories,
          // as Axe will only ignore very specific elements and keep reporting
          // violations on other elements of this rule.
          id: 'autocomplete-valid',
          selector: '*:not([autocomplete="nope"])',
        },
        {
          // To disable a rule across all stories, set `enabled` to `false`.
          // Use with caution: all violations of this rule will be ignored!
          id: 'autocomplete-valid',
          enabled: false,
        },
      ],
    },
  },
};

停用檢查

如果您希望完全停用部分 stories 的 a11y 檢查，您可以使用 story 參數控制此功能

export const MyNonCheckedStory = () => <SomeComponent />;
MyNonCheckedStory.parameters = {
  // Avoid doing this, as it fully disables all accessibility checks for this story,
  // and consider the techniques described above.
  a11y: { disable: true },
};

參數

若要進行更多客製化，請使用參數來設定 aXe 選項。 您也可以在 story 層級覆寫這些選項。

import React from 'react';
import { addDecorator, addParameters, storiesOf } from '@storybook/react';

export default {
  title: 'button',
  parameters: {
    a11y: {
      // optional selector which element to inspect
      element: '#storybook-root',
      // axe-core configurationOptions (https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#parameters-1)
      config: {},
      // axe-core optionsParameter (https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter)
      options: {},
      // optional flag to prevent the automatic check
      manual: true,
    },
  },
};

export const accessible = () => <button>Accessible button</button>;

export const inaccessible = () => (
  <button style={{ backgroundColor: 'red', color: 'darkRed' }}>Inaccessible button</button>
);

使用測試執行器自動化無障礙性測試

測試執行器預設不會套用您在 stories 中設定的任何規則。 您可以設定執行器以正確套用規則，方法是依照 Storybook 文件中的指南操作。

路線圖

• 使 UI 具備無障礙性
• 在 story 中顯示違規之處。
• 新增更多範例測試
• 新增測試
• 使 CI 整合成為可能