Синтаксис PropertyPath XAML
Объект PropertyPath поддерживает сложный встроенный синтаксис XAML для установки различных свойств, которые принимают тип PropertyPath как их значение. Этот раздел описывает синтаксис PropertyPath в применении к синтаксису привязки и анимации.
В этом разделе содержатся следующие подразделы.
- Где используется PropertyPath
- PropertyPath для объектов в связывании данных
- PropertyPath для целей анимации
- PropertyPath в коде
- Связанные разделы
Где используется PropertyPath
PropertyPath является общим объектом, который используется в нескольких возможностях Windows Presentation Foundation (WPF). Несмотря на использование общего PropertyPath для передачи сведений о пути свойства, это свойство используется для каждой области, где PropertyPath используется в качестве иного типа. Таким образом, оно является более удобным для документирования синтаксиса на основе возможностей.
В основном, WPF использует PropertyPath для описания путей модели объектов для обхода свойств источника данных объекта и описания заданного пути для заданной анимации.
Некоторые свойства стилей и шаблонов, например Setter.Property, принимают полное имя свойства, которое внешне напоминает PropertyPath. Однако это неверный PropertyPath; вместо этого используется полный строковый формат владелец.свойство, который предоставляется процессором WPF XAML в сочетании с преобразователем типа для DependencyProperty.
PropertyPath для объектов в связывании данных
Связывание данных является возможностью WPF, при помощи которой можно привязать заданное значение любого свойства зависимости. Однако источником привязки данных не должно быть свойство зависимости; им может быть любой тип, распознаваемый применимым поставщиком данных. Пути свойства особенно часто используются для ObjectDataProvider, который используется для получения источников привязки из объектов common language runtime (CLR) и их свойств.
Обратите внимание, что привязка данных к XML не использует PropertyPath, так как она не использует Path в Binding. Вместо этого используйте свойство XPath и укажите допустимый синтаксис XPath в XML Document Object Model (DOM) данных. XPath также задается как строка, но не документируется здесь; см. раздел Практическое руководство. Привязка к данным xml с помощью XMLDataProvider и запросов XPath.
Ключом для понимания путей свойства в связывании данных является то, что можно назначить привязку к отдельному значению свойства, или вместо этого можно сделать привязку к заданным свойствам, которые принимают списки или коллекций. Если связываются коллекции, например ListBox, расширяющаяся в зависимости от количества элементов данных в коллекции, путь свойства должен ссылаться на объект коллекции, а не на отдельные элементы коллекции. Ядро привязки данных будет соответствовать коллекции, используемой как источник данных для типа целевого объекта привязки автоматически, что приводит к заполнению ListBox массивом элементов.
Одинарное свойство для интерпретации объекта как контекста данных
<Binding Path="propertyName" .../>
propertyName должно быть именем свойства в текущем DataContext для использования Path. Если привязка обновляет источник, то это свойство должно быть для чтения/записи, и исходный объект должен быть изменяемым.
Одинарный индексатор для интерпретации объекта как контекста данных
<Binding Path="[key]" .../>
key должен быть либо типизированным индексом для словаря или хэш-таблицы, либо целочисленным индексом массива. Кроме того, значением ключа должен быть тип, являющийся непосредственно привязываемым к свойству, где оно применяется. Например, хэш-таблица, содержащая строку ключей и строковые значения, может использоваться таким образом для привязки к тексту для TextBox. Или, если ключ указывает на коллекцию или подиндекс, то можно использовать этот синтаксис для привязки к заданному свойству коллекции. В противном случае, необходимо ссылаться на конкретное свойство с помощью синтаксиса, такого как <Binding Path="[key].propertyName" .../>.
Можно указать тип индекса, если необходимо. Более подробные сведения об этом аспекте индексированного пути свойства см. в разделе Binding.Path.
Множественное свойство (косвенная ссылка на свойство)
<Binding Path="propertyName.propertyName2" .../>
propertyName должно быть именем свойства, являющимся текущим DataContext. Свойства пути propertyName и propertyName2 могут быть любыми свойствами, которые существуют в отношении, где propertyName2 является свойством, существующем для типа, который является значением propertyName.
Одинарное свойство, присоединенное или с указанием типа
<object property="(ownerType.propertyName)" .../>
Скобки указывают, что это свойство в PropertyPath должно быть создано с помощью частичной квалификации. Это позволяет использовать пространство имен XML для поиска типа с соответствующим сопоставлением. Свойство ownerType ищет типы, к которым процессор XAML имеет доступ, с помощью объявлений XmlnsDefinitionAttribute в каждой сборке. В большинстве приложений по умолчанию пространство имен XML сопоставлено с пространством имен https://schemas.microsoft.com/winfx/2006/xaml/presentation, поэтому префикс необходим обычно только для пользовательских типов или типов вне этого пространства имен. Объект propertyName должен быть именем свойства, существующим в ownerType. Этот синтаксис обычно используется в одном из следующих случаев:
Путь задается в XAML, который находится в стиле или шаблоне, не имеющем указанного целевого типа. Полное использование, как правило, недопустимо в других случаях, так как без использования стиля или шаблона свойство, которое существует в экземпляре, не является типом.
Свойство является вложенным свойством.
При привязке к статическому свойству.
Для использования в качестве заданной раскадровки, свойство, определенное как propertyName, должно быть DependencyProperty.
Источник прохождений (привязка к иерархиям коллекции)
<object Path="propertyName/propertyNameX" .../>
Прямая косая черта / в синтаксисе используется для перехода между объектом источника иерархических данных и несколькими переходами в иерархию с последовательной/посимвольной поддержкой. Источник перехода отсчитывается для текущей позиции указателя записи, которая определяется синхронизацией данных с помощью пользовательского интерфейса его представления. Сведения о связывании с объектами иерархических данных источника и концепция текущего указателя записи в связывании данных см. в разделе Практическое руководство. Использование шаблона "основной-подчиненный" с иерархическими данными или Общие сведения о связывании данных.
.gif "Примечание") Примечание |
|---|
Внешне данный синтаксис имеет сходство с XPath.Истинное выражение XPath для привязки к источнику данных XML не используется как значение Path, вместо этого следует его использовать для взаимно исключающего свойства XPath. |
Представления коллекций
Чтобы создать ссылку на представление именованной коллекции, добавьте к имени представления коллекции префикс в виде символа решетки (#).
Указатель текущей записи
Чтобы создать ссылку на указатель текущей записи для представления коллекции или главный сценарий привязки к подробным данным, начините строку пути косой чертой (/). Любой путь после прямой косой черты обходится, начиная с указателя текущей записи.
Множественные индексаторы
<object Path="[index1,index2...]" .../>
or
<object Path="propertyName[index,index2...]" .../>
Если данный объект поддерживает множественные индексаторы, то эти индексаторы можно указать в порядке, аналогичном синтаксису ссылок массива. Рассматриваемый объект может быть либо текущим контекстом, либо значением свойства, которое содержит объект с несколькими индексами.
По умолчанию значения индексатора введены с помощью характеристик базового объекта. Можно указать тип индекса, если необходимо. Сведения о вводе индексаторов см. в разделе Binding.Path.
Смешанные синтаксисы
Каждый из синтаксисов, показанных выше, может быть интерпретирован. Ниже приведен пример, который создает путь свойства к цвета на отдельных x,y для свойства ColorGrid, которое содержит массив сетки пикселей объектов SolidColorBrush:
<Rectangle Fill="{Binding ColorGrid[20,30].SolidColorBrushResult}" .../>
Escape-последовательности для строк путей свойств
Для определенных бизнес-объектов может возникнуть случай, когда для корректного анализа строки пути к свойствам требуется escape-последовательность. Необходимость в применении escape-символов должна возникать редко, так как многие из этих символов имеют аналогичные проблемы взаимодействия при именовании в тех языках, которые обычно используются для определения бизнес-объектов.
Внутри индексаторов ([ ]) знак "крышки" (^) используется для пропуска следующего символа.
Некоторые символы со специальным значением в определении языка XML необходимо преобразовать в escape-последовательность (с помощью сущностей XML). Чтобы избежать знака "&", используйте выражение &. Чтобы избежать завершающего тега ">", используйте выражение >.
Символы, специально используемые в синтаксическом анализаторе WPF XAML при обработке расширения разметки, необходимо преобразовать в escape-последовательность (с помощью обратной косой черты \).
Знак обратной косой черты (\) используется в качестве escape-символа для самого себя.
Знак равенства (=) разделяет имя и значение свойства.
Запятая (,) разделяет свойства.
Правая фигурная скобка (}) определяет конец расширения разметки.
| Примечание |
|---|
С технической точки зрения эти escape-последовательности работают также для пути свойства раскадровки, но обычно для существующих объектов WPF выполняется обход объектных моделей, и escape-преобразование оказывается ненужным. |
PropertyPath для целей анимации
Целевым свойством анимации должно быть свойство зависимости, которое принимает Freezable или простой тип. Однако заданное свойство для типа и возможное анимированное свойство может существовать для различных объектов. Для анимации путь свойства используется для определения соединения между свойством именованного заданного объекта анимации и предполагаемым свойством заданной анимации путем обхода связей свойства объекта в значениях свойства.
Общие вопросы свойств объекта для анимации
Дополнительные сведения об общих концепциях анимации см. в разделе Общие сведения о Storyboard Общие сведения об эффектах анимации.
Тип значения или свойство для анимации должны быть или Freezable, или простым типом. Свойство, которое запускает путь, должно быть именем свойства зависимости, которое существует в указанном типе TargetName.
Чтобы поддерживать клонирование для анимации объекта Freezable, который уже блокирован, объект, заданный свойством TargetName, должен быть производным классом FrameworkElement или FrameworkContentElement.
Одинарное свойство для конечного объекта
<animation Storyboard.TargetProperty="propertyName" .../>
Свойство propertyName должно быть именем свойства зависимости, которое существует для указанного типа TargetName.
Косвенное задание свойства
<animation Storyboard.TargetProperty="propertyName.propertyName2" .../>
Свойство propertyName должно быть либо типом значения Freezable, либо простым типом, который существует для указанного типа TargetName.
Свойство propertyName2 должно быть именем свойства зависимости, существующего для объекта, который является значением propertyName. Другими словами, propertyName2 должно существовать как свойство зависимости для типа, которым является свойством PropertyType propertyName.
Косвенное задание анимации необходимо, потому что применяются стили и шаблоны. Чтобы задать анимацию, требуется TargetName для конечного объекта, и это имя устанавливается как x:Name или Name. Хотя шаблоны и стили элементов также могут иметь имена, эти имена допустимы только в пределах области видимости имени стиля или шаблона. (Если шаблоны и стили имели общую область видимости имен с разметкой приложения, имена не могут быть уникальными. Стили и шаблоны буквально распределены между экземплярами и сохранили бы повторяющиеся имена.) Таким образом, если отдельные свойства элемента, который нужно анимировать, поставляются из стиля или шаблона, необходимо начать с именованного экземпляра элемента, который не поставляется из шаблона стиля, и затем перейти к стилю или шаблону визуального дерева для получения свойства, которое нужно анимировать.
Например, свойство Background для Panel является полным классом Brush (а именно, SolidColorBrush), поставляемым из шаблона темы. Чтобы полностью анимировать Brush, потребуется BrushAnimation (возможно, один для каждого типа Brush), и такой тип отсутствует. Чтобы анимировать Brush, вместо этого анимируйте свойства конкретного типа Brush. Чтобы применить здесь ColorAnimation, необходимо вернуться из SolidColorBrush к его свойству Color. Путь свойства для этого примера должен быть Background.Color.
Вложенные свойства
<animation Storyboard.TargetProperty="(ownerType.propertyName)" .../>
Скобки указывают, что это свойство в PropertyPath должно быть создано с помощью частичной квалификации. Это позволяет использовать пространство имен XML для поиска типа. Свойство ownerType ищет типы, к которым процессор XAML имеет доступ, с помощью объявлений XmlnsDefinitionAttribute в каждой сборке. В большинстве приложений по умолчанию пространство имен XML сопоставлено с пространством имен https://schemas.microsoft.com/winfx/2006/xaml/presentation, поэтому префикс необходим обычно только для пользовательских типов или типов вне этого пространства имен. Объект propertyName должен быть именем свойства, существующим в ownerType. Свойство, заданное как propertyName, должно быть DependencyProperty. (Все вложенные свойства WPF реализуются как свойства зависимости, поэтому эта проблема возникает только для настраиваемых вложенных свойств.)
Indexers
<animation Storyboard.TargetProperty="propertyName.propertyName2[index].propertyName3" .../>
Большинство свойств зависимости или типов Freezable не поддерживают индексатор. Поэтому использование только индексатора в пути анимации является промежуточной позицией между свойством, которое начинает цепочку в именованной цели, и возможным анимированным свойством. В представленном синтаксисе этоpropertyName2. Например, использование индексатора может потребоваться, если промежуточное свойство является коллекцией, например TransformGroup, в пути свойства, например RenderTransform.Children[1].Angle.
PropertyPath в коде
Использование кода для PropertyPath, включая способ создания PropertyPath, описано в разделе ссылок для PropertyPath.
В общем случае, объект PropertyPath предназначен для использования двух различных конструкторов: один — для привязки и простого применения анимации, и один — для применения сложной анимации. Используйте подпись PropertyPath(Object) для привязки, когда объектом является строка. Используйте подпись PropertyPath(Object) для путей одношаговой анимации, где объектом является DependencyProperty. Используйте подпись PropertyPath(String, Object[]) для сложной анимации. Этот последний конструктор использует строку токена для первого параметра и массив объектов, которые заполняют позиции в строке токена, чтобы определить отношение пути свойства.