Pintasan keyboard

Blockly mempertahankan registry pintasan keyboard yang memetakan tombol (atau kombinasi tombol seperti ctrl-C) ke tindakan. Registry diisi otomatis dengan sejumlah pintasan, seperti ctrl-C dan meta-C untuk menyalin. Anda dapat menambahkan dan menghapus pintasan dari registri.

Cara kerja pintasan keyboard

Registry pintasan berisi objek yang memodelkan pintasan keyboard. Saat pengguna menekan tombol (atau kombinasi tombol), Blockly:

  1. Memeriksa registry untuk melihat apakah ada pintasan yang berlaku untuk kunci. Jika lebih dari satu pintasan menggunakan tombol, pintasan akan dicoba dalam urutan terbalik pendaftaran. Artinya, pintasan yang baru saja didaftarkan akan dicoba terlebih dahulu.

  2. Memanggil fungsi preconditionFn pintasan, yang menentukan apakah pintasan berlaku untuk situasi saat ini. Misalnya, pintasan salin berlaku untuk blok, tetapi tidak untuk ruang kerja. Jika pintasan tidak berlaku, Blockly akan mencoba pintasan berikutnya dalam daftar, jika ada.

  3. Memanggil fungsi callback pintasan, yang menjalankan tindakan pintasan. Misalnya, pintasan salin membuat salinan objek yang saat ini difokuskan, seperti blok. Jika fungsi ini menampilkan true, pemrosesan akan berhenti. Jika menampilkan false, Blockly akan mencoba pintasan berikutnya dalam daftar, jika ada.

Cakupan

Objek Scope mengidentifikasi komponen Blockly yang saat ini memiliki fokus. Objek cakupan diteruskan ke preconditionFn dan callback, yang menggunakannya untuk memutuskan apakah pintasan berlaku untuk komponen tertentu dan, jika ya, cara menerapkannya.

Untuk menggunakan objek Scope, gunakan properti focusedNode-nya. Ini adalah objek yang menerapkan IFocusableNode. Antarmuka ini diterapkan oleh semua komponen Blockly yang dapat difokuskan pengguna, termasuk ruang kerja, blok, kolom, komentar, dan komponen kustom Anda sendiri; untuk mengetahui informasi selengkapnya, lihat Sistem fokus.

Misalnya, preconditionFn dapat menggunakan focusedNode untuk memastikan bahwa pintasan hanya berlaku untuk blok.

preconditionFn(workspace, scope) {
  return (scope.focusedNode instanceof Blockly.BlockSvg);
}

Antarmuka KeyboardShortcut

Objek dalam pendaftaran pintasan menerapkan antarmuka KeyboardShortcut. Objek ini berisi properti berikut.

nama (wajib diisi)

Nama unik untuk pintasan. Deskripsi ini tidak ditampilkan kepada pengguna dan tidak perlu dapat dibaca oleh manusia. Tidak boleh diterjemahkan.

const logFieldsShortcut = {
  name: 'logFields',
  // ...
};

preconditionFn (opsional)

Blockly memanggil fungsi ini untuk memutuskan apakah pintasan berlaku untuk situasi saat ini. Jika menampilkan true, Blockly akan memanggil callback. Jika menampilkan false, Blockly akan mengabaikan pintasan ini. Contoh:

const logFieldsShortcut = {
  // ...
  preconditionFn(workspace, scope) {
    // This shortcut only applies to blocks.
    return (scope.focusedNode instanceof Blockly.BlockSvg);
  },
  // ...
};

Pintasan dapat menghilangkan fungsi ini jika pintasan selalu diterapkan (tidak umum). Pintasan tidak boleh menghilangkan fungsi ini, lalu mengambil tindakan secara bersyarat di callback. Tindakan ini mencegah Blockly melakukan hal-hal seperti membuat menu bantuan kontekstual yang menampilkan pintasan yang berlaku.

callback (opsional)

Fungsi ini menjalankan tindakan yang terkait dengan pintasan. Metode ini dipanggil hanya jika preconditionFn menampilkan true atau tidak ada. Parameternya adalah:

  • workspace: WorkspaceSvg saat ini.
  • e: Event yang memulai pintasan.
  • shortcut: KeyboardShortcut itu sendiri.
  • scope: Scope yang menjadi tujuan pintasan.

Fungsi ini menampilkan true jika berhasil dan false jika gagal.

Contoh:

const logFieldsShortcut = {
  // ...
  callback(workspace, event, shortcut, scope) {
    // preconditionFn required focusedNode to be a BlockSvg.
    for (input of scope.focusedNode.inputList) {
      // Log the values of all named fields. (Label fields usually don't have names.)
      for (field of input.fieldRow) {
        if (field.name) {
          console.log(field.name + ': ' + field.getText());
        }
      }
    }
    return true;
  },
  // ...
};

Meskipun callback bersifat opsional, umumnya tidak ada alasan untuk tidak menerapkannya.

keyCodes (opsional)

Array tombol (atau kombinasi tombol) yang mengaktifkan pintasan ini. Untuk mengidentifikasi tombol, gunakan kode tombol di Blockly.utils.KeyCodes. Contoh:

const logFieldsShortcut = {
  // ...
  keyCodes: [Blockly.utils.KeyCodes.L],
  // ...
};

Jika Anda ingin memetakan tombol tambahan ke pintasan yang ada -- misalnya, Anda ingin menambahkan tombol ke pintasan default -- Anda dapat memanggil Blockly.ShortcutRegistry.registry.addKeyMapping. Hal ini tidak umum.

Kombinasi tombol

Jika pintasan keyboard Anda diaktifkan oleh kombinasi tombol, seperti menahan Control dan C secara bersamaan, buat keycode berseri dengan memanggil Blockly.ShortcutRegistry.registry.createSerializedKey:

const ctrlC = Blockly.ShortcutRegistry.registry.createSerializedKey(
  Blockly.utils.KeyCodes.C,       // Keycode of main key
  [Blockly.utils.KeyCodes.CTRL],  // Array of modifier keys
);

const copyShortcut = {
  // ...
  keyCodes: [ctrlC], // Use the serialized keycode
  // ...
};

Control dan Meta

Di Windows, banyak pintasan diaktifkan dengan tombol Control. Di Mac, pintasan keyboard ini menggunakan tombol Command, yang dikenali sebagai kode tombol META. Untuk mendukung kedua sistem operasi, daftarkan pintasan Anda dengan kode tombol CTRL dan kode tombol META.

const ctrlC = Blockly.ShortcutRegistry.registry.createSerializedKey(
  Blockly.utils.KeyCodes.C,
  [Blockly.utils.KeyCodes.CTRL],
);
const metaC = Blockly.ShortcutRegistry.registry.createSerializedKey(
  Blockly.utils.KeyCodes.C,
  [Blockly.utils.KeyCodes.META],
);

const copyShortcut = {
  // ...
  keyCodes: [ctrlC, metaC],
  // ...
};

Catatan penerapan

Handler peristiwa keyboard Blockly menggunakan properti keycode dari KeyboardEvent meskipun sudah tidak digunakan lagi.

allowCollision (opsional)

Secara default, Anda hanya dapat mendaftarkan satu pintasan untuk tombol atau kombinasi tombol tertentu. Dengan menyetel properti ini ke true, Anda dapat mendaftarkan tombol (atau kombinasi tombol) meskipun pintasan dengan tombol (atau kombinasi tombol) yang sama telah didaftarkan.

Perhatikan bahwa properti ini hanya berlaku saat mencoba mendaftarkan pintasan ini. Tindakan ini tidak mencegah pintasan lain menggunakan tombol (atau kombinasi tombol) yang sama. Apakah dapat didaftarkan atau tidak bergantung pada nilai properti allowCollision.

Terlepas dari jumlah pintasan yang terdaftar untuk tombol atau kombinasi tombol tertentu, paling banyak satu pintasan akan berhasil dieksekusi. Pintasan dicoba dalam urutan pendaftaran terbalik (dari yang terakhir didaftarkan hingga yang pertama didaftarkan). Setelah salah satu pintasan menampilkan true dari callback-nya, tidak ada pintasan lain yang dicoba.

metadata (opsional)

Ini adalah objek arbitrer yang berisi informasi tambahan. ID ini tersedia untuk callback melalui parameter shortcut.

Menambahkan, menghapus, dan mengubah pintasan

Untuk menambahkan pintasan keyboard baru, panggil Blockly.ShortcutRegistry.registry.register:

Blockly.ShortcutRegistry.registry.register(logFieldsShortcut);

Fungsi ini memiliki parameter kedua (allowOverrides) yang memungkinkan Anda mengganti pintasan yang ada dengan nama yang sama dengan pintasan Anda. Perhatikan bahwa ini berbeda dengan KeyboardShortcut.allowCollision, yang memungkinkan Anda menambahkan pintasan dengan nama yang berbeda, tetapi menggunakan tombol atau kombinasi tombol yang sama dengan pintasan yang ada.

Untuk menghapus pintasan keyboard, panggil Blockly.ShortcutRegistry.registry.unregister dan teruskan nama pintasan:

Blockly.ShortcutRegistry.registry.unregister('logFields');

Anda tidak dapat mengubah pintasan keyboard di tempat. Sebagai gantinya, Anda harus menghapus pintasan yang ada dan menambahkan pintasan baru. Contoh:

// Get the existing shortcut. getRegistry returns an object keyed by shortcut name.
const allShortcuts = Blockly.ShortcutRegistry.registry.getRegistry();
const modLogFieldsShortcut = allShortcuts[logFieldsShortcut.name];
// Apply the shortcut only to math blocks,
modLogFieldsShortcut.preconditionFn = function (workspace, scope) {
  return (scope.focusedNode instanceof Blockly.BlockSvg &&
          scope.focusedNode.type.startsWith('math_'));
}
// Delete the existing shortcut and add the modified shortcut.
Blockly.ShortcutRegistry.registry.unregister(logFieldsShortcut.name);
Blockly.ShortcutRegistry.registry.register(modLogFieldsShortcut);

Pintasan default

Registry pintasan telah diisi otomatis dengan sejumlah pintasan. Anda dapat menemukannya di https://github.com/google/blockly/blob/master/core/shortcut_items.ts. Pintasan ditentukan dalam fungsi registerXxxx.

Pintasan navigasi keyboard

Plugin navigasi keyboard berisi pintasan yang memungkinkan pengguna menavigasi Blockly dengan keyboard, seperti menggunakan tombol panah. Navigasi keyboard sangat penting bagi pengguna yang tidak dapat menggunakan mouse, seperti pengguna dengan gangguan motorik atau penglihatan. Fitur ini juga berguna bagi pengguna super yang mungkin ingin menggunakan pintasan keyboard untuk efisiensi.