chrome.commands

refresh date: 2026-09-25 robots: noindex

Açıklama

Uzantınızda işlem tetikleyen klavye kısayolları eklemek için commands API'yi kullanın. Örneğin, tarayıcı işlemini açma veya uzantıya komut gönderme işlemi.

Manifest

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

"commands"

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ındaki "commands" nesnesinin özellikleri olarak tanımlanmalıdır.

Ö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, 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ğlarken geçerli nesne özellikleri default, chromeos, linux, mac ve windows'dir.

Daha fazla bilgi için Tuş kombinasyonu koşulları bölümünü 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. Standart komutlar için açıklama zorunludur ancak işlem komutları için açıklamalar 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. Büyük/küçük harf kullanımı yanlış olan 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ı komut kısayolları Ctrl veya Alt içermelidir.

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

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

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

    • Başka bir platformun kombinasyonunda 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ı komut kısayollarından önceliklidir ve bunların üzerine yazılamaz.

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, tarayıcı işleminizi 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 harekete geçmeniz gerekiyorsa pop-up'ınızın JavaScript'inde bir DOMContentLoaded etkinliğini dinlemeyi düşünebilirsiniz.

Kapsam

Varsayılan olarak komutlar Chrome Tarayıcı'yı kapsar. Yani tarayıcıda odak yoksa komut kısayolları etkin değildir. Chrome 35'ten itibaren uzantı geliştiriciler, isteğe bağlı olarak bir komutu "global" olarak işaretleyebilir. Genel komutlar, Chrome'un odaklanmadığı durumlarda da ç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 koruyucu bir önlemdir. Örneğin, Alt+P genel olarak izin verilirse yazdırma iletişim kutusunu açmak için kullanılan klavye kısayolu diğer uygulamalarda çalışmayabilir.

Son kullanıcılar, chrome://extensions/shortcuts adresinde gösterilen 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şlevleri gösterilmektedir.

Temel komut

Komutlar, uzantıların mantığı kullanıcı tarafından çağrılabilecek 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 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

Kullanım bölümünde açıklandığı gibi, bir komutu bir uzantının işlemine 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 bir uyarı gösteren bir içerik komut dosyası eklenmektedir.

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ığı önceden tahmin edip yükleme sırasında çakışma olup olmadığını kontrol ederek daha sağlam 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.
    }
  });
}

Türler

Command

Özellikler

  • açıklama

    string isteğe bağlı

    Uzantı komutu açıklaması

  • ad

    string isteğe bağlı

    Uzantı komutunun adı

  • kısayol

    string isteğe bağlı

    Bu komut için etkin olan kısayol veya etkin değilse boş.

Yöntemler

getAll()

Taahhüt 
chrome.commands.getAll(
  callback?: function,
): Promise<Command[]>

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ürmüyordu.

Parametreler

  • callback

    function isteğe bağlı

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

    (commands: Command[]) => void

İadeler

  • Promise<Command[]>

    Chrome 96+

    Kayıtlı komutların listesini döndürür.

    Promise'ler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırma işlevlerini kullanması gerekir.

Etkinlikler

onCommand

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

Kayıtlı bir komut, klavye kısayolu kullanılarak etkinleştirildiğinde tetiklenir.

Parametreler

  • callback

    işlev

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

    (command: string, tab?: tabs.Tab) => void

    • command

      dize

    • sekme

      tabs.Tab isteğe bağlı