chrome.commands

Açıklama

Uzantınızda işlemleri tetikleyen klavye kısayolları (ör. tarayıcı eylemini açan veya uzantıya komut gönderen bir işlem) eklemek için komutlar API'sini kullanın.

Manifest

Bu API'yi kullanmak için aşağıdaki anahtarlar manifest dosyasında beyan edilmelidir.

"commands"

Kavramlar ve kullanım

Komutlar API'si, 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 tanımlanmalıdır.

Mülk anahtarı, komutun adı olarak kullanılır. Komut nesneleri iki özellik alabilir.

suggested_key

Komut için varsayılan klavye kısayollarını açıklayan isteğe bağlı bir özelliktir. Atlanırsa komutun bağları kaldırılır. Bu mülk, 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 platform için özelleştirmesine olanak tanır. Platforma özgü kısayollar sağlarken geçerli nesne özellikleri default, chromeos, linux, mac ve windows'dir.

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 bir dize. Bu dize, uzantı klavye kısayolu yönetim 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 bulunabilir ancak en fazla dört önerilen klavye kısayolu belirtilebilir. Kullanıcı, chrome://extensions/shortcuts iletişim kutusunda manuel olarak daha fazla kısayol ekleyebilir.

Desteklenen Anahtarlar

Aşağıdaki tuşlar, kullanılabilen 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ımıyla bir uzantı yüklemeye çalışmak, yükleme sırasında manifest ayrıştırma hatasına neden olur.

Alfa anahtarları

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

Tuş kombinasyonu şartları

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

  • Değiştiriciler, medya anahtarlarıyla birlikte kullanılmaz.

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

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

• macOS'te Ctrl otomatik olarak Command'e 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 Kontrol tuşunu kullanmak için "mac" kısayolunu tanımlarken Ctrl yerine MacCtrl 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.

Not: AltGr anahtarıyla çakışmaları önlemek 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"
      }
    }
  },
  ...
}

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:

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 tetikleme, tarayıcı işlemi veya sayfa işlemi için ayrılmıştır. Bu komutlar, standart komutlar gibi command.onCommand etkinlikleri dağıtmaz.

Pop-up'ınızın açılmasına bağlı olarak işlem yapmanız gerekiyorsa pop-up'ınızın JavaScript'inde DOMContentLoaded etkinliğini dinleyebilirsiniz.

Kapsam

Varsayılan olarak komutlar Chrome Tarayıcı'ya yöneliktir. Bu, tarayıcıda odak olmadığında komut kısayollarının etkin olmadığı anlamına gelir. Chrome 35'ten itibaren uzantı geliştiricileri isteğe bağlı olarak bir komutu "evrensel" olarak işaretleyebilir. Küresel komutlar, Chrome'un odağı olmadığında da çalışır.

Not: ChromeOS, genel komutları desteklemez.

Küresel komutlar için klavye kısayolu önerileri Ctrl+Shift+[0..9] ile sınırlıdır. Bu, diğer uygulamalarda kısayolların geçersiz kılınması riskini en aza indirmek için alınan bir koruma önlemidir. Örneğin, Alt+P'e genel olarak izin verilse yazdırma iletişim kutusunu açma klavye kısayolu diğer uygulamalarda çalışmayabilir.

Son kullanıcılar, chrome://extensions/shortcuts adresinde sunulan kullanıcı arayüzünü kullanarak genel komutları tercih ettikleri tuş kombinasyonlarıyla 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 göstermektedir.

Temel komut

Komutlar, uzantıların mantığı kullanıcı tarafından çağrılabilecek klavye kısayollarıyla eşleştirmesine olanak tanır. En temel haliyle 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:

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 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 mevcut sayfada uyarı gösteren bir içerik komut dosyası enjekte edilmektedir.

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 güçlü bir son kullanıcı deneyimi sunabilirsiniz.

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 etkin olan kısayol veya etkin değilse boş.

Yöntemler

getAll()

Promise

chrome.commands.getAll(
  callback?: function,
)

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ürmezdi.

Parametreler

• geri çağırma

  işlev isteğe bağlı

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

  (commands: Command[]) => void

  • commands

    Komut[]

İadeler

• Promise<Command[]>

  Chrome 96 ve üzeri sürümler

  Sözler Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türle çözülür.

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ı