Açıklama
Uzantınızdaki işlemleri (ör. tarayıcı işlemini açma veya uzantıya komut gönderme işlemi) tetikleyen klavye kısayolları eklemek için komutlar API'sını kullanın.
Manifest
Kullanım
Commands API, uzantı geliştiricilerinin belirli komutları tanımlamasına ve bunları varsayılan bir anahtar kombinasyonuna bağlamasına olanak tanır. Uzantının kabul ettiği her komut, uzantının manifest dosyasında "commands"
nesnesinin özellikleri olarak bildirilmelidir.
Özellik anahtarı, komutun adı olarak kullanılır. Komut nesneleri iki özellik alabilir.
suggested_key
Komut için varsayılan klavye kısayolları 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 klavye kısayolunu her bir platform için özelleştirmesine olanak tanır. Platforma özel kısayollar sağlanırken
default
,chromeos
,linux
,mac
vewindows
geçerli nesne özellikleri sunulur.
Daha fazla bilgi için Anahtar kombinasyonu koşulları 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ısayolları yönetimi kullanıcı arayüzünde görünür. Açıklamalar standart komutlar için gereklidir, ancak İşlem komutları için yoksayılır.
Bir uzantı birçok komut içerebilir, ancak önerilen klavye kısayollarından en fazla dört tanesi de belirtebilir. Kullanıcı, chrome://extensions/shortcuts
iletişim kutusundan manuel olarak daha fazla kısayol ekleyebilir.
Desteklenen Anahtarlar
Aşağıdaki tuşlar kullanılabilir komut kısayollarıdır. Anahtar tanımları büyük/küçük harfe duyarlıdır. Büyük/küçük harf kullanımı yanlış olan bir uzantının yüklenmeye çalışılması, 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 Tuşları -
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ş kombinasyonu gereksinimleri
Uzantı komut kısayolları,
Ctrl
veyaAlt
içermelidir.- Değiştiriciler, Medya Tuşları ile birlikte kullanılamaz.
macOS'te
Ctrl
, otomatik olarakCommand
biçimine dönüştürülür.macOS'te Control tuşunu kullanmak istiyorsanız
"mac"
kısayolunu tanımlarkenCtrl
yerineMacCtrl
kullanın.MacCtrl
başka bir platformla birlikte kullanıldığında 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), Uzantı komut kısayollarına göre her zaman önceliklidir ve bunların üzerine yazılamaz.
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'te tanımlanan komutların her birine bir 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 dağıtmaz.
Açılan pop-up'ınıza göre işlem yapmanız gerekiyorsa pop-up'ınızın JavaScript'inde bir DOMContentLoaded etkinliği dinlemeyi düşünün.
Kapsam
Varsayılan olarak, komutlar Chrome tarayıcı kapsamına alınır. Bu, tarayıcıda odak olmadığında komut kısayollarının devre dışı olduğu 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 yokken da çalışır.
Genel komutlar için klavye kısayolu önerileri Ctrl+Shift+[0..9]
ile sınırlıdır. Bu, diğer uygulamalardaki kısayolları geçersiz kılma riskini en aza indirmek için alınmış bir önlemdir. Örneğin, Alt+P
uygulamasına genel olarak izin verilseydi, yazdırma iletişim kutusu açmak için klavye kısayolu diğer uygulamalarda çalışmayabilir.
Son kullanıcılar, chrome://extensions/shortcuts
adresinde gösterilen kullanıcı arayüzünü kullanarak genel komutları tercih ettikleri tuş kombinasyonuna 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 örneklerde, Commands API'nin temel işlevleri gösterilmektedir.
Temel komut
Komutlar, uzantıların mantığı, kullanıcı tarafından çağrılabilecek klavye kısayollarıyla eşleştirmesine olanak tanır. Bir komut, en temelde 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 bir uzantının işlemiyle de eşleyebilirsiniz. Aşağıdaki örnekte, kullanıcı uzantının işlemini tıkladığında veya klavye kısayolunu tetiklediğinde geçerli sayfada bir uyarı görüntüleyen içerik komut dosyası yerleştirilir.
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`);
});
Kayıtlı doğrulama komutları
Bir uzantı, başka bir uzantı tarafından kullanılan bir kısayolu kaydetmeye çalışırsa ikinci uzantının kısayolu beklendiği gibi kaydedilmez. Bu olasılığı tahmin ederek 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((reason) => {
if (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
string isteğe bağlı
Uzantı Komutunun açıklaması
-
ad
string isteğe bağlı
Uzantı Komutunun adı
-
kısayol
string isteğe bağlı
Kısayol bu komut için etkin veya etkin değilse boştur.
Yöntemler
getAll()
chrome.commands.getAll(
callback?: function,
)
Bu uzantı için kayıtlı tüm uzantı komutlarını ve kısayolunu (etkinse) döndürür. Chrome 110 sürümünden önce bu komut _execute_action
döndürmüyordu.
Parametreler
İlerlemeler
-
Söz verme<Komut[]>
Chrome 96 ve sonraki sürümlerVaatler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırmaları kullanması gerekir.
Etkinlikler
onCommand
chrome.commands.onCommand.addListener(
callback: function,
)
Kayıtlı bir komut, klavye kısayolu kullanılarak etkinleştirildiğinde tetiklenir.