中的自動化屬性 Xamarin.Forms

Xamarin.Forms 允許使用 AutomationProperties 類別的附加屬性，在使用者介面元素上設定輔助功能值，進而設定原生輔助功能值。 本文說明如何使用 AutomationProperties 類別，讓螢幕助讀程式可以讀出頁面上的項目。

Xamarin.Forms 允許透過下列附加屬性，在使用者介面元素上設定自動化屬性：

• AutomationProperties.IsInAccessibleTree – 表示項目是否可供可存取的應用程式使用。 如需詳細資訊，請參閱 AutomationProperties.IsInAccessibleTree。
• AutomationProperties.Name – 作為項目可朗讀識別碼的項目簡短描述。 如需詳細資訊，請參閱 AutomationProperties.Name。
• AutomationProperties.HelpText – 項目的較長描述，可視為與項目建立關聯的工具提示文字。 如需詳細資訊，請參閱 AutomationProperties.HelpText。
• AutomationProperties.LabeledBy – 可讓另一個項目定義目前項目的協助工具資訊。 如需詳細資訊，請參閱 AutomationProperties.LabeledBy。

這些附加屬性會設定原生協助工具值，讓螢幕助讀程式可以讀出項目。 如需附加屬性的詳細資訊，請參閱附加屬性。

重要

使用 AutomationProperties，附加屬性可能會影響 Android 上的 UI 測試執行。 AutomationId、AutomationProperties.Name 和 AutomationProperties.HelpText 屬性，都會設定原生 ContentDescription 屬性，且 AutomationProperties.Name 和 AutomationProperties.HelpText 屬性值會優先於 AutomationId 值 (如果 AutomationProperties.Name 和 AutomationProperties.HelpText 都已設定的話，將會串連值)。 這表示尋找 AutomationId 的任何測試將會失敗，如果 AutomationProperties.Name 或 AutomationProperties.HelpText 也在項目上設定的話。 在此案例中，UI 測試應該更改為尋找 AutomationProperties.Name 或 AutomationProperties.HelpText 的值，或是兩者的串連。

每個平台都有不同的螢幕助讀程式，以敘述協助工具值：

• iOS 有 VoiceOver。 如需詳細資訊，請參閱 developer.apple.com 上的 Test Accessibility on Your Device with VoiceOver (使用 VoiceOver，在裝置上測試協助工具)。
• Android 有 TalkBack。 如需詳細資訊，請參閱 developer.android.com 上的 Testing Your App's Accessibility (測試應用程式協助工具)。
• Windows 有「朗讀程式」。 如需詳細資訊，請參閱使用朗讀程式來確認主應用程式案例。

不過，螢幕助讀程式的確切行為取決於軟體和其使用者組態。 例如，大部分的螢幕助讀程式獲得焦點時，會讀出與控制項建立關聯的文字，讓使用者能在頁面上控制項之間移動時定位自己。 某些螢幕助讀程式也會在頁面出現時讀出整個應用程式使用者介面，這可讓使用者能在嘗試巡覽頁面之前，就收到頁面的所有可用資訊內容。

螢幕助讀程式也會讀出不同的協助工具值。 在範例應用程式中：

• VoiceOver 會讀出 Entry 的 Placeholder 值，後面接著使用控制項的指示。
• TalkBack 會讀出 Entry 的 Placeholder 值、後面接著 AutomationProperties.HelpText 值，然後接著使用控制項的指示。
• 朗讀程式會讀出 Entry 的 AutomationProperties.LabeledBy 值，後面接著使用控制項的指示。

此外，朗讀程式會依序優先處理 AutomationProperties.Name、AutomationProperties.LabeledBy，然後處理 AutomationProperties.HelpText。 在 Android 上，TalkBack 可以結合 AutomationProperties.Name 和 AutomationProperties.HelpText 值。 因此，建議在每個平台上進行徹底的協助工具測試，以確保獲得最佳的體驗。

AutomationProperties.IsInAccessibleTree

AutomationProperties.IsInAccessibleTree 附加屬性是 boolean，它決定項目是否可供螢幕助讀程式存取，並因此可見。 它必須設定為 true 才能使用其他協助工具附加屬性。 執行下列工作即可用 XAML 來達成這點：

<Entry AutomationProperties.IsInAccessibleTree="true" />

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

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

注意

請注意，SetValue 方法也可用來設定 AutomationProperties.IsInAccessibleTree 附加屬性 – entry.SetValue(AutomationProperties.IsInAccessibleTreeProperty, true);

AutomationProperties.Name

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

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

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

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

注意

請注意，SetValue 方法也可用來設定 AutomationProperties.Name 附加屬性 – activityIndicator.SetValue(AutomationProperties.NameProperty, "Progress indicator");

AutomationProperties.HelpText

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

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

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

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

注意

請注意，SetValue 方法也可用來設定 AutomationProperties.HelpText 附加屬性 – button.SetValue(AutomationProperties.HelpTextProperty, "Tap to toggle the activity indicator");

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

AutomationProperties.LabeledBy

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

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

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

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

重要

AutomationProperties.LabeledByProperty iOS 尚不支援 。

注意

請注意，SetValue 方法也可用來設定 AutomationProperties.IsInAccessibleTree 附加屬性 – entry.SetValue(AutomationProperties.LabeledByProperty, nameLabel);

協助工具的複雜性

以下章節描述在特定控制項上，設定協助工具值的複雜性。

NavigationPage

若要在 Android 上，設定螢幕助讀程式為 NavigationPage 中動作列 [上一步] 箭頭朗讀的文字，請在 Page 上設定 AutomationProperties.Name 及 AutomationProperties.HelpText 屬性。 但請注意，這對 OS [上一步] 按鈕沒有任何效果。

FlyoutPage

若要在 iOS 和通用 Windows 平台上，設定螢幕助讀程式為 FlyoutPage 上 [切換] 按鈕朗讀的文字，請在 FlyoutPage 或是 Flyout 頁面的 IconImageSource 屬性上，設定 AutomationProperties.Name 或 AutomationProperties.HelpText 屬性。

若要在 Android 上，設定螢幕助讀程式為 FlyoutPage 上 [切換] 按鈕朗讀的文字，請將字串資源新增至 Android 專案：

<resources>
    <string name="app_name">Xamarin Forms Control Gallery</string>
    <string name="btnMDPAutomationID_open">Open Side Menu message</string>
    <string name="btnMDPAutomationID_close">Close Side Menu message</string>
</resources>

然後將 Flyout 頁面 IconImageSource 屬性的 AutomationId 屬性，設為適當的字串：

var flyout = new ContentPage { ... };
flyout.IconImageSource.AutomationId = "btnMDPAutomationID";

ToolbarItem

假如未定義 AutomationProperties.Name 或 AutomationProperties.HelpText 的值，那麼在 iOS、Android 及 UWP 上，螢幕助讀程式就會朗讀 ToolbarItem 執行個體的 Text 屬性值。

在 iOS 及 UWP 上，AutomationProperties.Name 屬性值會取代螢幕助讀程式所朗讀的 Text 屬性值。

在 Android 上，AutomationProperties.Name 及 (或) AutomationProperties.HelpText 屬性值會完全取代螢幕助讀程式可同時看到及朗讀的 Text 屬性值。 請注意，此為小於 26 的 API 之限制。

相關連結

• 附加屬性