Guia de sintaxe do XAML

Explicamos as regras de sintaxe XAML e a terminologia que descreve as restrições ou opções disponíveis para sintaxe XAML. Você achará este tópico útil se não estiver familiarizado com o uso da linguagem XAML, quiser um atualizador sobre a terminologia ou partes da sintaxe ou se estiver curioso sobre como a linguagem XAML funciona e deseja mais contexto e plano de fundo.

XAML é XML

XAML (Extensible Application Markup Language) tem uma sintaxe básica que se baseia em XML e, por definiçã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 XML é que o XAML normalmente não é imposto com um esquema, como um arquivo XSD. Isso ocorre porque o XAML se destina a ser extensível, é isso que o "X" no acrônimo XAML significa. Depois que o XAML for analisado, espera-se que os elementos e atributos referenciados no XAML existam em alguma representação de código de backup, seja nos tipos principais definidos pelo Windows Runtime ou em tipos que se estendem ou são baseados no Windows Runtime. Às vezes, a documentação do SDK refere-se aos tipos que já são internos ao Windows Runtime e podem ser usados no XAML como sendo o vocabulário XAML para o Windows Runtime. 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 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 é conceitualizada como elementos e atributos. No sentido mais básico, um elemento que você declara na marcação XAML torna-se um objeto em uma representação de objeto de runtime de backup. Para criar um objeto em tempo de execução para seu aplicativo, você deve declarar um elemento XAML nas marcações de XAML. O objeto é criado quando o Windows Runtime 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 em 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: Isso 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 a sintaxe de atributo: Isso usa um valor de cadeia de caracteres embutida 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 tenha a opção de qualquer sintaxe para criação de objeto em um vocabulário XAML. Alguns objetos só podem ser criados usando a sintaxe do elemento de objeto. Alguns objetos só podem ser criados sendo inicialmente definidos em um atributo. Na verdade, objetos que podem ser criados com sintaxe de elemento de objeto ou atributo são relativamente raros em vocabulários XAML. Mesmo que ambas as formas de sintaxe sejam possíveis, uma das sintaxes será mais comum como uma questão de estilo. Há também técnicas que você pode usar no 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 de seu aplicativo ou modelos de programação.

Declarando um objeto usando a sintaxe do elemento de objeto

Para declarar um objeto com sintaxe de elemento de objeto, você escreve tags assim: <objectName> </objectName>, onde objectName é o nome do tipo do 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 de objeto usando uma marca de auto-fechamento 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 Retângulo.

<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 texto interno usado como valores de inicialização para construção. No XAML, essa técnica e sintaxe são chamadas de texto de inicialização. Conceitualmente, o texto de inicialização é semelhante à chamada de um construtor que tem parâmetros. O texto de inicialização é útil para definir valores iniciais de determinadas estruturas.

Geralmente, você 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ê poderá 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 útil e compartilhável de CornerRadius, Thickness, GridLength ou Color .

Este exemplo abreviado usa o texto de inicialização para especificar valores para uma Espessura, nesse 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 Thickness, consulte Thickness.

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

Definindo 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 do elemento em que o conteúdo (texto interno ou elementos filho) define 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 dão suporte apenas a uma das técnicas. Algumas propriedades dão suporte a mais de um formulário; por exemplo, há propriedades que podem usar 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 à API do Windows Runtime, você verá os usos XAML que você pode usar 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 sintaxe XAML são fornecidas nas seções uso XAML de páginas de referência para propriedades que podem ser definidas em XAML.

Algumas propriedades em objetos não podem ser definidas em XAML por qualquer meio e só podem ser definidas usando código. Geralmente, 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 definir isso, como uma sobrecarga de construtor, um método auxiliar, ou suporte a propriedades calculadas. Uma propriedade calculada depende dos valores de outras propriedades configuráveis, além de, à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 o suporte de propriedade calculada, consulte a visão geral das propriedades de dependência.

A sintaxe de coleção em XAML dá a impressão de que uma propriedade somente leitura está sendo configurada, mas na verdade não. 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. Definir atributos XAML é semelhante à forma como você define valores de atributo em XML. O nome do atributo é especificado em qualquer ponto dentro das marcas 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 coloquem o valor entre si. 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ásica.

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.de objeto>.

Para usar a sintaxe do 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, no XAML, o ponto no nome do elemento identifica o elemento como um elemento de propriedade, com a expectativa de que a propriedade seja 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 marcas de 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 autofechamento.

Na gramática a seguir, a propriedade é 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.

< objeto>

< objeto.propriedade>

propertyValueAsObjectElement

</ objeto.propriedade>

</ objeto>

O exemplo a seguir usa a sintaxe do elemento de propriedade para definir o Preenchimento de um Retângulo com um elemento de objeto SolidColorBrush . (No SolidColorBrush, a cor é definida 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

Propriedades e eventos que aparecem como membros XAML de um tipo XAML do Windows Runtime 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 de controle 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 da coleção são herdadas no contexto do vocabulário XAML. Eventos (como os vários eventos UIElement ) também são herdados.

Se você usar a referência do Windows Runtime 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 originalmente define a propriedade, porque esse tópico de referência é compartilhado por todos os tipos possíveis que a 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 de unir a herança e fornecer uma lista precisa de atributos que estão disponíveis para configuração depois que você começar a usar 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 habilita uma sintaxe de conteúdo XAML. Para a propriedade de conteúdo XAML de um tipo, você pode omitir o elemento de propriedade para essa propriedade ao especificá-lo em XAML. Ou você pode definir a propriedade como um valor de texto interno fornecendo esse texto diretamente dentro das tags de elemento do tipo ao qual pertence. As propriedades de conteúdo XAML dão suporte à sintaxe de marcação simples 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" da sintaxe dessa propriedade na documentação de referência do Windows Runtime. 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 de Border.Child como um único objeto de um Border, desta forma:

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

Se a propriedade declarada como a propriedade de conteúdo XAML for o tipo Objeto ou for o tipo String, a sintaxe de conteúdo XAML oferecerá 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 propriedade 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 de 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 intermixar 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 inteiramente depois. Por exemplo, isso é 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ê fosse usar 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 dá suporte a um modelo de coleção de backup típico, 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 da classe. A combinação de processamento de coleção implícita e sintaxe de conteúdo XAML é frequentemente 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 de sintaxe da coleção XAML

A princípio, pode ser que o XAML esteja habilitando um "conjunto" da propriedade de coleção somente leitura. Na realidade, o que o XAML habilita 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 backup, 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 objeto desse tipo é criado primeiro a partir de um elemento e, em seguida, cada novo objeto é adicionado para a coleção que 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 subjacente, o que significa que o parâmetro de entrada de Add espera que o que for passado deve ter 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 do elemento de atributo ou propriedade

Todas as propriedades que podem ser definidas em XAML suportarão a sintaxe de elemento de propriedade ou atributo para configuração direta de valor, mas potencialmente não darão suporte ao uso intercambiável dessas sintaxes. Algumas propriedades dão suporte a alguma das sintaxes, e algumas propriedades suportam opções adicionais de sintaxe, como uma propriedade XAML de conteúdo. O tipo de sintaxe XAML compatível com 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 duplo (float ou decimal), inteiro, booliano ou cadeia de caracteres, a propriedade sempre oferecerá 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, compatível com essa propriedade específica ou com suporte em geral para todos os valores que usam esse tipo de propriedade. O valor da cadeia de caracteres do atributo é usado para definir propriedades importantes para a inicialização do novo valor do objeto. Potencialmente, um conversor de tipo específico também pode criar subclasses diferentes 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. Como 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 Windows Runtime).

Lógica e regras de análise XAML

Às vezes, é informativo ler o XAML de forma semelhante à forma como um analisador XAML deve lê-lo: como um conjunto de tokens de string encontrado 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, há realmente etapas discretas aqui em relação a como um processador XAML analisa essa marcação.

Primeiro, a presença do elemento de objeto 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 de XAML é que os atributos de um elemento devem ser capazes de ser definidos em qualquer ordem. Por exemplo, não há diferença entre <Rectangle Height="50" Width="100" /> e <Rectangle Width="100" Height="50" />. Qual ordem você usa é uma questão de estilo.

Propriedades anexadas

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

No XAML, você define as 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 desse nome no tipo de suporte e, dessa forma, funcionam um pouco como uma propriedade global ou um atributo definido por um namespace XML diferente, como o atributo xml:space .

No XAML do Windows Runtime, você verá propriedades anexadas que dão suporte a esses cenários:

• Os elementos filho podem informar aos painéis de contêiner pai como eles devem se comportar no layout: Canvas, Grid, VariableSizedWrapGrid.
• Os usos de controle podem influenciar o comportamento de uma parte de controle importante que vem do modelo de controle: ScrollViewer, VirtualizingStackPanel.
• Usando um serviço disponível em uma classe relacionada, em que o serviço e a classe que o usa não compartilham herança: Tipografia, VisualStateManager, AutomationProperties, ToolTipService.
• Alvo de animação: Storyboard.

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

Valores literais de "{"

Como o símbolo de chave de abertura { inicia a sequência de extensão de marcação, utiliza-se uma sequência de escape para especificar um valor literal de cadeia de caracteres que começa com "{". A sequê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.

Valores de enumeração

Muitas propriedades na API do Windows Runtime 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 utilizando o nome não qualificado da constante. Por exemplo, veja como definir UIElement.Visibility em XAML: <Button Visibility="Visible"/>. Aqui, o "Visível" 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, isso é 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á explicitamente ou implicitamente, dependendo de como a enumeração foi definida. Embora possa parecer funcionar, é uma prática incorreta no XAML ou no código porque você está confiando no que pode ser um detalhe de implementação transitório. Por exemplo, não faça isso: <Button Visibility="1"/>.

As enumerações podem ser flagwise, o que significa que são atribuídas com FlagsAttribute. Se você precisar especificar uma combinação de valores para uma enumeração flagwise 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 interveniente. Atributos sinalizadores não são comuns no vocabulário XAML do Windows Runtime, mas ManipulationModes é um exemplo em que há suporte para definir um valor de enumeração sinalizador no 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 do ButtonBase. Essas propriedades dão suporte a padrões de design MVVM (Model-View-ViewModel), onde a interface ICommand é o contrato de como as visões e os modelos interagem.

Convenções de espaço reservado XAML na referência do Windows Runtime

Se você examinou qualquer uma das seções de sintaxe de tópicos de referência para APIs do Windows Runtime que podem usar XAML, provavelmente já viu que a sintaxe inclui bastantes marcadores de posição. A sintaxe XAML é diferente da sintaxe das extensões de componente C#, Microsoft Visual Basic ou Visual C++ (C++/CX), pois a sintaxe XAML é uma sintaxe de uso. Ele está sugerindo seu uso eventual em seus próprios arquivos XAML, mas sem ser prescritivo demais sobre os valores que você pode usar. Portanto, geralmente, o uso descreve um tipo de gramática que combina 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 originalmente define a propriedade. Mas o XAML do Windows Runtime 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 definiu pela primeira vez a propriedade/atributo. Por exemplo, você pode definir Visibilidade como um atributo em qualquer classe derivada de UIElement usando uma herança profunda. Por exemplo: <Button Visibility="Visible" />. Portanto, não leve o nome do elemento mostrado em nenhuma 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 para o tipo mostrado como o elemento definidor estar em uso no mundo real, esse nome de tipo é deliberadamente em 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 logo abaixo da seção Sintaxe.

As seções de uso do XAML também usam vários placeholders generalizados. Esses espaços reservados não são redefinidos todas as vezes em Valores XAML, pois você adivinhará ou aprenderá o que eles representam. Achamos que a maioria dos leitores se cansaria de vê-los várias vezes em Valores XAML, por isso os excluímos 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:

• objeto: teoricamente qualquer valor de objeto, mas na prática geralmente limitado a certos tipos de objetos, como uma escolha entre cadeia de caracteres e objeto; é recomendado que você verifique as Observações na página de referência para obter mais informações.
• objectproperty: objectproperty 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: <objectproperty="predefinedColorName"/>
• eventhandler: isso 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 arquivo code-behind da página XAML. No nível de programação, essa função deve corresponder à assinatura delegada do evento que você está tratando ou o código do aplicativo não será compilado. Mas isso é realmente uma consideração de programação, não uma consideração XAML, então não tentamos sugerir nada sobre o tipo delegado na sintaxe XAML. Se você quiser saber qual delegado você deve implementar para um evento, isso está na seção Informações de evento do tópico de referência do evento, em uma linha de tabela rotulada 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 tipo de texto:. Para o valor de 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: 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 todos os membros nesses tipos .NET quando trabalhar com seus valores definidos por XAML no code-behind do .NET. Se estiver programando usando C++/CX, você usará os tipos primitivos do C++, mas também poderá considerá-los equivalentes aos tipos definidos pelo namespace plataforma , por exemplo , Platform::String. Às vezes, haverá restrições de valor adicionais para propriedades específicas. Mas você geralmente os verá anotados em uma seção de valor de propriedade ou seção Comentários e não em uma seção XAML, porque essas restrições se aplicam tanto a usos de código quanto a usos de XAML.

Dicas e truques, anotações sobre estilo

• As extensões de marcação em geral são descritas na visão geral principal do XAML. 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 do XAML em recursos reutilizáveis, provenientes de um XAML ResourceDictionary. Você quase sempre define modelos de controle e estilos relacionados em um ResourceDictionary. Geralmente, você define as partes menores de uma definição de modelo de controle ou estilo específico do aplicativo em um ResourceDictionary também, 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 pode agora ser definida na sintaxe de atributo. Mas os benefícios de modularizar XAML para reutilização vão além de simplificar a sintaxe apenas no nível da página. Para obter mais informações, consulte as referências de recurso ResourceDictionary e XAML.
• Você verá várias convenções diferentes sobre como o espaço em branco e os feeds de linha são aplicados em exemplos XAML. Em particular, há convenções diferentes para como dividir elementos de objeto que têm muitos atributos diferentes definidos. Isso é só uma questão de estilo. O editor XML do Visual Studio aplica algumas regras de estilo padrão ao editar 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 whitespace.

Tópicos relacionados

• Visão geral do XAML
• namespaces XAML e mapeamento de namespaces
• ResourceDictionary e referências de recursos do XAML