browser.commands

Açıklama

Uzantınızda işlem tetikleyen klavye kısayolları eklemek için commands API'yi kullanın. Örneğin, tarayıcı işlemini açma veya uzantıya komut gönderme işlemi.

Manifest

Bu API'yi kullanmak için aşağıdaki anahtarların manifest dosyasında tanımlanması 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ındaki "commands" nesnesinin özellikleri olarak tanımlanmalıdır.

Ö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, 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ğlarken geçerli nesne özellikleri default, chromeos, linux, mac ve windows'dir.

  Daha fazla bilgi için Tuş kombinasyonu koşulları bölümüne bakın.

description

Kullanıcıya komutun amacının kısa bir açıklamasını sunmak 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çıklama gerekir ancak işlem komutları için açıklamalar yoksayılır.

Bir uzantının birçok komutu olabilir ancak en fazla dört önerilen klavye kısayolu 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. Yanlış büyük/küçük harf içeren bir anahtara sahip bir uzantıyı yüklemeye çalışmak, yükleme sırasında manifest ayrıştırma hatasına neden olur.

Alfa tuşları

A … Z

Sayısal 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), Option (yalnızca macOS), Command (yalnızca macOS), Search (yalnızca ChromeOS)

Tuş kombinasyonu şartları

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

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

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

  • macOS'te Ctrl yerine Command veya MacCtrl, Alt yerine de Option tuşu kullanılabilir (sonraki madde işaretine bakın).

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

  • Command, Command tuşunu açıkça belirtmek için "mac" kısayolunda da kullanılabilir.

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

  • Başka bir platformun kombinasyonunda 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ı komut kısayollarından önceliklidir ve geçersiz kılınamaz.

Not: AltGr tuşuyla çakışmaları önlemek için Ctrl+Alt içeren tuş kombinasyonlarına izin verilmez.

Komut etkinliklerini yönetme

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ınızda, onCommand.addListener kullanarak manifest dosyasında tanımlanan komutların her birine bir işleyici bağlayabilirsiniz. Örneğin:

service-worker.js:

browser.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 tetiklemek 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 harekete geçmeniz gerekiyorsa pop-up'ınızın JavaScript'inde bir DOMContentLoaded etkinliğini dinlemeyi düşünebilirsiniz.

Kapsam

Varsayılan olarak komutlar Chrome Tarayıcı'yı kapsar. Bu, tarayıcıda odak yokken komut kısayollarının etkin olmadığı anlamına gelir. Chrome 35'ten itibaren uzantı geliştiriciler, isteğe bağlı olarak bir komutu "global" olarak işaretleyebilir. Genel komutlar, Chrome'un odaklanmadığı durumlarda 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ın geçersiz kılınması riskini en aza indirmek için alınan koruyucu bir önlemdir. Örneğin, Alt+P kısayolunun global olarak kullanılmasına izin verilirse yazdırma iletişim kutusunu açmak için kullanılan 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ı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 beyanı 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:

browser.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" triggered`);
});

İşlem komutu

Kavramlar ve kullanım bölümünde açıklandığı gibi, bir komutu bir 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ı eklenmektedir.

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:

browser.action.onClicked.addListener((tab) => {
  browser.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"
browser.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" called`);
});

Kayıtlı komutları doğrulama

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ığı önceden tahmin edip yükleme sırasında çakışma olup olmadığını kontrol ederek daha sağlam bir son kullanıcı deneyimi sunabilirsiniz.

service-worker.js:

browser.runtime.onInstalled.addListener((details) => {
  if (details.reason === browser.runtime.OnInstalledReason.INSTALL) {
    checkCommandShortcuts();
  }
});

// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
  browser.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ı komutu açıklaması

• ad

  string isteğe bağlı

  Uzantı komutunun adı

• kısayol

  string isteğe bağlı

  Bu komut için etkin olan kısayol veya etkin değilse boş.

Yöntemler

getAll()

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

Bu uzantı için kayıtlı tüm uzantı komutlarını ve kısayollarını (etkinse) döndürür. Chrome 110'dan önce bu komut _execute_action döndürmüyordu.

İadeler

• Promise<Command[]>

  Chrome 96 ve sonraki sürümler Chrome 148'den itibaren browser.*

  Kayıtlı komutların listesini döndürür.

Etkinlikler

onCommand

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

Kayıtlı bir komut, klavye kısayolu kullanılarak etkinleştirildiğinde tetiklenir.

Parametreler

• callback

  işlev

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

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

  • command

    dize

  • sekme

    tabs.Tab isteğe bağlı