Синтаксис PropertyPath XAMLPropertyPath XAML Syntax

Объект PropertyPath поддерживает сложный встроенный XAMLXAML синтаксис для установки различных свойств, которые принимают тип PropertyPath в качестве значения.The PropertyPath object supports a complex inline XAMLXAML syntax for setting various properties that take the PropertyPath type as their value. В этом разделе документируется синтаксис PropertyPath, примененный к синтаксису привязки и анимации.This topic documents the PropertyPath syntax as applied to binding and animation syntaxes.

Где используется PropertyPathWhere PropertyPath Is Used

PropertyPath — это общий объект, используемый в нескольких Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF)ных функциях.PropertyPath is a common object that is used in several Windows Presentation Foundation (WPF)Windows Presentation Foundation (WPF) features. Несмотря на использование общих PropertyPath для передачи сведений о пути к свойству, использование каждой функциональной области, где PropertyPath используется в качестве типа, различается.Despite using the common PropertyPath to convey property path information, the usages for each feature area where PropertyPath is used as a type vary. Таким образом, более практично документировать синтаксис для каждой функции.Therefore, it is more practical to document the syntaxes on a per-feature basis.

В основном WPFWPF использует PropertyPath для описания путей к объектной модели для обхода свойств источника данных объекта и для описания целевого пути для целевых анимаций.Primarily, WPFWPF uses PropertyPath to describe object-model paths for traversing the properties of an object data source, and to describe the target path for targeted animations.

Некоторые свойства стиля и шаблона, такие как Setter.Property, имеют полное имя свойства, которое внешне напоминает PropertyPath.Some style and template properties such as Setter.Property take a qualified property name that superficially resembles a PropertyPath. Но это не правда PropertyPath; Вместо этого он является полным владельцем. использование формата строки свойства, включенного процессором XAMLXAML WPF в сочетании с преобразователем типов для DependencyProperty.But this is not a true PropertyPath; instead it is a qualified owner.property string format usage that is enabled by the WPF XAMLXAML processor in combination with the type converter for DependencyProperty.

PropertyPath для объектов в привязке данныхPropertyPath for Objects in Data Binding

Привязка данных является функцией WPFWPF, которую можно привязать к целевому значению любого свойства зависимостей.Data binding is a WPFWPF feature whereby you can bind to the target value of any dependency property. Однако источник такой привязки данных не обязательно должен быть свойством зависимостей. Это может быть любой тип свойства, распознаваемый применимым поставщиком данных.However, the source of such a data binding need not be a dependency property; it can be any property type that is recognized by the applicable data provider. Пути к свойствам особенно используются для ObjectDataProvider, который используется для получения источников привязки из объектов среды CLR и их свойств.Property paths are particularly used for the ObjectDataProvider, which is used for obtaining binding sources from common language runtime (CLR) objects and their properties.

Обратите внимание, что привязка данных к XML не использует PropertyPath, так как не использует Path в Binding.Note that data binding to XML does not use PropertyPath, because it does not use Path in the Binding. Вместо этого используйте XPath и укажите допустимый синтаксис XPath в XML-модель DOM (DOM) данных.Instead, you use XPath and specify valid XPath syntax into the XML Document Object Model (DOM) of the data. XPath также указывается в виде строки, но здесь не описывается. см. статью Привязка к XML-данным с помощью XmlDataProvider и запросов XPath.XPath is also specified as a string, but is not documented here; see Bind to XML Data Using an XMLDataProvider and XPath Queries.

Ключом к пониманию путей к свойствам в привязке к данным является то, что можно настроить целевой объект привязки на отдельное значение свойства либо использовать привязку к целевым свойствам, которые принимают списки или коллекции.A key to understanding property paths in data binding is that you can target the binding to an individual property value, or you can instead bind to target properties that take lists or collections. При привязке коллекций для привязки к экземпляру ListBox, который будет расширяться в зависимости от количества элементов данных в коллекции, путь к свойству должен ссылаться на объект коллекции, а не на отдельные элементы коллекции.If you are binding collections, for instance binding a ListBox that will expand depending on how many data items are in the collection, then your property path should reference the collection object, not individual collection items. Обработчик привязки данных будет сопоставлять коллекцию, используемую в качестве источника данных, с типом целевого объекта привязки автоматически, что приводит к поведению, например заполнению ListBox массивом элементов.The data binding engine will match the collection used as the data source to the type of the binding target automatically, resulting in behavior such as populating a ListBox with an items array.

Одиночное свойство в объекте интерпретации в качестве контекста данныхSingle Property on the Immediate Object as Data Context

<Binding Path="propertyName" .../>

PropertyName должен быть разрешен в качестве имени свойства, которое находится в текущем DataContext для использования Path.propertyName must resolve to be the name of a property that is in the current DataContext for a Path usage. Если привязка обновляет источник, это свойство должно быть доступно для чтения и записи, а исходный объект должен быть изменяемым.If your binding updates the source, that property must be read/write and the source object must be mutable.

Одиночный индексатор в объекте интерпретации в контексте данныхSingle Indexer on the Immediate Object as Data Context

<Binding Path="[key]" .../>

key должен быть либо типизированным индексом для словаря или хэш-таблицы, либо целочисленным индексом массива.key must be either the typed index to a dictionary or hash table, or the integer index of an array. Кроме того, значение ключа должно быть типом, который можно непосредственно привязать к свойству, в котором оно применяется.Also, the value of the key must be a type that is directly bindable to the property where it is applied. Например, хэш-таблица, содержащая строковые ключи и строковые значения, может использоваться таким образом для привязки к тексту для TextBox.For instance, a hash table that contains string keys and string values can be used this way to bind to Text for a TextBox. Либо, если ключ указывает на коллекцию или субиндекс, этот синтаксис можно использовать для привязки к целевому свойству коллекции.Or, if the key points to a collection or subindex, you could use this syntax to bind to a target collection property. В противном случае необходимо ссылаться на конкретное свойство, например с помощью синтаксиса <Binding Path="[key].propertyName" .../>.Otherwise, you need to reference a specific property, through a syntax such as <Binding Path="[key].propertyName" .../>.

При необходимости можно указать тип индекса.You can specify the type of the index if necessary. Дополнительные сведения об этом аспекте пути индексированного свойства см. в разделе Binding.Path.For details on this aspect of an indexed property path, see Binding.Path.

Несколько свойств (косвенное назначение свойства)Multiple Property (Indirect Property Targeting)

<Binding Path="propertyName.propertyName2" .../>

propertyName должен быть разрешен в качестве имени свойства, которое является текущим DataContextом.propertyName must resolve to be the name of a property that is the current DataContext. Свойствами пути propertyName и propertyName2 могут быть любые свойства, которые существуют в связи, где propertyName2 — свойство, которое существует в типе, являющемся значением propertyName.The path properties propertyName and propertyName2 can be any properties that exist in a relationship, where propertyName2 is a property that exists on the type that is the value of propertyName.

Одиночное свойство, присоединенное свойство или свойство с указанием типаSingle Property, Attached or Otherwise Type-Qualified

<object property="(ownerType.propertyName)" .../>

Круглые скобки указывают, что это свойство в PropertyPath должно быть создано с использованием частичной квалификации.The parentheses indicate that this property in a PropertyPath should be constructed using a partial qualification. Может использоваться пространство имен XML для поиска типа с соответствующим сопоставлением.It can use an XML namespace to find the type with an appropriate mapping. ownerType ищет типы, к которым обработчик XAMLXAML имеет доступ, через объявления XmlnsDefinitionAttribute в каждой сборке.The ownerType searches types that a XAMLXAML processor has access to, through the XmlnsDefinitionAttribute declarations in each assembly. В большинстве приложений есть пространство имен XML по умолчанию, сопоставленное пространству имен http://schemas.microsoft.com/winfx/2006/xaml/presentation, поэтому префикс обычно требуется только для настраиваемых типов или типов вне этого пространства имен.Most applications have the default XML namespace mapped to the http://schemas.microsoft.com/winfx/2006/xaml/presentation namespace, so a prefix is usually only necessary for custom types or types otherwise outside that namespace. propertyName должно разрешаться как имя свойства, существующего в ownerType.propertyName must resolve to be the name of a property existing on the ownerType. Этот синтаксис обычно используется в одном из следующих случаев.This syntax is generally used for one of the following cases:

  • Путь, указанный в XAMLXAML, который находится в стиле или шаблоне, не имеющем указанного целевого типа.The path is specified in XAMLXAML that is in a style or template that does not have a specified Target Type. Использование полных имен обычно недействительно для иных случаев, поскольку в отличие от стилей и шаблонов свойство существует в экземпляре, а не в типе.A qualified usage is generally not valid for cases other than this, because in non-style, non-template cases, the property exists on an instance, not a type.

  • Свойство является присоединенным свойством.The property is an attached property.

  • Выполняется привязка к статическому свойству.You are binding to a static property.

Для использования в качестве цели раскадровки свойство, указанное как propertyName, должно быть DependencyProperty.For use as storyboard target, the property specified as propertyName must be a DependencyProperty.

Обход источников (привязка к иерархиям коллекций)Source Traversal (Binding to Hierarchies of Collections)

<object Path="propertyName/propertyNameX" .../>

/ в этом синтаксисе используется для навигации в иерархическом объекте источника данных. Поддерживается несколько шагов в иерархии с последовательными символами /.The / in this syntax is used to navigate within a hierarchical data source object, and multiple steps into the hierarchy with successive / characters are supported. Обход источников учитывает текущую позицию указателя записи, которая определяется синхронизацией данных с пользовательским интерфейсом его представления.The source traversal accounts for the current record pointer position, which is determined by synchronizing the data with the UI of its view. Дополнительные сведения о привязке к иерархическим объектам источника данных и концепции указателя текущей записи в привязке данных см. в разделе Использование шаблона "Основной/подробности" с иерархическими данными или Общие сведения о привязке данных.For details on binding with hierarchical data source objects, and the concept of current record pointer in data binding, see Use the Master-Detail Pattern with Hierarchical Data or Data Binding Overview.

Примечание

Внешне этот синтаксис напоминает XPath.Superficially, this syntax resembles XPath. Истинное выражение XPath для привязки к источнику данных XML не используется в качестве Pathого значения и должно использоваться для взаимоисключающего XPath свойства.A true XPath expression for binding to an XML data source is not used as a Path value and should instead be used for the mutually exclusive XPath property.

Представления коллекцийCollection Views

Для ссылки на представление именованной коллекции перед именем представления используется символ решетки (#).To reference a named collection view, prefix the collection view name with the hash character (#).

Указатель текущей записиCurrent Record Pointer

Чтобы ссылаться на указатель текущей записи для представления коллекции или сценария привязки данных "Основной/подробности", в начале строки пути поставьте косую черту (/).To reference the current record pointer for a collection view or master detail data binding scenario, start the path string with a forward slash (/). Обход любого пути, проходящего через косую черту, начинается с указателя текущей записи.Any path past the forward slash is traversed starting from the current record pointer.

Несколько индексаторовMultiple Indexers

<object Path="[index1,index2...]" .../>

илиor

<object Path="propertyName[index,index2...]" .../>

Если данный объект поддерживает несколько индексаторов, их можно указать по порядку, аналогично синтаксису ссылок на массив.If a given object supports multiple indexers, those indexers can be specified in order, similar to an array referencing syntax. Рассматриваемый объект может быть либо текущим контекстом, либо значением свойства, содержащего объект с несколькими индексами.The object in question can be either the current context or the value of a property that contains a multiple index object.

По умолчанию значения индексатора вводятся с использованием характеристик базового объекта.By default, the indexer values are typed by using the characteristics of the underlying object. При необходимости можно указать тип индекса.You can specify the type of the index if necessary. Дополнительные сведения о вводе индексаторов см. в разделе Binding.Path.For details on typing the indexers, see Binding.Path.

Смешанные синтаксисыMixing Syntaxes

Можно смешивать все синтаксисы, показанные выше.Each of the syntaxes shown above can be interspersed. Например, ниже приведен пример, в котором создается путь к свойству для цвета в определенном x, y свойства ColorGrid, содержащем массивную сетку SolidColorBrush объектов:For instance, the following is an example that creates a property path to the color at a particular x,y of a ColorGrid property that contains a pixel grid array of SolidColorBrush objects:

<Rectangle Fill="{Binding ColorGrid[20,30].SolidColorBrushResult}" .../>

Escape-символы для строк путей к свойствамEscapes for Property Path Strings

Для некоторых бизнес-объектов может возникнуть случай, когда для правильного анализа строки пути к свойству требуется escape-последовательность.For certain business objects, you might encounter a case where the property path string requires an escape sequence in order to parse correctly. Такая необходимость должна возникать редко, так как многие из этих символов имеют аналогичные проблемы взаимодействия при именовании в языках, которые обычно используются для определения бизнес-объекта.The need to escape should be rare, because many of these characters have similar naming-interaction issues in languages that would typically be used to define the business object.

  • Внутри индексаторов ([ ]) символ каретки (^) служит escape-символом для следующего символа.Inside indexers ([ ]), the caret character (^) escapes the next character.

  • Необходимо предварять escape-символами (используя XML-сущности) определенные символы, которые являются специальными для определения языка XML.You must escape (using XML entities) certain characters that are special to the XML language definition. Используйте & в качестве escape-символа для символа &.Use & to escape the character "&". Используйте > в качестве escape-символа для символа >.Use > to escape the end tag ">".

  • Необходимо предварять escape-символами (с помощью обратной косой черты \) символы, которые являются специальными для поведения средства синтаксического анализа WPF XAML для обработки расширения разметки.You must escape (using backslash \) characters that are special to the WPF XAML parser behavior for processing a markup extension.

    • Обратная косая черта (\) сама по себе является escape-символом.Backslash (\) is the escape character itself.

    • Знак равенства (=) разделяет имя и значение свойства.The equal sign (=) separates property name from property value.

    • Запятая (,) разделяет свойства.Comma (,) separates properties.

    • Закрывающая фигурная скобка (}) — это конец расширения разметки.The right curly brace (}) is the end of a markup extension.

Примечание

С технической точки зрения, эти escape-последовательности также работают для пути к свойству раскадровки, но обычно объектные модели обходятся для существующих объектов WPF и использование escape-символов не требуется.Technically, these escapes work for a storyboard property path also, but you are usually traversing object models for existing WPF objects, and escaping should be unnecessary.

PropertyPath для целевых объектов анимацииPropertyPath for Animation Targets

Свойство Target анимации должно быть свойством зависимости, которое принимает либо Freezable, либо примитивный тип.The target property of an animation must be a dependency property that takes either a Freezable or a primitive type. Однако целевое свойство типа и конечное анимированное свойство могут существовать в различных объектах.However, the targeted property on a type and the eventual animated property can exist on different objects. Для анимаций путь к свойству используется для определения связи между свойством целевого объекта именованной анимации и заданным целевым свойством анимации путем обхода отношений "объект/свойство" в значениях свойств.For animations, a property path is used to define the connection between the named animation target object's property and the intended target animation property, by traversing object-property relationships in the property values.

Общие рекомендации для отношений "объект/свойство" для анимацийGeneral Object-Property Considerations for Animations

Подробнее о концепциях анимации в целом см. в разделах Общие сведения о раскадровке и Общие сведения об анимации .For more information on animation concepts in general, see Storyboards Overview and Animation Overview.

Тип значения или анимированное свойство должны быть либо типом Freezable, либо примитивом.The value type or the property being animated must be either a Freezable type or a primitive. Свойство, запускающее путь, должно быть разрешено в качестве имени свойства зависимости, существующего для указанного типа TargetName.The property that starts the path must resolve to be the name of a dependency property that exists on the specified TargetName type.

Для поддержки клонирования для анимации Freezable, которая уже заморожена, объект, заданный TargetName, должен быть FrameworkElementным или FrameworkContentElement производным классом.In order to support cloning for animating a Freezable that is already frozen, the object specified by TargetName must be a FrameworkElement or FrameworkContentElement derived class.

Одно свойство в целевом объектеSingle Property on the Target Object

<animation Storyboard.TargetProperty="propertyName" .../>

propertyName должен быть разрешен в качестве имени свойства зависимостей, существующего в указанном типе TargetName.propertyName must resolve to be the name of a dependency property that exists on the specified TargetName type.

Косвенное назначение свойстваIndirect Property Targeting

<animation Storyboard.TargetProperty="propertyName.propertyName2" .../>

propertyName должно быть свойством, которое является типом значения Freezable или примитивом, который существует для указанного типа TargetName.propertyName must be a property that is either a Freezable value type or a primitive, which exists on the specified TargetName type.

propertyName2 должно быть именем свойства зависимостей, существующего в объекте, который является значением propertyName.propertyName2 must be the name of a dependency property that exists on the object that is the value of propertyName. Иными словами, propertyName2 должны существовать как свойство зависимостей для типа, который является propertyName PropertyType.In other words, propertyName2 must exist as a dependency property on the type that is the propertyName PropertyType.

Косвенное назначение анимации необходимо из-за примененных стилей и шаблонов.Indirect targeting of animations is necessary because of applied styles and templates. Чтобы ориентироваться на анимацию, требуется TargetName на целевом объекте, и это имя устанавливается с помощью x:Name или Name.In order to target an animation, you need a TargetName on a target object, and that name is established by x:Name or Name. Хотя элементы шаблона и стиля также могут иметь имена, эти имена действительны только в области имен стиля и шаблона.Although template and style elements also can have names, those names are only valid within the namescope of the style and template. (Если бы шаблоны и стили совместно использовали пространства имен с разметкой приложения, имена не могли бы быть уникальными.(If templates and styles did share namescopes with application markup, names couldn't be unique. Стили и шаблоны буквально совместно используются экземплярами и будут постоянно дублировать имена.) Таким способом, если отдельные свойства элемента, которые вы хотели бы анимировать, поступили из стиля или шаблона, необходимо начать с именованного экземпляра элемента, который не относится к шаблону стиля, а затем перейти к визуальному дереву стиля или шаблона, чтобы оно поступало на свойство Вы хотите анимировать.The styles and templates are literally shared between instances and would perpetuate duplicate names.) Thus, if the individual properties of an element that you might wish to animate came from a style or template, you need to start with a named element instance that is not from a style template, and then target into the style or template visual tree to arrive at the property you wish to animate.

Например, свойство Background Panel является полным Brush (фактически SolidColorBrush), полученным из шаблона темы.For instance, the Background property of a Panel is a complete Brush (actually a SolidColorBrush) that came from a theme template. Чтобы полностью анимировать Brush, необходимо быть Брушаниматион (возможно, по одному для каждого типа Brush) и такого типа нет.To animate a Brush completely, there would need to be a BrushAnimation (probably one for every Brush type) and there is no such type. Чтобы анимировать кисть, необходимо анимировать свойства определенного типа Brush.To animate a Brush, you instead animate properties of a particular Brush type. Чтобы применить ColorAnimation, необходимо получить от SolidColorBrush до Color.You need to get from SolidColorBrush to its Color to apply a ColorAnimation there. Путь к свойству в этом примере будет Background.Color.The property path for this example would be Background.Color.

Вложенные свойстваAttached Properties

<animation Storyboard.TargetProperty="(ownerType.propertyName)" .../>

Круглые скобки указывают, что это свойство в PropertyPath должно быть создано с использованием частичной квалификации.The parentheses indicate that this property in a PropertyPath should be constructed using a partial qualification. Для поиска типа может использоваться пространство имен XML.It can use an XML namespace to find the type. ownerType ищет типы, к которым обработчик XAMLXAML имеет доступ, через объявления XmlnsDefinitionAttribute в каждой сборке.The ownerType searches types that a XAMLXAML processor has access to, through the XmlnsDefinitionAttribute declarations in each assembly. В большинстве приложений есть пространство имен XML по умолчанию, сопоставленное пространству имен http://schemas.microsoft.com/winfx/2006/xaml/presentation, поэтому префикс обычно требуется только для настраиваемых типов или типов вне этого пространства имен.Most applications have the default XML namespace mapped to the http://schemas.microsoft.com/winfx/2006/xaml/presentation namespace, so a prefix is usually only necessary for custom types or types otherwise outside that namespace. propertyName должно разрешаться как имя свойства, существующего в ownerType.propertyName must resolve to be the name of a property existing on the ownerType. Свойство, указанное как propertyName, должно быть DependencyProperty.The property specified as propertyName must be a DependencyProperty. (Все присоединенные свойства WPFWPF реализуются как свойства взаимозависимостей, поэтому эта проблема возникает только для настраиваемых присоединенных свойств.)(All WPFWPF attached properties are implemented as dependency properties, so this issue is only of concern for custom attached properties.)

ИндексаторыIndexers

<animation Storyboard.TargetProperty="propertyName.propertyName2[index].propertyName3" .../>

Большинство свойств зависимости или типов Freezable не поддерживают индексатор.Most dependency properties or Freezable types do not support an indexer. Таким образом, единственное использование индексатора в пути к анимации — это промежуточное положение между свойством, которое запускает цепочку в именованном целевом объекте и конечным анимированным свойством.Therefore, the only usage for an indexer in an animation path is at an intermediate position between the property that starts the chain on the named target and the eventual animated property. В предоставленном синтаксисе это propertyName2.In the provided syntax, that is propertyName2. Например, может потребоваться использование индексатора, если промежуточное свойство является коллекцией, например TransformGroup, в пути к свойству, например RenderTransform.Children[1].Angle.For instance, an indexer usage might be necessary if the intermediate property is a collection such as TransformGroup, in a property path such as RenderTransform.Children[1].Angle.

PropertyPath в кодеPropertyPath in Code

Использование кода для PropertyPath, включая создание PropertyPath, описано в справочном разделе, посвященном PropertyPath.Code usage for PropertyPath, including how to construct a PropertyPath, is documented in the reference topic for PropertyPath.

В целом PropertyPath предназначен для использования двух различных конструкторов: один для использования привязки и простейший способ использования анимации, а второй — для сложных использований анимации.In general, PropertyPath is designed to use two different constructors, one for the binding usages and simplest animation usages, and one for the complex animation usages. Используйте PropertyPath(Object) подпись для использования привязки, где объект является строкой.Use the PropertyPath(Object) signature for binding usages, where the object is a string. Используйте сигнатуру PropertyPath(Object) для одношаговых путей анимации, где объект является DependencyProperty.Use the PropertyPath(Object) signature for one-step animation paths, where the object is a DependencyProperty. Используйте подпись PropertyPath(String, Object[]) для сложных анимаций.Use the PropertyPath(String, Object[]) signature for complex animations. Последний конструктор использует строку токена для первого параметра и массив объектов, которые заполняют позиции в строке токена, чтобы определить отношение пути к свойству.This latter constructor uses a token string for the first parameter and an array of objects that fill positions in the token string to define a property path relationship.

См. такжеSee also