VisualStateManager Kelas

Referensi

Definisi

Ruang nama:: Microsoft.UI.Xaml

Penting

Beberapa informasi terkait produk prarilis yang dapat diubah secara signifikan sebelum dirilis. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Edit

Mengelola status visual dan logika untuk transisi antara status visual untuk kontrol. Juga menyediakan dukungan properti terlampir untuk VisualStateManager.VisualStateGroups, yaitu cara Anda menentukan status visual di XAML untuk templat kontrol.

/// [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 : DependencyObject

Public Class VisualStateManager
Inherits DependencyObject

Warisan: Object IInspectable DependencyObject VisualStateManager

Atribut: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Contoh

Contoh ini menunjukkan cara menggunakan VisualStateManager.VisualStateGroups properti terlampir XAML. Perhatikan bagaimana sebaliknya tidak ada tag "VisualStateManager" yang ditentukan. Secara konseptual, VisualStateManager.VisualStateGroups berisi status visual untuk kontrol, sebagai tag turunan langsung dari akar templat dalam templat kontrol.

Kumpulan status visual tertentu berisi satu VisualStateGroup, yang disebut "CommonStates", yang menentukan objek VisualState "PointerOver" dan "Normal". Saat pengguna meletakkan penunjuk di atas Tombol, Kisi berubah dari hijau menjadi merah dalam .5 detik. Saat pengguna memindahkan penunjuk menjauh dari tombol, Grid segera berubah kembali menjadi hijau.

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

Cuplikan berikutnya adalah kode untuk digunakan bersama dengan XAML, menunjukkan bagaimana aplikasi mungkin mendeteksi lebar jendela aplikasi dan menggunakan info tersebut untuk memanggil status visual yang sesuai.

String state = (Window.Current.Bounds.Width > 768) ? "DefaultLayout" : "Below768Layout";
VisualStateManager.GoToState(this, state, false); // 'this' is the LayoutAwarePage, scope is page code-behind

Keterangan

VisualStateManager mendukung dua fitur penting untuk penulis kontrol, dan untuk pengembang aplikasi yang menerapkan templat kustom ke kontrol:

Penulis kontrol atau pengembang aplikasi menambahkan elemen objek VisualStateGroup ke elemen akar definisi templat kontrol di XAML, menggunakan VisualStateManager.VisualStateGroups properti terlampir. VisualStateGroup Dalam elemen , setiap VisualState mewakili status visual kontrol diskrit. Masing-masing VisualState memiliki nama yang mewakili status UI yang dapat diubah oleh pengguna, atau diubah oleh logika kontrol. A VisualState sebagian besar terdiri dari Storyboard. Ini Storyboard menargetkan perubahan nilai properti dependensi individu yang harus diterapkan setiap kali kontrol berada dalam status visual tersebut.
Kontrol transisi penulis atau pengembang aplikasi antara status ini dengan memanggil metode GoToState statis dari VisualStateManager. Penulis kontrol melakukan ini setiap kali logika kontrol menangani peristiwa yang menunjukkan perubahan status, atau logika kontrol memulai perubahan status dengan sendirinya. Lebih umum bagi kode definisi kontrol untuk melakukan ini daripada kode aplikasi, sehingga semua status visual yang mungkin serta transisi dan kondisi pemicunya ada secara default untuk kode aplikasi, dan logika dienkapsulasi oleh kontrol.

Sebagian besar pengembang hanya akan menggunakan dua VisualStateManager API: VisualStateManager.VisualStateGroups, , dan GoToState, seperti yang dijelaskan di atas. API yang tersisa semuanya untuk dukungan ekstensi dan membuat kustom VisualStateManager. Untuk informasi selengkapnya, lihat bagian "VisualStateManager Kustom" dalam topik ini.

Saat Anda mengedit salinan gaya seperti yang diaktifkan oleh permukaan desain XAML Microsoft Visual Studio, status visual dari templat default ditentukan dalam XAML yang Anda edit. Pastikan Anda tidak menghapus status ini atau mengubah namanya, karena logika kontrol mengharapkan bahwa status visual ini ada di templat.

Selain status visual, model status visual juga mencakup transisi. Transisi adalah tindakan animasi yang dikontrol oleh Papan Cerita yang terjadi di antara setiap status visual saat status diubah. Transisi dapat didefinisikan secara berbeda untuk setiap kombinasi status awal dan status akhir seperti yang didefinisikan oleh serangkaian status visual kontrol Anda. Transisi didefinisikan oleh properti Transisi dari VisualStateGroup, di XAML menggunakan sintaks elemen properti. Sebagian besar templat kontrol default tidak menentukan transisi. Dengan tidak adanya transisi yang ditentukan secara khusus, transisi antar status terjadi secara instan (tanpa durasi). Untuk informasi selengkapnya, lihat VisualTransition.

VisualStateManager Kustom

Jika Anda ingin menerapkan logika Anda sendiri untuk transisi antar status (skenario lanjutan), Anda dapat membuat kelas yang mewarisi dari VisualStateManager. Ikuti panduan berikut:

Kelas turunan harus mengambil alih metode GoToStateCore yang dilindungi. Setiap instans kustom VisualStateManager menggunakan logika Core ini ketika metode GoToState-nya dipanggil.
Untuk mereferensikan kelas kustom VisualStateManager Anda, atur nilai VisualStateManager.CustomVisualStateManager properti terlampir pada elemen akar ControlTemplate tempat Anda ingin menggunakan perilaku kelas kustom VisualStateManager , bersama VisualStateManager.VisualStateGroups dengan penggunaan properti terlampir yang menentukan status visual untuk templat. Anda biasanya membuat instans kelas kustom VisualStateManager melalui konstruksi XAML default di Application.Resources. VisualStateManager.CustomVisualStateManager Kemudian properti terlampir diatur menggunakan referensi ekstensi markup {StaticResource} ke kunci sumber daya kustomVisualStateManager.

Itu adalah persyaratan dasar untuk membuat dan menggunakan kustom VisualStateManager. Anda juga dapat memilih untuk mengambil alih beberapa perilaku lagi:

Ambil alih RaiseCurrentStateChanged untuk mengontrol kapan peristiwa CurrentStateChanged diaktifkan oleh VisualStateGroup yang dikelola oleh VisualStateManager.
Ambil alih RaiseCurrentStateChanging untuk mengontrol kapan peristiwa CurrentStateChanging diaktifkan oleh VisualStateGroup yang dikelola oleh VisualStateManager.
Mengambil alih atau membebani konstruktor jika kelas kustom Anda memerlukan informasi tambahan untuk diinisialisasi.

Semua API lainnya (CustomVisualStateManagerProperty, GetCustomVisualStateManager, GetVisualStateGroups, SetCustomVisualStateManager) adalah infrastruktur untuk dukungan properti terlampir, dan Anda tidak perlu memanggilnya atau melakukan apa pun dengannya.

Status visual untuk elemen yang bukan kontrol

Status visual terkadang berguna untuk skenario di mana Anda ingin mengubah status beberapa area UI yang tidak segera menjadi subkelas Kontrol . Anda tidak dapat melakukan ini secara langsung karena parameter kontrol metode GoToState memerlukan Control subkelas, yang mengacu pada objek yang ditindak lanjuti VisualStateManager. Halaman adalah Control subkelas, dan cukup jarang Anda akan menampilkan UI dalam konteks di mana Anda tidak memiliki Page, atau akar Window.Content Anda bukan Control subkelas. Kami sarankan Anda menentukan UserControl kustom untuk menjadi Window.Content root atau menjadi kontainer untuk konten lain yang ingin Anda terapkan statusnya (seperti Panel). Kemudian Anda dapat memanggil GoToState di Anda UserControl dan menerapkan status terlepas dari apakah konten lainnya adalah Control. Misalnya Anda dapat menerapkan status visual ke UI yang hanya terdiri dari SwapChainPanel selama Anda menempatkannya di dalam status bernama dan UserControl dideklarasikan yang berlaku untuk properti induk UserControl atau bagian bernama SwapChainPanel dari templat.

Properti terlampir XAML

VisualStateManager adalah kelas layanan host untuk beberapa properti terlampir XAML.

Untuk mendukung akses prosesor XAML ke properti terlampir, dan juga untuk mengekspos operasi get dan set yang setara ke kode, setiap properti terpasang XAML memiliki sepasang Get metode pengakses dan Set . Cara lain untuk mendapatkan atau mengatur nilai dalam kode adalah dengan menggunakan sistem properti dependensi, memanggil GetValue atau SetValue dan meneruskan bidang pengidentifikasi sebagai pengidentifikasi properti dependensi.

Properti Terlampir	Deskripsi
VisualStateGroups	Mendapatkan koleksi elemen VisualStateGroup yang ditentukan oleh elemen akar definisi templat. Kontrol biasanya mendefinisikan ini sebagai bagian dari templatnya. Jenis: VisualStateGroup Bidang pengidentifikasi: T/A Metode pengaktif: GetVisualStateGroups Saat mendapatkan properti ini dalam kode, gunakan GetVisualStateGroups. Ini mengembalikan objek koleksi, yang dapat Anda tambahkan itemnya. Ini menyejajarkan perilaku pemrosesan XAML dari elemen turunan dari penggunaan elemen properti VisualStateManager.VisualStateGroups. Karena tidak ada pengidentifikasi properti dependensi publik untuk properti terlampir khusus ini, Anda tidak dapat menggunakan GetValue untuk mendapatkan nilai properti terlampir ini, Anda harus selalu menggunakan GetVisualStateGroups.
CustomVisualStateManager	Mendapatkan atau mengatur objek VisualStateManager kustom yang menangani transisi antara status kontrol. Jenis: VisualStateManager Bidang pengidentifikasi: CustomVisualStateManagerProperty Metode aksesor: GetCustomVisualStateManager, SetCustomVisualStateManager Properti terlampir ini hanya diperlukan untuk kasus di mana Anda ingin menggunakan kelas implementasi kustom untuk menangani perubahan status visual aplikasi Anda, bukan kelas VisualStateManager default yang diterapkan oleh Windows Runtime. Jika Anda tidak berniat menggunakan implementasi kustom, Anda tidak perlu mengatur properti ini.

Properti Terlampir

Deskripsi

VisualStateGroups

Mendapatkan koleksi elemen VisualStateGroup yang ditentukan oleh elemen akar definisi templat. Kontrol biasanya mendefinisikan ini sebagai bagian dari templatnya.

Jenis: VisualStateGroup
Bidang pengidentifikasi: T/A
Metode pengaktif: GetVisualStateGroups

Saat mendapatkan properti ini dalam kode, gunakan GetVisualStateGroups. Ini mengembalikan objek koleksi, yang dapat Anda tambahkan itemnya. Ini menyejajarkan perilaku pemrosesan XAML dari elemen turunan dari penggunaan elemen properti VisualStateManager.VisualStateGroups.

Karena tidak ada pengidentifikasi properti dependensi publik untuk properti terlampir khusus ini, Anda tidak dapat menggunakan GetValue untuk mendapatkan nilai properti terlampir ini, Anda harus selalu menggunakan GetVisualStateGroups.

CustomVisualStateManager

Mendapatkan atau mengatur objek VisualStateManager kustom yang menangani transisi antara status kontrol.

Jenis: VisualStateManager
Bidang pengidentifikasi: CustomVisualStateManagerProperty
Metode aksesor: GetCustomVisualStateManager, SetCustomVisualStateManager

Properti terlampir ini hanya diperlukan untuk kasus di mana Anda ingin menggunakan kelas implementasi kustom untuk menangani perubahan status visual aplikasi Anda, bukan kelas VisualStateManager default yang diterapkan oleh Windows Runtime. Jika Anda tidak berniat menggunakan implementasi kustom, Anda tidak perlu mengatur properti ini.

Konstruktor

VisualStateManager()

Menginisialisasi instans baru kelas VisualStateManager .

Properti

CustomVisualStateManagerProperty	Mengidentifikasi properti dependensi VisualStateManager.CustomVisualStateManager .
Dispatcher	Selalu kembali `null` di aplikasi SDK Aplikasi Windows. Gunakan DispatcherQueue sebagai gantinya . (Diperoleh dari DependencyObject)
DispatcherQueue	`DispatcherQueue` Mendapatkan yang dikaitkan dengan objek ini. `DispatcherQueue` mewakili fasilitas yang dapat mengakses `DependencyObject` pada utas UI bahkan jika kode dimulai oleh utas non-UI. (Diperoleh dari DependencyObject)

Properti yang Terlampir