Partilhar via

Guia de sintaxe XAML

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ê for novo no uso da linguagem XAML, quiser uma atualização sobre a terminologia ou partes da sintaxe ou estiver curioso sobre como a linguagem XAML funciona e quiser mais plano de fundo e contexto.

XAML é XML

Extensible Application Markup Language (XAML) 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 de XML é que o XAML normalmente não é imposto com um esquema, como um arquivo XSD. Isso porque o XAML se destina a ser extensível, é isso que o "X" na sigla XAML significa. Depois que o XAML é analisado, espera-se que os elementos e atributos referenciados em 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 se 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á estão incorporados 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ções válidas dentro desse vocabulário XAML. O Visual Studio também pode incluir seus tipos personalizados para uso de XAML, desde que a origem desses tipos seja referenciada corretamente no projeto. Para saber mais sobre XAML e tipos personalizados, veja 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 a sua aplicação, declare 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 gráfico 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 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 do atributo: Isso 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 certos objetos e propriedades comuns.
  • Usando uma extensão de marcação.

Isso não significa que você sempre tenha a escolha de qualquer sintaxe para a criação de objetos em um vocabulário XAML. Alguns objetos podem ser criados somente usando a sintaxe do elemento objeto. Alguns objetos podem ser criados apenas sendo inicialmente definidos em um atributo. Na verdade, objetos que podem ser criados com elemento de objeto ou sintaxe de 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 de 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 object

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

<Canvas>
</Canvas>

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

Contentores

Muitos objetos usados como elementos da interface do usuário, como Canvas, podem conter outros objetos. Estes são por vezes referidos como contentores. O exemplo a seguir mostra um contêiner Canvas que contém um elemento, um Rectangle.

<Canvas>
  <Rectangle />
</Canvas>

Declarando um objeto usando sintaxe de atributo

Como esse comportamento está vinculado à configuração da 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 que é 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 alvo. Para algumas estruturas, não é possível 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 saber mais sobre o texto de inicialização da espessura , veja 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. O texto de inicialização não é suportado 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.

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 sintaxe de atributo.
  • Usando a sintaxe do elemento de propriedade.
  • Ao usar a sintaxe de 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).

Tal como acontece com a declaração de objeto, esta 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 suportam mais de um formulário; Por exemplo, há propriedades que podem usar a sintaxe do elemento Property ou a sintaxe do atributo. O que é possível depende da propriedade e do tipo de objeto que a propriedade usa. Na referência da API do Windows Runtime, irá ver os usos de XAML que 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. A orientação para a sintaxe XAML é fornecida nas seções Uso 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 por qualquer meio e só podem ser definidas usando código. Normalmente, essas são propriedades mais apropriadas para trabalhar no code-behind, não em XAML.

Uma propriedade somente leitura não pode ser definida em XAML. Mesmo no código, o tipo proprietário teria de suportar outra forma de defini-lo, como uma sobrecarga de construtor, um método auxiliar ou com suporte para propriedades calculadas. 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 saber mais sobre como as propriedades de dependência são úteis para o suporte de propriedades calculadas, veja Visão geral das propriedades de dependência.

A sintaxe de coleção em XAML sugere que está-se a atribuir uma propriedade de leitura única, mas na realidade não está. Consulte "Sintaxe da coleção" mais adiante neste tópico.

Definindo uma propriedade usando 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 definição de atributos XAML é semelhante à forma como você define valores de atributos 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 citações podem ser aspas duplas ou aspas simples, desde que correspondam e envolvam o valor. O próprio valor do atributo 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 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, 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 de elemento de propriedade. Um elemento de propriedade sempre terá algum conteúdo (elemento único, vários elementos ou texto interno); Não adianta 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 satisfazer os 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 Rectângulo com um elemento de objeto SolidColorBrush. (Dentro do SolidColorBrush, Color é definido como um atributo.) O resultado analisado deste XAML é idêntico ao exemplo XAML anterior que definiu Fill usando 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 eventos tal como aparecem como membros XAML de um tipo XAML do Windows Runtime são frequentemente 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ê olhar para o tópico de referência para 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 e escrita e as propriedades de coleção são herdadas no sentido do vocabulário XAML. Os 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 orientação 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, porque 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 para XAML do Visual Studio no editor XML, o IntelliSense e seus menus suspensos farão um ótimo trabalho ao aglutinar 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 object para uma instância de classe.

Propriedades de conteúdo XAML

Alguns tipos definem uma de suas propriedades de modo que a propriedade permita 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 tags de elemento de objeto do tipo proprietário. As propriedades de conteúdo XAML oferecem 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 dessa propriedade na documentação de referência do Tempo de Execução do Windows. Por exemplo, a página Child de 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 objeto único de um Border, da seguinte forma:

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

Se a propriedade declarada como a propriedade de conteúdo XAML for o tipo Object ou o 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 tags 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 exemplo de uso:

<TextBlock>Hello!</TextBlock>

Se existir uma propriedade de conteúdo XAML para uma classe, isso é indicado no tópico de referência para a classe, na seção "Atributos". Procure o valor de ContentPropertyAttribute. Este 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, será apresentado 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 quaisquer elementos de propriedade ou inteiramente 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 suporta múltiplos elementos filho, assim como um modelo típico de coleção de suporte, tratando as propriedades que utilizam um tipo de coleção como implícitas e realizando um tratamento especial para quaisquer elementos 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 é 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 de mesmo nível em um StackPanel.

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

O mecanismo de sintaxe da coleção XAML

Inicialmente, pode parecer que o XAML está permitindo atribuir um valor à 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 suporte a XAML dependem de uma convenção em tipos de coleção subjacentes para permitir esta 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 objeto é criado primeiro a partir de um elemento e, em seguida, cada novo objeto é adicionado para a coleção contendo 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 tudo o que for passado deve ser uma correspondência de tipo com o tipo do 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 está a tentar usar for de leitura exclusiva, isto poderá causar uma exceção de análise de XAML. Basta usar a sintaxe de coleção implícita e você não verá essa exceção.

Quando usar a sintaxe do atributo ou elemento de propriedade

Todas as propriedades que permitem ser definidas em XAML suportarão a sintaxe de atributo ou de elemento de propriedade para a configuração direta de valores, mas potencialmente não suportarão essas sintaxes de forma intercambiável. Algumas propriedades oferecem suporte a qualquer sintaxe e algumas propriedades oferecem suporte a opções de sintaxe adicionais, como uma propriedade de conteúdo XAML. O tipo de sintaxe XAML suportado 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 duplo (float ou decimal), inteiro, booleano ou string, a propriedade sempre oferece 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. No caso dos primitivos, isto verifica-se sempre, a conversão de tipo está integrada no analisador. No entanto, alguns outros tipos de objeto também podem ser criados usando uma string especificada como um valor de atributo, em vez de um elemento de objeto dentro de um elemento de propriedade. Para que isso funcione, tem que haver uma conversão de tipo subjacente, suportada por essa propriedade específica ou suportada geralmente 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 oferecem 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 Tempo de Execução do Windows).

Lógica e regras de análise XAML

Às vezes, é útil ler o XAML de maneira semelhante à forma como um analisador de XAML deve lê-lo: como um conjunto de sequências 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 é que 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 de XAML geralmente promovem convenções de ordenação se você usar superfícies de design diferentes do editor XML, mas poderá 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 uma propriedade anexada. Semelhante à sintaxe do elemento de propriedade, a sintaxe de 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. Nome da propriedade 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, eles funcionam um pouco 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 oferecem 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, use uma sequência de escape para especificar um valor de cadeia de caracteres literal que comece com "{". A sequência de escape é "{}". Por exemplo, para especificar um valor de string que seja uma única chaveta de abertura, 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.

Observação

"\}" também funciona se estiver dentro de um atributo citado.  

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 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 é 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 incorreta em XAML ou em 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"/>.

Observação

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

As enumerações podem ser sinalizadas, o que significa que são atribuídas a 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 sem caracteres de espaço intervenientes. Os atributos flagwise não são comuns no vocabulário XAML do Tempo de Execução do Windows, mas ManipulationModes é um exemplo em que a definição de um valor de enumeração flagwise em XAML é suportada.

Interfaces em XAML

Em casos raros, você verá uma sintaxe XAML em que o tipo de propriedade é uma interface. No sistema de tipo 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 suportam padrões de design MVVM (Model-View-ViewModel), onde a interface ICommand é o contrato para a forma como as visões e os modelos interagem.

Convenções de marcadores de posição XAML em referência ao Tempo de Execução do Windows

Se tiveres examinado alguma das secções de Sintaxe dos tópicos de referência para as APIs do Windows Runtime que podem usar XAML, deves ter reparado que a sintaxe inclui bastantes espaços reservados. A sintaxe XAML é diferente da sintaxe C#, Microsoft Visual Basic ou Visual C++ component extensions (C++/CX) porque a sintaxe XAML é uma sintaxe de uso. Ele está sugerindo seu eventual uso 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 elementos em uma sintaxe XAML para uma propriedade, o nome mostrado é para o tipo que originalmente define 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 leve 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 do mundo real, esse nome de tipo é deliberadamente reduzido 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 na seção "Uso" que são definidos em uma seção Valores XAML que está diretamente sob a seção Sintaxe .

As seções de uso XAML também usam vários marcadores de posição generalizados. Esses espaços reservados não são redefinidos toda vez 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 marcadores de posição e o que eles significam no sentido geral:

  • object: teoricamente qualquer valor de objeto, mas muitas vezes praticamente limitado a certos tipos de objetos, como uma opção entre cadeia de caracteres e objeto. Deve verificar as Notas na referência para obter mais informações.
  • Propriedade do objeto: a propriedadedo 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: <objectproperty="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, então não tentamos sugerir nada sobre o tipo de delegado na sintaxe XAML. Se você quiser saber qual representante você deve implementar para um evento, isso está na seção Informações do evento do tópico de referência para o evento, em uma linha da tabela rotulada como Delegado.
  • enumMemberName: mostrado na sintaxe de atributo para todas as enumerações. Existe um marcador de posição similar para propriedades que usam um valor de enumeração, mas usualmente adiciona um prefixo ao marcador de posição com uma indicação 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: são tipos primitivos conhecidos pela linguagem XAML. Se estiver a programar em C# ou Visual Basic, esses tipos correspondem aos tipos equivalentes do Microsoft .NET, como Double, Int32, String e Boolean, e pode utilizar quaisquer membros desses tipos .NET ao trabalhar com os seus valores definidos por XAML no code-behind do .NET. Se você estiver programando usando C++/CX, usará os tipos primitivos 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á essas restrições anotadas em uma seção Valor da propriedade ou na seção Comentários e não em uma seção XAML, porque essas restrições se aplicam tanto aos usos de código quanto aos usos de XAML.

Dicas e truques, notas 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 a orientação dada neste tópico é a extensão de marcação StaticResource (e a relacionada ThemeResource). A função da extensão de marcação StaticResource é permitir organizar o seu XAML em recursos reutilizáveis provenientes de um ResourceDictionary XAML. Você quase sempre define modelos de controle e estilos relacionados em um ResourceDictionary. Você geralmente 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 para definir agora pode ser definida na sintaxe de atributo. Mas os benefícios da fatoração de 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 sobre como o espaço em branco e os feeds de linha são aplicados em exemplos XAML. Em particular, existem diferentes convenções para 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 saber mais, veja XAML e espaço em branco.
  • Last updated on