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
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 dihilangkan, perintah akan menjadi tidak terikat. Properti ini dapat mengambil string atau nilai 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 menyediakan pintasan khusus platform, properti objek yang valid adalah
default
,chromeos
,linux
,mac
, danwindows
.
Lihat Persyaratan kombinasi kunci untuk detail tambahan.
description
String yang digunakan untuk memberi pengguna deskripsi singkat tentang tujuan perintah. String ini muncul dalam 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 kunci peka huruf besar/kecil. Mencoba memuat ekstensi dengan kunci yang salah kapitalisasi akan menyebabkan error penguraian manifes pada 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
atauAlt
.- Pengubah tidak dapat digunakan bersama Tombol Media.
Di macOS,
Ctrl
akan otomatis dikonversi menjadiCommand
.Untuk menggunakan tombol Control di macOS, ganti
Ctrl
denganMacCtrl
saat menentukan pintasan"mac"
.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.Pintasan Chrome dan sistem operasi tertentu (misalnya, pengelolaan jendela) selalu lebih 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) masing-masing dicadangkan untuk tindakan memicu tindakan,
tindakan browser, atau tindakan halaman Anda. Perintah ini tidak mengirim 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 tercakup di browser Chrome. Artinya, saat browser tidak memiliki fokus, pintasan perintah akan menjadi tidak aktif. Mulai Chrome 35, developer ekstensi dapat memilih untuk 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 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 untuk memetakan logika ke pintasan keyboard yang dapat dipanggil oleh pengguna. Pada dasarnya, perintah hanya memerlukan deklarasi perintah dalam manifes ekstensi dan pendaftaran pemroses seperti 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 Usage, Anda juga dapat memetakan perintah ke tindakan ekstensi. Contoh berikut memasukkan 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 konflik pada 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.
}
});
}
Jenis
Command
Properti
-
deskripsi
string opsional
Deskripsi Perintah Ekstensi
-
name
string opsional
Nama Perintah Ekstensi
-
pintasan
string opsional
Pintasan aktif untuk perintah ini, atau kosong jika tidak aktif.
Metode
getAll()
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
Hasil
-
Promise<Command[]>
Chrome 96 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise 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.