添付プロパティの概要Attached properties overview

添付プロパティは、XAML の概念です。An attached property is a XAML concept. 添付プロパティは、追加のプロパティ/値ペアをオブジェクトに設定できますが、このプロパティは元のオブジェクト定義の一部ではありません。Attached properties enable additional property/value pairs to be set on an object, but the properties are not part of the original object definition. 添付プロパティは、一般に、所有者型のオブジェクト モデルで従来のプロパティ ラッパーを持たない特殊な形式の依存関係プロパティとして定義されます。Attached properties are typically defined as a specialized form of dependency property that doesn't have a conventional property wrapper in the owner type's object model.

前提条件Prerequisites

依存関係プロパティの基本的な概念を理解し、「依存関係プロパティの概要」を読んでいることを前提としています。We assume that you understand the basic concept of dependency properties, and have read Dependency properties overview.

XAML での添付プロパティAttached properties in XAML

XAML では、AttachedPropertyProvider.PropertyName 構文を使って添付プロパティを設定します。In XAML, you set attached properties by using the syntax AttachedPropertyProvider.PropertyName. XAML で Canvas.Left を設定する例を次に示します。Here is an example of how you can set Canvas.Left in XAML.

<Canvas>
  <Button Canvas.Left="50">Hello</Button>
</Canvas>

注意

だけを使っている Canvas.Left 完全に使用する理由を説明することがなく添付プロパティの例として。We're just using Canvas.Left as an example attached property without fully explaining why you'd use it. Canvas.Left の用途や、Canvas がそのレイアウトの子を処理する方法について詳しくは、Canvas のリファレンス トピックまたは「XAML を使ったレイアウトの定義」をご覧ください。If you want to know more about what Canvas.Left is for and how Canvas handles its layout children, see the Canvas reference topic or Define layouts with XAML.

添付プロパティを使う理由Why use attached properties?

添付プロパティは、リレーションシップ内の別々のオブジェクトが実行時に情報をやり取りするのを防ぐようなコーディング規則を回避する方法の 1 つです。Attached properties are a way to escape the coding conventions that might prevent different objects in a relationship from communicating information to each other at run time. 共通の基底クラスにプロパティを設定し、各オブジェクトがそのプロパティを取得、設定できるようにすることも可能です。It's certainly possible to put properties on a common base class so that each object could just get and set that property. ただ、このようにする可能性のあるシナリオの数はきわめて多く、共有できるプロパティによって基底クラスが大きくなるおそれがあります。But eventually the sheer number of scenarios where you might want to do this will bloat your base classes with shareable properties. 何百もの子孫のうちわずか 2 つしか使わないプロパティが存在するなどという事態が発生することも考えられます。It might even introduce cases where there might just be two of hundreds of descendants trying to use a property. これでは、優れたクラス設計にはなりません。That's not good class design. この問題に対処するため、添付プロパティの概念では、自らのクラス構造では定義されないプロパティに対してオブジェクトが値を割り当てられるようになっています。To address this, the attached property concept enables an object to assign a value for a property that its own class structure doesn't define. 定義クラスでは、オブジェクト ツリーで各種オブジェクトが作成された後、実行時に子オブジェクトから値を読み取ります。The defining class can read the value from child objects at run time after the various objects are created in an object tree.

たとえば、子要素では添付プロパティを使用して、子要素がどのように UI に表示されるかを親要素に通知できます。For example, child elements can use attached properties to inform their parent element of how they are to be presented in the UI. Canvas.Left 添付プロパティの場合がこれに該当します。This is the case with the Canvas.Left attached property. Canvas.Left が添付プロパティとして作成されるのは、このプロパティが Canvas 自体ではなく Canvas 要素に含まれる要素に対して設定されるためです。Canvas.Left is created as an attached property because it is set on elements that are contained within a Canvas element, rather than on the Canvas itself. 子要素は、Canvas.LeftCanvas.Top を使って、レイアウト オフセットを親である Canvas レイアウト コンテナー内で指定します。Any possible child element then uses Canvas.Left and Canvas.Top to specify its layout offset within the Canvas layout container parent. 基本の要素オブジェクト モデルに多数のプロパティがあり、それぞれのプロパティが多数のレイアウト コンテナーの 1 つのみに適用される場合でも、添付プロパティを使えば、そのオブジェクト モデルを煩雑な状態にすることなくこれを実現できます。Attached properties make it possible for this to work without cluttering the base element's object model with lots of properties that each apply to only one of the many possible layout containers. 代わりに、レイアウト コンテナーの多くは独自の添付プロパティ セットを実装します。Instead, many of the layout containers implement their own attached property set.

添付プロパティを実装するには、Canvas クラスは、Canvas.LeftProperty という名前の静的な DependencyProperty フィールドを定義します。To implement the attached property, the Canvas class defines a static DependencyProperty field named Canvas.LeftProperty. 次に Canvas では、SetLeft メソッドと GetLeft メソッドを添付プロパティのパブリック アクセサーとして提供して、XAML の設定とランタイム値のアクセスの両方を可能にします。Then, Canvas provides the SetLeft and GetLeft methods as public accessors for the attached property, to enable both XAML setting and run-time value access. XAML と依存関係プロパティ システムに対しては、この API のセットは添付プロパティ用の特定の XAML 構文を使い、依存関係プロパティ ストアに値を格納するパターンを実現できます。For XAML and for the dependency property system, this set of APIs satisfies a pattern that enables a specific XAML syntax for attached properties, and stores the value in the dependency property store.

所有する型による添付プロパティの使用方法How the owning type uses attached properties

添付プロパティは任意の XAML 要素 (または基になる DependencyObject) に設定できますが、プロパティを設定することによって具体的な結果が生成されたり、値がアクセスされたりするわけではありません。Although attached properties can be set on any XAML element (or any underlying DependencyObject), that doesn't automatically mean that setting the property produces a tangible result, or that the value is ever accessed. 添付プロパティを定義する型は、一般に次のいずれかのシナリオに従います。The type that defines the attached property typically follows one of these scenarios:

  • 添付プロパティを定義する型が、他のオブジェクトのリレーションシップで親になっている。The type that defines the attached property is the parent in a relationship of other objects. 子オブジェクトは、添付プロパティの値を設定します。The child objects will set values for the attached property. 添付プロパティの所有者型には、オブジェクトの有効期間内のある時点に子要素を反復処理し、値を取得し、その値を処理するという動作が元からいくつか備わっています (レイアウト操作 SizeChanged など)。The attached property owner type has some innate behavior that iterates through its child elements, obtains the values, and acts on those values at some point in object lifetime (a layout action, SizeChanged, etc.)
  • 添付プロパティを定義する型は、さまざまな親要素とコンテンツ モデルの子要素として使われますが、この情報はレイアウト情報である必要はありません。The type that defines the attached property is used as the child element for a variety of possible parent elements and content models, but the info isn't necessarily layout info.
  • 添付プロパティは、別の UI 要素ではなくサービスに情報を報告します。The attached property reports info to a service, not to another UI element.

これらのシナリオや所有する型について詳しくは、「カスタム添付プロパティ」の「Canvas.Left の詳細」セクションをご覧ください。For more info on these scenarios and owning types, see the "More about Canvas.Left" section of Custom attached properties.

コードでの添付プロパティAttached properties in code

添付プロパティには、他の依存関係プロパティのような、取得および設定アクセスを容易にする標準的なプロパティ ラッパーがありません。Attached properties don't have the typical property wrappers for easy get and set access like other dependency properties do. これは、添付プロパティが設定されているインスタンスのコード中心のオブジェクト モデルに、その添付プロパティが組み込まれているとは限らないからです。This is because the attached property is not necessarily part of the code-centered object model for instances where the property is set. (他の型で設定できると同時に、所有する型では従来の方法で使われる添付プロパティを定義することもできますが、決して一般的ではありません。)(It is permissible, though uncommon, to define a property that is both an attached property that other types can set on themselves, and that also has a conventional property usage on the owning type.)

コードでは 2 つの方法で添付プロパティを設定できます。1 つはプロパティ システムの API を使う方法、もう 1 つは XAML パターン アクセサーを使う方法です。There are two ways to set an attached property in code: use the property-system APIs, or use the XAML pattern accessors. これらの方法は最終的な結果という点ではほぼ同じため、どちらを使うかは主にコーディング スタイルによって決まります。These techniques are pretty much equivalent in terms of their end result, so which one to use is mostly a matter of coding style.

プロパティ システムを使う場合Using the property system

Windows ランタイムの添付プロパティは依存関係プロパティとして実装されるため、プロパティ システムを使って共有依存関係プロパティ ストアに値を格納できます。Attached properties for the Windows Runtime are implemented as dependency properties, so that the values can be stored in the shared dependency-property store by the property system. したがって、添付プロパティは所有するクラスで依存関係プロパティ ID を公開します。Therefore attached properties expose a dependency property identifier on the owning class.

コードで添付プロパティを設定するには、SetValue メソッドを呼び出し、その添付プロパティの ID となる DependencyProperty フィールドを渡します。To set an attached property in code, you call the SetValue method, and pass the DependencyProperty field that serves as the identifier for that attached property. (設定する値も渡します)。(You also pass the value to set.)

コードで添付プロパティの値を取得するには、GetValue メソッドを呼び出し、同じく ID となる DependencyProperty フィールドを渡します。To get the value of an attached property in code, you call the GetValue method, again passing the DependencyProperty field that serves as the identifier.

XAML アクセサー パターンを使う場合Using the XAML accessor pattern

XAML をオブジェクト ツリーに解析するときは、XAML プロセッサが添付プロパティの値を設定できる必要があります。A XAML processor must be able to set attached property values when XAML is parsed into an object tree. 添付プロパティの所有者型は、GetPropertyNameSetPropertyName の形式で名前を付けた専用のアクセサー メソッドを実装する必要があります。The owner type of the attached property must implement dedicated accessor methods named in the form GetPropertyName and SetPropertyName. この専用のアクセサー メソッドは、コードで添付プロパティを取得または設定する方法の 1 つでもあります。These dedicated accessor methods are also one way to get or set the attached property in code. コードの観点からすると、添付プロパティは、プロパティ アクセサーではなくメソッド アクセサーを持つバッキング フィールドに似ています。このバッキング フィールドは、どのオブジェクトにも存在する可能性があり、具体的に定義する必要はありません。From a code perspective, an attached property is similar to a backing field that has method accessors instead of property accessors, and that backing field can exist on any object rather than having to be specifically defined.

次の例は、コードで XAML アクセサー API を使って添付プロパティを設定する方法を示しています。The next example shows how you can set an attached property in code via the XAML accessor API. この例の myCheckBox は、CheckBox クラスのインスタンスです。In this example, myCheckBox is an instance of the CheckBox class. 実際に値を設定するコードは最後の行です。それまでの行では、インスタンスとその親子関係を設定しています。The last line is the code that actually sets the value; the lines before that just establish the instances and their parent-child relationship. コメント解除された最後の行は、プロパティ システムを使う場合の構文です。The uncommented last line is the syntax if you use the property system. コメント アウトされた最後の行は、XAML アクセサー パターンを使う場合の構文です。The commented last line is the syntax if you use the XAML accessor pattern.

    Canvas myC = new Canvas();
    CheckBox myCheckBox = new CheckBox();
    myCheckBox.Content = "Hello";
    myC.Children.Add(myCheckBox);
    myCheckBox.SetValue(Canvas.TopProperty,75);
    //Canvas.SetTop(myCheckBox, 75);
    Dim myC As Canvas = New Canvas()
    Dim myCheckBox As CheckBox= New CheckBox()
    myCheckBox.Content = "Hello"
    myC.Children.Add(myCheckBox)
    myCheckBox.SetValue(Canvas.TopProperty,75)
    ' Canvas.SetTop(myCheckBox, 75)
Canvas myC;
CheckBox myCheckBox;
myCheckBox.Content(winrt::box_value(L"Hello"));
myC.Children().Append(myCheckBox);
myCheckBox.SetValue(Canvas::TopProperty(), winrt::box_value(75));
// Canvas::SetTop(myCheckBox, 75);
    Canvas^ myC = ref new Canvas();
    CheckBox^ myCheckBox = ref new CheckBox();
    myCheckBox->Content="Hello";
    myC->Children->Append(myCheckBox);
    myCheckBox->SetValue(Canvas::TopProperty,75);
    // Canvas::SetTop(myCheckBox, 75);

カスタム添付プロパティCustom attached properties

カスタム添付プロパティの定義方法に関するコード例と添付プロパティを使うシナリオに関する詳しい情報については、「カスタム添付プロパティ」をご覧ください。For code examples of how to define custom attached properties, and more info about the scenarios for using an attached property, see Custom attached properties.

添付プロパティ参照の特別な構文Special syntax for attached property references

添付プロパティ名に含まれるドットは、識別パターンの重要な部分です。The dot in an attached property name is a key part of the identification pattern. ドットが別の意味に解釈される構文または状況では、あいまいさが生じる場合があります。Sometimes there are ambiguities when a syntax or situation treats the dot as having some other meaning. たとえば、バインディング パスではドットがオブジェクト モデル トラバーサルと見なされます。For example, a dot is treated as an object-model traversal for a binding path. あいまいさに関してほとんどの場合、添付プロパティ用の特別な構文によって、内部のドットは添付プロパティの owner . property 区切り文字として解析されています。In most cases involving such ambiguity, there is a special syntax for an attached property that enables the inner dot still to be parsed as the owner.property separator of an attached property.

  • 添付プロパティをアニメーション用ターゲット パスの一部として指定する場合は、添付プロパティ名をかっこ "()" で囲みます。たとえば、"(Canvas.Left)" のようにします。To specify an attached property as part of a target path for an animation, enclose the attached property name in parentheses ("()")—for example, "(Canvas.Left)". 詳しくは、「Property-path 構文」をご覧ください。For more info, see Property-path syntax.

警告

Windows ランタイムの XAML 実装の既存の制限は、カスタム添付プロパティをアニメーション化することはできません。An existing limitation of the Windows Runtime XAML implementation is that you cannot animate a custom attached property.

  • リソース ファイルからリソースの参照に対するターゲットのプロパティとして添付プロパティを指定するX:uid、特別な構文、コード スタイルの完全修飾の挿入を使用してを使用して: 宣言内角かっこ ("[]")、意図的なスコープ区切りを挿入します。To specify an attached property as the target property for a resource reference from a resource file to x:Uid, use a special syntax that injects a code-style, fully qualified using: declaration inside square brackets ("[]"), to create a deliberate scope break. たとえば、要素が存在すると仮定すると<TextBlock x:Uid="Title" />を対象とするリソース ファイル内のリソース キー、 Canvas.Topそのインスタンスの値が"タイトル[。using:Windows.UI.Xaml.Controls]Canvas.Top"。For example, assuming there exists an element <TextBlock x:Uid="Title" />, the resource key in the resource file that targets the Canvas.Top value on that instance is "Title.[using:Windows.UI.Xaml.Controls]Canvas.Top". リソース ファイルと XAML の詳細については、次を参照してください。クイック スタート。UI リソースを翻訳するします。For more info on resource files and XAML, see Quickstart: Translating UI resources.