chrome.commands

Açıklama

Uzantınızda işlemleri (ör. tarayıcı işlemini açma işlemi veya uzantıya komut gönderme) tetikleyen klavye kısayolları eklemek için Komutlar API'sini kullanın.

Manifest

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

"commands"

Kavramlar ve kullanım

Commands API, uzantı geliştiricilerin belirli komutları tanımlamasına ve bunları varsayılan bir komuta bağlamasına olanak tanır tuş kombinasyonunu kullanın. Bir uzantının kabul ettiği her komut, Uzantının manifest dosyasındaki "commands" nesnesi.

Ö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 komutunun bağlantısı kaldırılır. Bu özellik bir dize veya nesne değeri alabilir.

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

• Nesne değeri, uzantı geliştiricisinin her bir öğe için klavye kısayolunu özelleştirmesine olanak tanır platformu. Platforma özel kısayollar sağlanırken geçerli nesne özellikleri default, chromeos, linux, mac ve windows.

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ı yerine getirilir, 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. İlgili içeriği oluşturmak için kullanılan 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. Şunları yapmaya çalışılıyor: bir uzantıyı yanlış yazılmış bir anahtarla yüklemek, şurada manifest ayrıştırma hatasına neden olur: yükleme süresidir.

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)

ziyaret edin.

'nı inceleyin.

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

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" öğesini tanımlarken Ctrl yerine MacCtrl kullanın kısayolunu görürsünüz.

  • 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ı komutu kısayolları ve geçersiz kılınamaz.

ziyaret edin.

Not: Ctrl+Alt öğesini içeren tuş kombinasyonlarına, AltGr anahtarı.

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, manifest dosyasında tanımlanan komutların her birine bir işleyici bağlayabilirsiniz. onCommand.addListener kullanılıyor. Ö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ı, işleminizi tetikleme işlemi için ayrılmıştır. tarayıcı işlemi veya sayfa işlemi. Bu komutlar command.onCommand etkinliklerini içeren standart komutlar kullanılabilir.

Açılan pop-up'a göre işlem yapmanız gerekiyorsa şu komutu dinlemeyi düşünün: DOMContentLoaded etkinliğini artırır.

Kapsam

Varsayılan olarak, komutlar Chrome Tarayıcı'nın kapsamına alınır. Bu, tarayıcı iletişim kurmadığında komut kısayolları etkin değil. Chrome 35'ten itibaren uzantı geliştiricileri, isteğe bağlı olarak bir komutu "global" olarak işaretleyebilirsiniz. Genel komutlar, Chrome'da odak olmadığında 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 uygulamalarda kısayolları geçersiz kılma riskini en aza indirmek için koruyucu önlemdir; çünkü örneğin, Alt+P yazdırma iletişim kutusu açmak için kullanılan klavye kısayolu olan global olarak diğer uygulamalarda çalışmayabilir.

Son kullanıcılar, genel komutları, gösterilen kullanıcı arayüzünü kullanarak tercih ettikleri tuş kombinasyonuyla yeniden eşleyebilir Yer: chrome://extensions/shortcuts.

Ö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. Saat En temel komutlar için yalnızca uzantının manifest dosyasında bir komut bildirimi ve işleyici kaydına sahip olmalıdır.

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 eyleme dökülebilir. Aşağıdaki örnek, Kullanıcı uzantı işlemine ilişkin işlemi tıkladığında veya klavye kısayolunu kullanın.

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 kaydedilmiyor. Daha sağlam bir son kullanıcı deneyimi tahmin ederek ve yükleme sırasında çakışmalar olup olmadığını kontrol ederek

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 kısayol etkin ya da etkin değilse boştur.

Yöntemler

getAll()

Söz 'nı inceleyin.

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

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

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 sonraki sürümler 'nı inceleyin.

  Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, 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ı