chrome.commands

Deskripsi

Gunakan API perintah untuk menambahkan pintasan keyboard yang memicu tindakan di ekstensi Anda, misalnya, tindakan untuk membuka tindakan browser atau mengirimkan perintah ke ekstensi.

Manifes

Kunci berikut harus dideklarasikan dalam manifes untuk menggunakan API ini.

"commands"

Konsep dan penggunaan

Commands API memungkinkan developer ekstensi menentukan perintah tertentu, dan mengikatnya ke perintah default kombinasi tombol. Setiap perintah yang diterima ekstensi harus dideklarasikan sebagai properti Objek "commands" dalam manifes ekstensi.

Kunci properti digunakan sebagai nama perintah. Objek perintah dapat mengambil dua properti.

suggested_key

Properti opsional yang mendeklarasikan pintasan keyboard default untuk perintah. Jika dihilangkan, menjadi tidak terikat. Properti ini dapat mengambil string atau nilai objek.

  • Nilai string menentukan pintasan keyboard default yang harus digunakan di semua di seluruh platform Google.

  • Nilai objek memungkinkan developer ekstensi menyesuaikan pintasan keyboard untuk setiap nilai terkelola sepenuhnya. Saat menyediakan pintasan khusus platform, properti objek yang valid adalah default, chromeos, linux, mac, dan windows.

Lihat Persyaratan kombinasi kunci untuk detail tambahan.

description

String yang digunakan untuk memberi pengguna deskripsi singkat tentang tujuan perintah. String ini muncul di UI pengelolaan pintasan keyboard ekstensi. Deskripsi diperlukan untuk standar perintah, tetapi diabaikan untuk Perintah tindakan.

Ekstensi dapat memiliki banyak perintah, tetapi dapat menentukan maksimal empat pintasan keyboard yang disarankan. Tujuan pengguna dapat menambahkan pintasan lainnya secara manual dari dialog chrome://extensions/shortcuts.

Kunci yang Didukung

Tombol berikut adalah pintasan perintah yang dapat digunakan. Definisi kunci peka huruf besar/kecil. Mencoba untuk memuat ekstensi dengan huruf besar/kecil yang salah akan mengakibatkan error penguraian manifes pada atau waktu penginstalan.

Tombol alfa
A ... Z
Tombol numerik
0 ... 9
String kunci standar

Umum–Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete

Tombol panah–Up, Down, Left, Right

Kunci Media–MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

String kunci pengubah

Ctrl, Alt (Option di macOS), Shift, MacCtrl (khusus MacOS), Command (khusus MacOS), Search (khusus ChromeOS)

Persyaratan kombinasi kunci

  • Pintasan perintah ekstensi harus menyertakan Ctrl atau Alt.

    • Pengubah tidak dapat digunakan bersama Tombol Media.

  • Di macOS, Ctrl akan otomatis dikonversi menjadi Command.

    • Untuk menggunakan tombol Control di macOS, ganti Ctrl dengan MacCtrl saat menentukan "mac" {i>shortcut<i}.

    • Penggunaan MacCtrl dalam kombinasi untuk platform lain akan menyebabkan error validasi dan mencegah ekstensi diinstal.

  • Shift adalah pengubah opsional di semua platform.

  • Search adalah pengubah opsional yang eksklusif untuk ChromeOS.

  • Sistem operasi dan pintasan Chrome tertentu (misalnya pengelolaan jendela) selalu diprioritaskan daripada Pintasan perintah ekstensi dan tidak dapat diganti.

Menangani peristiwa perintah

manifest.json:

{
  "name": "My extension",
  ...
  "commands": {
    "run-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+Y",
        "mac": "Command+Shift+Y"
      },
      "description": "Run \"foo\" on the current page."
    },
    "_execute_action": {
      "suggested_key": {
        "windows": "Ctrl+Shift+Y",
        "mac": "Command+Shift+Y",
        "chromeos": "Ctrl+Shift+U",
        "linux": "Ctrl+Shift+J"
      }
    }
  },
  ...
}

Di pekerja layanan, Anda dapat mengikat pengendali ke setiap perintah yang ditentukan dalam manifes menggunakan onCommand.addListener. Contoh:

service-worker.js:

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command: ${command}`);
});

Perintah tindakan

_execute_action (Manifes V3), _execute_browser_action (Manifes V2), dan Perintah _execute_page_action (Manifest V2) disediakan untuk tindakan memicu tindakan Anda, tindakan browser, atau tindakan halaman. Perintah-perintah ini tidak mengirim command.onCommand seperti perintah standar.

Jika Anda perlu mengambil tindakan berdasarkan pembukaan {i>pop-up<i}, pertimbangkan untuk mendengarkan DOMContentLoaded di dalam JavaScript pop-up.

Cakupan

Secara default, perintah tercakup di browser Chrome. Ini berarti bahwa ketika browser tidak memiliki fokus, pintasan perintah tidak aktif. Mulai Chrome 35, developer ekstensi dapat secara opsional menandai perintah sebagai "global". Perintah global juga berfungsi saat Chrome tidak memiliki fokus.

Saran pintasan keyboard untuk perintah global dibatasi hingga Ctrl+Shift+[0..9]. Ini adalah tindakan perlindungan untuk meminimalkan risiko penggantian pintasan di aplikasi lain, karena contoh, Alt+P akan diizinkan sebagai global, pintasan keyboard untuk membuka dialog cetak mungkin tidak berfungsi di aplikasi lain.

Pengguna akhir bebas memetakan ulang perintah global ke kombinasi tombol pilihan mereka menggunakan UI yang diekspos pukul chrome://extensions/shortcuts.

Contoh:

manifest.json:

{
  "name": "My extension",
  ...
  "commands": {
    "toggle-feature-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+5"
      },
      "description": "Toggle feature foo",
      "global": true
    }
  },
  ...
}

Contoh

Contoh berikut menunjukkan fungsi inti Commands API.

Perintah dasar

Perintah memungkinkan ekstensi memetakan logika ke pintasan keyboard yang dapat dipanggil oleh pengguna. Di yang paling dasar, sebuah perintah hanya memerlukan deklarasi perintah dalam manifes ekstensi dan pendaftaran seperti yang ditunjukkan dalam contoh berikut.

manifest.json:

{
  "name": "Command demo - basic",
  "version": "1.0",
  "manifest_version": 3,
  "background": {
    "service_worker": "service-worker.js"
  },
  "commands": {
    "inject-script": {
      "suggested_key": "Ctrl+Shift+Y",
      "description": "Inject a script on the page"
    }
  }
}

service-worker.js:

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" triggered`);
});

Perintah Action

Seperti yang dijelaskan di bagian Konsep dan penggunaan, Anda juga dapat memetakan perintah ke tindakan. Contoh berikut memasukkan skrip konten yang menunjukkan di halaman saat ini saat pengguna mengklik tindakan ekstensi atau memicu pintasan keyboard tertentu.

manifest.json:

{
  "name": "Commands demo - action invocation",
  "version": "1.0",
  "manifest_version": 3,
  "background": {
    "service_worker": "service-worker.js"
  },
  "permissions": ["activeTab", "scripting"],
  "action": {},
  "commands": {
    "_execute_action": {
      "suggested_key": {
        "default": "Ctrl+U",
        "mac": "Command+U"
      }
    }
  }
}

service-worker.js:

chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: {tabId: tab.id},
    func: contentScriptFunc,
    args: ['action'],
  });
});

function contentScriptFunc(name) {
  alert(`"${name}" executed`);
}

// This callback WILL NOT be called for "_execute_action"
chrome.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" called`);
});

Memverifikasi perintah yang terdaftar

Jika ekstensi mencoba mendaftarkan pintasan yang sudah digunakan oleh ekstensi lain, pintasan ekstensi kedua tidak terdaftar seperti yang diharapkan. Anda dapat menyediakan jaringan pengguna akhir yang lebih andal dengan mengantisipasi kemungkinan ini dan memeriksa tumbukan pada waktu instalasi.

service-worker.js:

chrome.runtime.onInstalled.addListener((details) => {
  if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
    checkCommandShortcuts();
  }
});

// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
  chrome.commands.getAll((commands) => {
    let missingShortcuts = [];

    for (let {name, shortcut} of commands) {
      if (shortcut === '') {
        missingShortcuts.push(name);
      }
    }

    if (missingShortcuts.length > 0) {
      // Update the extension UI to inform the user that one or more
      // commands are currently unassigned.
    }
  });
}

Jenis

Command

Properti

  • deskripsi

    string opsional

    Deskripsi Perintah Ekstensi

  • nama

    string opsional

    Nama Perintah Ekstensi

  • pintasan

    string opsional

    Pintasan aktif untuk perintah ini, atau kosong jika tidak aktif.

Metode

getAll()

Janji 
chrome.commands.getAll(
  callback?: function,
)

Menampilkan semua perintah ekstensi terdaftar untuk ekstensi ini dan pintasannya (jika aktif). Sebelum Chrome 110, perintah ini tidak menampilkan _execute_action.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (commands: Command[]) => void

Hasil

  • Promise<Command[]>

    Chrome 96 dan yang lebih baru

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

Acara

onCommand

chrome.commands.onCommand.addListener(
  callback: function,
)

Diaktifkan saat perintah yang terdaftar diaktifkan menggunakan pintasan keyboard.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (command: string, tab?: tabs.Tab) => void

    • perintah

      string

    • tab

      tabs.Tab opsional