Classes de personalizadas para WPF e XAML

Extensible Application Markup Language (XAML)conforme implementado.NET oferece suporte a capacidade de definir uma classe personalizada ou uma estrutura em qualquer common language runtime (CLR) idioma e, em seguida, acesso que a classe usando XAML marcação. Você pode usar uma mistura de Windows Presentation Foundation (WPF)-definido tipos e seus tipos personalizados dentro do mesmo arquivo de marcação, normalmente, mapeando os tipos personalizados a um prefixo de namespace XAML. This topic discusses the requirements that a custom class must satisfy to be usable as a XAML element.

Este tópico contém as seguintes seções.

• Custom Classes in Applications or Assemblies
• Requirements for a Custom Class as a XAML Element
• Requirements for Properties of a Custom Class as XAML Attributes
• Requirements for XAML Event Handler Attribute Syntax on Events of a Custom Class
• Writing Collection Properties
• Declaring XAML Content Properties
• Serializing XAML
• Tópicos relacionados

Custom Classes in Applications or Assemblies

Classes personalizadas que são usadas em XAML podem ser definidos de duas maneiras distintas: no code-behind ou outro código que produz o principal Windows Presentation Foundation (WPF) aplicativo, ou como uma classe em um assembly separado, como um executável ou DLL usada como uma biblioteca de classe. Each of these approaches has particular advantages and disadvantages.

• The advantage of creating a class library is that any such custom classes can be shared across many different possible applications. Uma biblioteca separada também facilita a controle de questões de versão dos aplicativos e simplifica a criação de uma classe onde o uso pretendido de classe é como um elemento raiz em um XAML página.

• A vantagem da definição das classes personalizadas no aplicativo é que essa técnica é relativamente simples e minimiza a implantação e testes problemas encontrados ao apresentar o conjuntos separados além do executável do aplicativo principal. No entanto, uma desvantagem notável é a que você não pode usar classes definidas no mesmo assembly como elemento raiz dos outros XAML páginas no aplicativo.

• Se definido no assembly iguais ou diferente, classes personalizadas precisam ser mapeados entre o namespace CLR e o namespace XML para ser usado em XAML como elementos. See Namespaces XAML e o mapeamento de Namespace para WPF XAML.

Requirements for a Custom Class as a XAML Element

In order to be able to be instantiated as an object element, your class must meet the following requirements:

• Your custom class must be public and support a default (parameterless) public constructor. (Consulte a próxima seção para notas de estruturas).

• Sua classe personalizada não deve ser uma classe aninhada. Classes aninhadas e "dot" seus CLR geral sintaxe de uso interferem com os outros WPF e/ou propriedades de recursos anexados como XAML.

Além de habilitar a sintaxe de elemento de objeto, a definição de objeto também permite sintaxe de elemento de propriedade para quaisquer propriedades pública que utilizam esse objeto como o tipo de valor. This is because the object can now be instantiated as an object element and can fill the property element value of such a property.

Structures

Estruturas que você define como tipos personalizados são sempre capazes de ser construído no XAML na WPF .Isso ocorre porque o CLR compiladores criar implicitamente um construtor padrão para uma estrutura que inicializa todos os valores de propriedade para seus padrões. Em alguns casos, o padrão construção comportamento e/ou o objeto elemento uso para uma estrutura não é desejável. Talvez a estrutura é destinada a valores de preenchimento e a função conceitualmente como uma união, onde os valores contidos podem ter interpretações mutuamente e, portanto, nenhuma de suas propriedades são configuráveis. A WPF exemplo dessa estrutura é GridLength. Geralmente, essas estruturas devem implementar um conversor de tipo de modo que os valores podem ser expressos no formulário de atributo, usando as convenções de seqüência para criam a diferentes interpretações ou modos dos valores da estrutura. A estrutura também deve expor um comportamento semelhante para construção de código por meio de um construtor não-padrão.

Requirements for Properties of a Custom Class as XAML Attributes

Propriedades devem fazer referência a um tipo por valor (como um primitivo) ou usar uma classe para o tipo que tem um construtor padrão ou um conversor de tipo dedicado que pode ser acessados por um processador XAML. A implementação do CLR XAML, processadores XAML ou localizar esses conversores por meio do suporte nativo para os primitivos de idioma ou aplicativos de TypeConverterAttribute para um tipo ou membro fazer definições de tipo

Alternatively, the property may reference an abstract class type, or an interface. Interfaces ou classes abstratas, a expectativa de análise de XAML é que o valor da propriedade deve ser preenchido com instâncias de classe prático que implementam a interface ou instâncias de tipos que derivam da classe abstrata.

Propriedades podem ser declaradas em uma classe abstrata, mas só podem ser definidas em práticas classes que derivam da classe abstrata. Isso ocorre porque a criação de elemento de objeto para a classe em todos os exige um construtor público padrão da classe.

TypeConverter habilitado a sintaxe de atributo

If you provide a dedicated, attributed type converter at the class level, the applied type conversion enables attribute syntax for any property that needs to instantiate that type. A type converter does not enable object element usage of the type; only the presence of a default constructor for that type enables object element usage. Therefore, properties that are type-converter enabled are generally speaking not usable in property syntax, unless the type itself also supports object element syntax. The exception to this is that you can specify a property element syntax, but have the property element contain a string. That usage is really essentially equivalent to an attribute syntax usage, and such a usage is not common unless there is a need for more robust whitespace handling of the attribute value. For example, the following is a property element usage that takes a string, and the attribute usage equivalent:

<Button>Hallo!
  <Button.Language>
    de-DE
  </Button.Language>
</Button>

<Button Language="de-DE">Hallo!</Button>

Examples of properties where attribute syntax is allowed but property element syntax that contains an object element is disallowed through XAML are various properties that take the Cursor type. The Cursor class has a dedicated type converter CursorConverter, but does not expose a default constructor, so the Cursor property can only be set through attribute syntax even though the actual Cursor type is a reference type.

Per-Property Type Converters

Alternatively, the property itself may declare a type converter at the property level. This enables a "mini language" that instantiates objects of the type of the property inline, by processing incoming string values of the attribute as input for a ConvertFrom operation based on the appropriate type. Typically this is done to provide a convenience accessor, and not as the sole means to enable setting a property in XAML. However, it is also possible to use type converters for attributes where you want to use existing CLR types that do not supply either a default constructor or an attributed type converter. Exemplos deWPF  APIssão determinadas propriedades que levam a CultureInfo tipo. Nesse caso, WPF usado existente Microsoft .NET Framework CultureInfo tipo de lidar melhor com os cenários de migração e de compatibilidade que foram usados em versões anteriores das estruturas, mas o CultureInfo tipo não oferecem suporte a construtores necessários ou conversão de tipo de nível do tipo a ser usado como um XAML diretamente o valor da propriedade.

Whenever you expose a property that has a XAML usage, particularly if you are a control author, you should strongly consider backing that property with a dependency property. Isso é especialmente verdadeiro se você usar a existente Windows Presentation Foundation (WPF) a implementação da XAML processador, porque você pode melhorar o desempenho usando DependencyProperty backup. A dependency property will expose property system features for your property that users will come to expect for a XAML accessible property. This includes features such as animation, data binding, and style support. For more information, see Propriedades de Dependência Personalizada and Carregando XAML e Propriedades de Dependência.

Writing and Attributing a Type Converter

Ocasionalmente, será necessário escrever um personalizado TypeConverter derivado da classe para fornecer conversão de tipo para o tipo de propriedade. For instructions on how to derive from and create a type converter that can support XAML usages, and how to apply the TypeConverterAttribute, see TypeConverters and XAML.

Requirements for XAML Event Handler Attribute Syntax on Events of a Custom Class

To be usable as a CLR event, the event must be exposed as a public event on a class that supports a default constructor, or on an abstract class where the event can be accessed on derived classes. In order to be used conveniently as a routed event, your CLR event should implement explicit add and remove methods, which add and remove handlers for the CLR event signature and forward those handlers to the AddHandler and RemoveHandler methods. These methods add or remove the handlers to the routed event handler store on the instance that the event is attached to.

Writing Collection Properties

Properties that take a collection type have a XAML syntax that enables you to specify objects that are added to the collection. This syntax has two notable features.

• The object that is the collection object does not need to be specified in object element syntax. The presence of that collection type is implicit whenever you specify a property in XAML that takes a collection type.

• Elementos filho de propriedade de coleção na marcação são processados para se tornar membros da coleção. Normalmente, o acesso ao código para os membros de uma coleção é realizado por meio de métodos de lista para o dicionário como Add, ou através de um indexador. Mas XAML sintaxe não oferece suporte a métodos ou indexadores. Collections are obviously a very common requirement for building a tree of elements, and you need some way to populate these collections in declarative XAML. Therefore, child elements of a collection property are processed by adding them to the collection that is the collection property type value.

A.NET XAML implementação e, portanto, o processador do WPF XAML usa a seguinte definição para o que constitui uma propriedade de coleção. The property type of the property must implement one of the following:

• Implementa IList.

• Implements IDictionary or the generic equivalent (IDictionary<TKey, TValue>).

• Derives from Array (for more information about arrays in XAML, see x:Array de marcação de extensão.)

• Implements IAddChild (an interface defined by WPF).

Cada um desses tipos CLR tem um Add método, que é usado pelo XAML o processador para adicionar itens à coleção subjacente ao criar o gráfico do objeto.

When you declare a property that takes a collection, be cautious about how that property value is initialized in new instances of the type. If you are not implementing the property as a dependency property, then having the property use a backing field that calls the collection type constructor is adequate. If your property is a dependency property, then you may need to initialize the collection property as part of the default type constructor. Isso ocorre porque um propriedade de dependência leva seu padrão de valor de metadados e normalmente não deseja o valor inicial de uma propriedade de coleção a ser um conjunto estático, compartilhado. Deve haver uma instância da coleção por cada instância do tipo recipiente. For more information, see Propriedades de Dependência Personalizada.

You can implement a custom collection type for your collection property. Because of implicit collection property treatment, the custom collection type does not need to provide a default constructor in order to be used in XAML implicitly. However, you can optionally provide a default constructor for the collection type. Isso pode ser uma prática vale a pena. A menos que você fornecer um construtor padrão, você não pode declarar explicitamente a coleção como um elemento de objeto. Some markup authors might prefer to see the explicit collection as a matter of markup style. Also, a default constructor can simplify the initialization requirements when you create new objects that use your collection type as a property value.

Declaring XAML Content Properties

O XAML linguagem define o conceito de um XAML propriedade de conteúdo. Cada classe que pode ser usado na sintaxe de objeto pode ter exatamente um XAML propriedade de conteúdo. Para declarar uma propriedade para ser a XAML propriedade para a sua classe de conteúdo, aplicar o ContentPropertyAttribute como parte da definição de classe. Specify the name of the intended XAML content property as the Name in the attribute.

You can specify a collection property to be the XAML content property. This results in a usage for that property whereby the object element can have one or more child elements, without any intervening collection object elements or property element tags. Esses elementos são considerados o valor para o XAML propriedade de conteúdo e adicionado à instância de coleção de backup.

Some existing WPF XAML content properties use the property type of Object. This enables a XAML content property that can take primitive values such as a String as well as taking a single reference object value. If you follow this model, your type is responsible for type determination as well as the handling of possible types. O motivo típico para um Object é do tipo de conteúdo para dar suporte a uma forma simples de adicionar o conteúdo do objeto como uma seqüência de caracteres (que recebe um tratamento de apresentação padrão), ou de um meio avançado de adicionar o conteúdo do objeto que especifica uma apresentação de não-padrão ou dados adicionais.

Serializing XAML

Para determinados cenários, como, por exemplo, se você for um autor de controle, você também deseja garantir que qualquer representação de objeto que pode ser instanciada em XAML também podem ser serializados para o equivalente XAML. Serialization requirements are not described in this topic. See Visão geral sobre criação de controles and Árvore de Elemento e Serialização.

Consulte também

Conceitos

Visão geral do XAML (WPF)

Propriedades de Dependência Personalizada

Visão geral sobre criação de controles

Visão geral sobre elementos base

Carregando XAML e Propriedades de Dependência