Guia de sintaxe do XAML

  • Artigo

Explicamos as regras de sintaxe XAML e a terminologia que descreve as restrições ou opções disponíveis para a sintaxe XAML. Este tópico será útil se você não estiver familiarizado com o uso da linguagem XAML, se quiser uma atualização sobre a terminologia ou partes da sintaxe ou se estiver curioso sobre como a linguagem XAML funciona e se quiser mais informações básicas e contextuais.

XAML é XML

XAML (Extensible Application Markup Language) tem uma sintaxe básica que se baseia em XML e, por definição, o XAML válido deve ser XML válido. Mas o XAML também tem seus próprios conceitos de sintaxe que estendem o XML. Uma determinada entidade XML pode ser válida em XML simples, mas essa sintaxe pode ter um significado diferente e mais completo como XAML. Este tópico explica esses conceitos de sintaxe XAML.

Vocabulários XAML

Uma área em que o XAML difere da maioria dos usos de XML é que o XAML normalmente não é imposto com um esquema, como um arquivo XSD. Isso ocorre porque o XAML deve ser extensível, é isso que significa o "X" no acrônimo XAML. Depois que o XAML é analisado, espera-se que os elementos e atributos que você referencia no XAML existam em alguma representação de código de suporte, seja nos tipos principais definidos pelo Tempo de Execução do Windows ou em tipos que estendem ou são baseados no Tempo de Execução do Windows. A documentação do SDK às vezes se refere aos tipos que já são internos ao Tempo de Execução do Windows e podem ser usados em XAML como sendo o vocabulário XAML para o Tempo de Execução do Windows. O Microsoft Visual Studio ajuda você a produzir marcação válida dentro desse vocabulário XAML. O Visual Studio também pode incluir seus tipos personalizados para uso em XAML, desde que a origem desses tipos seja referenciada corretamente no projeto. Para obter mais informações sobre XAML e tipos personalizados, consulte Namespaces XAML e mapeamento de namespace.

Declarando objetos

Os programadores geralmente pensam em termos de objetos e membros, enquanto uma linguagem de marcação é conceituada como elementos e atributos. No sentido mais básico, um elemento que você declara na marcação XAML se torna um objeto em uma representação de objeto de tempo de execução de suporte. Para criar um objeto de tempo de execução para seu aplicativo, você declara um elemento XAML na marcação XAML. O objeto é criado quando o Tempo de Execução do Windows carrega seu XAML.

Um arquivo XAML sempre tem exatamente um elemento servindo como sua raiz, que declara um objeto que será a raiz conceitual de alguma estrutura de programação, como uma página, ou o grafo de objeto de toda a definição de tempo de execução de um aplicativo.

Em termos de sintaxe XAML, há três maneiras de declarar objetos em XAML:

  • Diretamente, usando a sintaxe do elemento de objeto: usa marcas de abertura e fechamento para instanciar um objeto como um elemento de formulário XML. Você pode usar essa sintaxe para declarar objetos raiz ou para criar objetos aninhados que definem valores de propriedade.
  • Indiretamente, usando sintaxe de atributo: usa um valor de cadeia de caracteres embutido que tem instruções sobre como criar um objeto. O analisador XAML usa essa cadeia de caracteres para definir o valor de uma propriedade como um valor de referência recém-criado. O suporte para ele é limitado a determinados objetos e propriedades comuns.
  • Usando uma extensão de marcação.

Isso não significa que você sempre tem a opção de qualquer sintaxe para criação de objetos em um vocabulário XAML. Alguns objetos podem ser criados somente usando a sintaxe do elemento de objeto. Alguns objetos podem ser criados apenas sendo inicialmente definidos em um atributo. Na verdade, objetos que podem ser criados com sintaxe de elemento de objeto ou atributo são comparativamente raros em vocabulários XAML. Mesmo que ambas as formas de sintaxe sejam possíveis, uma das sintaxes será mais comum por uma questão de estilo. Também há técnicas que você pode usar em XAML para fazer referência a objetos existentes em vez de criar novos valores. Os objetos existentes podem ser definidos em outras áreas do XAML ou podem existir implicitamente por meio de algum comportamento da plataforma e seus modelos de aplicativo ou programação.

Declarando um objeto usando a sintaxe do elemento de objeto

Para declarar um objeto com sintaxe de elemento de objeto, escreva tags como esta: <objectName> </objectName>, em que objectName é o nome do tipo para o objeto que você deseja instanciar. Aqui está o uso do elemento de objeto para declarar um objeto Canvas:

<Canvas>
</Canvas>

Se o objeto não contiver outros objetos, você poderá declarar o elemento do objeto usando uma tag de fechamento automático em vez de um par de abertura/fechamento: <Canvas />

Contêineres

Muitos objetos usados como elementos de interface do usuário, como Canvas, podem conter outros objetos. Às vezes, eles são chamados de contêineres. O exemplo a seguir mostra um contêiner Canvas que contém um elemento, um Rectangle. 

<Canvas>
  <Rectangle />
</Canvas>

Declarando um objeto usando a sintaxe de atributo

Como esse comportamento está vinculado à configuração de propriedade, falaremos mais sobre isso nas próximas seções.

Texto de inicialização

Para alguns objetos, você pode declarar novos valores usando o texto interno usado como valores de inicialização para construção. Em XAML, essa técnica e sintaxe são chamadas de texto de inicialização. Conceitualmente, o texto de inicialização é semelhante a chamar um construtor que tem parâmetros. O texto de inicialização é útil para definir valores iniciais de determinadas estruturas.

Você geralmente usa uma sintaxe de elemento de objeto com texto de inicialização se quiser um valor de estrutura com um x:Key, para que ele possa existir em um ResourceDictionary. Você pode fazer isso se compartilhar esse valor de estrutura entre várias propriedades de destino. Para algumas estruturas, você não pode usar a sintaxe de atributo para definir os valores da estrutura: o texto de inicialização é a única maneira de produzir um recurso CornerRadius, Thickness, GridLength ou Color útil e compartilhável.

Este exemplo abreviado usa texto de inicialização para especificar valores para uma Espessura, neste caso, especificando valores que definem Esquerda e Direita como 20 e Superior e Inferior como 10. Este exemplo mostra a Espessura criada como um recurso com chave e, em seguida, a referência a esse recurso. Para obter mais informações sobre o texto de inicialização Espessura, consulte Espessura.

<UserControl ...>
  <UserControl.Resources>
    <Thickness x:Key="TwentyTenThickness">20,10</Thickness>
    ....
  </UserControl.Resources>
  ...
  <Grid Margin="{StaticResource TwentyTenThickness}">
  ...
  </Grid>
</UserControl ...>

Observação Algumas estruturas não podem ser declaradas como elementos de objeto. Não há suporte para texto de inicialização e eles não podem ser usados como recursos. Você deve usar uma sintaxe de atributo para definir propriedades para esses valores em XAML. Esses tipos são: Duration, RepeatBehavior, Point, Rect e Size.

Definir propriedades

Você pode definir propriedades em objetos declarados usando a sintaxe do elemento de objeto. Há várias maneiras de definir propriedades em XAML:

  • Usando a sintaxe de atributo.
  • Usando a sintaxe do elemento de propriedade.
  • Usando a sintaxe de elemento em que o conteúdo (texto interno ou elementos filho) está definindo a propriedade de conteúdo XAML de um objeto.
  • Usando uma sintaxe de coleção (que geralmente é a sintaxe de coleção implícita).

Assim como acontece com a declaração de objeto, essa lista não implica que qualquer propriedade possa ser definida com cada uma das técnicas. Algumas propriedades suportam apenas uma das técnicas. Algumas propriedades dão suporte a mais de uma forma; Por exemplo, há propriedades que podem usar a sintaxe de elemento de propriedade ou sintaxe de atributo. O que é possível depende da propriedade e do tipo de objeto que a propriedade usa. Na referência da API do Tempo de Execução do Windows, você verá os usos de XAML que podem ser usados na seção Sintaxe . Às vezes, há um uso alternativo que funcionaria, mas seria mais detalhado. Esses usos detalhados nem sempre são mostrados porque estamos tentando mostrar as práticas recomendadas ou os cenários do mundo real para usar essa propriedade em XAML. As diretrizes para a sintaxe XAML são fornecidas nas seções Uso de XAML das páginas de referência para propriedades que podem ser definidas em XAML.

Algumas propriedades em objetos não podem ser definidas em XAML de forma alguma e só podem ser definidas usando código. Normalmente, essas são propriedades mais apropriadas para trabalhar no code-behind, não no XAML.

Uma propriedade somente leitura não pode ser definida em XAML. Mesmo no código, o tipo proprietário teria que dar suporte a alguma outra maneira de defini-lo, como uma sobrecarga de construtor, método auxiliar ou suporte a propriedade calculada. Uma propriedade calculada depende dos valores de outras propriedades configuráveis e, às vezes, de um evento com manipulação interna; Esses recursos estão disponíveis no sistema de propriedades de dependência. Para obter mais informações sobre como as propriedades de dependência são úteis para suporte a propriedades calculadas, consulte Visão geral das propriedades de dependência.

A sintaxe de coleção em XAML dá a aparência de que você está definindo uma propriedade somente leitura, mas na verdade não está. Consulte "Sintaxe de coleção" mais adiante neste tópico.

Definindo uma propriedade usando a sintaxe de atributo

Definir um valor de atributo é o meio típico pelo qual você define um valor de propriedade em uma linguagem de marcação, por exemplo, em XML ou HTML. A configuração de atributos XAML é semelhante à forma como você define valores de atributo em XML. O nome do atributo é especificado em qualquer ponto dentro das tags após o nome do elemento, separado do nome do elemento por pelo menos um espaço em branco. O nome do atributo é seguido por um sinal de igual. O valor do atributo está contido em um par de aspas. As aspas podem ser aspas duplas ou aspas simples, desde que correspondam e delimitem o valor. O valor do atributo em si deve ser expressável como uma cadeia de caracteres. A cadeia de caracteres geralmente contém numerais, mas para XAML, todos os valores de atributo são valores de cadeia de caracteres até que o analisador XAML se envolva e faça alguma conversão de valor básico.

Este exemplo usa a sintaxe de atributo para quatro atributos para definir as propriedades Name, Width, Height e Fill de um objeto Rectangle.

<Rectangle Name="rectangle1" Width="100" Height="100" Fill="Blue" />

Definindo uma propriedade usando a sintaxe do elemento de propriedade

Muitas propriedades de um objeto podem ser definidas usando a sintaxe do elemento de propriedade. Um elemento de propriedade tem esta aparência: <propriedade> do objeto..

Para usar a sintaxe de elemento de propriedade, crie elementos de propriedade XAML para a propriedade que deseja definir. No XML padrão, esse elemento seria considerado apenas um elemento que tem um ponto em seu nome. No entanto, em XAML, o ponto no nome do elemento identifica o elemento como um elemento de propriedade, com a propriedade esperada para ser um membro do objeto em uma implementação de modelo de objeto de suporte. Para usar a sintaxe do elemento de propriedade, deve ser possível especificar um elemento de objeto para "preencher" as tags do elemento de propriedade. Um elemento de propriedade sempre terá algum conteúdo (elemento único, vários elementos ou texto interno); Não faz sentido ter um elemento de propriedade de fechamento automático.

Na gramática a seguir, property é o nome da propriedade que você deseja definir e propertyValueAsObjectElement é um único elemento de objeto, que deve atender aos requisitos de tipo de valor da propriedade.

<object>

<propriedade do objeto.>

propertyValueAsObjectElement

</propriedade do objeto.>

</object>

O exemplo a seguir usa a sintaxe do elemento de propriedade para definir o Preenchimento de um Rectangle com um elemento de objeto SolidColorBrush. (Dentro do SolidColorBrush, Color é definido como um atributo.) O resultado analisado desse XAML é idêntico ao exemplo XAML anterior que define Fill usando a sintaxe de atributo.

<Rectangle
  Name="rectangle1"
  Width="100" 
  Height="100"
> 
  <Rectangle.Fill> 
    <SolidColorBrush Color="Blue"/> 
  </Rectangle.Fill>
</Rectangle>

Vocabulários XAML e programação orientada a objetos

As propriedades e os eventos à medida que aparecem como membros XAML de um tipo XAML do Tempo de Execução do Windows geralmente são herdados de tipos base. Considere este exemplo: <Button Background="Blue" .../>. A propriedade Background não é uma propriedade declarada imediatamente na classe Button. Em vez disso, Background é herdado da classe Control base. Na verdade, se você examinar o tópico de referência de Button, verá que as listas de membros contêm pelo menos um membro herdado de cada uma de uma cadeia de classes base sucessivas: ButtonBase, Control, FrameworkElement, UIElement, DependencyObject. Na lista Propriedades, todas as propriedades de leitura/gravação e propriedades de coleção são herdadas em um sentido de vocabulário XAML. Eventos (como os vários eventos UIElement ) também são herdados.

Se você usar a referência do Tempo de Execução do Windows para diretrizes XAML, o nome do elemento mostrado em uma sintaxe ou até mesmo no código de exemplo às vezes é para o tipo que define originalmente a propriedade, pois esse tópico de referência é compartilhado por todos os tipos possíveis que o herdam de uma classe base. Se você usar o IntelliSense do Visual Studio para XAML no editor XML, o IntelliSense e suas listas suspensas farão um ótimo trabalho ao unir a herança e fornecer uma lista precisa de atributos que estão disponíveis para configuração depois que você começar com um elemento de objeto para uma instância de classe.

Propriedades de conteúdo XAML

Alguns tipos definem uma de suas propriedades, de modo que a propriedade habilite uma sintaxe de conteúdo XAML. Para a propriedade de conteúdo XAML de um tipo, você pode omitir o elemento de propriedade dessa propriedade ao especificá-la em XAML. Ou você pode definir a propriedade como um valor de texto interno fornecendo esse texto interno diretamente nas marcas de elemento de objeto do tipo proprietário. As propriedades de conteúdo XAML dão suporte à sintaxe de marcação direta para essa propriedade e tornam o XAML mais legível por humanos, reduzindo o aninhamento.

Se uma sintaxe de conteúdo XAML estiver disponível, essa sintaxe será mostrada nas seções "XAML" de Sintaxe para essa propriedade na documentação de referência do Tempo de Execução do Windows. Por exemplo, a página de propriedade Child para Border mostra a sintaxe de conteúdo XAML em vez da sintaxe do elemento de propriedade para definir o valor Border.Child de objeto único de uma Border, desta forma:

<Border>
  <Button .../>
</Border>

Se a propriedade declarada como a propriedade de conteúdo XAML for o tipo Object ou for do tipo String, a sintaxe de conteúdo XAML dará suporte ao que é basicamente texto interno no modelo de documento XML: uma cadeia de caracteres entre as marcas de objeto de abertura e fechamento. Por exemplo, a página de propriedades Text para TextBlock mostra a sintaxe de conteúdo XAML que tem um valor de texto interno para definir Text, mas a cadeia de caracteres "Text" nunca aparece na marcação. Aqui está um uso de exemplo:

<TextBlock>Hello!</TextBlock>

Se existir uma propriedade de conteúdo XAML para uma classe, isso será indicado no tópico de referência da classe, na seção "Atributos". Procure o valor do ContentPropertyAttribute. Esse atributo usa um campo nomeado "Nome". O valor de "Name" é o nome da propriedade dessa classe que é a propriedade de conteúdo XAML. Por exemplo, na página de referência Border, você verá o seguinte: ContentProperty("Name=Child").

Uma regra de sintaxe XAML importante que devemos mencionar é que você não pode misturar a propriedade de conteúdo XAML e outros elementos de propriedade definidos no elemento. A propriedade de conteúdo XAML deve ser definida inteiramente antes de qualquer elemento de propriedade ou totalmente depois. Por exemplo, este é um XAML inválido:

<StackPanel>
  <Button>This example</Button>
  <StackPanel.Resources>
    <SolidColorBrush x:Key="BlueBrush" Color="Blue"/>
  </StackPanel.Resources>
  <Button>... is illegal XAML</Button>
</StackPanel>

Sintaxe da coleção

Todas as sintaxes mostradas até agora estão definindo propriedades para objetos únicos. Mas muitos cenários de interface do usuário exigem que um determinado elemento pai possa ter vários elementos filho. Por exemplo, uma interface do usuário para um formulário de entrada precisa de vários elementos de caixa de texto, alguns rótulos e talvez um botão "Enviar". Ainda assim, se você usasse um modelo de objeto de programação para acessar esses vários elementos, eles normalmente seriam itens em uma única propriedade de coleção, em vez de cada item ser o valor de propriedades diferentes. O XAML dá suporte a vários elementos filho, bem como a um modelo típico de coleção de suporte, tratando propriedades que usam um tipo de coleção como implícito e executando tratamento especial para qualquer elemento filho de um tipo de coleção.

Muitas propriedades de coleção também são identificadas como a propriedade de conteúdo XAML para a classe. A combinação de processamento de coleção implícita e sintaxe de conteúdo XAML é freqüentemente vista em tipos usados para composição de controle, como painéis, exibições ou controles de itens. Por exemplo, o exemplo a seguir mostra o XAML mais simples possível para compor dois elementos de interface do usuário par em um StackPanel.

<StackPanel>
  <TextBlock>Hello</TextBlock>
  <TextBlock>World</TextBlock>
</StackPanel>

O mecanismo da sintaxe de coleção XAML

À primeira vista, pode parecer que o XAML está habilitando um "conjunto" da propriedade de coleção somente leitura. Na realidade, o que o XAML permite aqui é adicionar itens a uma coleção existente. A linguagem XAML e os processadores XAML que implementam o suporte a XAML dependem de uma convenção nos tipos de coleção de suporte para habilitar essa sintaxe. Normalmente, há uma propriedade de suporte, como um indexador ou uma propriedade Items , que se refere a itens específicos da coleção. Geralmente, essa propriedade não é explícita na sintaxe XAML. Para coleções, o mecanismo subjacente para análise XAML não é uma propriedade, mas um método: especificamente, o método Add na maioria dos casos. Quando o processador XAML encontra um ou mais elementos de objeto dentro de uma sintaxe de coleção XAML, cada um desses objetos é criado primeiro a partir de um elemento e, em seguida, cada novo objeto é adicionado para a coleção que o contém chamando o método Add da coleção.

Quando um analisador XAML adiciona itens a uma coleção, é a lógica do método Add que determina se um determinado elemento XAML é um filho de item permitido do objeto de coleção. Muitos tipos de coleção são fortemente tipados pela implementação de suporte, o que significa que o parâmetro de entrada de Add espera que o que for passado deve ser uma correspondência de tipo com o tipo de parâmetro Add .

Para propriedades de coleção, tenha cuidado ao tentar especificar a coleção explicitamente como um elemento de objeto. Um analisador XAML criará um novo objeto sempre que encontrar um elemento de objeto. Se a propriedade de coleção que você está tentando usar for somente leitura, isso poderá gerar uma exceção de análise XAML. Basta usar a sintaxe de coleção implícita e você não verá essa exceção.

Quando usar a sintaxe de atributo ou elemento de propriedade

Todas as propriedades que dão suporte à definição em XAML darão suporte à sintaxe de atributo ou elemento de propriedade para configuração de valor direto, mas potencialmente não darão suporte a nenhuma sintaxe de forma intercambiável. Algumas propriedades dão suporte a qualquer sintaxe e algumas propriedades dão suporte a opções de sintaxe adicionais, como uma propriedade de conteúdo XAML. O tipo de sintaxe XAML com suporte por uma propriedade depende do tipo de objeto que a propriedade usa como seu tipo de propriedade. Se o tipo de propriedade for um tipo primitivo, como um double (float ou decimal), inteiro, booleano ou cadeia de caracteres, a propriedade sempre dará suporte à sintaxe de atributo.

Você também pode usar a sintaxe de atributo para definir uma propriedade se o tipo de objeto usado para definir essa propriedade puder ser criado processando uma cadeia de caracteres. Para primitivos, esse é sempre o caso, a conversão de tipo é incorporada ao analisador. No entanto, determinados outros tipos de objeto também podem ser criados usando uma cadeia de caracteres especificada como um valor de atributo, em vez de um elemento de objeto dentro de um elemento de propriedade. Para que isso funcione, deve haver uma conversão de tipo subjacente, com suporte por essa propriedade específica ou com suporte geral para todos os valores que usam esse tipo de propriedade. O valor da cadeia de caracteres do atributo é usado para definir propriedades que são importantes para a inicialização do novo valor do objeto. Potencialmente, um conversor de tipo específico também pode criar diferentes subclasses de um tipo de propriedade comum, dependendo de como ele processa exclusivamente as informações na cadeia de caracteres. Os tipos de objeto que dão suporte a esse comportamento terão uma gramática especial listada na seção de sintaxe da documentação de referência. Por exemplo, a sintaxe XAML para Brush mostra como uma sintaxe de atributo pode ser usada para criar um novo valor SolidColorBrush para qualquer propriedade do tipo Brush (e há muitas propriedades Brush no XAML do Tempo de Execução do Windows).

Lógica e regras de análise XAML

Às vezes, é informativo ler o XAML de maneira semelhante a como um analisador XAML deve lê-lo: como um conjunto de tokens de cadeia de caracteres encontrados em uma ordem linear. Um analisador XAML deve interpretar esses tokens sob um conjunto de regras que fazem parte da definição de como o XAML funciona.

Definir um valor de atributo é o meio típico pelo qual você define um valor de propriedade em uma linguagem de marcação, por exemplo, em XML ou HTML. Na sintaxe a seguir, objectName é o objeto que você deseja instanciar, propertyName é o nome da propriedade que você deseja definir nesse objeto e propertyValue é o valor a ser definido.

<objectName propertyName="propertyValue" .../>

-or-

<objectName propertyName="propertyValue">

...<!--element children -->

</objectName>

Qualquer sintaxe permite que você declare um objeto e defina uma propriedade nesse objeto. Embora o primeiro exemplo seja um único elemento na marcação, na verdade há etapas discretas aqui em relação a como um processador XAML analisa essa marcação.

Primeiro, a presença do elemento object indica que um novo objeto objectName deve ser instanciado. Somente depois que essa instância existir, a propriedade propertyName da instância poderá ser definida nela.

Outra regra do XAML é que os atributos de um elemento devem poder ser definidos em qualquer ordem. Por exemplo, não há diferença entre <Rectangle Height="50" Width="100" /> e <Rectangle Width="100" Height="50" />. A ordem que você usa é uma questão de estilo.

Observação Os designers XAML geralmente promovem convenções de ordenação se você usar superfícies de design diferentes do editor XML, mas você pode editar livremente esse XAML mais tarde, para reordenar os atributos ou introduzir novos.

Propriedades anexadas

O XAML estende o XML adicionando um elemento de sintaxe conhecido como propriedade anexada. Semelhante à sintaxe do elemento de propriedade, a sintaxe da propriedade anexada contém um ponto e o ponto tem um significado especial para a análise XAML. Especificamente, o ponto separa o provedor da propriedade anexada e o nome da propriedade.

Em XAML, você define propriedades anexadas usando a sintaxe AttachedPropertyProvider.PropertyName Aqui está um exemplo de como você pode definir a propriedade anexada Canvas.Left em XAML:

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

Você pode definir a propriedade anexada em elementos que não têm uma propriedade com esse nome no tipo de suporte e, dessa forma, eles funcionam como uma propriedade global ou um atributo definido por um namespace XML diferente, como o atributo xml:space .

No XAML do Tempo de Execução do Windows, você verá propriedades anexadas que dão suporte a estes cenários:

Para obter mais informações, consulte Visão geral das propriedades anexadas.

Valores literais "{"

Como o símbolo de chave de abertura { é a abertura da sequência de extensão de marcação, você usa uma sequência de escape para especificar um valor de cadeia de caracteres literal que começa com "{". A seqüência de escape é "{}". Por exemplo, para especificar um valor de cadeia de caracteres que seja uma chave de abertura única, especifique o valor do atributo como "{}{". Você também pode usar as aspas alternativas (por exemplo, um ' dentro de um valor de atributo delimitado por "") para fornecer um valor "{" como uma cadeia de caracteres.

Observe que "\}" também funciona se estiver dentro de um atributo entre aspas.  

Valores de enumeração

Muitas propriedades na API do Tempo de Execução do Windows usam enumerações como valores. Se o membro for uma propriedade de leitura/gravação, você poderá definir essa propriedade fornecendo um valor de atributo. Você identifica qual valor de enumeração usar como o valor da propriedade usando o nome não qualificado do nome da constante . Por exemplo, veja como definir UIElement.Visibility em XAML: <Button Visibility="Visible"/>. Aqui, o "Visible" como uma cadeia de caracteres é mapeado diretamente para uma constante nomeada da enumeração Visibility, Visible.

  • Não use um formulário qualificado, ele não funcionará. Por exemplo, este é um XAML inválido: <Button Visibility="Visibility.Visible"/>.
  • Não use o valor da constante. Em outras palavras, não confie no valor inteiro da enumeração que está lá explícita ou implicitamente, dependendo de como a enumeração foi definida. Embora possa parecer funcionar, é uma prática ruim em XAML ou em código porque você está confiando no que poderia ser um detalhe de implementação transitório. Por exemplo, não faça isso: <Button Visibility="1"/>.

Observação Em tópicos de referência para APIs que usam XAML e usam enumerações, clique no link para o tipo de enumeração na seção Valor da propriedade de Sintaxe. Isso é vinculado à página de enumeração em que você pode descobrir as constantes nomeadas para essa enumeração.

As enumerações podem ser sinalizadas, o que significa que elas são atribuídas com FlagsAttribute. Se você precisar especificar uma combinação de valores para uma enumeração sinalizada como um valor de atributo XAML, use o nome de cada constante de enumeração, com uma vírgula (,) entre cada nome e nenhum caractere de espaço intermediário. Atributos sinalizados não são comuns no vocabulário XAML do Tempo de Execução do Windows, mas ManipulationModes é um exemplo em que há suporte para a configuração de um valor de enumeração sinalizado em XAML.

Interfaces em XAML

Em casos raros, você verá uma sintaxe XAML em que o tipo de uma propriedade é uma interface. No sistema de tipos XAML, um tipo que implementa essa interface é aceitável como um valor quando analisado. Deve haver uma instância criada desse tipo disponível para servir como o valor. Você verá uma interface usada como um tipo na sintaxe XAML para as propriedades Command e CommandParameter de ButtonBase. Essas propriedades dão suporte a padrões de design MVVM (Model-View-ViewModel) em que a interface ICommand é o contrato de como as exibições e os modelos interagem.

Convenções de espaço reservado XAML na referência do Tempo de Execução do Windows

Se você examinou qualquer um dos tópicos de referência da seção Sintaxe para APIs do Tempo de Execução do Windows que podem usar XAML, provavelmente viu que a sintaxe inclui alguns espaços reservados. A sintaxe XAML é diferente da sintaxe C#, Microsoft Visual Basic ou Visual C++ (C++/CX) porque a sintaxe XAML é uma sintaxe de uso. Ele está sugerindo seu uso eventual em seus próprios arquivos XAML, mas sem ser excessivamente prescritivo sobre os valores que você pode usar. Portanto, geralmente o uso descreve um tipo de gramática que mistura literais e espaços reservados e define alguns dos espaços reservados na seção Valores XAML .

Quando você vê nomes de tipo/nomes de elemento em uma sintaxe XAML para uma propriedade, o nome mostrado é para o tipo que define originalmente a propriedade. Mas o XAML do Tempo de Execução do Windows dá suporte a um modelo de herança de classe para as classes baseadas em DependencyObject. Portanto, muitas vezes você pode usar um atributo em uma classe que não é literalmente a classe definidora, mas deriva de uma classe que primeiro definiu a propriedade/atributo. Por exemplo, você pode definir Visibility como um atributo em qualquer classe derivada de UIElement usando uma herança profunda. Por exemplo: <Button Visibility="Visible" />. Portanto, não tome o nome do elemento mostrado em qualquer sintaxe de uso XAML muito literalmente; A sintaxe pode ser viável para elementos que representam essa classe e também elementos que representam uma classe derivada. Nos casos em que é raro ou impossível que o tipo mostrado como o elemento definidor esteja em um uso real, esse nome de tipo é deliberadamente minúsculo na sintaxe. Por exemplo, a sintaxe que você vê para UIElement.Visibility é :

<uiElement Visibility="Visible"/>
-or-
<uiElement Visibility="Collapsed"/>

Muitas seções de sintaxe XAML incluem espaços reservados no "Uso" que são definidos em uma seção Valores XAML que está diretamente abaixo da seção Sintaxe .

As seções de uso de XAML também usam vários espaços reservados generalizados. Esses espaços reservados não são redefinidos todas as vezes em valores XAML, porque você adivinhará ou eventualmente aprenderá o que eles representam. Achamos que a maioria dos leitores se cansaria de vê-los em valores XAML repetidamente, então os deixamos de fora das definições. Para referência, aqui está uma lista de alguns desses espaços reservados e o que eles significam em um sentido geral:

  • object: teoricamente, qualquer valor de objeto, mas muitas vezes praticamente limitado a certos tipos de objetos, como uma opção de cadeia de caracteres ou objeto, e você deve verificar os Comentários na página de referência para obter mais informações.
  • Propriedade do objeto: A propriedade do objeto em combinação é usada para casos em que a sintaxe que está sendo mostrada é a sintaxe de um tipo que pode ser usado como um valor de atributo para muitas propriedades. Por exemplo, o Uso do atributo Xaml mostrado para Brush inclui: <object property="predefinedColorName"/>
  • eventhandler: aparece como o valor do atributo para cada sintaxe XAML mostrada para um atributo de evento. O que você está fornecendo aqui é o nome da função para uma função de manipulador de eventos. Essa função deve ser definida no code-behind da página XAML. No nível de programação, essa função deve corresponder à assinatura delegada do evento que você está manipulando, ou o código do aplicativo não será compilado. Mas isso é realmente uma consideração de programação, não uma consideração de XAML, portanto, não tentamos sugerir nada sobre o tipo de delegado na sintaxe XAML. Se você quiser saber qual delegado você deve implementar para um evento, isso está na seção Informações do evento do tópico de referência do evento, em uma linha da tabela rotulada como Delegado.
  • enumMemberName: mostrado na sintaxe de atributo para todas as enumerações. Há um espaço reservado semelhante para propriedades que usam um valor de enumeração, mas geralmente prefixa o espaço reservado com uma dica do nome da enumeração. Por exemplo, a sintaxe mostrada para FrameworkElement.FlowDirection é< frameworkElementFlowDirection="flowDirectionMemberName"/>. Se você estiver em uma dessas páginas de referência de propriedade, clique no link para o tipo de enumeração que aparece na seção Valor da Propriedade, ao lado do texto Tipo:. Para o valor do atributo de uma propriedade que usa essa enumeração, você pode usar qualquer cadeia de caracteres listada na coluna Membro da lista Membros .
  • double, int, string, bool: esses são tipos primitivos conhecidos pela linguagem XAML. Se você estiver programando usando C# ou Visual Basic, esses tipos serão projetados para tipos equivalentes do Microsoft .NET, como Double, Int32, String e Boolean, e você poderá usar qualquer membro nesses tipos .NET ao trabalhar com seus valores definidos por XAML no code-behind do .NET. Se você estiver programando usando C++/CX, usará os tipos primitivos do C++, mas também poderá considerá-los equivalentes aos tipos definidos pelo namespace Platform, por exemplo, Platform::String. Às vezes, haverá restrições de valor adicionais para propriedades específicas. Mas você geralmente verá isso anotado em uma seção de valor de propriedade ou seção de comentários e não em uma seção XAML, pois essas restrições se aplicam a usos de código e usos de XAML.

Dicas e truques, notas sobre estilo

  • As extensões de marcação em geral são descritas na visão geral do XAML principal. Mas a extensão de marcação que mais afeta as diretrizes fornecidas neste tópico é a extensão de marcação StaticResource (e ThemeResource relacionado). A função da extensão de marcação StaticResource é habilitar a fatoração de seu XAML em recursos reutilizáveis provenientes de um ResourceDictionary XAML. Você quase sempre define modelos de controle e estilos relacionados em um ResourceDictionary. Muitas vezes, você também define as partes menores de uma definição de modelo de controle ou estilo específico do aplicativo em um ResourceDictionary, por exemplo, um SolidColorBrush para uma cor que seu aplicativo usa mais de uma vez para diferentes partes da interface do usuário. Usando um StaticResource, qualquer propriedade que, de outra forma, exigiria o uso de um elemento de propriedade para ser definida agora pode ser definida na sintaxe de atributo. Mas os benefícios de fatorar XAML para reutilização vão além de apenas simplificar a sintaxe no nível da página. Para obter mais informações, consulte ResourceDictionary e referências de recursos XAML.
  • Você verá várias convenções diferentes de como o espaço em branco e os feeds de linha são aplicados em exemplos de XAML. Em particular, existem diferentes convenções sobre como dividir elementos de objeto que têm muitos atributos diferentes definidos. Isso é apenas uma questão de estilo. O editor XML do Visual Studio aplica algumas regras de estilo padrão quando você edita XAML, mas você pode alterá-las nas configurações. Há um pequeno número de casos em que o espaço em branco em um arquivo XAML é considerado significativo; para obter mais informações, consulte XAML e espaço em branco.