chrome.commands

Deskripsi

Manifes

Konsep dan penggunaan

Commands API memungkinkan developer ekstensi menentukan perintah tertentu, dan mengikatnya ke kombinasi tombol default. 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 tidak disertakan, perintah tidak akan terikat. Properti ini dapat mengambil nilai string atau objek.

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

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

  Lihat Persyaratan kombinasi tombol untuk mengetahui detail tambahan.

description

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

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

Kunci yang Didukung

Tombol berikut adalah pintasan perintah yang dapat digunakan. Definisi utama peka huruf besar/kecil. Mencoba memuat ekstensi dengan kunci yang salah akan menyebabkan error penguraian manifes pada saat penginstalan.

Kunci alfa

A … Z

Tombol angka

0 … 9

String kunci standar

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

Tombol panah–Up, Down, Left, Right

Tombol Media–MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

String tombol pengubah

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

Persyaratan kombinasi tombol

• Pintasan perintah ekstensi harus menyertakan Ctrl atau Alt.

  • Pengubah tidak dapat digunakan bersama dengan Tombol Media.

  • Di banyak keyboard macOS, Alt merujuk pada tombol Option.

  • Di macOS, Command atau MacCtrl juga dapat digunakan sebagai pengganti Ctrl, dan tombol Option dapat digunakan sebagai pengganti Alt (lihat poin berikutnya).

• Di macOS, Ctrl otomatis dikonversi menjadi Command.

  • Command juga dapat digunakan dalam pintasan "mac" untuk secara eksplisit merujuk ke tombol Command.

  • Untuk menggunakan tombol Control di macOS, ganti Ctrl dengan MacCtrl saat menentukan pintasan "mac".

  • Menggunakan MacCtrl dalam kombinasi untuk platform lain akan menyebabkan error validasi dan mencegah penginstalan ekstensi.

• Shift adalah pengubah opsional di semua platform.

• Search adalah pengubah opsional khusus untuk ChromeOS.

• Pintasan sistem operasi dan 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

Perintah _execute_action (Manifes V3), _execute_browser_action (Manifes V2), dan _execute_page_action (Manifes V2) dicadangkan untuk tindakan memicu tindakan, tindakan browser, atau tindakan halaman Anda. Perintah ini tidak mengirimkan peristiwa command.onCommand seperti perintah standar.

Jika Anda perlu mengambil tindakan berdasarkan pembukaan pop-up, pertimbangkan untuk memproses peristiwa DOMContentLoaded di dalam JavaScript pop-up Anda.

Cakupan

Secara default, perintah dicakup ke browser Chrome. Artinya, saat browser tidak fokus, pintasan perintah tidak aktif. Mulai Chrome 35, developer ekstensi dapat menandai perintah sebagai "global" secara opsional. Perintah global juga berfungsi saat Chrome tidak memiliki fokus.

Saran pintasan keyboard untuk perintah global terbatas pada Ctrl+Shift+[0..9]. Ini adalah tindakan perlindungan untuk meminimalkan risiko mengganti pintasan di aplikasi lain karena jika, misalnya, Alt+P 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 ditampilkan di 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. Pada dasarnya, perintah hanya memerlukan deklarasi perintah dalam manifes ekstensi dan pendaftaran pemroses 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 tindakan

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

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 akan terdaftar seperti yang diharapkan. Anda dapat memberikan pengalaman pengguna akhir yang lebih andal dengan mengantisipasi kemungkinan ini dan memeriksa tabrakan saat waktu penginstalan.

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.
    }
  });
}

chrome.commands.getAll(): Promise<Command[]>

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