# Web 無障礙

> 關於 Web 無障礙的資訊



## 背景

Flutter 支援 Web 無障礙，方法是將其內部的 Semantics 樹轉譯為可供螢幕閱讀器理解的無障礙 HTML DOM 結構。
由於 Flutter 會在單一畫布上渲染其 UI，因此需要一個特殊的層來將 UI 的意義與結構暴露給網頁瀏覽器。


## 選擇性啟用 Web 無障礙

### 隱形按鈕

為了效能考量，Flutter 的 Web 無障礙功能預設是關閉的。
若要開啟無障礙功能，使用者需要按下帶有 `aria-label="Enable accessibility"` 的隱形按鈕。
按下此按鈕後，DOM 樹將會反映所有元件 (Widget) 的無障礙資訊。
在行動瀏覽器上的嵌入式或多 view 網頁應用程式中，Flutter 會將這個佔位按鈕限定在各個 Flutter view 範圍內，
因此不會阻擋周圍 HTML 頁面上的點擊。

### 以程式碼開啟無障礙模式

另一種方式是，在執行應用程式時加入以下程式碼，以開啟無障礙模式。

```dart
import 'package:flutter/semantics.dart';

void main() {
  runApp(const MyApp());
  if (kIsWeb) {
    SemanticsBinding.instance.ensureSemantics();
  }
}
```



## 使用語意角色提升無障礙性

### 什麼是語意角色（Semantic Roles）？

語意角色（Semantic Roles）定義了 UI 元件 (Widget) 的用途，協助螢幕閱讀器及其他輔助工具正確解讀並呈現你的應用程式給使用者。例如，一個角色可以指出某個元件是按鈕、連結、標題、滑桿，或是表格的一部分。

雖然 Flutter 的標準元件 (Widget) 通常會自動提供這些語意資訊，但如果自訂元件沒有明確定義角色，對於螢幕閱讀器使用者來說，可能會變得難以理解。


透過指派適當的角色，你可以確保：

* 螢幕閱讀器能正確宣告元素的類型與用途。
* 使用者能透過輔助科技更有效地瀏覽你的應用程式。
* 你的應用程式符合網頁無障礙標準，提升可用性。

### 在 Flutter for web 中使用 `SemanticsRole`

Flutter 提供了 [`Semantics` 元件（Widget）][`Semantics` widget] 搭配 [`SemanticsRole` 列舉（enum）][`SemanticsRole` enum]，讓開發者能為自己的元件 (Widget) 指派特定角色。當你的 Flutter web 應用程式被渲染 (render) 時，這些 Flutter 專屬的角色會被轉換為對應的 ARIA 角色，並反映在網頁的 HTML 結構中。

[`Semantics` widget]: https://api.flutter.dev/flutter/widgets/Semantics-class.html
[`SemanticsRole` enum]: https://api.flutter.dev/flutter/dart-ui/SemanticsRole.html

**1. 標準元件 (Widget) 自動帶有語意資訊**

:::version-note
針對 `Slider`、`RangeSlider` 與 `SemanticsRole.slider` 的增強版 `<input type="range" role="slider">` 語意、
具名路由的 `role="region"` landmark、角色更新與 `WidgetsApp.router` 對話框期間的 DOM 焦點保留，
以及以 `Escape` 鍵關閉 tooltip，皆需要 Flutter 3.50 或更新版本。
:::

許多標準 Flutter 元件（如 `TabBar`、`MenuAnchor`、`Slider`、`RangeSlider` 和 `Table`）
會自動包含語意資訊及其角色：

* **滑桿 (Sliders)**：`Slider` 與 `RangeSlider`（使用 `SemanticsFlag.isSlider`），
  以及使用 `SemanticsRole.slider` 的自訂元件，
  會渲染出可聚焦的 `<input type="range" role="slider">` 元素，
  並同步 `aria-label`、`aria-valuenow`、`aria-valuetext`，以及鍵盤方向鍵導覽。
* **Landmark 與選單**：設定 `scopesRoute: true`、`namesRoute: true`
  且 `label` 不為空的具名路由會輸出 `role="region"` landmark，
  而可捲動選單（`MenuAnchor`、`DropdownMenu`）會直接向螢幕閱讀器提供項目數量，
  不需要中間的 `group` 包裝層。

此外，Web engine 會在語意角色變更時保留 DOM 焦點且不觸發捲動，
在 `WidgetsApp.router` 應用程式中關閉對話框或 modal 路由時還原焦點，
並在使用者按下 `Escape` 時關閉可見的 `Tooltip` 元件。

建議盡可能優先使用這些標準元件，因為它們已經內建處理多項無障礙相關細節。

**2. 明確新增或覆寫角色**

針對自訂元件，或當預設語意資訊不足時，可以使用 `Semantics` 元件來定義角色：

以下是一個明確定義清單及其項目的範例：

```dart
import 'package:material_ui/material_ui.dart';
import 'package:flutter/semantics.dart';


class MyCustomListWidget extends StatelessWidget {
  const MyCustomListWidget({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // This example shows how to explicitly assign list and listitem roles
    // when building a custom list structure.
    return Semantics(
      role: SemanticsRole.list,
      explicitChildNodes: true,
      child: Column(
        children: <Widget>[
          Semantics(
            role: SemanticsRole.listItem,
            child: const Padding(
              padding: EdgeInsets.all(8.0),
              child: Text('Content of the first custom list item.'),
            ),
          ),
          Semantics(
            role: SemanticsRole.listItem,
            child: const Padding(
              padding: EdgeInsets.all(8.0),
              child: Text('Content of the second custom list item.'),
            ),
          ),
        ],
      ),
    );
  }
}
```

## 檢視區縮放與行動裝置文字輸入

:::version-note
預設 500% 雙指縮放（`maximum-scale=5.0`）
以及 iOS Safari 自動套用 16px 文字輸入字型大小，皆需要 Flutter 3.50 或更新版本。
:::

在全頁模式下，Flutter 預設會將頁面的
`<meta name="viewport" flt-viewport>` 標籤設為 `maximum-scale=5.0`，且不含 `user-scalable=no`。
這讓使用者可以雙指縮放至 500%，以符合 WCAG 2.1 AA 的文字縮放準則。

在 iOS Safari 上，Flutter 也會自動為其隱藏的語意 `<input>` 與 `<textarea>` 元素設定最小 `16px` 的字型大小，
避免使用者聚焦文字欄位時，瀏覽器出現非預期的自動縮放。

