Axe DevTools for WebのブラウザーJavaScript APIリファレンス

This page is not available in the language you requested. You have been redirected to the English version of the page.

Link to this page copied to clipboard

Axe DevTools for WebのブラウザーJavaScript APIとその使用方法について説明します

Not for use with personal data

はじめに

Axe DevTools APIは、前世代のアクセシビリティAPIを改良するように設計されています。それにより、次の利点が提供されます。

最新のブラウザどれでも動作する
既存のテストインフラストラクチャと連携するよう設計
ローカルで実行され、サードパーティのサーバーへの接続は不要
入れ子になった複数のレベルのiframeで違反チェックを実行
アクセシビリティチェックに合格したルールと要素の一覧を提供し、ドキュメント全体に対してルールが実行されたことを確認

開始方法

このセクションでは、ウェブページのコンテンツを分析し、見つかったアクセシビリティ違反を一覧としてJSONオブジェクトで返すためのAxe DevTools APIの使用方法について簡単に説明します。

Axe DevTools APIは、ウェブサイトの多くのページ、あるいはすべてのページで実行される広範なプロセスの一部として使用できます。APIは、ウェブページのコンテンツを分析し、発見されたアクセシビリティ違反を一覧としてJSONオブジェクトで返します。以下の方法で開始してください。

テストシステムでページをロード
必要に応じて、JavaScript APIの設定オプションを設定 (AxeDevTools.configure)
JavaScript APIを呼び出して分析 (AxeDevTools.run)
結果を確認するか、後で処理するために保存

APIリファレンス

概要

Axe DevToolsのAPIは、JavaScriptファイルaxe-devtools.jsで提供されます。これはテスト対象のウェブページに含まれている必要があります。パラメータはJavaScript関数のパラメータとして送信され、結果はJSON形式で返されます。

APIノート

ルールテストはサブテストで構成されており、各サブテストは「チェック」の配列で返されます。
結果オブジェクトの"helpUrl"は、より広範なアクセシビリティ問題の説明と推奨される解決策へのリンクです。これらのリンクはすべてDeque Universityのヘルプページを指しています。

`AxeDevTools.init`

note

このAPIは@axe-devtools/script-builderのような言語固有のバインディングでは利用できません。それらのバインディングは同じことを達成する独自のAPIを持っています。

目的

組み込みの標準ルールセットの1つを利用するためにAxe DevTools APIを初期化します。

説明

Axe DevToolsエンジンを初期化し、デフォルトのルールセットを上書きし、標準のルールサブセットの1つを有効にします。

note

AxeDevTools.configureまたはAxeDevTools.initのどちらかを使用する必要がありますが、両方は使わないでください。互いに上書きされます。

概要

AxeDevTools.init(ruleSetID);

パラメータ

ruleSetID - オプション ルールセットを識別する文字列。現在有効な値は次のとおりです。
- 508
- en301549
- rgaav4
- ttv5
- wcag2
- wcag21
- wcag22
- wcag2aaa
- wcag21aaa
- wcag22aaa

返り値: 未定義

`AxeDevTools.ruleSets`

note

目的

標準ルールセット定義の配列

説明

標準ルールセット定義配列への直接アクセスを提供します。この配列は次の構造を持つJavaScriptオブジェクトで構成されています。

{
  id: String identifier for the rule set,
  defn: Object containing the rule set definition
}

例1

WCAG 2 レベル A および AA のルールセット定義を見つけるために配列をフィルタリングする方法。

var rsets = AxeDevTools.ruleSets;
var wcag2 = rsets.filter(function (item) {
  return item.id === 'wcag2';
})[0].defn;

`AxeDevTools.getRules`

目的

システム内のすべてのルールに関する情報を得るため

説明

すべてのルールの ID と説明を含むリストを返します。

概要

AxeDevTools.getRules([Tag Name 1, Tag Name 2...]);

パラメータ

tags - オプション 返されるルールをフィルタリングするためのタグの配列。省略した場合、すべてのルールを返します。

返される値: 入力フィルタと一致するルールの配列。各エントリーは {ruleId: <id>, description: <desc>} の形式を持ちます。

現在サポートされているタグは以下の表に一覧されています。

タグ名	アクセシビリティ標準
wcag2a	WCAG 2.0 レベル A
wcag2aa	WCAG 2.0 レベル AA
wcag2aaa	WCAG 2.0 レベル AAA
wcag21a	WCAG 2.1 レベル A
wcag21aa	WCAG 2.1 レベル AA
wcag21aaa	WCAG 2.1 レベル AAA
wcag22a	WCAG 2.2 レベル A
wcag22aa	WCAG 2.2 レベル AA
wcag22aaa	WCAG 2.2 レベル AAA
section508	セクション 508
EN-301-549	EN 301 549
RGAAv4	RGAA バージョン 4
TTv5	Trusted Tester v5
best-practice	Deque によって推奨されるベストプラクティス

例 1

この例では、WCAG 2 A と AA タグを AxeDevTools.getRules に渡してそれらのルールのみを取得します。関数呼び出しは、ルールの配列を返します。

呼び出し: AxeDevTools.getRules(['wcag2aa', 'wcag2a']);

返されたデータ:

[
  { ruleId: "area-alt", description: "Checks the <area> elements of image…" },
  { ruleId: "aria-allowed-attr", description: "Checks all attributes that start…" },
  { ruleId: "aria-required-attr", description: "Checks all elements that contain…" },
  …
]

`AxeDevTools.configure`

目的

Axe DevTools によって使用されるデータ形式を設定するため。この設定は、新しいルールを追加する際に使用され、ライブラリに登録する必要があります。

説明

ユーザーは AxeDevTools.run のコールバックに渡される JSON 構造の形式を指定します。

概要

AxeDevTools.configure({
  branding: {
    brand: String,
    application: String
  },
  reporter: 'option',
  checks: [Object],
  rules: [Object]
});

パラメータ

configurationOptions - 有効な名前/値のペアが次のようになるオプションオブジェクト:
- branding - mixed（任意） helpUrlsのブランディングを設定するために使用します。
  - brand - string（任意）ブランド文字列を設定します--デフォルト: 「worldspace」
  - application - string（任意）アプリケーション文字列を設定します--デフォルト: 「AxeDevToolsAPI」
- reporter - AxeDevTools.run関数がコールバック関数に渡す出力フォーマットを設定するために使用します
  - v1 を使用して前のバージョンのフォーマットを使用: AxeDevTools.configure({ reporter: "v1" });
  - v2 を使用して現在のバージョンのフォーマットを使用: AxeDevTools.configure({ reporter: "v2" });
- checks - ルールで使用されるチェックのリストにチェックを追加したり、既存のチェックのプロパティを上書きするために使用します。
  - checks 属性はチェックオブジェクトの配列です。
  - 各チェックオブジェクトは、次の属性を含むことができます:
  - id - string（必須）。これはチェックを一意に識別します。チェックが既に存在する場合、提供された任意のチェックプロパティが上書きされます。新規の場合に必要 としてマークされている以下のプロパティは、チェックを上書きする際に任意です。
  - evaluate - function（新規の場合に必要）。これはチェックの機能を実装する関数です。
  - after - function（任意）。ページレベルで動作するチェックの結果を処理するために呼び出される関数です。
  - options - mixed（任意）。このoptionsオブジェクトはevaluate 関数に渡され、チェックを設定するために使用されることを目的としています。これは既存のチェックのために上書きされる最も一般的なプロパティです。
  - matches - string（任意）。このCSSセレクタ文字列は、evaluate 関数に渡されるノードをフィルタするものです。
  - enabled - boolean（任意、デフォルト true）。これはチェックがデフォルトでオンかオフかを示します。オフになっているチェックは、ルールに含まれていても評価されません。これを上書きすることは、複数のルールにわたって特定のチェックを無効にする一般的な方法です。
- rules - 既存のルールセットにルールを追加したり、既存のルールのプロパティを上書きするために使用します。rules 属性はrule オブジェクトの配列です。各ruleオブジェクトは、次の属性を含むことができます:
  - id - string（必須）。これはルールを一意に識別します。ルールが既に存在する場合、提供された属性で上書きされます。以下で必須としてマークされている属性は、新しいルールの場合のみ必要です。
  - selector - string（任意、デフォルト *）。評価のためにルールに渡される要素を識別するために使用されるCSSセレクタです。
  - excludeHidden - boolean（任意、デフォルト true）。非表示要素が評価のためにルールに渡されるかどうかを示します。
  - enabled - boolean（任意、デフォルト true）。ルールがオンになっているかどうかを示します（上書きのための一般的な属性です）。
  - pageLevel - boolean（任意、デフォルト false）。ページが完全なスコープのときにのみ動作するかどうかを示します。このようなルールの例としてスキップリンク ルールがあります。このプロパティを上書きすることは、実装が同時に変更されない限り推奨されません。
  - any - array（任意、デフォルト []）。すべてのチェックが合格しないと違反となるチェックのリストです。
  - all - array（任意、デフォルト []）。いずれかのチェックが失敗すると違反が発生するチェックのリストです。
  - none - array（任意、デフォルト []）。チェックがすべて合格しないと違反が発生するチェックのリストです。
  - tags - array（任意、デフォルト []）。分類ルールを分類するタグのリストです。実際には、有効なタグをいくつか指定しないと、デフォルトの評価ではルールが呼び出されません。標準（WCAG 2 と/またはセクション508）、WCAG 2 レベル、セクション508の段落、WCAG 2 成功基準を含めるのが慣例です。タグはすべての文字を小文字に変換し、スペースやピリオドを削除し、結果を連結して構成します。たとえば、WCAG 2 A の成功基準 1.1.1 は ["wcag2a", "wcag111"] になります。
  - matches - string（任意、デフォルト *）。これに一致しない要素を除外するCSSセレクタです。

戻り値: なし

`AxeDevTools.reset`

目的

構成をデフォルトの構成にリセットします。

説明

以前にAxeDevTools.configureまたはAxeDevTools.resetを呼び出した場合は、これを上書きし、構成をデフォルトの構成にリセットします。

note

これは、登録された新しいルールやチェックの登録をない解除せず、それ以外のすべての構成をデフォルトの構成にリセットします。

概要

AxeDevTools.reset();

パラメータ

なし

戻り値: 未定義

`AxeDevTools.run`

目的

現在読み込まれているページを分析します。

説明

提供されたHTMLページに対していくつかのルールを実行し、結果として生成された問題リストを返します。

概要

AxeDevTools.run(context, options, callback);

`AxeDevTools.run`のパラメータ

context: （オプション）解析の範囲を定義します。解析したいDOMの一部を指定します。通常はdocumentまたはクラス名、ID、セレクターなどの特定のセレクターになります。
options: （オプション）ルールやチェックに渡されるオプションのセットで、一時的にそれらを変更します。これはより永続的なAxeDevTools.configureとは対照的です。詳しくは上記を参照
callback: （オプション）最初のパラメータとしてnullまたはエラー結果を受け取り、解析が成功した場合は結果オブジェクト、失敗した場合はundefinedを受け取るコールバック関数。

`context` パラメータ

デフォルトでは、AxeDevTools.runはドキュメント全体をテストします。contextオブジェクトは、どの要素をテストするか、テストしないかを指定するオプションのパラメータです。以下のいずれかを渡すことができます：

解析が必要なドキュメントの部分を表す要素の参照
- 例：解析を<div id="content">要素に限定するには：document.getElementById("content")
document.querySelectorAllによって返されたようなNodeList。
解析する必要があるドキュメントの部分を選択するCSSセレクター。この中には以下が含まれます：
- クラス名としてのCSSセレクター（例：.classname）
- ノード名としてのCSSセレクター（例：div）
- 要素IDのCSSセレクター（例：#tag）
インクルード-エクスクルードオブジェクト（以下参照）

`include`および`exclude`オブジェクト

インクルード-エクスクルードオブジェクトは、2つの属性includeとexcludeを持つJSONオブジェクトです。includeまたはexcludeのどちらかが必要です。excludeのみが指定された場合、includeはdocument全体がデフォルトになります。

ノード、または
CSSセレクターの配列の配列

ほとんどの場合、配列には1つのCSSセレクターしか含まれません。複数のCSSセレクターが必要になるのは、ページ内の領域を含めたり除外したりするためにiframe（またはさらにその中のiframeなど）の中にある場合だけです。この場合、最初のn-1セレクターがiframeを選択し、n番目のセレクターがiframe内の領域を選択します。

`context` パラメータの例

$fixtureNodeList内の最初の項目を含めるが、その最初の子を除外する
```
{
  include: $fixture[0],
  exclude: $fixture[0].firstChild
}
```
IDがfixの要素を含めるが、その中のすべてのdivを除外する
```
{
  include: [['#fix']],
  exclude: [['#fix div']]
}
```
クラスexclude1またはexclude2を含む親を持つ構造を除いて、ドキュメント全体を含める
```
{
  exclude: [['.exclude1'], ['.exclude2']];
}
```

`options` パラメータ

optionsパラメータは、AxeDevTools.runがどのように動作するかを構成する柔軟な方法です。動作モードは以下の通りです：

アクセシビリティ標準に対応するすべてのルールを実行します。
指定されたルールのリストを除いて、システムに定義されているすべてのルールを実行します。
ルールIDのリストとして提供された特定のルールセットを実行します。

`options` パラメータの例

アクセシビリティ標準のためのルールのみを実行

一連のルールを選択するために使用できる特定の標準が定義されています。定義された標準とタグ文字列は以下の通りです：

タグ名	アクセシビリティ標準
wcag2a	WCAG 2.0 レベルA
wcag2aa	WCAG 2.0 レベルAA
wcag2aaa	WCAG 2.0 レベルAAA
wcag21a	WCAG 2.1 レベルA
wcag21aa	WCAG 2.1 レベルAA
wcag21aaa	WCAG 2.1 レベルAAA
wcag22a	WCAG 2.2 レベルA
wcag22aa	WCAG 2.2 レベルAA
wcag22aaa	WCAG 2.2 レベルAAA
section508	セクション508
EN-301-549	EN 301 549
TTv5	Trusted Tester v5
best-practice	Dequeにより推奨されるベストプラクティス

WCAG 2.0 レベルAのルールのみを実行するには、optionsとして指定します。

{
  runOnly: {
   type: "tag",
   values: ["wcag2a"]
  }
}

WCAG 2.0 レベルAとレベルAAの両方のルールを実行するには、wcag2aとwcag2aaの両方を指定する必要があります。

{
  runOnly: {
    type: "tag",
    values: ["wcag2a", "wcag2aa"]
  }
}

特定のルールのみを実行する

特定のルールのみを実行したい場合、オプションを次のように指定します。
```
{
  runOnly: {
    type: "rule",
    values: [ "ruleId1", "ruleId2", "ruleId3" ]
  }
}
```
この例では、ruleId1、ruleId2、ruleId3のIDを持つルールのみが実行されます。その他のルールは実行されません。
リスト以外のすべての有効なルールを実行する

AxeDevTools.runのデフォルトの操作は、WCAG 2.0 レベルAとレベルAAのすべてのルールを実行することです。実行を無効にするルールがあれば、optionsを次のように指定します。
```
{
  "rules": {
    "color-contrast": { enabled: false },
    "valid-lang": { enabled: false }
  }
}
```
この例では、color-contrastまたはvalid-langのIDを持つルールが無効になります。その他のすべてのルールは実行されます。有効なルールIDのリストは以下のセクションで指定されています。
タグとルール有効を用いた修正セットを実行する

修正セットは、タグを希望するtypeとrulesオプションを使用してrunOnlyを組み合わせることで定義できます。これにより、特定されていないタグのルールを含め、指定されたタグやタグを持つルールを除外することができます。
```
{
  runOnly: {
    type: "tag",
    values: ["wcag2a"]
  },
  "rules": {
    "color-contrast": { enabled: true },
    "valid-lang": { enabled: false }
  }
}
```
この例では、valid-lang以外のすべてのレベルAルールが含まれ、レベルAAの色コントラストルールも含まれます。
一部のタグのみを実行し、他のタグを除外する

runOnlyオプションは、includeとexcludeプロパティを持つオブジェクトを受け付けます。含まれるタグと一致するチェックのみが実行され、除外リストのタグと共有するものは除外されます。
```
{
  runOnly: {
    type: 'tags',
    value: {
      include: ['wcag2a', 'wcag2aa'],
      exclude: ['experimental']
    }
  }
}
```
この例では、まずすべてのwcag2aとwcag2aaルールが含まれます。experimentalとしてタグ付けされたすべてのルールが次に実行されるルールから削除されます。

`callback`パラメーター

callbackパラメーターは、非同期AxeDevTools.run関数が完了したときに呼び出される関数です。callback関数には2つのパラメーターが渡されます。最初のパラメーターは、AxeDevTools.runが完了できない場合にAxe DevTools内でスローされたエラーになります。Axe DevToolsが正しく完了した場合、最初のパラメータはnullとなり、2番目のパラメータは結果オブジェクトとなります。

Promiseを返す

コールバックが定義されていない場合、Axe DevToolsは代わりにプロミスを返します。ただし、Axe DevToolsはプロミスライブラリをポリフィルしません。そのため、プロミスをサポートしないシステムではこの機能は利用できません。Axe DevToolsを必要とするシステムがプロミスサポートをしているか不明な場合、AxeDevTools.runで提供されるコールバックを使用することをお勧めします。

`error`結果

これはnullまたはErrorのインスタンスであるオブジェクトのいずれかです。エラーを一貫して受け取る場合は、Deque Systemsにこの問題を報告してください。

`results`オブジェクト

AxeDevTools.a11yCheckの第3引数として渡されたコールバック関数は、resultsオブジェクトで実行されます。このオブジェクトには2つのコンポーネントがあります: passes配列とviolations配列です。passes配列はすべての合格したテストと各テストの詳細情報を追跡します。これにより、特に手動テストの場合に、どのテストが既に合格したかを簡単に判断できるため、テスト効率が向上します。同様に、violations配列はすべての失敗したテストと各テストの詳細情報を追跡します。

`url`

テストされたページのURL。

`timestamp`

分析が完了した日時。

`passes`と`violations`配列

description - ルールの内容を説明するテキスト文字列
help - 実行されたテストを説明するヘルプテキスト
helpUrl - 違反の詳細についての情報を提供するURL。Deque Universityのサイトへのリンクです。
id - ルールの一意識別子; ルール一覧を参照
impact - 違反の深刻度。失敗した場合は軽微、中程度、重大、致命的のいずれか、チェックが合格した場合はnullとなります。
tags - このルールに割り当てられたタグの配列。タグはoptionオブジェクトで使用され、実行するルールを選択します（オプションパラメータを参照）。
nodes - ルールによってテストされたすべての要素の配列
- html - 要素のHTMLスニペット
- impact - 違反の深刻度。テストが失敗した場合は軽微、中程度、重大、致命的のいずれか、チェックが成功した場合はnull。
- target - 各要素がiframeまたはフレームのレベルに対応するセレクタの配列。iframeまたはフレームが一つある場合、targetには二つのエントリがあります。iframeレベルが三つある場合、targetには四つのエントリがあります。
- any - 少なくとも一つが成功しているチェックの配列。配列内の各エントリには以下の情報が含まれます。
  - id - チェックの固有識別子。チェックIDはルールIDと同じ場合があります。
  - impact - チェックの深刻度。軽微、中程度、重大、致命的 のいずれかです。ルールの一部である各チェックは異なる影響を持つことがあります。すべての失敗したチェックの中で最も高い影響がルールに報告されます。
  - message - このチェックが成功または失敗した理由の説明。
  - data - チェックの種類に特有の追加のオプション情報。たとえば、色のコントラストチェックでは、前景色、背景色、コントラスト比などが含まれます。
  - relatedNodes - このチェックに関連する他のノードについての情報の任意の配列。たとえば、重複IDチェックの違反では、同じ重複IDを持つ他のセレクタがリストされます。配列内の各エントリには以下の情報が含まれます。
    - target - 関連ノードのセレクタの配列
    - html - 関連ノードのHTMLソース
- all - すべてが成功していなければならないチェックの配列。配列内の各エントリにはany配列と同じ情報が含まれます。
- none - すべてが成功していないべきなかったチェックの配列。配列内の各エントリにはany配列と同じ情報が含まれます。

例２

この例では、ドキュメント全体のセレクタを渡し、オプションを渡さず、すべての有効なルールが実行され、シンプルなコールバック関数が結果オブジェクト全体をコンソールログに記録します。

AxeDevTools.run(document, function (err, results) {
  if (err) throw err;
  console.log(results);
});

`passes` 配列

passes[0] ...
- help - "Elements must have sufficient color contrast"
- helpURL - "https://dequeuniversity.com/courses/html-css/visual-layout/color-contrast"
- id - "color-contrast"
  - nodes
  - target[0] - "#js_off-canvas-wrap > .inner-wrap >.kinja-title.proxima.js_kinja-title-desktop"
passes[1] ...

上記の例では、passes 配列にはテストされた2つのルールに対応する2つのエントリが含まれています。配列の最初の要素は色のコントラストチェックを記述します。help、helpUrl、id フィールドは、passes 配列のそれぞれのエントリに対して返されます。target 配列には、値が以下の1つの要素が含まれます。

#js_off-canvas-wrap > .inner-wrap >.kinja-title.proxima.js_kinja-title-desktop

target[0] によって選択された要素は、色のコントラストルールに対してチェックされ、成功しました。

通過した配列内の各次のエントリは同じ形式ですが、実行された異なるルールの詳細が記載されます。

`violations` 配列

violations[0]
- help - "<button> elements must have alternate text"
- helpURL - "https://dequeuniversity.com/courses/html-css/forms/form-labels#id84_example_button"
- id - "button-name"
  - nodes
  - target[0]
  - "post_5919997 > .row.content-wrapper > .column > span > iframe" * target[1]
  - "#u_0_1 > .pluginConnectButton > .pluginButtonImage > button"
violations[1] ...

violations 配列は、ボタンに有効な代替テキストがあるかどうかをチェックするテストに対応する1つのエントリを含んでいます（button-name ルール）。この配列の最初のエントリにはhelp、helpUrl、id フィールドがあります。

target 配列は、指定されたノードがiframe またはframe内にある場合のセレクタ指定方法を示しています。target 配列の最初の要素（target[0]）は、ボタンを含むiframeまでのセレクタを指定します。target 配列の2番目の要素（target[1]）は、target[0]で選択されたiframe内から始まる実際のボタンへのセレクタを指定します。

違反配列内の各次のエントリは同じ形式ですが、アクセシビリティ違反を生成したルールの詳細が記載されます。

例３

この例では、ドキュメント全体のセレクタを渡し、2つの追加のベストプラクティスルールを有効にし、シンプルなコールバック関数が結果オブジェクト全体をコンソールログに記録します。

AxeDevTools.run(
  document,
  {
    rules: {
      'heading-order': { enabled: true },
      'label-title-only': { enabled: true }
    }
  },
  function (err, results) {
    if (err) throw err;
    console.log(results);
  }
);

Axe DevTools for WebのブラウザーJavaScript APIリファレンス

はじめに

開始方法

APIリファレンス

概要

APIノート

AxeDevTools.init

目的

説明

概要

パラメータ

AxeDevTools.ruleSets

目的

説明

例1

AxeDevTools.getRules

目的

説明

概要

パラメータ

例 1

AxeDevTools.configure

目的

説明

概要

パラメータ

AxeDevTools.reset

目的

説明

概要

パラメータ

AxeDevTools.run

目的

説明

概要

AxeDevTools.runのパラメータ

context パラメータ

includeおよびexcludeオブジェクト

context パラメータの例

options パラメータ

options パラメータの例

callbackパラメーター

Promiseを返す

error結果

resultsオブジェクト

url

timestamp

passesとviolations配列

例２

passes 配列

violations 配列

例３

Is this page helpful?

Help us improve this page

Still need help?

`AxeDevTools.init`

`AxeDevTools.ruleSets`

`AxeDevTools.getRules`

`AxeDevTools.configure`

`AxeDevTools.reset`

`AxeDevTools.run`

`AxeDevTools.run`のパラメータ

`context` パラメータ

`include`および`exclude`オブジェクト

`context` パラメータの例

`options` パラメータ

`options` パラメータの例

`callback`パラメーター

`error`結果

`results`オブジェクト

`url`

`timestamp`

`passes`と`violations`配列

`passes` 配列

`violations` 配列