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

2025-04-30

可及性語意關注於打造能讓您的應用程式具有包容性的使用體驗，這些體驗是面向在各種環境中使用技術的人士，他們以各種需求和經歷來接觸您的使用者介面。在許多情況下，輔助功能的法律需求可能會為開發人員解決輔助功能問題提供動力。無論如何，建議您建置具包容性和無障礙的應用程式，以便觸及最廣泛的受眾。

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

許多使用者的無障礙需求是透過使用者安裝的輔助技術產品，或由操作系統提供的工具和設定來滿足的。這包括螢幕助讀程式、螢幕放大和高對比度設定等功能。

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

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

大部分螢幕助讀程式都會自動讀取與接收輔助功能焦點之控件相關聯的任何文字。這表示使用者可以存取具有Label屬性集的控制項，例如 Button 或 Text。不過，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!");

元素的無障礙資訊也可以定義在另一個元素上。例如， Label 旁邊的 Switch 可用來描述所 Switch 代表的內容。這可以在 XAML 中完成，如下所示：

<Label x:Name="label"
       Text="Enable dark mode: " />
<Switch SemanticProperties.Description="{Binding x:DataType='Label', 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 屬性。這是因為視覺文字應該與螢幕助讀程式大聲朗讀的文字相符。
請避免在 Android 上的 Description 或 Entry 設定Editor附加屬性。這樣做會停止 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.Level2);
SemanticProperties.SetHeadingLevel(label5, SemanticHeadingLevel.Level3);
SemanticProperties.SetHeadingLevel(label7, SemanticHeadingLevel.Level4);

此外， 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 在應用程式中提供無障礙功能值的方法，已被語意屬性取代。如需語意屬性的詳細資訊，請參閱語意屬性。

排除帶子女者

類型為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 附加屬性可以在元素及其子系需要從輔助功能樹狀結構中移除的情況下設定。

名為IsInAccessibleTree的附加屬性，類型為bool?，決定元素是否能被螢幕助讀程式看到。它必須設定為 true ，才能使用其他自動化屬性。這可以在 XAML 中完成，如下所示：

<Entry AutomationProperties.IsInAccessibleTree="true" />

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

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

警告

在 iOS 上，若任何具子系的控件上設定了IsInAccessibleTree屬性，螢幕助讀程式將無法存取這些子系。這是因為 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附加屬性可讓另一個元素定義目前元素的輔助功能資訊。例如， Label 旁邊的 Entry 可用來描述所 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 和 Windows 應用程式的無障礙性洞見。
Android 應用程式的輔助功能掃描器。
適用於 iOS 和 macOS 應用程式的輔助功能偵測器。
適用於 Android 應用程式的 Android Studio 版面配置偵測器。
適用於 iOS 和 macOS 應用程式的 Xcode 檢視調試程式。

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

啟用螢幕助讀程式

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

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 的替代方法，請參閱在 iPhone 上開啟和練習 VoiceOver 和在 iPad 上練習 VoiceOver。

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

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

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

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

啟用朗讀程式

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

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

無障礙檢查清單

請遵循下列提示，以確保您的 .NET MAUI 應用程式能夠被盡可能廣泛的使用者使用：

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

共用方式為

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

語意屬性

說明

提示

標題層級

語意焦點

語意螢幕助讀程式

局限性

自動化屬性

排除帶子女者

IsInAccessibleTree

名稱

HelpText

LabeledBy

測試可及性

啟用螢幕助讀程式

啟用 TalkBack

啟用 VoiceOver

啟用朗讀程式

無障礙檢查清單

意見反應

其他資源