カスタムオートメーションピア

[アーティクル]
06/02/2023

Microsoft UI オートメーションに対するオートメーションピアの概念について説明します。また、独自のカスタム UI クラスに対してオートメーションのサポートを提供する方法についても説明します。

UI オートメーションにより、オートメーションクライアントが多様な UI プラットフォームやフレームワークのユーザーインターフェイスを検証、または操作するときに利用できるフレームワークが提供されます。 Windows アプリを作成している場合は、UI に使用するクラスによって UI オートメーションサポートが既に提供されています。既にある非シールクラスから派生させて、新しい種類の UI コントロールやサポートクラスを定義することもできます。これを行う手順の間に、既定の UI オートメーションサポートでは対応していないがアクセシビリティサポートを必要とする動作が、クラスによって追加されることがあります。この場合、基本実装で使った AutomationPeer クラスから派生し、必要なサポートをピア実装に追加した後、Windows アプリコントロールのインフラストラクチャに、新しいピアを作成する必要があることを通知することによって、既存の UI オートメーションサポートを拡張する必要があります。

UI オートメーションにより、スクリーンリーダーなどのアクセシビリティアプリや支援技術だけでなく、品質保証 (テスト) コードも有効になります。いずれのシナリオについても、UI オートメーションクライアントでは、ユーザーインターフェイス要素を検証し、アプリの外部の他のコードからアプリに対するユーザー操作のシミュレーションを行うことができます。すべてのプラットフォームを対象とした UI オートメーション、およびその広範な意味については、「UI オートメーションの概要」をご覧ください。

UI オートメーションフレームワークは次の 2 種類のオーディエンスによって使われます。

UI オートメーション クライアント 現在ユーザーに表示されているすべての UI に関する情報を取得するために UI オートメーション API を呼び出します。たとえば、スクリーンリーダーなどの支援技術は UI オートメーションクライアントとして機能します。 UI は、関連するオートメーション要素のツリーとして提示されます。 UI オートメーションクライアントの関心の対象は、一度に 1 つのアプリに限定される場合もあれば、ツリー全体である場合もあります。 UI オートメーションクライアントは、UI オートメーション API を使ってツリーを操作して、オートメーション要素の情報を読み上げたり変更したりできます。
UI オートメーション プロバイダー アプリの一部として導入された UI の要素を公開する API を実装して、UI オートメーションツリーに情報を提供します。新しいコントロールを作るときには、UI オートメーションプロバイダーのシナリオの参加者としての役割を果たしてください。プロバイダーとして配慮する点は、アクセシビリティ目的とテスト目的の両方で、すべての UI オートメーションクライアントが UI オートメーションフレームワークを使ってコントロールを操作できるようにすることです。

UI オートメーションフレームワークには、通常、対応する 2 つの API があります。1 つは UI オートメーションクライアント用の API、もう 1 つは、似た名前を持つ UI オートメーションプロバイダー用の API です。このトピックでは主に、UI オートメーションプロバイダー用の API、特にこの UI フレームワークでプロバイダーの拡張性を可能にするクラスとインターフェイスについて説明します。全体像を示すために、UI オートメーションクライアント用の UI オートメーション API に触れる場合もあります。また、クライアントとプロバイダー API の相関関係を示す表も含まれています。クライアント側から見た説明については、「UI オートメーションクライアントのプログラマガイド」をご覧ください。

注意

UI オートメーションクライアントは通常、マネージコードを使用せず、UWP アプリ (一般にはデスクトップアプリ) としては実装されません。 UI オートメーションは、特定の実装またはフレームワークではなく、標準に基づいています。スクリーンリーダーなどの支援技術製品を含め、多くの既存の UI オートメーションクライアントは、コンポーネントオブジェクトモデル (COM) インターフェイスを使って UI オートメーション、システム、子ウィンドウで実行するアプリを操作します。 COM インターフェイスの情報と COM を使った UI オートメーションクライアントの作成方法について詳しくは、「UI オートメーションの基礎」をご覧ください。

カスタム UI クラスに対する UI オートメーションサポートの既存状態の特定

カスタムコントロールに対するオートメーションピアを実装する前にまず、基底クラスとそのオートメーションピアによって、必要なアクセシビリティやオートメーションのサポートが既に提供されているかどうかをテストする必要があります。多くの場合、FrameworkElementAutomationPeer の実装、特定のピア、および実装するパターンを組み合わせれば、基本的だが十分なアクセシビリティエクスペリエンスが確保されます。これが当てはまるかどうかは、コントロールと対応する基底クラスに対するオブジェクトモデルの公開に対し、どの程度変更を加えたかによって異なります。また、基底クラス機能に対する追加がテンプレートコントラクト中の新しい UI 要素、またはコントロールの外観のどちらに対応しているかにも依存します。状況によっては、それらの変更により、追加的なアクセシビリティサポートが必要になる新しい側面を伴うユーザーエクスペリエンスが導入される可能性があります。

既にある基本ピアクラスを使って基本的なアクセシビリティサポートを確保できる場合でも、自動テストのシナリオで UI オートメーションに正確な ClassName 情報を報告できるように、ピアを定義することをお勧めします。これは、第三者が使うコントロールを作る場合には特に重要になります。

オートメーションピアクラス

UWP は、Windows フォーム、Windows Presentation Foundation (WPF)、Microsoft Silverlight などの従来のマネージコードによる UI フレームワークで使われていた既存の UI オートメーションに伴う手法と慣例に基づいて構築されています。コントロールクラス、各関数、およびその用途の多くが、従来の UI フレームワークを起源としています。

規則上、ピアクラス名は、コントロールのクラス名で始まり、"AutomationPeer" で終わります。たとえば、ButtonAutomationPeer は、Button コントロールクラスのピアクラスです。

注意

ここでは、このトピックの目的に合わせて、アクセシビリティに関連するプロパティを、コントロールピアを実装するときの重要な要素として扱っています。 UI オートメーションサポートのより一般的な概念と、ピアを実装する際の推奨事項については、「UI オートメーションプロバイダーのプログラマガイド」と「UI オートメーションの基礎」をご覧ください。これらのトピックには、UWP フレームワークの情報を UI オートメーションに提供するために使う個々の AutomationPeer API の情報は含まれていませんが、クラスを識別したりその他の情報や対話式操作を提供したりするプロパティの情報が含まれています。

ピア、パターン、コントロール型

コントロールパターンは、コントロールの機能に関する特定の側面を UI オートメーションクライアントに公開するインターフェイス実装です。 UI オートメーションクライアントでは、コントロールパターンによって公開されたプロパティやメソッドを使って、コントロールの機能に関する情報を取得したり、実行時にコントロールの動作を操作したりします。

コントロールパターンは、コントロール型や外観に関係なく、コントロールの機能を分類したり公開したりするための手段です。たとえば、表形式のインターフェイスを表示するコントロールでは、Grid コントロールパターンを使って、表中の行と列の数を公開します。これにより UI オートメーションクライアント側では、表中の項目を取得できるようになります。ほかにもさまざまなコントロールパターンがあります。たとえば、Invoke コントロールパターンは、UI オートメーションクライアントでボタンなどの起動可能なコントロールに使います。また Scroll コントロールパターンは、リストボックス、リストビュー、コンボボックスなどのスクロールバーを含むコントロールに使います。各コントロールパターンは、それぞれ個別の機能に対応します。複数のコントロールパターンを組み合わせることにより、特定のコントロールでサポートする全体的な機能セットを記述することもできます。

コントロールパターンと UI の関係は、インターフェイスと COM オブジェクトの関係に似ています。 COM では、サポートしているインターフェイスをオブジェクトに問い合わせて、それらのインターフェイスを使って機能にアクセスできます。 UI オートメーションでは、UI オートメーションクライアントが UI オートメーション要素にどのコントロールパターンがサポートされているかを照会し、サポートされているコントロールパターンによって公開されるプロパティ、メソッド、イベント、構造体を使って、要素とそのピア対象のコントロールを操作できます。

オートメーションピアの主な目的の 1 つは、UI 要素がそのピアを通じてどのコントロールパターンをサポートできるのかを UI オートメーションクライアントに伝えることです。そのために、UI オートメーションプロバイダーは、GetPatternCore メソッドを上書きして GetPattern メソッドの動作を変更する新しいピアを実装しています。 UI オートメーションクライアントは、UI オートメーションプロバイダーを呼び出し元の GetPattern にマップする呼び出しを実行します。 UI オートメーションクライアントは、操作する個々の具体的なパターンを照会します。ピアでパターンがサポートされる場合は、パターンへのオブジェクト参照が返されます。サポートされない場合は、null が返されます。 null 以外が返された場合、UI オートメーションクライアントでは、そのコントロールパターンとやり取りするために、クライアントとしてパターンインターフェイスの API を呼び出すことができると想定します。

コントロール型は、ピアによって表されるコントロールの機能を広く定義する手段です。これはコントロールパターンとは異なる概念です。パターンでは、特定のインターフェイスを通じて取得できる情報や実行できる操作を UI オートメーションに通知しますが、コントロール型は、それよりも 1 つ上のレベルに位置するものです。各コントロール型には、UI オートメーションの次の側面に関するガイダンスが含まれています。

UI オートメーションコントロールパターン: コントロール型によっては、異なる分類の情報や操作を表す複数のパターンをサポートしている場合があります。各コントロール型には、そのコントロールでサポートする必要のあるコントロールパターンのセット、省略可能なセット、コントロールでサポートしてはいけないセットがあります。
UI オートメーションプロパティ値: 各コントロール型には、そのコントロールでサポートする必要のあるプロパティのセットがあります。これらは、「UI オートメーションプロパティの概要」で説明されている全般的なプロパティであり、パターン固有のプロパティではありません。
UI オートメーションイベント: 各コントロール型には、そのコントロールでサポートする必要のあるイベントのセットがあります。これらも、「UI オートメーションイベントの概要」で説明されている全般的なイベントであり、パターン固有のものではありません。
UI オートメーションツリー構造: 各コントロール型は、そのコントロールが UI コントロールツリー構造にどのように現れるかを定義します。

フレームワークのオートメーションピアの実装方法にかかわらず、UI オートメーションクライアントの機能は、UWP に縛られるものではありません。実際、支援技術などの既にある UI オートメーションクライアントでは、COM などの他のプログラミングモデルが使われていることがよくあります。 COM では、クライアントから QueryInterface を呼び出すことで、必要なパターンや、プロパティ、イベント、またはツリーの検査のための一般的な UI オートメーションフレームワークを実装する COM コントロールパターンインターフェイスを取得できます。パターンの場合は、そのインターフェイスコードが、UI オートメーションフレームワークにより、アプリの UI オートメーションプロバイダーとその関連ピアに対して実行されている UWP コードにマーシャリングされます。

C# または Microsoft Visual Basic を使った UWP アプリなど、マネージドコードフレームワークのコントロールパターンを実装すると、COM インターフェイスの表現ではなく、.NET Framework インターフェイスを使ってこれらのパターンを表すことができます。たとえば、Invoke というパターンの Microsoft .NET プロバイダーによる実装に対応した UI オートメーションパターンインターフェイスは、IInvokeProvider となります。

コントロールパターン、プロバイダーインターフェイス、それらの目的の一覧については、「コントロールパターンとインターフェイス」をご覧ください。コントロール型の一覧については、「UI オートメーションコントロール型の概要」を参照してください。

コントロールパターンの実装方法に関するガイダンス

コントロールパターンとその用途は、より広範囲にわたる UI オートメーションフレームワークの定義の一部であり、UWP アプリのアクセシビリティサポートに適用されるだけにとどまりません。コントロールパターンを実装するときは、これらのドキュメントに記載されているガイダンスに従って実装する必要があります。ガイダンスは UI オートメーション仕様にも含まれています。ガイダンスを確認する場合、通常は Microsoft ドキュメントを使うことができます。仕様を参照する必要はありません。各パターンのガイダンスは、「UI オートメーションコントロールパターンの実装」で説明されています。この分野の各トピックには、「実装のガイドラインと規則」と「必須メンバー」というセクションが含まれています。ガイダンスは、通常、「プロバイダー向けコントロールパターンインターフェイス」リファレンスにある関連するコントロールパターンインターフェイスの特定の API を参照しています。これらのインターフェイスはネイティブ/COM インターフェイスです (API では COM 形式の構文が使われます)。ただし、いずれも Windows.UI.Xaml.Automation.Provider 名前空間に同等のものが用意されています。

既定のオートメーションピアを使ってその動作を拡張している場合、それらのピアは、既に UI オートメーションガイドラインに準拠するように記述されています。それらのピアがコントロールパターンをサポートしている場合は、そのパターンサポートを使えば、「UI オートメーションコントロールパターンの実装」のガイダンスに従うことができます。コントロールピアが自身を UI オートメーションで定義されるコントロール型の表現として報告する場合、そのピアは「UI オートメーションコントロール型」のガイダンスに従っていることになります。

ただし、UI オートメーションの推奨事項に従ってピアを実装するためには、コントロールパターンやコントロール型に関する追加のガイダンスが必要になることもあります。これは特に、まだ UWP コントロールに既定の実装として含まれていないパターンやコントロール型のサポートを実装する場合に当てはまります。たとえば、既定の XAML コントロールには、いずれも注釈のパターンは実装されていません。しかし、注釈を広く利用するアプリを作っている場合は、この機能を表面に押し出してアクセスしやすくすると便利です。このようなシナリオでは、ピアで IAnnotationProvider を実装し、適切なプロパティを持つ Document コントロール型として自身を報告して、ドキュメントが注釈をサポートしていることを示します。

「UI オートメーションコントロールパターンの実装」で説明されているパターンに関するガイダンス、または「UI オートメーションコントロール型のサポート」で説明されているコントロール型に関するガイダンスを、方向性を示す全般的なガイダンスとして使うことをお勧めします。各 API の目的に関する説明や注意事項については、その API のリンク先をご覧ください。ただし、UWP アプリのプログラミングに必要な構文について詳しくは、Windows.UI.Xaml.Automation.Provider 名前空間にある同等の API を検索して、そのリファレンスページをご覧ください。

ビルトインオートメーションピアクラス

通常、UI 要素でユーザーからの UI アクティビティを受け入れる場合や、アプリの対話型の UI や意味のある UI を表す支援技術のユーザーが必要とする情報が要素の中に存在する場合は、要素によってオートメーションピアクラスを実装します。 UWP のすべてのビジュアル要素にオートメーションピアがあるわけではありません。オートメーションピアを実装するクラスの例として、Button や TextBox があります。一方、オートメーションピアを実装しないクラスの例として、Border のほか、Grid や Canvas など Panel ベースのクラスがあります。 Panel にはピアはありません。これは、ビジュアル専用のレイアウト動作が提供され、ユーザーが Panel とやり取りするためのアクセシビリティに関連する方法がないためです。代わりに、Panel に含まれる子要素はいずれも UI オートメーションツリーに対し、ピアまたは要素の表現が存在するツリー中で次に利用できる親の子要素として報告されます。

UI オートメーションと UWP のプロセス境界

UWP アプリにアクセスする UI オートメーションクライアントのコードは、通常はアウトプロセスで実行されます。 UI オートメーションフレームワークのインフラストラクチャを使うと、プロセス境界を越えて情報をやり取りできます。この概念について詳しくは、「UI オートメーションの基礎」をご覧ください。

OnCreateAutomationPeer

UIElement から派生されたクラスにはいずれも、保護された仮想メソッド OnCreateAutomationPeer が含まれます。オートメーションピアに対するオブジェクト初期化シーケンスでは、OnCreateAutomationPeer を呼び出すことにより、個々のコントロールに対するオートメーションピアオブジェクトを取得します。これにより、UI オートメーションツリーを構築して実行時に使うことができるようにします。 UI オートメーションコードでは、ピアを使ってコントロールの特性と機能に関する情報を取得し、そのコントロールパターンに基づいて対話型の使用方法をシミュレートできます。オートメーションをサポートするカスタムコントロールでは、OnCreateAutomationPeer を上書きし、AutomationPeer から派生するクラスのインスタンスを返す必要があります。たとえば、あるカスタムコントロールを ButtonBase クラスから派生させる場合、OnCreateAutomationPeer が返すオブジェクトは、ButtonBaseAutomationPeer から派生させる必要があります。

カスタムコントロールクラスを作成し、新しいオートメーションピアも指定する場合には、ピアの新しいインスタンスが返されるようにするために、カスタムコントロールに関して OnCreateAutomationPeer メソッドをオーバーライドする必要があります。ピアクラスは AutomationPeer から直接的または間接的に派生していることが必要です。

たとえば、次のコードでは、カスタムコントロール NumericUpDown により UI オートメーション用としてピア NumericUpDownPeer を使うことを宣言しています。

using Windows.UI.Xaml.Automation.Peers;
...
public class NumericUpDown : RangeBase {
    public NumericUpDown() {
    // other initialization; DefaultStyleKey etc.
    }
    ...
    protected override AutomationPeer OnCreateAutomationPeer()
    {
        return new NumericUpDownAutomationPeer(this);
    }
}

Public Class NumericUpDown
    Inherits RangeBase
    ' other initialization; DefaultStyleKey etc.
       Public Sub New()
       End Sub
       Protected Overrides Function OnCreateAutomationPeer() As AutomationPeer
              Return New NumericUpDownAutomationPeer(Me)
       End Function
End Class

// NumericUpDown.idl
namespace MyNamespace
{
    runtimeclass NumericUpDown : Windows.UI.Xaml.Controls.Primitives.RangeBase
    {
        NumericUpDown();
        Int32 MyProperty;
    }
}

// NumericUpDown.h
...
struct NumericUpDown : NumericUpDownT<NumericUpDown>
{
	...
    Windows::UI::Xaml::Automation::Peers::AutomationPeer OnCreateAutomationPeer()
    {
        return winrt::make<MyNamespace::implementation::NumericUpDownAutomationPeer>(*this);
    }
};

//.h
public ref class NumericUpDown sealed : Windows::UI::Xaml::Controls::Primitives::RangeBase
{
// other initialization not shown
protected:
    virtual AutomationPeer^ OnCreateAutomationPeer() override
    {
         return ref new NumericUpDownAutomationPeer(this);
    }
};

注意

OnCreateAutomationPeer の実装では、カスタムオートメーションピアの新しいインスタンスを初期化して呼び出し元のコントロールを所有者として渡し、そのインスタンスを返すだけにします。このメソッドで追加のロジックを実行しないでください。特に、AutomationPeer のデストラクションにつながる可能性のあるロジックが同じ呼び出し内にあると、ランタイムで予期しない動作が発生する場合があります。

OnCreateAutomationPeer の典型的な実装の場合、メソッドの上書きは、残りのコントロールクラス定義と同じスコープで行われるため、owner は、this または Me として指定されます。

実際のピアクラスは、コントロールと同じコードファイル、または別個のコードファイルで定義できます。ピア定義はいずれも、ピアを提供するコントロールとは別の Windows.UI.Xaml.Automation.Peers という名前空間に存在します。独自のピアも、OnCreateAutomationPeer メソッドの呼び出しに必要な名前空間を参照している限り、別個の名前空間に宣言できます。

正しいピアの基底クラスの選択

派生元となるコントロールクラスの既存のピアロジックに合致する基底クラスから AutomationPeer を派生させる必要があります。前の例の場合、RangeBase から派生しているためNumericUpDown、ピアを基にする RangeBaseAutomationPeer クラスを使用できます。コントロール自体の派生方法に最も合致するピアクラスを使うことにより、IRangeValueProvider は既に基本ピアクラスで実装されているため、少なくともその機能の一部は上書きせずに済みます。

基底クラス Control には、対応するピアクラスがありません。 Control から派生させたカスタムコントロールにピアクラスを対応させる場合は、FrameworkElementAutomationPeer からカスタムピアクラスを派生させます。

ContentControl からクラスを直接派生させる場合、そのクラスには、ピアクラスを参照する OnCreateAutomationPeer の実装がないため、既定のオートメーションピア動作は伴いません。したがって、OnCreateAutomationPeer を実装して独自のピアを使うか、FrameworkElementAutomationPeer をピアとして使います (コントロールにとってこのレベルのアクセシビリティサポートで十分である場合)。

注意

通常、FrameworkElementAutomationPeer ではなく AutomationPeer からは派生しません。 AutomationPeer から直接派生する場合、それ以外の場合に FrameworkElementAutomationPeer から得られる多くの基本的なアクセシビリティサポートを複製する必要があります。

カスタムピアクラスの初期化

オートメーションピアでは、基底クラスの初期化に所有者コントロールのインスタンスを使うタイプセーフなコンストラクターを定義する必要があります。次の例では、実装により owner の値が基本 RangeBaseAutomationPeer に渡されます。最終的に owner を使って FrameworkElementAutomationPeer.Owner を設定するのは FrameworkElementAutomationPeer です。

public NumericUpDownAutomationPeer(NumericUpDown owner): base(owner)
{}

Public Sub New(owner As NumericUpDown)
    MyBase.New(owner)
End Sub

// NumericUpDownAutomationPeer.idl
import "NumericUpDown.idl";
namespace MyNamespace
{
    runtimeclass NumericUpDownAutomationPeer : Windows.UI.Xaml.Automation.Peers.AutomationPeer
    {
        NumericUpDownAutomationPeer(NumericUpDown owner);
        Int32 MyProperty;
    }
}

// NumericUpDownAutomationPeer.h
...
struct NumericUpDownAutomationPeer : NumericUpDownAutomationPeerT<NumericUpDownAutomationPeer>
{
    ...
    NumericUpDownAutomationPeer(MyNamespace::NumericUpDown const& owner);
};

//.h
public ref class NumericUpDownAutomationPeer sealed :  Windows::UI::Xaml::Automation::Peers::RangeBaseAutomationPeer
//.cpp
public:    NumericUpDownAutomationPeer(NumericUpDown^ owner);

AutomationPeer のコアメソッド

UWP のインフラストラクチャ上の理由から、オートメーションピアの上書き可能メソッドは、次の 2 つのメソッドのペアで構成されます。UI オートメーションプロバイダーが UI オートメーションクライアントの転送ポイントとして使用するパブリックアクセスメソッドと、UWP クラスが動作に影響を与えるために上書きできる保護された "Core" カスタマイズメソッドの 2 つです。既定では、メソッドのペアは互いに結合されており、アクセスメソッドが呼び出されるたびに、対応するプロバイダーの実装を含む "Core" メソッドが (または、フォールバックとして基底クラスの既定の実装が) 呼び出されます。

カスタムコントロールのピアを実装するときは、そのカスタムコントロールに固有の動作を公開するオートメーションピア基底クラスから、すべての "Core" メソッドを上書きします。 UI オートメーションコードは、ピアクラスのパブリックメソッドを呼び出すことにより、コントロールに関する情報を取得します。コントロールに関する情報を提供するにあたり、コントロールの実装と設計によって作るアクセシビリティまたはその他の UI オートメーションのシナリオが、オートメーションピアの基底クラスによってサポートされているものとは異なる場合は、名前の末尾が "Core" というメソッドをすべて上書きする必要があります。

少なくとも、新規のピアクラスを定義するときは必ず、次の例に示すように、GetClassNameCore メソッドを実装します。

protected override string GetClassNameCore()
{
    return "NumericUpDown";
}

注意

文字列をメソッドの本文に直接格納する代わりに、定数として格納することもできます。 GetClassNameCore では、この文字列をローカライズする必要はありません。 UI オートメーションクライアントで、ClassName ではなくローカライズした文字列が必要とされる場合はいつも LocalizedControlType プロパティが使用されます。

GetAutomationControlType

一部の支援技術では、UI オートメーションツリー中の項目に関する特性を報告するときに、UI オートメーションの Name 以外の追加情報として、GetAutomationControlType の値を直接使っている場合があります。派生元のコントロールと大幅に異なるコントロールで、基本ピアクラスで報告されるものとは異なるコントロール型を報告する場合は、ピアを実装して GetAutomationControlTypeCore をオーバーライドする必要があります。 ItemsControl、ContentControl などの汎用の基底クラスを派生元として使う場合は、コントロール型に関する正確な情報が基本ピアから提供されないため、このことが特に重要になります。

GetAutomationControlTypeCore の実装で、AutomationControlType 値を返すことにより、コントロールを記述します。 AutomationControlType.Custom を返すこともできますが、コントロールのメインシナリオを正確に記述している場合は、より具体的なコントロールタイプのいずれかを返す必要があります。次に例を示します。

protected override AutomationControlType GetAutomationControlTypeCore()
{
    return AutomationControlType.Spinner;
}

注意

AutomationControlType.Custom を指定する場合以外は、GetLocalizedControlTypeCore を実装して LocalizedControlType プロパティ値をクライアントに提供する必要はありません。 AutomationControlType.Custom 以外のすべての AutomationControlType 値では、UI オートメーションの共通インフラストラクチャによって翻訳済みの文字列が提供されます。

GetPattern と GetPatternCore

GetPatternCore をピアで実装することにより、入力パラメーターで要求したパターンをサポートするオブジェクトが返されます。具体的には、UI オートメーションクライアントで、プロバイダーの GetPattern メソッドに転送されるメソッドを呼び出して、要求されたパターンを示す PatternInterface 列挙値を指定します。 GetPatternCore を上書きすると、指定されたパターンを実装するオブジェクトが返されます。ピアは、パターンのサポートを報告する対象である、対応するパターンインターフェイスを実装している必要があるため、そのオブジェクトはピア自身です。ピアにパターンのカスタム実装が含まれていないが、ピアの基本型にそのパターンが実装されていることがわかっている場合は、基本型の GetPatternCore の実装を GetPatternCore から呼び出すことができます。ピアでパターンがサポートされていない場合は、ピアの GetPatternCore で null を返す必要があります。ただし、通常は、独自の実装から直接 null を返すのではなく、基本実装の呼び出しを利用して null を返すようにします。

パターンがサポートされている場合、GetPatternCore 実装では this または Me を返すことができます。ここでは、GetPattern の戻り値が null 以外の場合は UI オートメーションクライアントが戻り値を要求されたパターンインターフェイスにキャストすることが前提とされています。

あるピアクラスが別のピアから継承された場合、必要なサポートとパターン報告がすべて基底クラスによって既に処理されていれば、GetPatternCore の実装は必要ありません。たとえば、RangeBase から派生させた範囲コントロールを実装する場合、ピアが RangeBaseAutomationPeer から派生されていれば、このピアは、PatternInterface.RangeValue に対して自身を返し、パターンをサポートする IRangeValueProvider インターフェイスの現行の実装を使います。

次の例は、実際のコードそのものではありませんが、RangeBaseAutomationPeer 中に既に存在している GetPatternCore の実装の概要を示しています。

protected override object GetPatternCore(PatternInterface patternInterface)
{
    if (patternInterface == PatternInterface.RangeValue)
    {
        return this;
    }
    return base.GetPattern(patternInterface);
}

ピアの実装時に、必要なすべてのサポートが基本ピアクラスから得られない場合、またはピアがサポートできる基本継承パターンのセットに変更や追加が必要な場合は、GetPatternCore を上書きして、UI オートメーションクライアントがパターンを使うことができるようにする必要があります。

UI オートメーションに対応した UWP 実装で利用可能なプロバイダーパターンの一覧については、「Windows.UI.Xaml.Automation.Provider」をご覧ください。このような個々のパターンにはそれぞれ、PatternInterface 列挙に対応する値があります。この値により、UI オートメーションクライアントが GetPattern の呼び出しでパターンを要求します。

ピアでは、複数のパターンをサポートしていることを伝えることができます。この場合、上書きのときに、サポートされる個々の PatternInterface 値に対するリターンパスロジックを指定して、一致するケースごとにペアが返されるようにする必要があります。このとき、呼び出し元では 1 回に 1 個ずつインターフェイスを要求すること、さらに予期されるインターフェイスへのキャストは呼び出し元が行うことが前提となります。

次にカスタムピアに対する GetPatternCore の上書きの例を示します。 IRangeValueProvider と IToggleProvider の 2 つのパターンに対するサポートが報告されます。このコントロールは、全画面表示として表示できるメディア表示コントロール (トグルモード) です。進行状況バーの表示位置は変更可能 (範囲コントロール) です。このコードは、XAML アクセシビリティサンプルの抜粋です。

protected override object GetPatternCore(PatternInterface patternInterface)
{
    if (patternInterface == PatternInterface.RangeValue)
    {
        return this;
    }
    else if (patternInterface == PatternInterface.Toggle)
    {
        return this;
    }
    return null;
}

子要素からのパターンの転送

GetPatternCore メソッドの実装では、ホストのパターンプロバイダーとして子要素や一部分を指定できます。この例は、ItemsControl が内部の ScrollViewer コントロールのピアに向けてスクロールパターン処理を転送する方法を模したものです。パターン処理の子要素を指定するために、このコードではまず子要素オブジェクトを取得して、FrameworkElementAutomationPeer.CreatePeerForElement メソッドにより子要素のピアを作り、新しいピアを返します。

protected override object GetPatternCore(PatternInterface patternInterface)
{
    if (patternInterface == PatternInterface.Scroll)
    {
        ItemsControl owner = (ItemsControl) base.Owner;
        UIElement itemsHost = owner.ItemsHost;
        ScrollViewer element = null;
        while (itemsHost != owner)
        {
            itemsHost = VisualTreeHelper.GetParent(itemsHost) as UIElement;
            element = itemsHost as ScrollViewer;
            if (element != null)
            {
                break;
            }
        }
        if (element != null)
        {
            AutomationPeer peer = FrameworkElementAutomationPeer.CreatePeerForElement(element);
            if ((peer != null) && (peer is IScrollProvider))
            {
                return (IScrollProvider) peer;
            }
        }
    }
    return base.GetPatternCore(patternInterface);
}

その他の Core メソッド

コントロールで、主要なシナリオに対してキーボードの同等機能のサポートが必要になる場合があります。これが必要になる理由について詳しくは、「キーボードのアクセシビリティ」をご覧ください。キーサポートの実装は、コントロールのロジックの一部であるため、ピアコードではなくコントロールコードの一部になりますが、ピアクラスでは、GetAcceleratorKeyCore と GetAccessKeyCore のメソッドを上書きすることにより、現在どのキーが使われているかを UI オートメーションクライアントに報告する必要があります。キーの情報を報告する文字列はローカライズされる可能性があるため、リソースから取得し、ハードコードした文字列は使いません。

コレクションをサポートするクラスのピアを提供する場合は、同じ種類のコレクションサポートが既に存在する機能クラスとピアクラスの両方から派生させるのが最もよい方法です。これができない場合は、子コレクションを維持しているコントロールのピアでコレクションに関連するピアメソッド、GetChildrenCore を上書きして、UI オートメーションツリーに親子の関係を正しく報告する必要があります。

IsContentElementCore メソッドと IsControlElementCore メソッドを実装して、コントロールにデータコンテンツが含まれているのか、またはユーザーインターフェイスで対話型の役割を果たすのか (あるいはその両方なのか) を指示します。既定では、両方のメソッドで true が返されます。これらの設定により、各メソッドを使ってオートメーションツリーをフィルターするスクリーンリーダーなどの支援技術の操作性が改善されます。 GetPatternCore メソッドで、子要素ピアにパターン処理を転送すると、子要素ピアの IsControlElementCore メソッドが、子要素ピアをオートメーションツリーから隠すために、false を返すことがあります。

コントロールの中には、テキストラベルの部分がテキスト以外の部分の情報を提供したり、コントロールと UI の別のコントロールとの間にラベル付けの関係が確立されたりする、ラベル付けのシナリオをサポートするものもあります。クラスベースの有用な動作を提供できる場合は、GetLabeledByCore をオーバーライドしてこの動作を提供できます。

GetBoundingRectangleCore と GetClickablePointCore は、主に自動テストのシナリオに使われます。コントロールの自動テストをサポートする場合は、これらのメソッドを上書きする必要があることがあります。範囲型のコントロールでは、座標空間でユーザーがクリックした場所によって範囲への効果が異なり、1 つのポイントのみを提案できないため、これが必要な場合があります。たとえば、既定の ScrollBar オートメーションピアは GetClickablePointCore を上書きして、"数字ではない" Point 値を返します。

GetLiveSettingCore は、UI オートメーションの LiveSetting 値のコントロール既定値に影響します。これをオーバーライドして、コントロールが AutomationLiveSetting.Off 以外の値を返すようにすることができます。 LiveSetting が何を表すかについて詳しくは、「AutomationProperties.LiveSetting」をご覧ください。

コントロールが、AutomationOrientation にマップできる設定可能な向きのプロパティを持っている場合は、GetOrientationCore を上書きできます。 ScrollBarAutomationPeer クラスと SliderAutomationPeer クラスがこれを行います。

FrameworkElementAutomationPeer の基本実装

FrameworkElementAutomationPeer の基本実装は、フレームワークレベルで定義されるレイアウトや動作のさまざまなプロパティから解釈できる UI オートメーションの情報を提供します。

GetBoundingRectangleCore: 既知のレイアウト特性に基づいて Rect 構造体を返します。 IsOffscreen が true の場合は、値が 0 の Rect を返します。
GetClickablePointCore: 既知のレイアウト特性に基づいて Point 構造体を返します (値が 0 でない BoundingRectangle がある場合)。
GetNameCore: このメソッドの動作は多岐にわたるため、ここでは紹介しきれません。詳しくは、「GetNameCore」をご覧ください。基本的には、ContentControl やコンテンツを持つ関連クラスの既知のコンテンツの文字列変換を試行します。また、LabeledBy の値がある場合は、その項目の Name の値が Name として使われます。
HasKeyboardFocusCore: 所有者の FocusState プロパティと IsEnabled プロパティに基づいて評価されます。コントロールではない要素は常に false を返します。
IsEnabledCore: 所有者の IsEnabled プロパティに基づいて評価されます (所有者が Control の場合)。コントロールではない要素は常に true を返します。これは、従来の対話式操作の意味で所有者が有効であることを示すのではなく、所有者に IsEnabled プロパティがなくてもピアは有効であることを示します。
IsKeyboardFocusableCore: 所有者が Control の場合は true、それ以外の場合は false を返します。
IsOffscreenCore: 所有者要素またはそのいずれかの親の Visibility が Collapsed の場合に IsOffscreen の値が true になります。 Popup オブジェクトは例外で、所有者の親が表示されていなくても表示される可能性があります。
SetFocusCore: Focus を呼び出します。
GetParent: 所有者から FrameworkElement.Parent を呼び出して適切なピアを検索します。これは、"Core" メソッドを含む上書きペアではないため、この動作を変更することはできません。

注意

UWP の既定のピアは、UWP を実装する内部のネイティブコードを使って動作を実装します。実際の UWP コードが使われるとは限りません。共通言語ランタイム (CLR) のリフレクションやその他の手法を使って実装のコードやロジックを見ることはできません。また、基本ピアの動作のサブクラス固有のオーバーライドに対応する個別のリファレンスページはありません。たとえば、TextBoxAutomationPeer の GetNameCore には、AutomationPeer.GetNameCore のリファレンスページでは説明されていない追加の動作がある可能性がありますが、TextBoxAutomationPeer.GetNameCore にはリファレンスページがありません。そもそも、TextBoxAutomationPeer.GetNameCore のリファレンスページは存在しません。代わりに、最も近いピアクラスのリファレンストピックを参照して、「注釈」セクションで実装の注釈を探してください。

ピアと AutomationProperties

オートメーションピアでは、コントロールのアクセシビリティに関連する情報に対して適切な既定値を提供する必要があります。コントロールを使うアプリコードでは、添付プロパティ AutomationProperties の値をコントロールインスタンスに取り込むことにより、その動作の一部をオーバーライドできます。呼び出し元では、既定コントロールまたはカスタムコントロールのいずれにも、この操作を行うことができます。たとえば、次の XAML では、カスタマイズした 2 つの UI オートメーションプロパティを使うボタンを作ります。<Button AutomationProperties.Name="Special" AutomationProperties.HelpText="This is a special button."/>

AutomationProperties 添付プロパティについて詳しくは、「基本的なアクセシビリティ情報」をご覧ください。

AutomationPeer メソッドの一部は、UI オートメーションプロバイダーがどのように情報を報告するかを定める一般的なコントラクトのために存在しています。ただし、通常これらのメソッドはコントロールピアでは実装されません。理由は、この情報が、特定の UI にあるコントロールを使ったアプリコードに適用する AutomationProperties 値から提供されることを前提としているためです。たとえば、大半のアプリでは、AutomationProperties.LabeledBy 値を適用することにより、UI 内の異なる 2 つのコントロール間でラベル付けの関係を定義します。ただし、コントロール中のデータや項目の関係を表す特定のピアでは LabeledByCore が実装されています。たとえば、ヘッダー部分を使ってデータフィールドの部分にラベルを付けたり、項目にコンテナーのラベルを付けたりする場合です。

パターンの実装

展開/折りたたみのコントロールパターンインターフェイスを実装することによって展開/折りたたみの動作を実装するコントロールに対するピアを作る方法を見てみます。ピアでは、PatternInterface.ExpandCollapse の値で GetPattern が呼び出されたら必ず自身を返して、展開/折りたたみの動作のアクセシビリティを有効にする必要があります。次に、そのパターンに対するプロバイダーインターフェイスを継承 (IExpandCollapseProvider) して、そのプロバイダーインターフェイスの各メンバーに対し実装を提供する必要があります。この例の場合、インターフェイスで次の 3 つのメンバーを上書きします。Expand、Collapse、ExpandCollapseState。

クラスの API 設計自体にアクセシビリティについて事前に考慮しておくと効果的です。 UI を使って作業をするユーザーとの典型的な対話式操作、またはオートメーションプロバイダーパターンのどちらかを介して要求する動作が想定される場合は必ず、UI の応答、またはオートメーションパターンのどちらからでも呼び出し可能な単一のメソッドを用意しておきます。たとえば、コントロールに、展開/折りたたみ可能なイベントハンドラーを結合したボタン部分と、各操作に対応するキーボードの同等機能を持たせる場合は、ピア中で使う IExpandCollapseProvider の Expand または Collapse の実装本体から呼び出すのと同じメソッドを、個々のイベントハンドラーから呼び出す必要があります。共通のロジックメソッドを使うことにより、コントロールの表示状態が更新されるため、動作の起動方法に依存することなく、ロジックの状態が一貫した方法で表示されるようになります。

典型的な実装として、まずプロバイダー API から実行時にコントロールインスタンスにアクセスするために Owner を呼び出し、次にこのオブジェクトに対して必要な動作メソッドを呼び出すという方法が考えられます。

public class IndexCardAutomationPeer : FrameworkElementAutomationPeer, IExpandCollapseProvider {
    private IndexCard ownerIndexCard;
    public IndexCardAutomationPeer(IndexCard owner) : base(owner)
    {
         ownerIndexCard = owner;
    }
}

別の実装は、コントロール自体がピアを参照する方法です。 RaiseAutomationEvent メソッドがピアメソッドであるため、これはコントロールからオートメーションイベントを生成する場合の一般的なパターンです。

UI オートメーションのイベント

UI オートメーションのイベントは、次のカテゴリに分類されます。

Event	説明
プロパティの変更	UI オートメーション要素またはコントロールパターンのプロパティが変更されたときに発生します。たとえば、クライアントでアプリのチェックボックスコントロールを監視する必要がある場合は、ToggleState プロパティのプロパティ変更イベントをリッスンするように登録します。チェックボックスコントロールがオンまたはオフになると、プロバイダーがこのイベントを発生させるため、クライアントで必要に応じて対処できます。
要素のアクション	ユーザーまたはプログラムによる操作の結果として UI が変更された場合に発生します (ボタンがクリックされた場合、Invoke パターンによって呼び出された場合など)。
構造の変更	UI オートメーションツリーの構造が変更された場合に発生します。構造は、新しい UI 項目が表示された場合、非表示になった場合、またはデスクトップから削除された場合に変更されます。
グローバルな変更	クライアントのグローバルな関心の対象となる操作が行われた場合に発生します (要素のフォーカスが別の要素に移動した場合、子ウィンドウが閉じられた場合など)。イベントによっては、必ずしも UI の状態が変更されたことを意味しません。たとえば、ユーザーが Tab キーを押してテキスト入力フィールドに移動し、ボタンをクリックしてフィールドを更新した場合、TextChanged イベントが発生しますが、実際にはテキストは変更されていません。イベントを処理する際、クライアントアプリケーションがアクションを起こす前に、実際に変更が行われたかどうかのチェックが必要となる場合があります。

AutomationEvents の識別子

UI オートメーションのイベントは、AutomationEvents の値によって識別されます。この列挙体の値は、イベントの種類を一意に識別します。

イベントの発生

UI オートメーションクライアントでは、オートメーションイベントを受信登録することができます。オートメーションピアモデルの場合、カスタムコントロールのピアでは RaiseAutomationEvent メソッドを呼び出すことによって、アクセシビリティに関連するコントロール状態に生じた変化を報告しなければなりません。同様に、キー UI オートメーションプロパティ値に変更があった場合は、カスタムコントロールピアから、RaisePropertyChangedEvent メソッドを呼び出す必要があります。

次のコード例は、コントロール定義コードの内部からピアオブジェクトを取得し、そのピアからイベントを発生させるメソッドを呼び出す方法を示しています。最適化のために、コードではこのイベントタイプのリスナーがいるかどうかを確認します。リスナーがいるときにのみイベントを発生させてピアオブジェクトを作ることにより、不要なオーバーヘッドがなくなり、コントロールが応答性を維持できるようになります。

if (AutomationPeer.ListenerExists(AutomationEvents.PropertyChanged))
{
    NumericUpDownAutomationPeer peer =
        FrameworkElementAutomationPeer.FromElement(nudCtrl) as NumericUpDownAutomationPeer;
    if (peer != null)
    {
        peer.RaisePropertyChangedEvent(
            RangeValuePatternIdentifiers.ValueProperty,
            (double)oldValue,
            (double)newValue);
    }
}

オートメーションピアが特定された後、UI オートメーションクライアントではピアオブジェクトの GetChildren と GetParent のメソッドを呼び出すことにより、アプリのピア構造をナビゲートすることができます。コントロール内部での UI 要素間のナビゲーションは、GetChildrenCore メソッドをピアで実装することにより、サポートされます。 UI オートメーションシステムでは、このメソッドを呼び出して、コントロールに含まれる子要素 (たとえば、リストボックス中のリスト項目) のツリーを構築します。 FrameworkElementAutomationPeer に含まれる既定の GetChildrenCore メソッドでは、要素のビジュアルツリーを走査してオートメーションピアのツリーを構築します。カスタムコントロールでは、このメソッドを上書きして、子要素を表す別の表示をオートメーションクライアントに公開することにより、情報の伝達やユーザー操作の許可を行う各要素のオートメーションピアを返すことができます。

テキストパターンのネイティブオートメーションサポート

既定の UWP アプリのオートメーションピアの一部は、テキストパターンに対するコントロールパターンのサポートを提供します (PatternInterface.Text)。ただし、このサポートはネイティブな方法で提供され、関係するピアは (管理された) 継承の ITextProvider インターフェイスに注目しません。それでも、管理されている、または管理されていない UI オートメーションクライアントがピアでパターンを照会すると、テキストパターンに対するサポートが報告され、クライアント API が呼び出されたときにパターンの一部の動作が提供されます。

UWP アプリのテキストコントロールの 1 つから派生させ、テキスト関連ピアの 1 つから派生するカスタムピアを作る場合は、ピアの「注釈」セクションをご覧になることで、パターンのネイティブレベルサポートについて詳しく知ることができます。管理されているプロバイダーインターフェイスの実装から基本実装を呼び出すと、カスタムピアのネイティブベースの動作にアクセスできますが、ピアのネイティブインターフェイスとその所有者のコントロールは両方とも公開されるため、基本実装で行われる動作を変更するのは困難です。一般的に、基本実装をそのまま使うか (基本実装のみを呼び出す)、基本実装を呼び出さないで機能を独自のマネージコードで完全に置き換えます。後者は高度なシナリオであり、コントロールでテキストサービスフレームワークを使う場合は、アクセシビリティ要件をサポートするためにフレームワークに関する詳しい知識が必要となります。

AutomationProperties.AccessibilityView

カスタムピアの提供に加えて、XAML で AutomationProperties.AccessibilityView を設定することにより、コントロールインスタンスのツリービュー表現を調整することもできます。これはピアクラスの一部としては実装されませんが、カスタムコントロールまたはカスタマイズしたテンプレートでの全体的なアクセシビリティのサポートに密接な関係があるため、ここで触れておきます。

AutomationProperties.AccessibilityView を使う主なシナリオでは、コントロール全体のアクセシビリティビューに対して有意に貢献しないので、UI オートメーションビューから意図的にテンプレート内の特定のコントロールを省略します。これを避けるために、AutomationProperties.AccessibilityView を "Raw" に設定します。

オートメーションピアからの例外のスロー

オートメーションピアサポートのために実装する API では、例外をスローすることが許されています。リッスンしている UI オートメーションクライアントはいずれも堅牢に作られていると想定され、例外がスローされても、ほとんどの場合は続行できることが求められています。リスナーが対象としているのは自分自身だけでなく他のアプリを含めたオートメーションツリー全体であり、クライアントが API を呼び出したときにツリーの一部でピアベースの例外がスローされたからといって、クライアント全体が停止するような設計は望ましくありません。

ピアに渡されたパラメーターについて入力を検証することは許容されます。たとえば、null が渡された場合、それを有効な値として扱わない実装では ArgumentNullException をスローすることができます。ただし、ピアで実行される後続の操作がある場合、ホストしているコントロールとピアとのやり取りには非同期的な性質があることに注意が必要です。ピアで実行した操作によって、必ずしもコントロールの UI スレッドがブロックされるとは限りません (そのような動作になることはほとんどありません)。したがって、ピアの作成時やオートメーションピアメソッドの初回の呼び出し時に、あるオブジェクトが使用可能であったり、特定のプロパティが設定されていたりしても、処理を行っている間にコントロールの状態が変わる可能性があります。このような場合にスローできる専用の例外が 2 つあります。

自身の API に渡された元の情報に基づいてピアの所有者または関連するピア要素にアクセスできない場合は、ElementNotAvailableException をスローします。たとえば、ピアでメソッドを実行しようとしているときに、モーダルダイアログが閉じられたなどの理由で、UI から所有者が削除された場合が当てはまります。 .NET 以外のクライアントでは、これは UIA_E_ELEMENTNOTAVAILABLE にマップされます。
所有者はまだ存在するものの、その所有者が IsEnabled=false などのモードになっていて、ピアで実行しようとしている特定の変更をプログラムで実現することができない場合は、ElementNotEnabledException をスローします。 .NET 以外のクライアントでは、これは UIA_E_ELEMENTNOTENABLED にマップされます。

他にも、ピアサポートからの例外のスローに関して、ピアでは比較的保守的な対応をとる必要があります。ほとんどのクライアントでは、ピアからの例外を処理することができないため、発生した例外は、ユーザーに選択を求める対話操作に変換されます。このため、ピアでの操作が失敗するたびに例外をスローするよりは、ピアの実装内で例外をキャッチし、再スローもせずに何もしない戦略の方が適している場合があります。また、多くの UI オートメーションクライアントはマネージコードで作られているわけではない点にも考慮する必要があります。ほとんどは COM で記述されているため、最終的にピアにアクセスする UI オートメーションクライアントメソッドを呼び出すときは、HRESULT が S_OK かどうかをチェックするだけになります。

カスタムオートメーションピア

カスタム UI クラスに対する UI オートメーションサポートの既存状態の特定

オートメーションピアクラス

ピア、パターン、コントロール型

コントロールパターンの実装方法に関するガイダンス

ビルトインオートメーションピアクラス

UI オートメーションと UWP のプロセス境界

OnCreateAutomationPeer

正しいピアの基底クラスの選択

カスタムピアクラスの初期化

AutomationPeer のコアメソッド

GetAutomationControlType

GetPattern と GetPatternCore

子要素からのパターンの転送

その他の Core メソッド

FrameworkElementAutomationPeer の基本実装

ピアと AutomationProperties

パターンの実装

UI オートメーションのイベント

AutomationEvents の識別子

イベントの発生

ピアのナビゲーション

テキストパターンのネイティブオートメーションサポート

AutomationProperties.AccessibilityView

オートメーションピアからの例外のスロー

フィードバック

その他のリソース

カスタム オートメーション ピア

カスタム UI クラスに対する UI オートメーション サポートの既存状態の特定

オートメーション ピア クラス

ピア、パターン、コントロール型

コントロール パターンの実装方法に関するガイダンス

ビルトイン オートメーション ピア クラス

UI オートメーションと UWP のプロセス境界

OnCreateAutomationPeer

正しいピアの基底クラスの選択

カスタム ピア クラスの初期化

AutomationPeer のコア メソッド

GetAutomationControlType

GetPattern と GetPatternCore

子要素からのパターンの転送

その他の Core メソッド

FrameworkElementAutomationPeer の基本実装

ピアと AutomationProperties

パターンの実装

UI オートメーションのイベント

AutomationEvents の識別子

イベントの発生

ピアのナビゲーション

テキスト パターンのネイティブ オートメーション サポート

AutomationProperties.AccessibilityView

オートメーション ピアからの例外のスロー

関連トピック

フィードバック

その他のリソース

カスタムオートメーションピア

カスタム UI クラスに対する UI オートメーションサポートの既存状態の特定

オートメーションピアクラス

コントロールパターンの実装方法に関するガイダンス

ビルトインオートメーションピアクラス

カスタムピアクラスの初期化

AutomationPeer のコアメソッド

テキストパターンのネイティブオートメーションサポート

オートメーションピアからの例外のスロー