Pintasan papan ketik

Gambar utama keyboard Surface

Tombol akselerator (atau akselerator keyboard) adalah pintasan keyboard yang meningkatkan kegunaan dan aksesibilitas aplikasi Windows Anda dengan menyediakan cara intuitif bagi pengguna untuk memanggil tindakan atau perintah umum tanpa menavigasi UI aplikasi.

Nota

Keyboard sangat diperlukan bagi pengguna dengan disabilitas tertentu (lihat Aksesibilitas keyboard), dan juga merupakan alat penting bagi pengguna yang lebih menyukainya sebagai cara yang lebih efisien untuk berinteraksi dengan aplikasi.

Lihat topik Tombol akses untuk detail tentang menavigasi UI aplikasi Windows dengan pintasan keyboard.

Untuk membuat pintasan keyboard kustom Anda sendiri, lihat topik Peristiwa keyboard .

Gambaran Umum

Akselerator terdiri dari dua jenis kunci: pengubah dan non-pengubah. Tombol pengubah termasuk Shift, Menu, Control, dan tombol Windows, yang diekspos melalui VirtualKeyModifiers. Non-pengubah mencakup VirtualKey apa pun, seperti Hapus, F3, Bilah Spasi, Panah, Esc, dan semua kunci alfanumerik dan tanda baca.

Nota

Akselerator biasanya menyertakan tombol fungsi F1 hingga F12 atau beberapa kombinasi kunci standar yang dipasangkan dengan satu atau beberapa tombol pengubah (CTRL, Shift). Misalnya, jika pengguna menekan Ctrl+Shift+M, kerangka kerja memeriksa pengubah (Ctrl dan Shift) dan menembakkan akselerator, jika ada.

Banyak kontrol XAML memiliki akselerator keyboard bawaan. Misalnya, ListView mendukung Ctrl+A untuk memilih semua item dalam daftar, dan RichEditBox mendukung Ctrl+Tab untuk menyisipkan Tab di kotak teks. Akselerator keyboard bawaan ini disebut sebagai akselerator kontrol dan dijalankan hanya jika fokusnya ada pada elemen atau salah satu turunannya. Akselerator yang ditentukan oleh Anda menggunakan API akselerator keyboard yang dibahas di sini disebut sebagai akselerator aplikasi.

Akselerator keyboard tidak tersedia untuk setiap tindakan tetapi sering dikaitkan dengan perintah yang diekspos dalam menu (dan harus ditentukan dengan konten item menu). Akselerator juga dapat dikaitkan dengan tindakan yang tidak memiliki item menu yang setara. Namun, karena pengguna mengandalkan menu aplikasi untuk menemukan dan mempelajari set perintah yang tersedia, Anda harus mencoba membuat penemuan akselerator semudah mungkin (menggunakan label atau pola yang ditetapkan dapat membantu hal ini).

Akselerator mengulangi secara otomatis (misalnya, ketika pengguna menekan Ctrl+Shift lalu menahan M, akselerator dipanggil berulang kali hingga M dilepaskan). Perilaku ini tidak dapat dimodifikasi.

Cuplikan layar akselerator keyboard di label item menu.
Akselerator keyboard yang dijelaskan dalam label item menu

Kapan menggunakan akselerator keyboard

Kami menyarankan agar Anda menentukan akselerator keyboard di mana pun yang sesuai di UI Anda, dan mendukung akselerator di semua kontrol kustom.

Akselerator keyboard membuat aplikasi Anda lebih mudah diakses oleh pengguna dengan disabilitas motorik, termasuk pengguna yang hanya dapat menekan satu tombol pada satu waktu atau mengalami kesulitan menggunakan mouse.

UI keyboard yang dirancang dengan baik adalah aspek penting dari aksesibilitas perangkat lunak. Ini memungkinkan pengguna dengan gangguan penglihatan atau yang memiliki disabilitas motorik tertentu untuk menavigasi aplikasi dan berinteraksi dengan fitur-fiturnya. Pengguna tersebut mungkin tidak dapat mengoperasikan mouse dan sebaliknya mengandalkan berbagai teknologi bantuan seperti alat peningkatan keyboard, keyboard di layar, pembenar layar, pembaca layar, dan utilitas input suara. Untuk pengguna ini, cakupan perintah komprehensif sangat penting.
Akselerator keyboard membuat aplikasi Anda lebih dapat digunakan untuk pengguna daya yang lebih suka berinteraksi melalui keyboard.

Pengguna berpengalaman sering memiliki preferensi yang kuat untuk menggunakan keyboard karena perintah berbasis keyboard dapat dimasukkan lebih cepat dan tidak mengharuskan mereka untuk melepas tangan mereka dari keyboard. Untuk pengguna ini, efisiensi dan konsistensi sangat penting; komprehensif hanya penting untuk perintah yang paling sering digunakan.

Tentukan akselerator keyboard

Gunakan API KeyboardAccelerator untuk membuat akselerator keyboard di aplikasi Windows. Dengan API ini, Anda tidak perlu menangani beberapa peristiwa KeyDown untuk mendeteksi kombinasi tombol yang ditekan, dan Anda dapat melokalisasi akselerator di sumber daya aplikasi.

Kami merekomendasikan agar Anda menetapkan akselerator keyboard untuk tindakan umum dalam aplikasi Anda dan mendokumentasikannya menggunakan label item menu atau tooltip. Dalam contoh ini, kami mendeklarasikan akselerator keyboard hanya untuk perintah Ganti Nama dan Salin.

<CommandBar Margin="0,200" AccessKey="M">
  <AppBarButton 
    Icon="Share" 
    Label="Share" 
    Click="OnShare" 
    AccessKey="S" />
  <AppBarButton 
    Icon="Copy" 
    Label="Copy" 
    ToolTipService.ToolTip="Copy (Ctrl+C)" 
    Click="OnCopy" 
    AccessKey="C">
    <AppBarButton.KeyboardAccelerators>
      <KeyboardAccelerator 
        Modifiers="Control" 
        Key="C" />
    </AppBarButton.KeyboardAccelerators>
  </AppBarButton>

  <AppBarButton 
    Icon="Delete" 
    Label="Delete" 
    Click="OnDelete" 
    AccessKey="D" />
  <AppBarSeparator/>
  <AppBarButton 
    Icon="Rename" 
    Label="Rename" 
    ToolTipService.ToolTip="Rename (F2)" 
    Click="OnRename" 
    AccessKey="R">
    <AppBarButton.KeyboardAccelerators>
      <KeyboardAccelerator 
        Modifiers="None" Key="F2" />
    </AppBarButton.KeyboardAccelerators>
  </AppBarButton>

  <AppBarButton 
    Icon="SelectAll" 
    Label="Select" 
    Click="OnSelect" 
    AccessKey="A" />
  
  <CommandBar.SecondaryCommands>
    <AppBarButton 
      Icon="OpenWith" 
      Label="Sources" 
      AccessKey="S">
      <AppBarButton.Flyout>
        <MenuFlyout>
          <ToggleMenuFlyoutItem Text="OneDrive" />
          <ToggleMenuFlyoutItem Text="Contacts" />
          <ToggleMenuFlyoutItem Text="Photos"/>
          <ToggleMenuFlyoutItem Text="Videos"/>
        </MenuFlyout>
      </AppBarButton.Flyout>
    </AppBarButton>
    <AppBarToggleButton 
      Icon="Save" 
      Label="Auto Save" 
      IsChecked="True" 
      AccessKey="A"/>
  </CommandBar.SecondaryCommands>

</CommandBar>

Cuplikan layar akselerator keyboard dalam tooltip.
Akselerator keyboard yang dijelaskan dalam tipsalat

Objek UIElement memiliki koleksi KeyboardAccelerator , KeyboardAccelerators, di mana Anda menentukan objek KeyboardAccelerator kustom Anda dan menentukan penekanan tombol untuk akselerator keyboard:

Key - VirtualKey yang digunakan sebagai akselerator keyboard.
Pengubah Tombol – VirtualKeyModifiers yang digunakan sebagai akselerator keyboard. Jika Modifier tidak diatur, nilai defaultnya adalah None.

Nota

Akselerator kunci tunggal (A, Hapus, F2, Bilah Spasi, Esc, Kunci Multimedia) dan akselerator multi-kunci (Ctrl+Shift+M) didukung. Namun, kunci virtual Gamepad tidak didukung.

Akselerator Terbatas

Beberapa akselerator hanya berfungsi dalam cakupan tertentu sementara yang lain bekerja di seluruh aplikasi.

Misalnya, Microsoft Outlook menyertakan akselerator berikut:

Ctrl+B, Ctrl+I dan ESC hanya berfungsi pada cakupan formulir kirim email
Ctrl+1 dan Ctrl+2 berfungsi di seluruh aplikasi

Menu kontekstual

Tindakan menu konteks hanya memengaruhi area atau elemen tertentu, seperti karakter yang dipilih di editor teks atau lagu dalam daftar putar. Untuk alasan ini, sebaiknya atur cakupan akselerator keyboard untuk item menu konteks ke induk menu konteks.

Gunakan properti ScopeOwner untuk menentukan cakupan akselerator keyboard. Kode ini menunjukkan cara mengimplementasikan menu konteks pada ListView dengan akselerator keyboard terlingkup:

<ListView x:Name="MyList">
  <ListView.ContextFlyout>
    <MenuFlyout>
      <MenuFlyoutItem Text="Share" Icon="Share"/>
      <MenuFlyoutItem Text="Copy" Icon="Copy">
        <MenuFlyoutItem.KeyboardAccelerators>
          <KeyboardAccelerator 
            Modifiers="Control" 
            Key="C" 
            ScopeOwner="{x:Bind MyList }" />
        </MenuFlyoutItem.KeyboardAccelerators>
      </MenuFlyoutItem>
      
      <MenuFlyoutItem Text="Delete" Icon="Delete" />
      <MenuFlyoutSeparator />
      
      <MenuFlyoutItem Text="Rename">
        <MenuFlyoutItem.KeyboardAccelerators>
          <KeyboardAccelerator 
            Modifiers="None" 
            Key="F2" 
            ScopeOwner="{x:Bind MyList}" />
        </MenuFlyoutItem.KeyboardAccelerators>
      </MenuFlyoutItem>
      
      <MenuFlyoutItem Text="Select" />
    </MenuFlyout>
    
  </ListView.ContextFlyout>
    
  <ListViewItem>Track 1</ListViewItem>
  <ListViewItem>Alternative Track 1</ListViewItem>

</ListView>

Atribut ScopeOwner dari elemen MenuFlyoutItem.KeyboardAccelerators menandai akselerator sebagai tercakup alih-alih global (defaultnya null, atau global). Untuk detail selengkapnya, lihat bagian Mengatasi akselerator nanti dalam topik ini.

Memanggil akselerator keyboard

Objek KeyboardAccelerator menggunakan pola kontrol UI Automation (UIA) untuk mengambil tindakan ketika akselerator dipanggil.

UIA [pola kontrol] mengekspos fungsionalitas kontrol umum. Misalnya, kontrol Tombol mengimplementasikan pola Kontrol pemanggilan untuk mendukung peristiwa Klik (biasanya kontrol dipanggil dengan mengklik, mengklik dua kali, atau menekan Enter, pintasan keyboard yang telah ditentukan sebelumnya, atau beberapa kombinasi penekanan tombol lainnya). Ketika akselerator keyboard digunakan untuk memanggil kontrol, kerangka kerja XAML mencari tahu apakah kontrol tersebut mengimplementasikan pola kontrol Invoke dan, jika iya, mengaktifkannya (tidak perlu mendengarkan peristiwa KeyboardAcceleratorInvoked).

Dalam contoh berikut, Control+S memicu peristiwa Klik karena tombol mengimplementasikan pola Panggil.

<Button Content="Save" Click="OnSave">
  <Button.KeyboardAccelerators>
    <KeyboardAccelerator Key="S" Modifiers="Control" />
  </Button.KeyboardAccelerators>
</Button>

Jika elemen menerapkan beberapa pola kontrol, hanya satu yang dapat diaktifkan melalui akselerator. Pola kontrol diprioritaskan sebagai berikut:

Panggil (Tombol)
Beralih (Kotak Centang)
Pilihan (ListView)
Perluas/Ciutkan (Kotak Kombo)

Jika tidak ada kecocokan yang diidentifikasi, akselerator tidak valid dan pesan debug ditampilkan ("Tidak ada pola otomatisasi untuk komponen ini yang ditemukan. Terapkan semua perilaku yang diinginkan dalam peristiwa 'Invoked'. Mengatur Handled ke true di penanganan peristiwa Anda menekan pesan ini.")

Perilaku akselerator keyboard kustom

Peristiwa yang dipanggil dari objek KeyboardAccelerator diaktifkan saat akselerator dijalankan. Objek peristiwa KeyboardAcceleratorInvokedEventArgs menyertakan properti berikut:

Ditangani (Boolean): Mengatur ini ke true mencegah peristiwa memicu pola kontrol dan menghentikan gelembung peristiwa akselerator. Defaultnya adalah false.
Elemen (DependencyObject): Objek yang terkait dengan akselerator.
KeyboardAccelerator: Akselerator keyboard yang digunakan untuk memicu peristiwa yang Dipanggil.

Di sini kami menunjukkan cara menentukan koleksi akselerator keyboard untuk item dalam ListView, dan cara menangani peristiwa yang Dipanggil untuk setiap akselerator.

<ListView x:Name="MyListView">
  <ListView.KeyboardAccelerators>
    <KeyboardAccelerator Key="A" Modifiers="Control,Shift" Invoked="SelectAllInvoked" />
    <KeyboardAccelerator Key="F5" Invoked="RefreshInvoked"  />
  </ListView.KeyboardAccelerators>
</ListView>

void SelectAllInvoked(KeyboardAccelerator sender, KeyboardAcceleratorInvokedEventArgs args)
{
  MyListView.SelectAll();
  args.Handled = true;
}

void RefreshInvoked(KeyboardAccelerator sender, KeyboardAcceleratorInvokedEventArgs args)
{
  MyListView.SelectionMode = ListViewSelectionMode.None;
  MyListView.SelectionMode = ListViewSelectionMode.Multiple;
  args.Handled = true;
}

Mengesampingkan perilaku keyboard default

Beberapa kontrol, ketika mereka memiliki fokus, mendukung akselerator keyboard bawaan yang menggantikan akselerator yang ditentukan aplikasi. Misalnya, ketika TextBox memiliki fokus, akselerator Control+C hanya menyalin teks yang saat ini dipilih (akselerator yang ditentukan aplikasi diabaikan dan tidak ada fungsionalitas lain yang dijalankan).

Meskipun kami tidak merekomendasikan mengubah perilaku kontrol default karena keakraban dan harapan pengguna, Anda dapat mengubah akselerator keyboard bawaan dari kontrol. Contoh berikut menunjukkan cara mengambil alih akselerator keyboard Control+C untuk TextBox melalui penanganan aktivitas PreviewKeyDown :

 private void TextBlock_PreviewKeyDown(object sender, KeyRoutedEventArgs e)
 {
    var ctrlState = CoreWindow.GetForCurrentThread().GetKeyState(Windows.System.VirtualKey.Control);
    var isCtrlDown = ctrlState == CoreVirtualKeyStates.Down || ctrlState 
        ==  (CoreVirtualKeyStates.Down | CoreVirtualKeyStates.Locked);
    if (isCtrlDown && e.Key == Windows.System.VirtualKey.C)
    {
        // Your custom keyboard accelerator behavior.
        
        e.Handled = true;
    }
 }

Menonaktifkan akselerator keyboard

Jika kontrol dinonaktifkan, akselerator terkait juga dinonaktifkan. Dalam contoh berikut, karena properti IsEnabled dari ListView diatur ke false, akselerator Control+A terkait tidak dapat dipanggil.

<ListView >
  <ListView.KeyboardAccelerators>
    <KeyboardAccelerator Key="A"
      Modifiers="Control"
      Invoked="CustomListViewSelecAllInvoked" />
  </ListView.KeyboardAccelerators>
  
  <TextBox>
    <TextBox.KeyboardAccelerators>
      <KeyboardAccelerator 
        Key="A" 
        Modifiers="Control" 
        Invoked="CustomTextSelecAllInvoked" 
        IsEnabled="False" />
    </TextBox.KeyboardAccelerators>
  </TextBox>

<ListView>

Kontrol parent dan child dapat berbagi akselerator yang sama. Dalam hal ini, kontrol induk dapat dipanggil bahkan jika anak memiliki fokus dan akseleratornya dinonaktifkan.

Pembaca layar dan akselerator keyboard

Pembaca layar seperti Narator dapat mengumumkan kombinasi tombol akselerator keyboard kepada pengguna. Secara default, ini adalah setiap pengubah (dalam urutan enum VirtualModifiers) diikuti oleh kunci (dan dipisahkan oleh tanda "+"). Anda dapat menyesuaikan ini melalui properti AutomationProperties AkseleratorKey yang melekat. Jika lebih dari satu akselerator ditentukan, hanya yang pertama yang diumumkan.

Dalam contoh ini, AutomationProperty.AcceleratorKey mengembalikan string "Control+Shift+A":

<ListView x:Name="MyListView">
  <ListView.KeyboardAccelerators>

    <KeyboardAccelerator 
      Key="A" 
      Modifiers="Control,Shift" 
      Invoked="CustomSelectAllInvoked" />
      
    <KeyboardAccelerator 
      Key="F5" 
      Modifiers="None" 
      Invoked="RefreshInvoked" />

  </ListView.KeyboardAccelerators>

</ListView>

Nota

Mengatur AutomationProperties.AcceleratorKey tidak mengaktifkan fungsionalitas keyboard, melainkan hanya menunjukkan kepada kerangka kerja otomatisasi antarmuka pengguna (UIA) kunci mana yang digunakan.

Akselerator Keyboard Umum

Kami menyarankan agar Anda membuat akselerator keyboard konsisten di seluruh aplikasi Windows.

Pengguna harus menghafal akselerator keyboard dan mengharapkan hasil yang sama (atau serupa), tetapi ini mungkin tidak selalu dimungkinkan karena perbedaan fungsionalitas di seluruh aplikasi.

Mengedit	Akselerator Keyboard Umum
Mulai mode pengeditan	Ctrl + E
Memilih semua item dalam kontrol atau jendela yang difokuskan	Ctrl + A
Cari dan ganti	Ctrl + H
Batalkan	Ctrl + Z
Mengulangi	Ctrl + Y
Menghapus pilihan dan menyalinnya ke clipboard	Ctrl + X
Menyalin pilihan ke clipboard	Ctrl + C, Ctrl + Insert
Tempelkan isi papan klip	Ctrl + V, Shift + Insert
Tempelkan isi papan klip (dengan opsi)	Ctrl + Alt + V
Mengganti nama item	F2
Menambahkan item baru	Ctrl + N
Menambahkan item sekunder baru	Ctrl + Shift + N
Hapus item terpilih (dengan urungkan)	Del, Ctrl+D
Hapus item terpilih (tanpa urungkan)	Shift + Del
Bold	Ctrl + B
Garisbawah	Ctrl + U
Cetak miring	Ctrl + I
Navigasi
Menemukan konten dalam kontrol atau Jendela yang difokuskan	Ctrl +F
Masuk ke hasil pencarian berikutnya	F3
Masuk ke panel UI berikutnya	F6
Masuk ke panel UI sebelumnya	Shift + F6
Tindakan Lain
Tambahkan favorit	Ctrl + D
Muat Ulang	F5 atau Ctrl + R
Perbesar tampilan	Ctrl + +
Jauhkan Tampilan	Ctrl + -
Perbesar tampilan default	Ctrl + 0
Save	Tekan Ctrl + S untuk menyimpan
Close	Ctrl + W
Print	Ctrl + P

Perhatikan bahwa beberapa kombinasi tidak valid untuk versi Windows yang dilokalkan. Misalnya, dalam versi Bahasa Spanyol Windows, Ctrl+N digunakan untuk tebal alih-alih Ctrl+B. Sebaiknya sediakan akselerator keyboard yang dilokalkan jika aplikasi dilokalkan.

Kegunaan untuk akselerator keyboard

Petunjuk Alat

Karena akselerator keyboard biasanya tidak dijelaskan langsung di UI aplikasi Windows Anda, Anda dapat meningkatkan kemudahan menemukan fitur melalui tooltip, yang ditampilkan secara otomatis ketika pengguna memindahkan fokus ke kontrol, menekan dan menahan, atau mengarahkan penunjuk mouse ke kontrol tersebut. Tooltip dapat mengidentifikasi apakah elemen kontrol memiliki akselerator keyboard terkait dan, jika ada, apa kombinasi tombol akseleratornya.

Windows 10, Versi 1803 (Pembaruan April 2018) dan yang lebih baru

Secara default, ketika akselerator keyboard dideklarasikan, semua kontrol (kecuali MenuFlyoutItem dan ToggleMenuFlyoutItem) menyajikan kombinasi tombol yang sesuai dalam tooltip.

Nota

Jika kontrol memiliki lebih dari satu akselerator yang ditentukan, hanya yang pertama yang disajikan.

Cuplikan layar tombol Simpan dengan info alat di atasnya yang menunjukkan dukungan untuk akselerator Ctrl+S.
Kombo kunci akselerator dalam info alat

Untuk objek Tombol, AppBarButton, dan AppBarToggleButton, akselerator keyboard ditambahkan ke tooltip bawaan kontrol. Untuk objek MenuFlyoutItem dan ToggleMenuFlyoutItem, akselerator keyboard ditampilkan bersama teks pada flyout.

Nota

Menentukan tooltips (lihat Tombol1 dalam contoh berikut) mengubah perilaku ini.

<StackPanel x:Name="Container" Grid.Row="0" Background="AliceBlue">
    <Button Content="Button1" Margin="20"
            Click="OnSave" 
            KeyboardAcceleratorPlacementMode="Auto" 
            ToolTipService.ToolTip="Tooltip">
        <Button.KeyboardAccelerators>
            <KeyboardAccelerator  Key="A" Modifiers="Windows"/>
        </Button.KeyboardAccelerators>
    </Button>
    <Button Content="Button2"  Margin="20"
            Click="OnSave" 
            KeyboardAcceleratorPlacementMode="Auto">
        <Button.KeyboardAccelerators>
            <KeyboardAccelerator  Key="B" Modifiers="Windows"/>
        </Button.KeyboardAccelerators>
    </Button>
    <Button Content="Button3"  Margin="20"
            Click="OnSave" 
            KeyboardAcceleratorPlacementMode="Auto">
        <Button.KeyboardAccelerators>
            <KeyboardAccelerator  Key="C" Modifiers="Windows"/>
        </Button.KeyboardAccelerators>
    </Button>
</StackPanel>

Kombinasi tombol akselerator ditambahkan ke tooltip default tombol

<AppBarButton Icon="Save" Label="Save">
    <AppBarButton.KeyboardAccelerators>
        <KeyboardAccelerator Key="S" Modifiers="Control"/>
    </AppBarButton.KeyboardAccelerators>
</AppBarButton>

Cuplikan layar tombol dengan ikon Disk dan tooltip yang menyertakan teks default Simpan dengan akselerator Ctrl+S dalam tanda kurung.

Kombinasi tombol akselerator ditambahkan ke tooltip bawaan AppBarButton

<AppBarButton AccessKey="R" Icon="Refresh" Label="Refresh" IsAccessKeyScope="True">
    <AppBarButton.Flyout>
        <MenuFlyout>
            <MenuFlyoutItem AccessKey="A" Icon="Refresh" Text="Refresh A">
                <MenuFlyoutItem.KeyboardAccelerators>
                    <KeyboardAccelerator Key="R" Modifiers="Control"/>
                </MenuFlyoutItem.KeyboardAccelerators>
            </MenuFlyoutItem>
            <MenuFlyoutItem AccessKey="B" Icon="Globe" Text="Refresh B" />
            <MenuFlyoutItem AccessKey="C" Icon="Globe" Text="Refresh C" />
            <MenuFlyoutItem AccessKey="D" Icon="Globe" Text="Refresh D" />
            <ToggleMenuFlyoutItem AccessKey="E" Icon="Globe" Text="ToggleMe">
                <MenuFlyoutItem.KeyboardAccelerators>
                    <KeyboardAccelerator Key="Q" Modifiers="Control"/>
                </MenuFlyoutItem.KeyboardAccelerators>
            </ToggleMenuFlyoutItem>
        </MenuFlyout>
    </AppBarButton.Flyout>
</AppBarButton>

Cuplikan layar Menu dengan MenuFlyoutItems yang menyertakan kombo kunci akselerator.
Kombo kunci akselerator ditambahkan ke teks MenuFlyoutItem

Kontrol perilaku presentasi dengan menggunakan properti KeyboardAcceleratorPlacementMode , yang menerima dua nilai: Otomatis atau Tersembunyi.

<Button Content="Save" Click="OnSave" KeyboardAcceleratorPlacementMode="Auto">
    <Button.KeyboardAccelerators>
        <KeyboardAccelerator Key="S" Modifiers="Control" />
    </Button.KeyboardAccelerators>
</Button>

Dalam beberapa kasus, Anda mungkin perlu menyajikan tooltip secara relatif terhadap elemen lain (biasanya objek kontainer).

Di sini, kami menunjukkan cara menggunakan properti KeyboardAcceleratorPlacementTarget untuk menampilkan kombinasi tombol akselerator keyboard untuk tombol Simpan dengan menampilkannya di dalam kontainer Grid alih-alih tombol itu sendiri.

<Grid x:Name="Container" Padding="30">
  <Button Content="Save"
    Click="OnSave"
    KeyboardAcceleratorPlacementMode="Auto"
    KeyboardAcceleratorPlacementTarget="{x:Bind Container}">
    <Button.KeyboardAccelerators>
      <KeyboardAccelerator  Key="S" Modifiers="Control" />
    </Button.KeyboardAccelerators>
  </Button>
</Grid>

Labels

Dalam beberapa kasus, sebaiknya gunakan label kontrol untuk mengidentifikasi apakah kontrol memiliki akselerator keyboard terkait dan, jika demikian, apa kombinasi tombol akseleratornya.

Beberapa kontrol platform melakukan ini secara default, khususnya objek MenuFlyoutItem dan ToggleMenuFlyoutItem , sementara AppBarButton dan AppBarToggleButton melakukannya saat muncul di menu luapan CommandBar.

Akselerator keyboard dijelaskan dalam label item menu.
Akselerator keyboard yang dijelaskan dalam label item menu

Anda dapat mengganti teks akselerator default untuk label melalui properti KeyboardAcceleratorTextOverride dari kontrol MenuFlyoutItem, ToggleMenuFlyoutItem, AppBarButton, dan AppBarToggleButton (gunakan spasi tunggal tanpa teks).

Nota

Teks penggantian tidak akan ditampilkan jika sistem tidak dapat mendeteksi keyboard yang terhubung (Anda dapat memeriksanya sendiri melalui properti KeyboardPresent).

Konsep Tingkat Lanjut

Di sini, kami meninjau beberapa aspek akselerator keyboard tingkat rendah.

Prioritas peristiwa input

Peristiwa input terjadi dalam urutan tertentu yang dapat Anda cegat dan tangani berdasarkan persyaratan aplikasi Anda.

Peristiwa gelembung KeyDown/KeyUp

Di XAML, penekanan tombol diproses seolah-olah hanya ada satu alur gelembung input. Alur input ini digunakan oleh peristiwa KeyDown/KeyUp dan input karakter. Misalnya, jika sebuah elemen memiliki fokus dan pengguna menekan tombol apa pun, peristiwa KeyDown dipicu pada elemen tersebut, diikuti oleh induk dari elemen, dan seterusnya ke atas pohon, hingga properti args.Handled menjadi true.

Peristiwa KeyDown juga digunakan oleh beberapa kontrol untuk mengimplementasikan akselerator kontrol bawaan. Ketika kontrol memiliki akselerator papan ketik, kontrol menangani event KeyDown, yang berarti bahwa tidak akan ada propagasi event KeyDown. Misalnya, RichEditBox mendukung penyalinan dengan Ctrl+C. Ketika Ctrl ditekan, event KeyDown dipicu dan membentuk gelembung, tetapi ketika pengguna menekan C pada saat yang sama, event KeyDown ditandai sebagai Ditangani dan tidak diaktifkan (kecuali parameter handledEventsToo dari UIElement.AddHandler diatur ke true).

Peristiwa CharacterReceived

Saat peristiwa CharacterReceived diaktifkan setelah peristiwa KeyDown untuk kontrol teks seperti TextBox, Anda dapat membatalkan input karakter di penanganan aktivitas KeyDown.

Peristiwa PreviewKeyDown dan PreviewKeyUp

Event input pratinjau dijalankan sebelum event lainnya. Jika Anda tidak menangani kejadian ini, akselerator untuk elemen yang memiliki fokus akan diaktifkan dan kemudian disusul oleh kejadian KeyDown. Kedua peristiwa menyebar sampai ditangani.

Diagram memperlihatkan urutan peristiwa utama Urutan peristiwa kunci

Urutan peristiwa:

Pratinjau peristiwa KeyDown
…
Akselerator aplikasi
Metode OnKeyDown
Peristiwa KeyDown
Akselerator aplikasi pada sistem induk
Metode OnKeyDown pada komponen induk
Peristiwa KeyDown pada elemen induk
(Gelembung ke akar)
…
Kejadian KarakterDiterima
Peristiwa PreviewKeyUp
KeyUpEvents

Ketika peristiwa akselerator ditangani, peristiwa KeyDown juga dianggap telah ditangani. Peristiwa KeyUp tetap tidak tertangani.

Mengatasi masalah akselerator

Peristiwa akselerator keyboard merambat dari elemen yang memiliki fokus hingga root. Jika peristiwa tidak ditangani, kerangka kerja XAML mencari akselerator aplikasi lain tanpa lingkup di luar jalur gelembung.

Ketika dua akselerator keyboard didefinisikan dengan kombinasi tombol yang sama, akselerator keyboard pertama yang ditemukan di pohon visual dipanggil.

Akselerator keyboard berlingkup hanya diaktifkan saat fokus berada di dalam cakupan tertentu. Misalnya, dalam Grid yang berisi puluhan kontrol, akselerator keyboard dapat dipanggil untuk kontrol hanya ketika fokus berada dalam Grid (pemilik cakupan).

Mendefinisikan ruang lingkup akselerator secara terprogram

Metode UIElement.TryInvokeKeyboardAccelerator memanggil akselerator yang cocok dalam subtree elemen.

Metode UIElement.OnProcessKeyboardAccelerators dijalankan sebelum akselerator keyboard. Metode ini meneruskan objek ProcessKeyboardAcceleratorArgs yang berisi kunci, pengubah, dan Boolean yang menunjukkan apakah akselerator keyboard ditangani. Jika ditandai sebagai ditangani, gelembung akselerator keyboard menyebar sehingga akselerator keyboard luar tidak pernah dipanggil.

Nota

OnProcessKeyboardAccelerators selalu diaktifkan, baik ditangani maupun tidak (mirip dengan peristiwa OnKeyDown). Anda harus memeriksa apakah kejadian ditandai sebagai ditangani.

Dalam contoh ini, kami menggunakan OnProcessKeyboardAccelerators dan TryInvokeKeyboardAccelerator untuk membuat lingkup akselerator keyboard pada objek Page.

protected override void OnProcessKeyboardAccelerators(
  ProcessKeyboardAcceleratorArgs args)
{
  if(args.Handled != true)
  {
    this.TryInvokeKeyboardAccelerator(args);
    args.Handled = true;
  }
}

Melokalisasi akselerator

Sebaiknya lokalkan semua akselerator keyboard. Anda dapat melakukan ini dengan file sumber daya standar (.resw) dan atribut x:Uid dalam deklarasi XAML Anda. Dalam contoh ini, Windows Runtime secara otomatis memuat sumber daya.

Diagram pelokalan akselerator keyboard dengan file sumber daya Pelokalan keyboard akselerator dengan file sumber daya

<Button x:Uid="myButton" Click="OnSave">
  <Button.KeyboardAccelerators>
    <KeyboardAccelerator x:Uid="myKeyAccelerator" Modifiers="Control"/>
  </Button.KeyboardAccelerators>
</Button>

Nota

Akselerator keyboard diimplementasikan sebagai tombol virtual. Akselerator yang dilokalkan harus dipilih dari kumpulan kodeVirtual-Key yang telah ditentukan sebelumnya (jika tidak, kesalahan pengurai XAML akan terjadi).

Menyiapkan akselerator secara terprogram

Berikut adalah contoh penentuan akselerator secara terprogram:

void AddAccelerator(
  VirtualKeyModifiers keyModifiers, 
  VirtualKey key, 
  TypedEventHandler<KeyboardAccelerator, KeyboardAcceleratorInvokedEventArgs> handler )
  {
    var accelerator = 
      new KeyboardAccelerator() 
      { 
        Modifiers = keyModifiers, Key = key
      };
    accelerator.Invoked += handler;
    this.KeyboardAccelerators.Add(accelerator);
  }

Nota

KeyboardAccelerator tidak dapat dibagikan, KeyboardAccelerator yang sama tidak dapat ditambahkan ke beberapa elemen.

Mengesampingkan perilaku akselerator keyboard

Anda dapat menangani peristiwa KeyboardAccelerator.Invoked untuk mengambil alih perilaku KeyboardAccelerator default.

Contoh ini menunjukkan cara mengambil alih perintah "Pilih semua" (Akselerator keyboard Ctrl+A) dalam kontrol ListView kustom. Kami juga mengatur properti Ditangani ke true untuk menghentikan peristiwa yang menggelegak lebih lanjut.

public class MyListView : ListView
{
  …
  protected override void OnKeyboardAcceleratorInvoked(KeyboardAcceleratorInvokedEventArgs args) 
  {
    if(args.Accelerator.Key == VirtualKey.A 
      && args.Accelerator.Modifiers == KeyboardModifiers.Control)
    {
      CustomSelectAll(TypeOfSelection.OnlyNumbers); 
      args.Handled = true;
    }
  }
  …
}

Samples

Galeri WinUI

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-12-02

Bagikan melalui

Pintasan papan ketik

Gambaran Umum

Kapan menggunakan akselerator keyboard

Tentukan akselerator keyboard

Akselerator Terbatas

Menu kontekstual

Memanggil akselerator keyboard

Perilaku akselerator keyboard kustom

Mengesampingkan perilaku keyboard default

Menonaktifkan akselerator keyboard

Pembaca layar dan akselerator keyboard

Akselerator Keyboard Umum

Kegunaan untuk akselerator keyboard

Petunjuk Alat

Labels

Konsep Tingkat Lanjut

Prioritas peristiwa input

Peristiwa gelembung KeyDown/KeyUp

Peristiwa CharacterReceived

Peristiwa PreviewKeyDown dan PreviewKeyUp

Mengatasi masalah akselerator

Mendefinisikan ruang lingkup akselerator secara terprogram

Melokalisasi akselerator

Menyiapkan akselerator secara terprogram

Mengesampingkan perilaku akselerator keyboard

Artikel terkait

Samples

Saran dan Komentar

Sumber Daya Tambahan: