VisualState Classe

  • Referência

Definição

Namespace:
Microsoft.UI.Xaml
Editar

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 é definido.

public ref class VisualState sealed : DependencyObject
/// [Microsoft.UI.Xaml.Markup.ContentProperty(Name="Storyboard")]
/// [Windows.Foundation.Metadata.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class VisualState final : DependencyObject
[Microsoft.UI.Xaml.Markup.ContentProperty(Name="Storyboard")]
[Windows.Foundation.Metadata.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
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
ContentPropertyAttribute ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Exemplos

Este exemplo cria um VisualStateGroup no ControlTemplate de um Botão chamado "CommonStates" e adiciona VisualState objetos para os estados, "Normal", "Pressionado" e "PointerOver". O Button também define um estado chamado "Desabilitado" que está em "CommonStates" chamado VisualStateGroup, mas o exemplo omite-o para 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 VisualState elemento 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 um como um elemento filho imediato do VisualStateGroup pai. 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 que tenha um VisualStateatributo x:Name , mas não especifique nada no Storyboard. Isso é útil porque tal usará VisualState todos os 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 em propriedades de modelo feitas por um estado visual anterior do mesmo VisualStateGroup.

Ao usar StateTriggers, você não precisará mais criar um vazio VisualState para chamar GoToState . Quando as condições de um StateTrigger não forem mais atendidas, todas as modificações nas propriedades feitas pelo correspondente VisualState 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 stateName parâmetro para informar ao VisualStateManager qual estado deve ser usado como um estado atual. Especifique um atributo x:Name para cada VisualState um que precisará ser aplicado manualmente usando uma GoToState chamada do código. Se você estiver usando StateTriggers para disparar automaticamente uma VisualState marcação de de, 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 De ou Para de um VisualTransition. Nesse caso, o nome identifica o estado ou 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 "Focados" 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 Name propriedade, mas elas são somente leitura. Essa Name propriedade 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 do XAML.

Substituindo um modelo de controle de 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 Modelos de controle XAML.

Quando você substitui um modelo de controle, é importante reproduzir todos os elementos nomeados VisualState existentes do conteúdo do modelo de VisualStateManager.VisualStateGroups 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 ausente VisualState 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 "Verificado" 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 um verificado CheckBox de um desmarcado CheckBox. 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 nomeados VisualState originais 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 tem estados visuais em seu modelo de controle XAML, é uma prática recomendada atribuir a classe de controle para indicar para controlar os 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 stateName valor 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

Sempre retorna null em um aplicativo SDK do Aplicativo Windows. Em vez disso, use DispatcherQueue .

(Herdado de DependencyObject)
DispatcherQueue

Obtém o ao DispatcherQueue qual esse objeto está associado. O DispatcherQueue 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 nesta 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)

Aplica-se a

Confira também