chrome.commands

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

Bu API'yi kullanmak için aşağıdaki anahtarların manifest'te beyan edilmesi gerekir.

"commands"

Kavramlar ve 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 ve windows 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'te Option), Shift, MacCtrl (yalnızca macOS), Command (yalnızca macOS), Search (yalnızca ChromeOS)

Not: Tab, erişilebilirlik nedeniyle Chrome 33'te desteklenen anahtarlar listesinden kaldırıldı.

Tuş kombinasyonu gereksinimleri

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

  • Değiştiriciler, Medya Tuşları ile birlikte kullanılamaz.

• macOS'te Ctrl, otomatik olarak Command biçimine dönüştürülür.

  • macOS'te Control tuşunu kullanmak istiyorsanız "mac" kısayolunu tanımlarken Ctrl yerine MacCtrl 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.

Not: AltGr anahtarıyla çakışma olmaması için Ctrl+Alt içeren anahtar kombinasyonlarına izin verilmez.

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 göndermez.

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.

Not: ChromeOS genel komutları desteklemez.

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ı, zaten 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((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

  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()

Söz

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

• geri çağırma

  Functions (isteğe bağlı)

  callback parametresi şu şekilde görünür:

  (commands: Command[])=>void

  • commands

    Komut[]

İlerlemeler

• Söz verme<Komut[]>

  Chrome 96 ve sonraki sürümler

  Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar 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.

Parametreler

• geri çağırma

  işlev

  callback parametresi şu şekilde görünür:

  (command: string,tab?: tabs.Tab)=>void

  • command

    dize

  • sekmesinden

    tabs.Tab isteğe bağlı