chrome.commands

Açıklama

Manifest

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 bildirilmelidir.

Ö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. Belirtilmezse komut bağlantısız olur. Bu özellik, dize veya nesne değeri alabilir.

• Dize değeri, tüm platformlarda kullanılması gereken varsayılan klavye kısayolunu belirtir.

• Bir nesne değeri, uzantı geliştiricinin her platform için klavye kısayolunu özelleştirmesine olanak tanır. Platforma özel kısayollar sağlarken geçerli nesne özellikleri default, chromeos, linux, mac ve windows'dir.

Ek ayrıntılar için Tuş kombinasyonu koşulları başlıklı makaleyi inceleyin.

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. Açıklamalar standart komutlar için gereklidir ancak işlem komutları için yoksayılır.

Bir uzantıda birçok komut olabilir ancak en fazla dört klavye kısayolu önerilebilir. 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. Yanlış büyük/küçük harf kullanılan bir anahtarla uzantı yüklemeye çalışmak, yükleme sırasında manifest ayrıştırma hatasına neden olur.

Alfa tuşları

A … Z

Sayı tuşları

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, Shift, MacCtrl (yalnızca macOS), Command (yalnızca macOS), Search (yalnızca ChromeOS)

Tuş kombinasyonu şartları

• Uzantı komutu kısayolları Ctrl veya Alt içermelidir.

  • Değiştiriciler, medya tuşlarıyla birlikte kullanılamaz.

  • Birçok macOS klavyede Alt, Option tuşunu ifade eder.

  • macOS'te Ctrl veya Alt yerine Command veya MacCtrl da kullanılabilir (sonraki maddeye bakın).

• macOS'te Ctrl otomatik olarak Command'ye dönüştürülür.

  • Command, Komut tuşuna açıkça atıfta bulunmak için "mac" kısayolunda da kullanılabilir.

  • macOS'te Control tuşunu kullanmak için "mac" kısayolunu tanımlarken Ctrl yerine MacCtrl tuşunu kullanın.

  • Başka bir platform için kombinasyonda MacCtrl kullanılması 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ı komutu kısayollarından ö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"       }     }   },   ... } 

Hizmet çalışanı içinde, onCommand.addListener kullanarak manifestte 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şleminizi veya sayfa işleminizi tetikleme işlemi için ayrılmıştır. Bu komutlar, standart komutlar gibi command.onCommand etkinliklerini göndermez.

Pop-up'ınızın açılmasına göre işlem yapmanız gerekiyorsa pop-up'ınızın JavaScript'inde bir DOMContentLoaded etkinliğini dinlemeyi düşünebilirsiniz.

Kapsam

Varsayılan olarak, komutlar Chrome Tarayıcı ile sınırlandırılır. Bu nedenle, tarayıcı odaklanmadığında komut kısayolları etkin olmaz. Chrome 35'ten itibaren uzantı geliştiriciler, komutları isteğe bağlı olarak "global" şeklinde işaretleyebilir. Chrome odaklanmamışken de genel komutlar ç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ın geçersiz kılınması riskini en aza indirmek için alınan bir koruyucu önlemdir. Örneğin, Alt+P küresel olarak izin verilirse yazdırma iletişim kutusunu açma 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şlevselliği gösterilmektedir.

Temel komut

Komutlar, uzantıların mantığı kullanıcı tarafından çağrılabilen klavye kısayollarıyla eşlemesine olanak tanır. En temel düzeyde, bir komut için yalnızca uzantının manifest dosyasında bir komut bildirimi ve aşağıdaki örnekte gösterildiği gibi bir dinleyici kaydı gerekir.

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

Kavramlar ve kullanım bölümünde açıklandığı gibi, bir komutu uzantının işlemine de eşleyebilirsiniz. Aşağıdaki örnekte, kullanıcı uzantının işlemini tıkladığında veya klavye kısayolunu tetiklediğinde mevcut sayfada bir uyarı gösteren bir 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ı komutları 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 iyi 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.     }   }); } 

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

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