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

Ö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 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 her platform için klavye kısayolunu özelleştirmesine olanak tanır. Platforma özel kısayollar sağlanırken default, chromeos, linux, mac ve windows geçerli nesne özellikleri kullanılır.

Daha fazla bilgi için Tuş kombinasyonu gereksinimleri 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ısayolu yönetimi kullanıcı arayüzünde görünür. Standart komutlar için açıklamalar gereklidir ancak İşlem komutları için yoksayılır.

Bir uzantı çok sayıda komut içerebilir, ancak önerilen en fazla dört klavye kısayolu belirtebilir. Kullanıcı, chrome://extensions/shortcuts iletişim kutusundan manuel olarak daha fazla kısayol ekleyebilir.

Desteklenen Tuşlar

Aşağıdaki tuşlar, kullanılabilir komut kısayollarıdır. Anahtar tanımları büyük/küçük harfe duyarlıdır. Bir uzantıyı yanlış yazılmış bir anahtarla yüklemeye çalışmak, 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 Anahtarları - 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)

Tuş kombinasyonuyla ilgili gereksinimler

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

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

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

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

  • MacCtrl öğesini başka bir platform için birlikte kullanmak, 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ına göre ö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"
      }
    }
  },
  ...
}

Service Worker'ınızda onCommand.addListener kullanarak manifest dosyasında tanımlanan komutların her birine 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'a bağlı olarak işlem yapmanız gerekiyorsa pop-up'ınızın JavaScript'inde bir DOMContentLoaded etkinliğini dinlemeyi düşünün.

Kapsam

Varsayılan olarak, komutlar Chrome Tarayıcı'nın kapsamına alınır. Bu, tarayıcıda odak olmadığında komut kısayollarının devre dışı olacağı 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 olmadığında da çalışır.

Genel komutlar için klavye kısayolu önerileri Ctrl+Shift+[0..9] ile sınırlıdır. Bu, örneğin Alt+P için global olarak izin verildiği durumlarda, bir yazdırma iletişim kutusu açmak için kullanılan klavye kısayolu, diğer uygulamalarda çalışmayabileceğinden, diğer uygulamalarda kısayolları geçersiz kılma riskini en aza indirmek için kullanılan koruyucu bir önlemdir.

Son kullanıcılar, chrome://extensions/shortcuts adresinde gösterilen kullanıcı arayüzünü kullanarak genel komutları tercih ettikleri tuş kombinasyonuyla 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 esnek hale getirir.

Temel komut

Komutlar, uzantıların, kullanıcı tarafından çağrılabilecek klavye kısayollarıyla mantığı eşlemesine olanak tanır. Bir komut, en temel haliyle 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 uzantının işlemiyle de eşleyebilirsiniz. Aşağıdaki örnek, kullanıcı uzantı işlemini tıkladığında veya klavye kısayolunu tetiklediğinde geçerli sayfada bir uyarı gösteren bir içerik komut dosyası ekler.

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`);
});

Komutların kaydedildiğini 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 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.
    }
  });
}

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

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