VisualState Classe

Definição

Namespace:

Windows.UI.Xaml

Representa a aparência visual de um elemento de interface do usuário quando ele está em um estado específico. Os estados visuais usam Setters ou um Storyboard para definir propriedades de interface do usuário em páginas ou modelos de controle em que o VisualState está definido.

public ref class VisualState sealed : DependencyObject

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.UI.Xaml.Markup.ContentProperty(Name="Storyboard")]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
class VisualState final : DependencyObject

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.UI.Xaml.Markup.ContentProperty(Name="Storyboard")]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
public sealed class VisualState : DependencyObject

Public NotInheritable Class VisualState
Inherits DependencyObject

<VisualState x:Name="stateName" />
-or-
<VisualState x:Name="stateName">
  singleStoryboard
</VisualState>
-or-
<VisualState x:Name="stateName">
  <VisualState.Setters>
    oneOrMoreSetters
  </VisualState.Setters>
  [optional]singleStoryboard
</VisualState>
-or-
<VisualState x:Name="stateName">
  <VisualState.StateTriggers>
    oneOrMoreTriggers
  </VisualState.StateTriggers>  
  <VisualState.Setters>
    oneOrMoreSetters
  </VisualState.Setters>
  [optional]singleStoryboard
</VisualState>

Herança

Object Platform::Object IInspectable DependencyObject VisualState

Atributos

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute ContentPropertyAttribute

Requisitos do Windows

Família de dispositivos	Windows 10 (introduzida na 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduzida na v1.0)

Exemplos

Este exemplo cria um VisualStateGroup no ControlTemplate de um Botão chamado "CommonStates" e adiciona objetos VisualState para os estados "Normal", "Pressed" e "PointerOver". O Botão também define um estado chamado "Desabilitado" que está em "CommonStates" chamado VisualStateGroup, mas o exemplo o omite para fins de brevidade.

<ControlTemplate TargetType="Button">
  <Border x:Name="RootElement">

    <VisualStateManager.VisualStateGroups>

      <!--Define the states for the common states.
          The states in the VisualStateGroup are mutually exclusive to
          each other.-->
      <VisualStateGroup x:Name="CommonStates">

        <!--The Normal state is the state the button is in
            when it is not in another state from this VisualStateGroup.-->
        <VisualState x:Name="Normal" />

        <!--Change the SolidColorBrush, BorderBrush, to red when the
            Pointer is over the button.-->
        <VisualState x:Name="PointerOver">
          <Storyboard>
            <ColorAnimation Storyboard.TargetName="BorderBrush" 
                              Storyboard.TargetProperty="Color" To="Red" />

          </Storyboard>

        </VisualState>

        <!--Change the SolidColorBrush, BorderBrush, to Transparent when the
            button is pressed.-->
        <VisualState x:Name="Pressed">
          <Storyboard >
            <ColorAnimation Storyboard.TargetName="BorderBrush" 
                              Storyboard.TargetProperty="Color" To="Transparent"/>
          </Storyboard>
        </VisualState>
          <!--The Disabled state is omitted for brevity.-->
        </VisualStateGroup>
  
    </VisualStateManager.VisualStateGroups>
    

    <Border.Background>
      <SolidColorBrush x:Name="BorderBrush" Color="Black"/>
    </Border.Background>

    <Grid Background="{TemplateBinding Background}" Margin="4">
      <ContentPresenter
        HorizontalAlignment="{TemplateBinding HorizontalContentAlignment}"
        VerticalAlignment="{TemplateBinding VerticalContentAlignment}"
        Margin="4,5,4,4" />

    </Grid>


  </Border>
</ControlTemplate>

<Page>
    <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <VisualStateManager.VisualStateGroups>
            <VisualStateGroup>
                <VisualState>
                    <VisualState.StateTriggers>
                        <!-- VisualState to be triggered when window width is >=720 effective pixels -->
                        <AdaptiveTrigger MinWindowWidth="720"/>
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Target="myPanel.Orientation" Value="Horizontal"/>
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateManager.VisualStateGroups>
        <StackPanel x:Name="myPanel" Orientation="Vertical">
            <TextBlock x:Name="myTextBlock" MaxLines="5" Style="{ThemeResource BodyTextBlockStyle}"/>
        </StackPanel>
    </Grid>
</Page>

Comentários

Um elemento VisualState sempre deve estar contido em um pai VisualStateGroup na marcação XAML. O VisualStateGroup tem uma propriedade de coleção implícita States, para que você possa colocar cada VisualState como um elemento filho imediato do pai visualStateGroup . Por exemplo:

<VisualStateGroup x:Name="CommonStates">
   <VisualState x:Name="Normal"/>
   <VisualState x:Name="PointerOver">...</VisualState>
<!-- do not need explicit VisualStateGroups.States property element, States is the XAML content property-->
</VisualStateGroup>

Ao usar StateTriggers, verifique se o VisualStateGroup é declarado no primeiro filho da raiz para que os gatilhos entrem em vigor automaticamente.

Estado padrão

É legal e comum definir um VisualState que tenha um atributo x:Name , mas não especifique nada no Storyboard. Isso é útil porque esse VisualState usará quaisquer valores presentes no modelo padrão. Em seguida, você pode solicitar especificamente o estado vazio de uma chamada GoToState . Quando um estado vazio se torna o estado atual, isso cancela todas as modificações nas propriedades do modelo feitas por um estado visual anterior do mesmo VisualStateGroup. Para obter mais informações sobre como usar grupos para estados visuais, consulte Animações com storyboard para estados visuais.

Quando você usa StateTriggers, não é mais necessário criar um VisualState vazio para chamar GoToState . Quando as condições de um StateTrigger não forem mais atendidas, todas as modificações nas propriedades feitas pelo VisualState correspondente serão removidas automaticamente e os valores fornecidos na marcação padrão entrarão em vigor.

VisualState e x:Name

O método GoToState (que normalmente é chamado do código de controle) requer um parâmetro stateName para informar ao VisualStateManager qual estado deve ser usado como um estado atual. Especifique um atributo x:Name para cada VisualState que precisará ser aplicado manualmente usando uma chamada GoToState do código. Se você estiver usando StateTriggers para disparar automaticamente um VisualState da marcação, não será necessário especificar um atributo x:Name nesse VisualState.

Se você usar transições visuais, o valor do atributo x:Name de um VisualState também será referenciado pelos valores From ou To de um VisualTransition. Nesse caso, o nome identifica o estado ou os estados entre os quais o VisualTransition fornece os valores intermediários.

O valor do atributo x:Name especificado para um VisualState deve ser exclusivo dentro do modelo de controle XAML em que o VisualState existe. O escopo para nomes de estado não está apenas no escopo de cada VisualStateGroup, ele tem como escopo todos os estados visuais no modelo. Por exemplo, você não pode definir dois estados diferentes chamados "Focalizados" no mesmo modelo XAML, mesmo que estejam em grupos diferentes.

Você deve usar o atributo x:Name para nomear um estado visual ou um grupo de estado de visuais; o atributo não prefixado "Name" não funcionará. VisualState e VisualStateGroup têm uma propriedade Name , mas são somente leitura. Essa propriedade Name existe para cenários avançados que usam código para examinar o conteúdo de um modelo de controle em tempo de execução, não para a configuração de XAML.

Substituindo o modelo de controle de um controle existente

Se você for um desenvolvedor de aplicativos usando um controle na interface do usuário do aplicativo, poderá substituir o modelo de controle definindo a propriedade Control.Template como um valor diferente. Ou você pode substituir o modelo declarando um novo estilo que usa a chave de estilo implícita para esse controle. Para obter mais informações sobre esses conceitos, consulte Início Rápido: modelos de controle.

Quando você substitui um modelo de controle, é importante reproduzir todos os elementos visualstate nomeados existentes do conteúdo VisualStateManager.VisualStateGroups do modelo de controle original em XAML. O código de controle (que você não está modificando) está chamando GoToState. Estados com esses nomes devem existir no modelo de controle. Uma solicitação para um VisualState ausente não gerará exceções, mas geralmente deixará o controle em um estado visual que será confuso para o usuário. Por exemplo, se você não fornecer um VisualState chamado "Checked" para um controle CheckBox , nenhum comentário visual será exibido quando o usuário selecionar o controle. O usuário espera que haja algo visualmente diferente para distinguir uma CheckBox marcada de uma CheckBox desmarcada. Portanto, uma falha ao reproduzir os estados visuais por parte do desenvolvedor do aplicativo fará com que o controle pareça quebrado para o usuário.

Quando você usa um IDE como o Microsoft Visual Studio, as ações que você usa para substituir um modelo de controle fornecem a opção de começar com uma cópia do modelo original XAML, para que você possa ver todos os elementos originais chamados VisualState e outras composições de controle que você está substituindo. É melhor começar com cópias de modelo e modificá-las para que você não omita acidentalmente um estado visual esperado do novo modelo.

Atribuir os estados visuais nomeados de um controle personalizado

Se você estiver definindo um controle personalizado que tenha estados visuais em seu modelo de controle XAML, é uma prática recomendada atribuir a classe de controle para indicar aos consumidores quais estados visuais estão disponíveis. Para fazer isso, aplique um ou mais atributos TemplateVisualState no nível de classe do código de definição de controle. Cada atributo deve especificar o atributo x:Name do estado, que é o valor stateName que um consumidor de controle passaria em uma chamada GoToState para usar esse estado visual. Se o VisualState fizer parte de um VisualStateGroup, isso também deverá ser indicado em seus valores de atributo.

Construtores

VisualState()

Inicializa uma nova instância da classe VisualState .

Propriedades

Dispatcher	Obtém o CoreDispatcher ao qual esse objeto está associado. O CoreDispatcher representa uma instalação que pode acessar o DependencyObject no thread da interface do usuário, mesmo que o código seja iniciado por um thread que não seja da interface do usuário. (Herdado de DependencyObject)
Name	Obtém o nome do VisualState.
Setters	Obtém uma coleção de objetos Setter que definem valores de propriedade discretos que controlam a aparência de UIElements quando este VisualState é aplicado.
StateTriggers	Obtém uma coleção de objetos StateTriggerBase que indicam quando esse VisualState deve ser aplicado. Se algum (nem todos) dos gatilhos estiver ativo, o VisualState será aplicado.
Storyboard	Obtém ou define um Storyboard que define valores de propriedade específicos do estado e a aparência do controle quando ele está usando esse estado visual.

Métodos

ClearValue(DependencyProperty)	Limpa o valor local de uma propriedade de dependência. (Herdado de DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Retorna qualquer valor base estabelecido para uma propriedade de dependência, que se aplicaria nos casos em que uma animação não está ativa. (Herdado de DependencyObject)
GetValue(DependencyProperty)	Retorna o valor efetivo atual de uma propriedade de dependência de um DependencyObject. (Herdado de DependencyObject)
ReadLocalValue(DependencyProperty)	Retorna o valor local de uma propriedade de dependência, se um valor local for definido. (Herdado de DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registra uma função de notificação para escutar alterações em uma DependencyProperty específica nessa instância dependencyObject . (Herdado de DependencyObject)
SetValue(DependencyProperty, Object)	Define o valor local de uma propriedade de dependência em um DependencyObject. (Herdado de DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Cancela uma notificação de alteração que foi registrada anteriormente chamando RegisterPropertyChangedCallback. (Herdado de DependencyObject)

Confira também

• DependencyObject
• VisualStateGroup
• Animações de storyboard para estados visuais
• Animações com storyboard
• Atributo x:Name
• Início rápido: modelos de controle
• Exemplo de estilo de aplicativo e controle XAML
• Exemplo de mestre/detalhes (Windows 10)