VisualState Classe

Definizione

Spazio dei nomi:

Windows.UI.Xaml

Rappresenta l'aspetto visivo di un elemento dell'interfaccia utente quando si trova in uno stato specifico. Gli stati di visualizzazione usano Setter o uno Storyboard per impostare le proprietà dell'interfaccia utente all'interno di pagine o modelli di controllo in cui è definito VisualState.

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>

Ereditarietà

Object Platform::Object IInspectable DependencyObject VisualState

Attributi

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute ContentPropertyAttribute

Requisiti Windows

Famiglia di dispositivi	Windows 10 (è stato introdotto in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (è stato introdotto in v1.0)

Esempio

In questo esempio viene creato un oggetto VisualStateGroup nell'oggetto ControlTemplate di un controllo Button denominato "CommonStates" e vengono aggiunti oggetti VisualState per gli stati, "Normal", "Pressed" e "PointerOver". Il pulsante definisce anche uno stato denominato "Disabled" che si trova in "CommonStates" denominato VisualStateGroup, ma l'esempio lo omette per brevità.

<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>

Commenti

Un elemento VisualState deve essere sempre contenuto all'interno di un elemento padre Di VisualStateGroup nel markup XAML. VisualStateGroup ha una proprietà di raccolta implicita States, pertanto è possibile inserire ogni Oggetto VisualState come elemento figlio immediato dell'elemento padre VisualStateGroup. Ad esempio:

<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>

Quando si usa StateTriggers, assicurarsi che VisualStateGroup sia dichiarato nel primo elemento figlio della radice affinché i trigger vengano applicati automaticamente.

Stato predefinito

È legale e comune definire un oggetto VisualState con un attributo x:Name , ma non specifica nulla nello Storyboard. Ciò è utile perché un oggetto VisualState di questo tipo userà tutti i valori presenti nel modello predefinito. È quindi possibile richiedere in modo specifico lo stato vuoto da una chiamata GoToState . Quando uno stato vuoto diventa lo stato corrente, che annulla tutte le modifiche apportate alle proprietà del modello apportate da uno stato di visualizzazione precedente dallo stesso Oggetto VisualStateGroup. Per altre info su come usare i gruppi per gli stati di visualizzazione, vedi Animazioni con storyboard per gli stati di visualizzazione.

Quando si usa StateTriggers, non è più necessario creare un oggetto VisualState vuoto per chiamare GoToState . Quando le condizioni per stateTrigger non vengono più soddisfatte, tutte le modifiche apportate dalle proprietà apportate dall'oggetto VisualState corrispondente vengono rimosse automaticamente e i valori forniti nel markup predefinito diventano effettivi.

VisualState e x:Name

Il metodo GoToState (che viene in genere chiamato dal codice del controllo) richiede un parametro stateName per informare VisualStateManager quale stato deve essere usato come stato corrente. Specificare un attributo x:Name per ogni oggetto VisualState che dovrà essere applicato manualmente usando una chiamata GoToState dal codice. Se si usa StateTriggers per attivare automaticamente un oggetto VisualState dal markup, non è necessario specificare un attributo x:Name in tale VisualState.

Se si usano transizioni visive, anche il valore dell'attributo x:Name di visualState viene fatto riferimento ai valori From o To di visualTransition. In questo caso il nome identifica lo stato o gli stati tra cui VisualTransition fornisce i valori intermedi.

Il valore dell'attributo x:Name specificato per visualState deve essere univoco all'interno del codice XAML del modello di controllo in cui è presente VisualState. L'ambito per i nomi di stato non è limitato a ogni oggetto VisualStateGroup, ma ha come ambito tutti gli stati di visualizzazione nel modello. Ad esempio, non è possibile definire due stati diversi denominati "Evidenziati" nello stesso codice XAML del modello, anche se si trovano in gruppi diversi.

È necessario utilizzare l'attributo x:Name per assegnare un nome a uno stato di visualizzazione o a un gruppo di stato di oggetti visivi; l'attributo senza prefisso "Name" non funzionerà. VisualState e VisualStateGroup dispongono di una proprietà Name, ma di sola lettura. Tale proprietà Name esiste per scenari avanzati che usano il codice per esaminare il contenuto di un modello di controllo in fase di esecuzione, non per l'impostazione da XAML.

Sostituzione del modello di controllo di un controllo esistente

Gli sviluppatori di app che usano un controllo nell'interfaccia utente dell'app possono sostituire il modello di controllo impostando la proprietà Control.Template su un valore diverso. In alternativa, è possibile sostituire il modello dichiarando un nuovo stile che usa la chiave di stile implicita per tale controllo. Per altre informazioni su questi concetti, vedi Guida introduttiva: Modelli di controllo.

Quando sostituisci un modello di controllo, è importante riprodurre tutti gli elementi VisualState denominati esistenti dal contenuto VisualStateManager.VisualStateGroups del modello di controllo originale in XAML. Il codice di controllo (che non si sta modificando) chiama GoToState. Gli stati con tali nomi devono esistere nel modello di controllo. Una richiesta per un oggetto VisualState mancante non genererà eccezioni, ma spesso lascerà il controllo in uno stato di visualizzazione che genererà confusione per l'utente. Ad esempio, se non si specifica un oggetto VisualState denominato "Checked" per un controllo CheckBox , non viene visualizzato alcun feedback visivo quando l'utente seleziona il controllo. L'utente si aspetta che ci sia qualcosa di visivamente diverso per distinguere un checkBox selezionato da un controllo CheckBox deselezionato. Pertanto, un errore di riprodurre gli stati di visualizzazione nella parte dello sviluppatore dell'app farà sembrare il controllo interrotto per l'utente.

Quando usi un IDE come Microsoft Visual Studio, le azioni che usi per sostituire un modello di controllo forniscono l'opzione per iniziare con una copia del codice XAML del modello originale, in modo da visualizzare tutti gli elementi originali denominati VisualState e altre composizioni di controlli che stai sostituendo. È consigliabile iniziare con le copie del modello, quindi modificarle, in modo da non omettere accidentalmente uno stato di visualizzazione previsto dal nuovo modello.

Attributi degli stati di visualizzazione denominati di un controllo personalizzato

Se si definisce un controllo personalizzato con stati di visualizzazione nel relativo codice XAML del modello di controllo, è consigliabile attribuire alla classe di controllo l'attributo per indicare ai consumer di controllo quali stati di visualizzazione sono disponibili. A tale scopo, applicare uno o più attributi TemplateVisualState a livello di classe del codice di definizione del controllo. Ogni attributo deve specificare l'attributo x:Name dello stato, ovvero il valore stateName che un consumer di controllo passerà in una chiamata GoToState per usare tale stato di visualizzazione. Se VisualState fa parte di un oggetto VisualStateGroup, questo deve essere indicato anche nei valori dell'attributo.

Costruttori

VisualState()

Inizializza una nuova istanza della classe VisualState .

Proprietà

Dispatcher	Ottiene coreDispatcher a cui è associato questo oggetto. CoreDispatcher rappresenta una funzionalità che può accedere a DependencyObject nel thread dell'interfaccia utente anche se il codice viene avviato da un thread non dell'interfaccia utente. (Ereditato da DependencyObject)
Name	Ottiene il nome dell'oggetto VisualState.
Setters	Ottiene un insieme di oggetti Setter che definiscono valori di proprietà discreti che controllano l'aspetto di UIElementquando viene applicato questo oggetto VisualState .
StateTriggers	Ottiene un insieme di oggetti StateTriggerBase che indicano quando deve essere applicato questo oggetto VisualState . Se sono attivi (non tutti) dei trigger, verrà applicato VisualState.
Storyboard	Ottiene o imposta uno Storyboard che definisce i valori e l'aspetto di proprietà specifici dello stato del controllo quando usa questo stato di visualizzazione.

Metodi

ClearValue(DependencyProperty)	Cancella il valore locale di una proprietà di dipendenza. (Ereditato da DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Restituisce qualsiasi valore di base stabilito per una proprietà di dipendenza, che si applica nei casi in cui un'animazione non è attiva. (Ereditato da DependencyObject)
GetValue(DependencyProperty)	Restituisce il valore effettivo corrente di una proprietà di dipendenza da dependencyObject. (Ereditato da DependencyObject)
ReadLocalValue(DependencyProperty)	Restituisce il valore locale di una proprietà di dipendenza, se è impostato un valore locale. (Ereditato da DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registra una funzione di notifica per l'ascolto delle modifiche apportate a una dipendenza specifica in questa istanza di DependencyObject . (Ereditato da DependencyObject)
SetValue(DependencyProperty, Object)	Imposta il valore locale di una proprietà di dipendenza su dependencyObject. (Ereditato da DependencyObject)
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Annulla una notifica di modifica registrata in precedenza chiamando RegisterPropertyChangedCallback. (Ereditato da DependencyObject)

Vedi anche

• DependencyObject
• VisualStateGroup
• Animazioni con storyboard per stati di visualizzazione
• Animazioni con storyboard
• Attributo x:Name
• Guida introduttiva: Modelli di controllo
• Esempio di applicazione di stili di controllo XAML e app
• Esempio master/dettaglio (Windows 10)