プロパティ パス構文Property-path syntax

PropertyPath クラスと文字列構文を使うと、PropertyPath 値を XAML またはコードでインスタンス化できます。You can use the PropertyPath class and the string syntax to instantiate a PropertyPath value either in XAML or in code. PropertyPath 値は、データ バインディングで使われます。PropertyPath values are used by data binding. ストーリーボードに設定されたアニメーションのターゲットを設定する場合も、同様の構文が使われます。A similar syntax is used for targeting storyboarded animations. どちらのシナリオにおいても、プロパティ パスは、最終的に 1 つのプロパティに解決される 1 つまたは複数のオブジェクトとプロパティの関係のトラバーサルを記述します。For both scenarios, a property path describes a traversal of one or more object-property relationships that eventually resolve to a single property.

プロパティ パス文字列は、XAML の属性に直接設定できます。You can set a property path string directly to an attribute in XAML. 同じ文字列構文を使って、Binding をコードで設定する PropertyPath を作成することも、SetTargetProperty を使ってコードでアニメーション ターゲットを設定することもできます。You can use the same string syntax to construct a PropertyPath that sets a Binding in code, or to set an animation target in code using SetTargetProperty. Windows ランタイムには、プロパティ パスを使う機能領域として、データ バインディングとアニメーション ターゲット設定の 2 つがあります。There are two distinct feature areas in the Windows Runtime that use a property path: data binding, and animation targeting. Windows ランタイムの実装時には、アニメーション ターゲット設定で基になる PropertyPath 値が作成されず、情報が文字列として保持されます。しかし、オブジェクトとプロパティのトラバーサルの概念はよく似ています。Animation targeting doesn't create underlying Property-path syntax values in the Windows Runtime implementation, it keeps the info as a string, but the concepts of object-property traversal are very similar. データ バインディングとアニメーション ターゲット設定ではプロパティ パスの評価方法が多少異なるため、それぞれについてプロパティ パス構文を説明していきます。Data binding and animation targeting each evaluate a property path slightly differently, so we describe property path syntax separately for each.

データ バインディングでのオブジェクトのプロパティ パスProperty path for objects in data binding

Windows ランタイムでは、任意の依存関係プロパティのターゲット値にバインドできます。In Windows Runtime, you can bind to the target value of any dependency property. データ バインディングのソース プロパティ値は、依存関係プロパティである必要はなく、ビジネス オブジェクト (たとえば、Microsoft .NET 言語または C++ で書かれたクラス) のプロパティを使うことができます。The source property value for a data binding doesn't have to be a dependency property; it can be a property on a business object (for example a class written in a Microsoft .NET language or C++). また、バインド値のソース オブジェクトには、アプリによって定義され、既に存在している依存関係オブジェクトを使うことができます。Or, the source object for the binding value can be an existing dependency object already defined by the app. ソースは、単純なプロパティ名を使うか、またはビジネス オブジェクトのオブジェクト グラフのオブジェクトとプロパティの関係のトラバーサルによって参照できます。The source can be referenced either by a simple property name, or by a traversal of the object-property relationships in the object graph of the business object.

バインド先として、個々のプロパティか、またはリストまたはコレクションを保持するターゲット プロパティを設定できます。You can bind to an individual property value, or you can bind to a target property that holds lists or collections. ソースがコレクションの場合、またはパスにコレクション プロパティが指定されている場合、データ バインディング エンジンにより、ソースのコレクション項目がバインディング ターゲットと照合されます。その結果、コレクション内の特定の項目を予測する必要なく、ListBox にデータ ソース コレクションの項目のリストを設定する動作が実行されます。If your source is a collection, or if the path specifies a collection property, the data-binding engine matches the collection items of the source to the binding target, resulting in behavior such as populating a ListBox with a list of items from a data source collection without needing to anticipate the specific items in that collection.

オブジェクト グラフのトラバーサルTraversing an object graph

オブジェクト グラフ内のオブジェクトとプロパティの関係のトラバーサルを示す構文要素は、ドット ( . ) 文字です。The element of the syntax that denotes the traversal of an object-property relationship in an object graph is the dot (.) character. プロパティ パス文字列の各ドットは、オブジェクト (ドットの左側) とそのオブジェクトのプロパティ (ドットの右側) の間の区切りを表します。Each dot in a property path string indicates a division between an object (left side of the dot) and a property of that object (right side of the dot). 文字列は左から右へ評価され、これにより複数のオブジェクトとプロパティの関係をステップごとに表すことができます。The string is evaluated left-to-right, which enables stepping through multiple object-property relationships. 次に例を示します。Let's look at an example:

"{Binding Path=Customer.Address.StreetAddress1}"

このパスは、次のように評価されます。Here's how this path is evaluated:

  1. データ コンテキスト オブジェクト (または同じ Binding によって指定された Source) で、"Customer" という名前のプロパティが検索されます。The data context object (or a Source specified by the same Binding) is searched for a property named "Customer".
  2. "Customer" プロパティの値であるオブジェクトで、"Address" という名前のプロパティが検索されます。The object that is the value of the "Customer" property is searched for a property named "Address".
  3. "Address" プロパティの値であるオブジェクトで、"StreetAddress1" という名前のプロパティが検索されます。The object that is the value of the "Address" property is searched for a property named "StreetAddress1".

これらのそれぞれの手順で、値はオブジェクトとして扱われます。At each of these steps, the value is treated as an object. 結果の型は、バインドが特定のプロパティに割り当てられたときにのみ確認されます。The type of the result is checked only when the binding is applied to a specific property. "Address" が単なる文字列値で、文字列のどの部分が番地を表しているかが示されない場合、この例は失敗します。This example would fail if "Address" were just a string value that didn't expose what part of the string was the street address. 通常、バインドは、既知の意図的な情報構造を持つビジネス オブジェクトの特定の入れ子にされたプロパティ値を指し示します。Typically, the binding is pointing to the specific nested property values of a business object that has a known and deliberate information structure.

データ バインディング プロパティ パスのプロパティの規則Rules for the properties in a data-binding property path

  • プロパティ パスで参照されるすべてのプロパティは、ソース ビジネス オブジェクト内でパブリックであることが必要です。All properties referenced by a property path must be public in the source business object.
  • 終了プロパティ (パスに指定された最後のプロパティ) は、パブリックであり変更可能である必要があります。静的値にバインドすることはできません。The end property (the property that is the last named property in the path) must be public and must be mutable – you can't bind to static values.
  • このパスが双方向バインドの Path 情報として使われる場合、終了プロパティは読み取り/書き込み可能である必要があります。The end property must be read/write if this path is used as the Path information for a two-way binding.

インデクサーIndexers

データ バインディングのプロパティ パスには、インデックス付きプロパティへの参照を含めることができます。A property path for data-binding can include references to indexed properties. これにより、順序指定された一覧/ベクターまたは辞書/地図へのバインドが可能になります。This enables binding to ordered lists/vectors, or to dictionaries/maps. 角かっこを使用して、"[]"インデックス付きプロパティを示す文字。Use square brackets "[]" characters to indicate an indexed property. 角かっこ内には、整数 (順序指定された一覧用) または引用符で囲まれていない文字列 (辞書用) を含めることができます。The contents of these brackets can be either an integer (for ordered list) or an unquoted string (for dictionaries). また、キーが整数である辞書にバインドすることもできます。You can also bind to a dictionary where the key is an integer. オブジェクトとプロパティを区切るドットを使って、同じパス内で異なるインデックス付きプロパティを使うことができます。You can use different indexed properties in the same path with a dot separating the object-property.

たとえば、"Teams" (順序指定された一覧) の一覧を含むビジネス オブジェクトがあるとします。それぞれには、各プレイヤーの姓がキーとして使われている、"Players" という辞書があるとします。For example, consider a business object where there is a list of "Teams" (ordered list), each of which has a dictionary of "Players" where each player is keyed by last name. 2 番目のチームの特定のプレーヤーにプロパティ パスの例に示します。"チーム[1]します。プレーヤー[Smith]"。An example property path to a specific player on the second team is: "Teams[1].Players[Smith]". (一覧はインデックス 0 で始まるため、"Teams" の 2 番目の項目を示すには 1 を使います)。(You use 1 to indicate the second item in "Teams" because the list is zero-indexed.)

  C++ のデータ ソースのインデックス作成のサポートは制限されています。 を参照してください深さでのデータ バインディングします。Note  Indexing support for C++ data sources is limited; see Data binding in depth.

添付プロパティAttached properties

プロパティ パスには、添付プロパティへの参照を含めることができます。Property paths can include references to attached properties. 添付プロパティの識別名には既にドットが含まれているため、ドットがオブジェクトとプロパティのステップとして処理されないように、すべての添付プロパティ名をかっこで囲む必要があります。Because the identifying name of an attached property already includes a dot, you must enclose any attached property name within parentheses so that the dot isn't treated as an object-property step. たとえば、Canvas.ZIndex をバインド パスとして使うことを指定する文字列は "(Canvas.ZIndex)" となります。For example, the string to specify that you want to use Canvas.ZIndex as a binding path is "(Canvas.ZIndex)". 添付プロパティについて詳しくは、「添付プロパティの概要」をご覧ください。For more info on attached properties see Attached properties overview.

プロパティ パス構文の組み合わせCombining property path syntax

プロパティ パス構文のさまざまな要素を 1 つの文字列で組み合わせることができます。You can combine various elements of property path syntax in a single string. たとえば、インデックス付き添付プロパティを参照するプロパティ パスを定義できます (データ ソースにインデックス付き添付プロパティがある場合)。For example, you can define a property path that references an indexed attached property, if your data source had such a property.

バインド プロパティ パスのデバッグDebugging a binding property path

プロパティ パスはバインド エンジンによって解釈され、実行時にのみ存在する可能性がある情報に依存するため、開発ツールの従来の設計時またはコンパイル時サポートに頼らずに、バインドのためのプロパティ パスをデバッグすることが必要になります。Because a property path is interpreted by a binding engine and relies on info that may be present only at run-time, you must often debug a property path for binding without being able to rely on conventional design-time or compile-time support in the development tools. 多くの場合、実行時にプロパティ パスの解決に失敗すると、エラーなしで空白値が生成されます。これは、バインド解決の意図的なフォールバック動作です。In many cases the run-time result of failing to resolve a property path is a blank value with no error, because that is the by-design fallback behavior of binding resolution. Microsoft Visual Studio には、バインド ソースを指定するプロパティ パスのどの部分で解決が失敗したかを特定できるデバッグ出力モードが用意されています。Fortunately, Microsoft Visual Studio provides a debug output mode that can isolate which part of a property path that's specifying a binding source failed to resolve. この開発ツールの機能の使い方について詳しくは、「データ バインディングの詳細」の「デバッグ」セクションをご覧ください。For more info on using this development tool feature, see "Debugging" section of Data binding in depth.

アニメーション ターゲット設定のためのプロパティ パスProperty path for animation targeting

アニメーションは、アニメーションの実行時にストーリーボードに設定された値が適用される依存関係プロパティのターゲット設定に依存します。Animations rely on targeting a dependency property where storyboarded values are applied when the animation runs. アニメーション化されるプロパティが存在するオブジェクトを識別するために、アニメーションは、要素を名前 (x:Name 属性) でターゲット設定します。To identify the object where the property to be animated exists, the animation targets an element by name (x:Name attribute). 通常、Storyboard.TargetName として識別されたオブジェクトで始まり、アニメーションが適用される特定の依存関係プロパティ値で終わるプロパティ パスを定義する必要があります。It is often necessary to define a property path that starts with the object identified as the Storyboard.TargetName, and ends with the particular dependency property value where the animation should apply. このプロパティ パスは、Storyboard.TargetProperty の値として使われます。That property path is used as the value for Storyboard.TargetProperty.

XAML でアニメーションを定義する方法について詳しくは、「ストーリーボードに設定されたアニメーション」をご覧ください。For more info on the how to define animations in XAML, see Storyboarded animations.

単純なターゲット設定Simple targeting

ターゲット設定されたオブジェクト自体に存在するプロパティをアニメーション化するときに、(プロパティ値のサブプロパティではなく) このプロパティの型にアニメーションを直接適用できる場合は、修飾を追加することなく、アニメーション化の対象のプロパティを指定するだけでかまいません。If you are animating a property that exists on the targeted object itself, and that property's type can have an animation applied directly to it (rather than to a sub-property of a property's value) then you can simply name the property being animated without any further qualification. たとえば、Shape サブクラス (Rectangle など) をターゲット設定し、アニメーション化された ColorFill プロパティに割り当てる場合、プロパティ パスとして "Fill" を指定できます。For example, if you are targeting a Shape subclass such as Rectangle, and you are applying an animated Color to the Fill property, your property path can be "Fill".

間接的なプロパティのターゲット設定Indirect property targeting

ターゲット オブジェクトのサブプロパティであるプロパティをアニメーション化できます。You can animate a property that is a sub-property of the target object. 言い換えると、ターゲット オブジェクトにプロパティがあり (つまり、オブジェクト自体)、このオブジェクトにプロパティがある場合は、オブジェクトとプロパティの関係をステップごとに表す方法を説明するプロパティ パスを定義する必要があります。In other words, if there's a property of the target object that's an object itself, and that object has properties, you must define a property path that explains how to step through that object-property relationship. サブプロパティをアニメーション化するオブジェクトを指定するときは、必ずプロパティ名をかっこで囲み、プロパティを typename.propertyname 形式で指定します。Whenever you are specifying an object where you want to animate a sub-property, you enclose the property name in parentheses, and you specify the property in typename.propertyname format. たとえば、ターゲット オブジェクトの RenderTransform プロパティのオブジェクト値を指定するには、"(UIElement.RenderTransform)" をプロパティ パスの最初のステップとして指定します。For example, to specify that you want the object value of a target object's RenderTransform property, you specify "(UIElement.RenderTransform)" as the first step in the property path. Transform 値に直接適用できるアニメーションはないため、これはまだ完全なパスではありません。This isn't yet a complete path, because there are no animations that can apply to a Transform value directly. そこで、この例では、Double 値によってアニメーション化できる Transform サブクラスのプロパティを終了プロパティに指定して、"(UIElement.RenderTransform).(CompositeTransform.TranslateX)" というプロパティ パスを完成させます。So for this example, you now complete the property path so that the end property is a property of a Transform subclass that can be animated by a Double value: "(UIElement.RenderTransform).(CompositeTransform.TranslateX)"

コレクション内の特定の子の指定Specifying a particular child in a collection

コレクション プロパティ内の子項目を指定する場合、数値インデクサーを使うことができます。To specify a child item in a collection property, you can use a numeric indexer. 角かっこを使用して、"[]"整数の周囲の文字のインデックス値。Use square brackets "[]" characters around the integer index value. 参照できるのは順序指定された一覧のみで、辞書は参照できません。You can reference only ordered lists, not dictionaries. コレクションはアニメーション化できる値ではないため、インデクサーの使用はプロパティ パスの終了プロパティとなりません。Because a collection isn't a value that can be animated, an indexer usage can never be the end property in a property path.

たとえば、最初の色をアニメーション化するように指定停止の色で、 LinearGradientBrush コントロールに適用されるバック グラウンドプロパティ、これは、プロパティ パス:"(されたルックアップ)。(GradientBrush.GradientStops)[0](。GradientStop.Color)"。For example, to specify that you want to animate the first color stop color in a LinearGradientBrush that is applied to a control's Background property, this is the property path: "(Control.Background).(GradientBrush.GradientStops)[0].(GradientStop.Color)". インデクサーがパスの最終ステップにならないことに注目してください。さらに、アニメーション化された値 Color を適用するために特に最終ステップでコレクション内の項目 0 の GradientStop.Color プロパティを参照する必要があることに注目してください。Note how the indexer is not the last step in the path, and that the last step particularly must reference the GradientStop.Color property of item 0 in the collection to apply a Color animated value to it.

添付プロパティのアニメーション化Animating an attached property

これは一般的なシナリオではありませんが、添付プロパティがアニメーションの種類と一致するプロパティ値を持つ限り、添付プロパティをアニメーション化することもあります。It isn't a common scenario, but it is possible to animate an attached property, so long as that attached property has a property value that matches an animation type. 添付プロパティの識別名には既にドットが含まれているため、ドットがオブジェクトとプロパティのステップとして処理されないように、すべての添付プロパティ名をかっこで囲む必要があります。Because the identifying name of an attached property already includes a dot, you must enclose any attached property name within parentheses so that the dot isn't treated as an object-property step. たとえば、オブジェクトの Grid.Row 添付プロパティをアニメーション化することを指定する文字列として、プロパティ パス "(Grid.Row)" を使います。For example, the string to specify that you want to animate the Grid.Row attached property on an object, use the property path "(Grid.Row)".

  この例では、値の Grid.Row は、 Int32プロパティの型。Note  For this example, the value of Grid.Row is an Int32 property type. したがって、Double アニメーションを使ってこれをアニメーション化することはできません。so you can't animate it with a Double animation. その代わり、DiscreteObjectKeyFrame コンポーネントを持つ ObjectAnimationUsingKeyFrames を定義します。ここで、ObjectKeyFrame.Value は、"0"、"1" などの整数に設定します。Instead, you'd define an ObjectAnimationUsingKeyFrames that has DiscreteObjectKeyFrame components, where the ObjectKeyFrame.Value is set to an integer such as "0" or "1".

アニメーション ターゲット設定プロパティ パスのプロパティの規則Rules for the properties in an animation targeting property path

  • プロパティ パスの想定される開始点は、Storyboard.TargetName によって識別されるオブジェクトです。The assumed starting point of the property path is the object identified by a Storyboard.TargetName.
  • プロパティ パスで参照されるすべてのオブジェクトおよびプロパティは、パブリックであることが必要です。All objects and properties referenced along the property path must be public.
  • 終了プロパティ (パスに指定された最後のプロパティ) は、パブリックで読み取り/書き込み可能な依存関係プロパティである必要があります。The end property (the property that is the last named property in the path) must be public, be read-write, and be a dependency property.
  • 終了プロパティは、さまざまなアニメーションの種類 (Color アニメーション、Double アニメーション、Point アニメーション、ObjectAnimationUsingKeyFrames) のいずれかでアニメーション化できるプロパティ型を持つ必要があります。The end property must have a property type that is able to be animated by one of the broad classes of animation types (Color animations, Double animations, Point animations, ObjectAnimationUsingKeyFrames).

PropertyPath クラスThe PropertyPath class

PropertyPath クラスは、バインド シナリオのための Binding.Path の基になるプロパティ型です。The PropertyPath class is the underlying property type of Binding.Path for the binding scenario.

ほとんどの場合、コードをまったく使わずに PropertyPath を XAML で適用できます。Most of the time, you can apply a PropertyPath in XAML without using any code at all. しかし、場合によっては、コードを使って PropertyPath オブジェクトを定義し、実行時にプロパティに割り当てることができます。But in some cases you may want to define a PropertyPath object using code and assign it to a property at run-time.

PropertyPath が、 PropertyPath(String) コンス トラクター、および既定のコンス トラクターはありません。PropertyPath has a PropertyPath(String) constructor, and doesn't have a default constructor. このコンストラクターには、前に説明したプロパティ パス構文を使って定義した文字列を渡します。The string you pass to this constructor is a string that's defined using the property path syntax as we explained earlier. これは、パスを Path 属性として割り当てるために使うのと同じ文字列でもあります。This is also the same string you'd use to assign Path as a XAML attribute. PropertyPath クラスの唯一の他の API は Path プロパティで、これは読み取り専用です。The only other API of the PropertyPath class is the Path property, which is read-only. このプロパティは、他の PropertyPath インスタンスの構成文字列として使うことができます。You could use this property as the construction string for another PropertyPath instance.