chrome.commands

refresh date: 2026-09-25 robots: noindex

Açıklama

Manifest

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 özellik. Atlanırsa komut 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.

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

Daha fazla bilgi 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ı birçok komuta sahip 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 kullanılan 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ı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 (macOS'te Option), Shift, MacCtrl (yalnızca macOS), Command (yalnızca macOS), Search (yalnızca ChromeOS)

Tuş kombinasyonu şartları

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

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

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

  • macOS'te Control tuşunu kullanmak için "mac" kısayolunu tanımlarken Ctrl yerine MacCtrl tuşunu 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, 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 manifest'te 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 tetikleme, tarayıcı işlemi veya sayfa 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 nedenle, tarayıcı odaklanmadığında komut kısayolları devre dışı kalır. Chrome 35'ten itibaren uzantı geliştiriciler, komutları isteğe bağlı olarak "global" şeklinde 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. Bu, diğer uygulamalardaki kısayolların geçersiz kılınma riskini en aza indirmek için alınan bir koruyucu önlemdir. Örneğin, Alt+P genel olarak kullanılmasına izin verilirse 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ş 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 temel düzeyde, 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

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ştirilir.

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 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ışmaları kontrol ederek daha iyi bir son kullanıcı deneyimi sunabilirsiniz.

service-worker.js:

chrome.runtime.onInstalled.addListener((reason) => {
  if (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,
): Promise<Command[]>

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