建置具有語意屬性的無障礙應用程式

發行項
05/14/2024

輔助功能的語意與建置體驗有關，這些體驗可讓您的應用程式包含於各種環境中使用技術的人員，並使用各種需求和體驗來接近您的UI。在許多情況下，輔助功能的法律需求可能會為開發人員解決輔助功能問題提供動力。無論如何，建議建置包容性和無障礙應用程式，讓您的應用程式達到最大的可能物件。

Web 內容輔助功能指導方針（WCAG）是 Web 和行動裝置的全球輔助功能標準和法律基準。這些指導方針說明各種方式，讓應用程式更容易察覺、可操作、可理解和健全。

許多使用者輔助功能需求都符合使用者或操作系統所提供的工具和設定所安裝的輔助技術產品。這包括螢幕助讀程式、螢幕放大和高對比度設定等功能。

螢幕助讀程式通常會提供畫面上顯示之控件的聽覺描述。這些描述可協助使用者瀏覽應用程式，並提供沒有輸入或文字之控件的參考，例如影像。螢幕助讀程式通常透過觸摸屏、軌跡板或鍵盤上的手勢來控制。如需啟用螢幕助讀程式的相關信息，請參閱啟用螢幕助讀程式。

操作系統有自己的螢幕助讀程式，具有自己的獨特行為和設定。例如，大部分螢幕助讀程式會在控件收到焦點時讀取與控件相關聯的文字，讓使用者在瀏覽應用程式時自行定位。不過，某些螢幕助讀程式也可以在頁面出現時讀取整個應用程式使用者介面，讓使用者在嘗試瀏覽頁面之前，先接收所有頁面的可用信息內容。

大部分螢幕助讀程式都會自動讀取接收協助工具焦點之控制項相關聯的任何文字。這表示使用者可以存取具有Text屬性集的控制項，例如 Label 或 Button。但由於 Image、ImageButton、ActivityIndicator 及其他元素沒有相關聯的文字，所以不會列在協助工具樹狀結構中。

.NET 多平臺應用程式 UI （.NET MAUI）支援兩種方法，以提供基礎平台輔助功能體驗的存取權。 語意屬性 是 .NET MAUI 方法，可用來在應用程式中提供輔助功能值，而且是建議的方法。 自動化屬性 是 Xamarin.Forms 在應用程式中提供輔助功能值的方法，而且已由語意屬性取代。在這兩種情況下，控件的默認輔助功能順序與 XAML 中列出或新增至版面配置的順序相同。不過，不同的版面配置可能會有影響輔助功能順序的其他因素。例如，的輔助功能順序 StackLayout 也會以其方向為基礎，而的輔助功能順序 Grid 則是根據其數據列和數據行排列。如需內容排序的詳細資訊，請參閱 Xamarin 部落格上的有意義內容排序。

注意

WebView當顯示可存取的網站時，它也會在 .NET MAUI 應用程式中存取。相反地，當顯示無法存取的網站時 WebView ，將無法在 .NET MAUI 應用程式中存取。

語意屬性

語意屬性可用來定義哪些控件應該接收輔助功能焦點的資訊，以及應該大聲朗讀哪些文字給使用者。語意屬性是附加屬性，可新增至任何元素以設定基礎平台輔助功能 API。

重要

語意屬性不會嘗試在每個平台上強制執行對等的行為。相反地，它們會依賴每個平臺所提供的輔助功能體驗。

類別 SemanticProperties 會定義下列附加屬性：

Description類型 string為，代表螢幕助讀程式將大聲朗讀的描述。如需詳細資訊，請參閱描述。
Hint型 string別為，類似於 Description，但會提供其他內容，例如控件的用途。如需詳細資訊，請參閱提示。
HeadingLevel型 SemanticHeadingLevel別為的，可讓項目標示為標題來組織 UI，並讓您更容易流覽。如需詳細資訊，請參閱標題層級。

這些附加屬性會設定平台輔助功能值，讓螢幕助讀程式可以談論元素。如需附加屬性的詳細資訊，請參閱附加屬性。

描述

Description附加屬性代表螢幕助讀程式用來宣告元素的簡短描述性string。此屬性應該針對具有了解內容或與使用者介面互動很重要的元素設定。設定這個屬性可以在 XAML 中完成：

<Image Source="dotnet_bot.png"
       SemanticProperties.Description="Cute dot net bot waving hi to you!" />

或者，它可以在 C# 中設定：

Image image = new Image { Source = "dotnet_bot.png" };
SemanticProperties.SetDescription(image, "Cute dot net bot waving hi to you!");

此外， SetValue 方法也可以用來設定 Description 附加屬性：

image.SetValue(SemanticProperties.DescriptionProperty, "Cute dot net bot waving hi to you!");

元素的輔助功能資訊也可以在另一個元素上定義。例如，Switch 旁的 Label可用來描述 Switch 代表什麼。執行下列工作即可用 XAML 來達成這點：

<Label x:Name="label"
       Text="Enable dark mode: " />
<Switch SemanticProperties.Description="{Binding Source={x:Reference label} Path=Text}" />

或者，可以在 C# 中設定，如下所示：

Label label = new Label
{
    Text = "Enable dark mode: "
};
Switch mySwitch = new Switch();
SemanticProperties.SetDescription(mySwitch, label.Text);

警告

避免在 Description 上 Label設定附加屬性。這會停止 Text 螢幕助讀程式所說的屬性。這是因為視覺文字應該與螢幕助讀程式大聲朗讀的文字相符。
避免在 Description 或 Editor Android上Entry設定附加屬性。這樣做會停止 Talkback 動作運作。請改用 Placeholder 屬性或 Hint 附加屬性。
在 iOS 上，如果您在具有子系的任何控件上設定 Description 屬性，螢幕助讀程式將無法連線到子系。這是因為 iOS 不提供可允許從父元素巡覽至子元素的輔助功能功能。

提示

Hint附加屬性代表，string提供附加屬性的其他內容Description，例如控件的用途。設定這個屬性可以在 XAML 中完成：

<Image Source="like.png"
       SemanticProperties.Description="Like"
       SemanticProperties.Hint="Like this post." />

或者，它可以在 C# 中設定：

Image image = new Image { Source = "like.png" };
SemanticProperties.SetDescription(image, "Like");
SemanticProperties.SetHint(image, "Like this post.");

此外， SetValue 方法也可以用來設定 Hint 附加屬性：

image.SetValue(SemanticProperties.HintProperty, "Like this post.");

在Android上，此屬性的行為會稍有不同，視其附加的控件而定。例如，對於沒有文字值的控件，例如 Switch 和 CheckBox，控件將會使用控件來顯示提示。不過，對於具有文字值的控件，不會顯示提示，而且會在文字值之後讀取。

警告

屬性 Hint 與 Entry.Placeholder Android 上的屬性衝突，這兩者都會對應至相同的平台屬性。因此，不建議將不同的 Hint 值設定為 Entry.Placeholder 值。

標題層級

HeadingLevel附加屬性可讓項目標示為標題來組織 UI，並讓您更容易流覽。某些螢幕助讀程式可讓用戶在標題之間快速跳躍。

標題具有從 1 到 9 的層級，並以列舉表示 SemanticHeadingLevel ，其會定義 None、和 Level1 透過 Level9 成員。

重要

雖然 Windows 提供 9 個層級的標題，但 Android 和 iOS 只提供單一標題。因此，在 Windows 上設定時 HeadingLevel ，它會對應至正確的標題層級。不過，在 Android 和 iOS 上設定時，它會對應至單一標題層級。

下列範例示範如何設定這個附加屬性：

<Label Text="Get started with .NET MAUI"
       SemanticProperties.HeadingLevel="Level1" />
<Label Text="Paragraphs of text go here." />
<Label Text="Installation"
       SemanticProperties.HeadingLevel="Level2" />
<Label Text="Paragraphs of text go here." />    
<Label Text="Build your first app"
       SemanticProperties.HeadingLevel="Level3" />
<Label Text="Paragraphs of text go here." />     
<Label Text="Publish your app"
       SemanticProperties.HeadingLevel="Level4" />
<Label Text="Paragraphs of text go here." />

或者，它可以在 C# 中設定：

Label label1 = new Label { Text = "Get started with .NET MAUI" };
Label label2 = new Label { Text = "Paragraphs of text go here." };
Label label3 = new Label { Text = "Installation" };
Label label4 = new Label { Text = "Paragraphs of text go here." };
Label label5 = new Label { Text = "Build your first app" };
Label label6 = new Label { Text = "Paragraphs of text go here." };
Label label7 = new Label { Text = "Publish your app" };
Label label8 = new Label { Text = "Paragraphs of text go here." };
SemanticProperties.SetHeadingLevel(label1, SemanticHeadingLevel.Level1);
SemanticProperties.SetHeadingLevel(label3, SemanticHeadingLevel.Level1);
SemanticProperties.SetHeadingLevel(label5, SemanticHeadingLevel.Level1);
SemanticProperties.SetHeadingLevel(label7, SemanticHeadingLevel.Level1);

此外， SetValue 方法也可以用來設定 HeadingLevel 附加屬性：

label1.SetValue(SemanticProperties.HeadingLevelProperty, SemanticHeadingLevel.Level1);

語意焦點

控件具有擴充 SetSemanticFocus 方法，可強制螢幕助讀程式焦點至指定的專案。例如，假設有名為 Label label的螢幕助讀程式焦點，可以使用下列程式代碼強制使用元素：

label.SetSemanticFocus();

.NET MAUI 提供 ISemanticScreenReader 介面，您可以指示螢幕助讀程式向使用者宣告文字。介面會透過 Default 屬性公開，而且可在命名空間中使用 Microsoft.Maui.Accessibility 。

若要指示螢幕助讀程式宣告文字，請使用 Announce 方法，傳遞 string 代表文字的自變數。下列範例示範如何使用此方法：

SemanticScreenReader.Default.Announce("This is the announcement text.");

限制

必須啟用預設平台螢幕助讀程式，才能大聲朗讀文字。

自動化屬性

自動化屬性是附加屬性，可新增至任何元素，以指出專案如何回報至基礎平台的輔助功能架構。

類別 AutomationProperties 會定義下列附加屬性：

ExcludedWithChildren型 bool?別為的，會判斷專案及其子系是否應該從輔助功能樹狀結構中排除。如需詳細資訊，請參閱 ExcludedWithChildren。
IsInAccessibleTree型 bool?別為的，表示專案是否可在輔助功能樹狀結構中使用。如需詳細資訊，請參閱 IsInAccessibleTree。
Name型 string別為的，表示專案的簡短描述，做為該專案的可讀標識碼。如需詳細資訊，請參閱名稱。
HelpText型 string別為的，代表元素的較長描述，可以視為與專案相關聯的工具提示文字。如需詳細資訊，請參閱 HelpText。
LabeledBy型 VisualElement別為的，可讓另一個專案定義目前項目的輔助功能資訊。如需詳細資訊，請參閱 LabeledBy。

這些附加屬性會設定平台輔助功能值，讓螢幕助讀程式可以談論元素。如需附加屬性的詳細資訊，請參閱附加屬性。

不同的螢幕助讀程式會讀取不同的輔助功能值。因此，使用自動化屬性時，建議在每個平臺上執行徹底的輔助功能測試，以確保獲得最佳體驗。

重要

自動化屬性是 Xamarin.Forms 在應用程式中提供輔助功能值的方法，而且已由語意屬性取代。如需語意屬性的詳細資訊，請參閱語意屬性。

ExcludedWithChildren

類型的ExcludedWithChildrenbool?附加屬性會判斷專案及其子系是否應該從輔助功能樹狀結構中排除。這可讓這類案例顯示在 AbsoluteLayout 另一個配置上，例如 StackLayout， StackLayout 且在看不到輔助功能樹狀結構時，會從輔助功能樹狀結構中排除。它可以從 XAML 使用，如下所示：

<StackLayout AutomationProperties.ExcludedWithChildren="true">
...
</StackLayout>

或者，可以在 C# 中設定，如下所示：

StackLayout stackLayout = new StackLayout();
...
AutomationProperties.SetExcludedWithChildren(stackLayout, true);

設定這個附加屬性時，.NET MAUI 會將 IsInAccessibleTree 指定專案及其子系上的附加屬性設定為 false 。

IsInAccessibleTree

警告

這個附加屬性通常應該保持未設定。大部分的控件應該存在於輔助功能樹狀結構中，而且 AutomationProperties.ExcludedWithChildren 附加屬性可以在元素及其子系需要從輔助功能樹狀結構中移除的情況下設定。

類型的IsInAccessibleTreebool?附加屬性會判斷螢幕助讀程式是否可以看到專案。它必須設定為 true ，才能使用其他自動化屬性。執行下列工作即可用 XAML 來達成這點：

<Entry AutomationProperties.IsInAccessibleTree="true" />

或者，可以在 C# 中設定，如下所示：

Entry entry = new Entry();
AutomationProperties.SetIsInAccessibleTree(entry, true);

警告

在 iOS 上 IsInAccessibleTree ，如果屬性位於 true 具有子系的任何控件上，螢幕助讀程式將無法連線到子系。這是因為 iOS 不提供可允許從父元素巡覽至子元素的輔助功能功能。

名稱

重要

附加 Name 屬性在 .NET 8 中已被取代。請改用 Description 附加屬性。

Name 附加屬性值應該是簡短的描述性文字字串，螢幕助讀程式會用它來宣告項目。對於了解內容或與使用者介面互動而言具有重要意義的項目，應該設定這個屬性。執行下列工作即可用 XAML 來達成這點：

<ActivityIndicator AutomationProperties.IsInAccessibleTree="true"
                   AutomationProperties.Name="Progress indicator" />

或者，可以在 C# 中設定，如下所示：

ActivityIndicator activityIndicator = new ActivityIndicator();
AutomationProperties.SetIsInAccessibleTree(activityIndicator, true);
AutomationProperties.SetName(activityIndicator, "Progress indicator");

HelpText

重要

附加 HelpText 屬性在 .NET 8 中已被取代。請改用 Hint 附加屬性。

HelpText 附加屬性應設為描述使用者介面項目的文字，且可以視為與項目建立關聯的工具提示文字。執行下列工作即可用 XAML 來達成這點：

<Button Text="Toggle ActivityIndicator"
        AutomationProperties.IsInAccessibleTree="true"
        AutomationProperties.HelpText="Tap to toggle the activity indicator" />

或者，可以在 C# 中設定，如下所示：

Button button = new Button { Text = "Toggle ActivityIndicator" };
AutomationProperties.SetIsInAccessibleTree(button, true);
AutomationProperties.SetHelpText(button, "Tap to toggle the activity indicator");

在某些平台上，對於編輯控制項，例如 Entry，HelpText 屬性可以有時省略並取代為預留位置文字。比方說，「輸入您的名稱」就是 Entry.Placeholder 屬性很好的候選，它會在使用者實際輸入之前將文字放在控制項中。

LabeledBy

重要

附加 LabeledBy 屬性在 .NET 8 中已被取代。請改用系 SemanticProperties.Description 結。如需詳細資訊，請參閱 SemanticProperties：Description。

LabeledBy 附加屬性可讓另一個項目定義目前項目的協助工具資訊。例如，Entry 旁的 Label可用來描述 Entry 代表什麼。執行下列工作即可用 XAML 來達成這點：

<Label x:Name="label" Text="Enter your name: " />
<Entry AutomationProperties.IsInAccessibleTree="true"
       AutomationProperties.LabeledBy="{x:Reference label}" />

或者，可以在 C# 中設定，如下所示：

Label label = new Label { Text = "Enter your name: " };
Entry entry = new Entry();
AutomationProperties.SetIsInAccessibleTree(entry, true);
AutomationProperties.SetLabeledBy(entry, label);

重要

AutomationProperties.LabeledByProperty iOS 不支援。

測試輔助功能

.NET MAUI 應用程式通常會以多個平台為目標，這表示根據平臺測試輔助功能功能。請瀏覽下列連結，了解如何測試每個平台上的協助工具：

下列工具可協助您進行輔助功能測試：

不過，這些工具都無法完美地模擬螢幕助讀程式用戶體驗，而測試及疑難解答應用程式的最佳方法一律會在具有螢幕助讀程式的實體裝置上手動進行疑難解答。

啟用螢幕助讀程式

每個平臺都有不同的預設螢幕助讀程式來朗讀輔助功能值：

Android 有 TalkBack。如需啟用 TalkBack 的資訊，請參閱啟用 TalkBack。
iOS 和 macOS 具有 VoiceOver。如需啟用 VoiceOver 的詳細資訊，請參閱啟用 VoiceOver。
Windows 有「朗讀程式」。如需啟用朗讀程式的詳細資訊，請參閱啟用朗讀程式。

啟用 TalkBack

TalkBack 是 Android 的主要螢幕助讀程式。其啟用方式取決於裝置製造商、Android 版本和 TalkBack 版本。不過，TalkBack 通常可透過裝置設定在您的 Android 裝置上啟用：

開啟設定 應用程式。
選取 [輔助功能>TalkBack]。
開啟 [使用 TalkBack ]。
選取 [確定]。

注意

雖然這些步驟適用於大部分的裝置，但您可能會遇到一些差異。

TalkBack 教學課程會在您第一次啟用 TalkBack 時自動開啟。

如需啟用 TalkBack 的替代方法，請參閱開啟或關閉交談。

啟用 VoiceOver

VoiceOver 是 iOS 和 macOS 上使用的主要螢幕助讀程式。在 iOS 上，可以啟用 VoiceOver，如下所示：

開啟設定 應用程式。
選取 [輔助功能 VoiceOver>]。
開啟 VoiceOver 。

啟用 VoiceOver 之後，您可以選取 VoiceOver 練習來開啟 VoiceOver 教學課程。

如需啟用 VoiceOver 的替代方法，請參閱開啟並練習 i 上的 VoiceOver 電話和在 iPad 上練習 VoiceOver。

在 macOS 上，可以啟用 VoiceOver，如下所示：

開啟 [ 系統喜好設定]。
選取 [輔助功能 VoiceOver>]。
選取 [ 啟用 VoiceOver]。
選取 [使用 VoiceOver]。

您可以選取 [開啟 VoiceOver 訓練...] 來開啟 VoiceOver 教學課程。

如需啟用 VoiceOver 的替代方法，請參閱在 Mac 上開啟或關閉 VoiceOver。

啟用朗讀程式

朗讀程式是 Windows 上使用的主要螢幕助讀程式。您可以一起按下 Windows 標誌鍵 + Ctrl + Enter 來啟用朗讀程式。您可以再次按下這些按鍵來停止朗讀程式。

如需朗讀程式的詳細資訊，請參閱朗讀程式的完整指南。

協助工具檢查清單

請遵循下列秘訣，以確保您的 .NET MAUI 應用程式可供盡可能廣泛的物件存取：

遵循 Web 內容輔助功能指導方針（WCAG），確保您的應用程式可感知、可操作、可理解且健全。 WCAG 是 Web 和行動裝置的全球輔助功能標準和法律基準。如需詳細資訊，請參閱 Web 內容輔助功能指導方針（WCAG）概觀。
請確定使用者介面是自我描述的。測試使用者介面的所有元素都是可存取螢幕助讀程式。視需要新增描述性文字和提示。
確定影像和圖示具有替代文字描述。
支援大型字型和高對比度。請避免硬式編碼控件維度，而是偏好重設大小以容納較大的字型大小的版面配置。以高對比度模式測試色彩配置，以確保其可讀取。
設計具有導覽考慮的可視化樹狀結構。使用適當的版面配置控件，讓使用替代輸入方法在控件之間巡覽會遵循與使用觸控相同的邏輯流程。此外，從螢幕助讀程式排除不必要的元素（例如，可存取字段的裝飾影像或標籤）。
不要單獨依賴音訊或色彩提示。避免在進度、完成或其他狀態的唯一指示是音效或色彩變更的情況。設計使用者介面以包含清楚的視覺提示、聲音和色彩僅供增強，或新增特定的輔助功能指標。選擇色彩時，請嘗試避免難以區分色彩盲的用戶調色盤。
提供視訊內容的標題，以及音訊內容的可讀取腳本。也有助於提供可調整音訊或視訊內容速度的控件，並確保音量和傳輸控件易於尋找和使用。
當應用程式支援多種語言時，將您的輔助功能描述當地語系化。
在應用程式目標的每個平台上測試其輔助功能功能。如需詳細資訊，請參閱測試輔助功能。

共用方式為

建置具有語意屬性的無障礙應用程式

語意屬性

描述

提示

標題層級

語意焦點

限制

自動化屬性

ExcludedWithChildren

IsInAccessibleTree

名稱

HelpText

LabeledBy

測試輔助功能

啟用螢幕助讀程式

啟用 TalkBack

啟用 VoiceOver

啟用朗讀程式

協助工具檢查清單

其他資源

共用方式為

建置具有語意屬性的無障礙應用程式

語意屬性

描述

提示

標題層級

語意焦點

語意螢幕助讀程式

限制

自動化屬性

ExcludedWithChildren

IsInAccessibleTree

名稱

HelpText

LabeledBy

測試輔助功能

啟用螢幕助讀程式

啟用 TalkBack

啟用 VoiceOver

啟用朗讀程式

協助工具檢查清單

其他資源