VisualStateManager Classe
Definição
Importante
Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.
Gerencia estados visuais e a lógica para transições entre estados visuais para controles. Também fornece o suporte à propriedade anexada para VisualStateManager.VisualStateGroups, que é como você define estados visuais em XAML para um modelo de controle.
/// [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 VisualStateManager : DependencyObject[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 class VisualStateManager : DependencyObjectPublic Class VisualStateManager
Inherits DependencyObject- Herança
- Atributos
Exemplos
Este exemplo mostra como usar a VisualStateManager.VisualStateGroups propriedade anexada XAML. Observe como, caso contrário, não há nenhuma marca "VisualStateManager" definida. Conceitualmente, VisualStateManager.VisualStateGroups contém os estados visuais de um controle, como uma marca filho imediata da raiz do modelo em um modelo de controle.
O conjunto específico de estados visuais contém um VisualStateGroup, chamado "CommonStates", que define os objetos "PointerOver" e "Normal" do VisualState . Quando o usuário coloca o ponteiro sobre o Botão, a Grade muda de verde para vermelho em 0,5 segundos. Quando o usuário move o ponteiro para longe do botão, a Grade muda imediatamente de volta para verde.
<ControlTemplate TargetType="Button">
<Grid >
<VisualStateManager.VisualStateGroups>
<VisualStateGroup x:Name="CommonStates">
<VisualStateGroup.Transitions>
<!--Take one half second to transition to the PointerOver state.-->
<VisualTransition To="PointerOver"
GeneratedDuration="0:0:0.5"/>
</VisualStateGroup.Transitions>
<VisualState x:Name="Normal" />
<!--Change the SolidColorBrush, ButtonBrush, to red when the
Pointer is over the button.-->
<VisualState x:Name="PointerOver">
<Storyboard>
<ColorAnimation Storyboard.TargetName="ButtonBrush"
Storyboard.TargetProperty="Color" To="Red" />
</Storyboard>
</VisualState>
</VisualStateGroup>
</VisualStateManager.VisualStateGroups>
<Grid.Background>
<SolidColorBrush x:Name="ButtonBrush" Color="Green"/>
</Grid.Background>
</Grid>
</ControlTemplate>
<common:LayoutAwarePage>
<Grid>
...
<VisualStateManager.VisualStateGroups>
<!-- Visual states reflect the application's window size -->
<VisualStateGroup>
<VisualState x:Name="DefaultLayout">
<Storyboard>
</Storyboard>
</VisualState>
<VisualState x:Name="Below768Layout">
<Storyboard>
<ObjectAnimationUsingKeyFrames Storyboard.TargetProperty="(FrameworkElement.Margin)"
Storyboard.TargetName="ContentRoot">
<DiscreteObjectKeyFrame KeyTime="0">
<DiscreteObjectKeyFrame.Value>
<Thickness>20,20,20,20</Thickness>
</DiscreteObjectKeyFrame.Value>
</DiscreteObjectKeyFrame>
</ObjectAnimationUsingKeyFrames>
<ObjectAnimationUsingKeyFrames Storyboard.TargetProperty="(FrameworkElement.HorizontalAlignment)"
Storyboard.TargetName="FooterPanel">
<DiscreteObjectKeyFrame KeyTime="0">
<DiscreteObjectKeyFrame.Value>
<HorizontalAlignment>Left</HorizontalAlignment>
</DiscreteObjectKeyFrame.Value>
</DiscreteObjectKeyFrame>
</ObjectAnimationUsingKeyFrames>
</Storyboard>
</VisualState>
</VisualStateGroup>
</VisualStateManager.VisualStateGroups>
</Grid>
</common:LayoutAwarePage>
O próximo snippet de código é o código para acompanhar o XAML, mostrando como um aplicativo pode detectar a largura da janela do aplicativo e usar essas informações para chamar o estado visual apropriado.
String state = (Window.Current.Bounds.Width > 768) ? "DefaultLayout" : "Below768Layout";
VisualStateManager.GoToState(this, state, false); // 'this' is the LayoutAwarePage, scope is page code-behind
Comentários
VisualStateManager dá suporte a dois recursos importantes para autores de controle e para desenvolvedores de aplicativos que estão aplicando um modelo personalizado a um controle:
- Os autores de controle ou desenvolvedores de aplicativos adicionam elementos de objeto VisualStateGroup ao elemento raiz de uma definição de modelo de controle em XAML, usando a
VisualStateManager.VisualStateGroupspropriedade anexada. Dentro de umVisualStateGroupelemento , cada VisualState representa um estado visual discreto de um controle. CadaVisualStateum tem um nome que representa um estado de interface do usuário que pode ser alterado pelo usuário ou alterado pela lógica de controle. UmVisualStateconsiste principalmente em um Storyboard. IssoStoryboardse destina a alterações de valor de propriedade de dependência individuais que devem ser aplicadas sempre que o controle estiver nesse estado visual. - Controlar a transição de autores ou desenvolvedores de aplicativos entre esses estados chamando o método GoToState estático de
VisualStateManager. Os autores de controle fazem isso sempre que a lógica de controle manipula eventos que indicam uma alteração de estado ou a lógica de controle inicia uma alteração de estado por si só. É mais comum que o código de definição de controle faça isso em vez do código do aplicativo, para que todos os estados visuais possíveis e suas transições e condições de gatilho estejam lá por padrão para o código do aplicativo, e a lógica seja encapsulada pelo controle.
A maioria dos desenvolvedores usará apenas duas das VisualStateManager APIs: VisualStateManager.VisualStateGroups, e GoToState, conforme descrito acima. As APIs restantes são todas para suporte à extensão e criação de um personalizado VisualStateManager. Para obter mais informações, consulte a seção "VisualStateManager personalizado" neste tópico.
Quando você edita cópias de estilos como habilitadas pela superfície de design XAML do Microsoft Visual Studio, os estados visuais do modelo padrão são definidos no XAML que você está editando. Certifique-se de não excluir esses estados ou alterar seus nomes, pois a lógica de controle espera que esses estados visuais existam no modelo.
Além dos estados visuais, o modelo de estado visual também inclui transições. As transições são ações de animação controladas por um Storyboard que ocorrem entre cada estado visual quando o estado é alterado. A transição pode ser definida de forma diferente para cada combinação de estado inicial e final, conforme definido pelo conjunto de estados visuais do controle. As transições são definidas pela propriedade Transitions de VisualStateGroup, em XAML usando a sintaxe do elemento de propriedade. A maioria dos modelos de controle padrão não define transições. Na ausência de transições definidas especificamente, as transições entre estados ocorrem instantaneamente (duração zero). Para obter mais informações, consulte VisualTransition.
VisualStateManager personalizado
Se você quiser implementar sua própria lógica para transições entre estados (um cenário avançado), poderá criar uma classe que herda de VisualStateManager. Siga estas diretrizes:
- A classe derivada deve substituir o método GoToStateCore protegido. Qualquer instância do personalizado
VisualStateManagerusa essa lógica Core quando seu método GoToState é chamado. - Para fazer referência à classe personalizada
VisualStateManager, defina o valor daVisualStateManager.CustomVisualStateManagerpropriedade anexada no elemento raiz de um ControlTemplate em que você deseja usar o comportamento da classe personalizadaVisualStateManager, juntamente com oVisualStateManager.VisualStateGroupsuso da propriedade anexada que define os estados visuais do modelo. Normalmente, você cria uma instância da classe personalizadaVisualStateManagerpor meio da construção XAML padrão em Application.Resources. Em seguida, aVisualStateManager.CustomVisualStateManagerpropriedade anexada é definida usando uma referência de extensão de marcação {StaticResource} à chave do recurso personalizadoVisualStateManager.
Esses são os requisitos básicos para criar e usar um personalizado VisualStateManager. Você também pode optar por substituir mais alguns comportamentos:
- Substitua RaiseCurrentStateChanged para controlar quando o evento CurrentStateChanged é disparado por um VisualStateGroup que está sendo gerenciado pelo
VisualStateManager. - Substitua RaiseCurrentStateChanging para controlar quando o evento CurrentStateChanging é acionado por um VisualStateGroup que está sendo gerenciado pelo
VisualStateManager. - Substitua ou sobrecarregue o construtor se sua classe personalizada precisar de informações adicionais para inicializar.
Todas as outras API (CustomVisualStateManagerProperty, GetCustomVisualStateManager, GetVisualStateGroups, SetCustomVisualStateManager) são infraestrutura para suporte à propriedade anexada e você não precisa chamá-las ou fazer nada com elas.
Estados visuais para elementos que não são controles
Às vezes, os estados visuais são úteis para cenários em que você deseja alterar o estado de alguma área da interface do usuário que não é imediatamente uma subclasse Control . Você não pode fazer isso diretamente porque o parâmetro de controle do método GoToState requer uma Control subclasse, que se refere ao objeto sobre o qual o VisualStateManager atua.
Page é uma Control subclasse e é bastante raro que você esteja mostrando a interface do usuário em um contexto em que você não tem um Pageou sua raiz Window.Content não é uma Control subclasse. Recomendamos que você defina um UserControl personalizado para ser a Window.Content raiz ou ser um contêiner para outro conteúdo ao qual você deseja aplicar estados (como um Painel). Em seguida, você pode chamar GoToState em seu UserControl e aplicar estados, independentemente de o restante do conteúdo ser um Control. Por exemplo, você pode aplicar estados visuais à interface do usuário que, de outra forma, consistem em apenas um SwapChainPanel , desde que você tenha colocado isso em seus UserControl estados nomeados e declarados que se aplicam às propriedades do pai UserControl ou da parte nomeada SwapChainPanel do modelo.
Propriedades anexadas de XAML
VisualStateManager é a classe de serviço de host para várias propriedades anexadas XAML.
Para dar suporte ao acesso do processador XAML às propriedades anexadas e também para expor operações de obtenção e definição equivalentes ao código, cada propriedade anexada XAML tem um par de Get métodos acessadores e Set . Outra maneira de obter ou definir o valor no código é usar o sistema de propriedades de dependência, chamando GetValue ou SetValue e passando o campo identificador como o identificador da propriedade de dependência.
| Propriedade anexada | Descrição |
|---|---|
| Visualstategroups | Obtém a coleção de elementos VisualStateGroup que são definidos por um elemento raiz de uma definição de modelo. Um controle normalmente define isso como parte de seu modelo.
Ao obter essa propriedade no código, use GetVisualStateGroups. Isso retorna um objeto de coleção ao qual você pode adicionar itens. Isso paraleliza o comportamento de processamento XAML de qualquer elemento filho de um uso de elemento de propriedade VisualStateManager.VisualStateGroups. Como não há nenhum identificador de propriedade de dependência pública para essa propriedade anexada específica, você não pode usar GetValue para obter esse valor de propriedade anexada, você sempre precisa usar GetVisualStateGroups. |
| Customvisualstatemanager | Obtém ou define o objeto VisualStateManager personalizado que manipula transições entre os estados de um controle.
Essa propriedade anexada só é necessária para casos em que você deseja usar uma classe de implementação personalizada para lidar com as alterações de estado visual do aplicativo, em vez da classe VisualStateManager padrão implementada pelo Windows Runtime. Se você não pretende usar uma implementação personalizada, não precisa definir essa propriedade. |
Construtores
| VisualStateManager() |
Inicializa uma nova instância da classe VisualStateManager . |
Propriedades
| CustomVisualStateManagerProperty |
Identifica a propriedade de dependência VisualStateManager.CustomVisualStateManager . |
| Dispatcher |
Sempre retorna |
| DispatcherQueue |
Obtém o ao |
Propriedades Anexadas
| CustomVisualStateManager |
Obtém ou define o objeto VisualStateManager personalizado que manipula transições entre os estados de um controle. |
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) |
| GetCustomVisualStateManager(FrameworkElement) |
Obtém o valor da propriedade anexada VisualStateManager.CustomVisualStateManager . |
| GetValue(DependencyProperty) |
Retorna o valor efetivo atual de uma propriedade de dependência de um DependencyObject. (Herdado de DependencyObject) |
| GetVisualStateGroups(FrameworkElement) |
Recupera a coleção de objetos VisualStateGroup associados ao FrameworkElement especificado. |
| GoToState(Control, String, Boolean) |
Faz a transição de um controle entre dois estados, solicitando um novo VisualState por nome. |
| GoToStateCore(Control, FrameworkElement, String, VisualStateGroup, VisualState, Boolean) |
Quando substituído em uma classe derivada, faz a transição de um controle entre estados. |
| RaiseCurrentStateChanged(VisualStateGroup, VisualState, VisualState, Control) |
Quando substituído em uma classe derivada, dispara o evento CurrentStateChanged no VisualStateGroup especificado. |
| RaiseCurrentStateChanging(VisualStateGroup, VisualState, VisualState, Control) |
Quando substituído em uma classe derivada, dispara o evento CurrentStateChanging no VisualStateGroup especificado. |
| 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) |
| SetCustomVisualStateManager(FrameworkElement, VisualStateManager) |
Define o valor da propriedade anexada VisualStateManager.CustomVisualStateManager . |
| 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) |