Açıklama
Uzantınızda işlemleri (ör. tarayıcı işlemini açma işlemi veya uzantıya komut gönderme) tetikleyen klavye kısayolları eklemek için Command API'yi kullanın.
Manifest
Bu API'yi kullanmak için aşağıdaki anahtarların manifest dosyasında beyan edilmesi gerekir.
"commands"
Kavramlar ve kullanım
Commands API, uzantı geliştiricilerin belirli komutları tanımlamasına ve bunları varsayılan bir tuş kombinasyonuna bağlamasına olanak tanır. Bir uzantının kabul ettiği her komut, uzantının manifest dosyasında "commands"
nesnesinin özellikleri olarak belirtilmelidir.
Özellik anahtarı, komutun adı olarak kullanılır. Komut nesneleri iki özellik alabilir.
suggested_key
Komut için varsayılan klavye kısayollarını bildiren isteğe bağlı bir özellik. Atlanırsa komutun bağlantısı kaldırılır. Bu özellik bir dize veya nesne değeri alabilir.
Dize değeri, tüm platformlarda kullanılması gereken varsayılan klavye kısayolunu belirtir.
Nesne değeri, uzantı geliştiricisinin her platform için klavye kısayolunu özelleştirmesine olanak tanır. Platforma özel kısayollar sağlanırken
default
,chromeos
,linux
,mac
vewindows
geçerli nesne özellikleri kullanılır.
Daha fazla bilgi için Tuş kombinasyonu gereksinimleri bölümüne bakın.
description
Kullanıcıya komutun amacının kısa bir açıklamasını sağlamak için kullanılan dize. Bu dize, uzantı klavye kısayolu yönetimi kullanıcı arayüzünde görünür. Standart komutlar için açıklamalar gereklidir ancak İşlem komutları için yoksayılır.
Bir uzantı çok sayıda komut içerebilir, ancak önerilen en fazla dört klavye kısayolu belirtebilir. Kullanıcı, chrome://extensions/shortcuts
iletişim kutusundan manuel olarak daha fazla kısayol ekleyebilir.
Desteklenen Tuşlar
Aşağıdaki tuşlar, kullanılabilir komut kısayollarıdır. Anahtar tanımları büyük/küçük harfe duyarlıdır. Bir uzantıyı yanlış yazılmış bir anahtarla yüklemeye çalışmak, yükleme sırasında manifest ayrıştırma hatasına neden olur.
- Alfa tuşları
A
...Z
- Sayısal anahtarlar
0
...9
- Standart anahtar dizeleri
Genel -
Comma
,Period
,Home
,End
,PageUp
,PageDown
,Space
,Insert
,Delete
Ok tuşları–
Up
,Down
,Left
,Right
Medya Anahtarları -
MediaNextTrack
,MediaPlayPause
,MediaPrevTrack
,MediaStop
- Değiştirici tuş dizeleri
Ctrl
,Alt
(macOS'teOption
),Shift
,MacCtrl
(yalnızca macOS),Command
(yalnızca macOS),Search
(yalnızca ChromeOS)
Tuş kombinasyonuyla ilgili gereksinimler
Uzantı komutu kısayolları
Ctrl
veyaAlt
içermelidir.- Değiştiriciler, Medya Anahtarları ile birlikte kullanılamaz.
macOS'te
Ctrl
, otomatik olarakCommand
biçimine dönüştürülür.macOS'te Control tuşunu kullanmak için,
"mac"
kısayolunu tanımlarkenCtrl
yerineMacCtrl
kullanın.MacCtrl
öğesini başka bir platform için birlikte kullanmak, doğrulama hatasına neden olur ve uzantının yüklenmesini engeller.
Shift
, tüm platformlarda isteğe bağlı bir değiştiricidir.Search
, ChromeOS'e özel isteğe bağlı bir değiştiricidir.Belirli işletim sistemi ve Chrome kısayolları (ör. pencere yönetimi), her zaman Uzantı komut kısayollarına göre önceliklidir ve geçersiz kılınamaz.
Komut etkinliklerini işleme
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"
}
}
},
...
}
Service Worker'ınızda onCommand.addListener
kullanarak manifest dosyasında tanımlanan komutların her birine işleyici bağlayabilirsiniz. Örneğin:
service-worker.js:
chrome.commands.onCommand.addListener((command) => {
console.log(`Command: ${command}`);
});
İşlem komutları
_execute_action
(Manifest V3), _execute_browser_action
(Manifest V2) ve _execute_page_action
(Manifest V2) komutları sırasıyla işleminizi, tarayıcı işlemini veya sayfa işlemini tetikleme işlemi için ayrılmıştır. Bu komutlar, standart komutlar gibi command.onCommand etkinliklerini göndermez.
Açılan pop-up'a bağlı olarak işlem yapmanız gerekiyorsa pop-up'ınızın JavaScript'inde bir DOMContentLoaded etkinliğini dinlemeyi düşünün.
Kapsam
Varsayılan olarak, komutlar Chrome Tarayıcı'nın kapsamına alınır. Bu, tarayıcıda odak olmadığında komut kısayollarının devre dışı olacağı anlamına gelir. Chrome 35'ten itibaren, uzantı geliştiricileri isteğe bağlı olarak bir komutu "genel" olarak işaretleyebilir. Genel komutlar, Chrome'da odak olmadığında da çalışır.
Genel komutlar için klavye kısayolu önerileri Ctrl+Shift+[0..9]
ile sınırlıdır. Bu, örneğin Alt+P
için global olarak izin verildiği durumlarda, bir yazdırma iletişim kutusu açmak için kullanılan klavye kısayolu, diğer uygulamalarda çalışmayabileceğinden, diğer uygulamalarda kısayolları geçersiz kılma riskini en aza indirmek için kullanılan koruyucu bir önlemdir.
Son kullanıcılar, chrome://extensions/shortcuts
adresinde gösterilen kullanıcı arayüzünü kullanarak genel komutları tercih ettikleri tuş kombinasyonuyla yeniden eşleyebilir.
Örnek:
manifest.json:
{
"name": "My extension",
...
"commands": {
"toggle-feature-foo": {
"suggested_key": {
"default": "Ctrl+Shift+5"
},
"description": "Toggle feature foo",
"global": true
}
},
...
}
Örnekler
Aşağıdaki örnekler, Commands API'nin temel işlevini esnek hale getirir.
Temel komut
Komutlar, uzantıların, kullanıcı tarafından çağrılabilecek klavye kısayollarıyla mantığı eşlemesine olanak tanır. Bir komut, en temel haliyle yalnızca uzantının manifest dosyasında bir komut bildirimi ve aşağıdaki örnekte gösterildiği gibi bir dinleyici kaydı gerektirir.
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`);
});
İşlem komutu
Kullanım bölümünde açıklandığı gibi, bir komutu uzantının işlemiyle de eşleyebilirsiniz. Aşağıdaki örnek, kullanıcı uzantı işlemini tıkladığında veya klavye kısayolunu tetiklediğinde geçerli sayfada bir uyarı gösteren bir içerik komut dosyası ekler.
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`);
});
Komutların kaydedildiğini doğrulama
Bir uzantı, başka bir uzantı tarafından zaten kullanılan bir kısayolu kaydetmeye çalışırsa ikinci uzantının kısayolu beklendiği gibi kaydedilmez. Bu olasılığı öngörerek ve yükleme sırasında çakışmaları kontrol ederek daha sağlam bir son kullanıcı deneyimi sağlayabilirsiniz.
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.
}
});
}
Türler
Command
Özellikler
-
açıklama
dize isteğe bağlı
Uzantı Komutu açıklaması
-
ad
dize isteğe bağlı
Uzantı Komutunun adı
-
kısayol
dize isteğe bağlı
Bu komut için kısayol etkin ya da etkin değilse boştur.
Yöntemler
getAll()
chrome.commands.getAll(
callback?: function,
)
Bu uzantı için tüm kayıtlı uzantı komutlarını ve kısayollarını (etkinse) döndürür. Bu komut, Chrome 110 sürümünden önce _execute_action
sonucunu döndürmüyordu.
Parametreler
İlerlemeler
-
Promise<Command[]>
Chrome 96 ve sonraki sürümlerVaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geri çağırma işlevleri, geriye dönük uyumluluk için sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.
Etkinlikler
onCommand
chrome.commands.onCommand.addListener(
callback: function,
)
Kayıtlı bir komut, klavye kısayolu kullanılarak etkinleştirildiğinde tetiklenir.