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

Ö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 özelliktir. Atlanırsa komut bağlantısız olur. Bu özellik dize veya nesne değeri alabilir.

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

  • Bir nesne değeri, uzantı geliştiricinin 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.

  Ek bilgiler için Tuş kombinasyonu koşulları başlıklı makaleyi inceleyin.

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. Açıklamalar standart komutlar için gereklidir ancak işlem komutları için 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 anahtarla uzantı yüklemeye çalışmak, yükleme sırasında manifest ayrıştırma hatasına neden olur.

Alfa tuşları

A … Z

Sayı 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ı komutu 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 da kullanılabilir. Ayrıca Alt yerine Option tuşu da kullanılabilir (sonraki maddeye bakın).

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

  • Command, Komut 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 tuşunu kullanın.

  • MacCtrl simgesini başka bir platform için kombinasyonda 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, yalnızca 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.

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ı dosyanızda, onCommand.addListener kullanarak manifestte 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şlem, tarayıcı işlemi veya sayfa işleminizi tetikleme işlemi 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 işlem yapmanız gerekiyorsa pop-up'ınızın JavaScript'inde bir DOMContentLoaded etkinliğini dinlemeyi düşünebilirsiniz.

Kapsam

Varsayılan olarak, komutlar Chrome Tarayıcı ile sınırlandırılır. Bu, tarayıcı odaklanmadığında komut kısayollarının etkin olmadığı anlamına gelir. Uzantı geliştiriciler, Chrome 35'ten itibaren isteğe bağlı olarak bir komutu "global" olarak işaretleyebilir. Chrome odaklanmamışken de genel komutlar çalışır.

Genel komutlar için klavye kısayolu önerileri Ctrl+Shift+[0..9] ile sınırlıdır. Örneğin, Alt+P kısayolunun genel 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. Bu nedenle, diğer uygulamalardaki kısayolların geçersiz kılınma riskini en aza indirmek için koruyucu bir önlem olarak bu kısayolun genel olarak kullanılmasına izin verilmez.

Son kullanıcılar, chrome://extensions/shortcuts adresinde sunulan 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şlevselliği 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 basit haliyle, bir komut için yalnızca uzantının manifest dosyasında bir komut bildirimi 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 uzantının işlemine de eşleyebilirsiniz. Aşağıdaki örnekte, kullanıcı uzantının işlem düğmesini tıkladığında veya klavye kısayolunu tetiklediğinde mevcut sayfada uyarı gösteren bir içerik komut dosyası yerleştirilmektedir.

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ığı göz önünde bulundurarak ve yükleme sırasında çakışma olup olmadığını kontrol ederek daha iyi 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.
    }
  });
}

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

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