chrome.commands

refresh date: 2026-09-25 robots: noindex

Opis

Użyj interfejsu Commands API, aby dodać skróty klawiszowe, które wywołują działania w rozszerzeniu, np. działanie otwierające działanie przeglądarki lub wysyłające polecenie do rozszerzenia.

Plik manifestu

Aby używać tego interfejsu API, musisz zadeklarować te klucze w pliku manifestu.

"commands"

Wykorzystanie

Interfejs Commands API umożliwia deweloperom rozszerzeń definiowanie konkretnych poleceń i powiązanie ich z domyślną kombinacją klawiszy. Każde polecenie akceptowane przez rozszerzenie musi być zadeklarowane jako właściwość obiektu "commands" w pliku manifestu rozszerzenia.

Klucz właściwości jest używany jako nazwa polecenia. Obiekty poleceń mogą mieć 2 właściwości.

suggested_key

Opcjonalna właściwość, która deklaruje domyślne skróty klawiszowe dla polecenia. Jeśli go pominiesz, polecenie nie będzie powiązane. Ta właściwość może przyjmować wartość ciągu znaków lub obiektu.

  • Wartość ciągu znaków określa domyślny skrót klawiszowy, który powinien być używany na wszystkich platformach.

  • Wartość obiektu umożliwia deweloperowi rozszerzenia dostosowanie skrótu klawiszowego do każdej platformy. W przypadku skrótów na konkretne platformy prawidłowe właściwości obiektu to default, chromeos, linux, mac i windows.

Więcej informacji znajdziesz w sekcji Wymagania dotyczące kombinacji klawiszy.

description

Ciąg znaków, który zawiera krótki opis celu polecenia. Ten ciąg znaków pojawia się w interfejsie zarządzania skrótami klawiszowymi rozszerzenia. Opisy są wymagane w przypadku poleceń standardowych, ale są ignorowane w przypadku poleceń działania.

Rozszerzenie może mieć wiele poleceń, ale może określać maksymalnie 4 sugerowane skróty klawiszowe. Użytkownik może ręcznie dodać więcej skrótów w oknie chrome://extensions/shortcuts.

Obsługiwane klucze

Te klawisze są skrótami poleceń. W definicjach kluczy wielkość liter ma znaczenie. Próba wczytania rozszerzenia z kluczem o nieprawidłowej wielkości liter spowoduje błąd analizy pliku manifestu podczas instalacji.

Klawisze alfanumeryczne
A … Z
Klawisze numeryczne
0 … 9
Standardowe ciągi kluczy

Ogólne – Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete

Klawisze strzałek – Up, Down, Left, Right

Klawisze multimedialne – MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

Ciągi klawiszy modyfikujących

Ctrl, Alt (Option w systemie macOS), Shift, MacCtrl (tylko macOS), Command (tylko macOS), Search (tylko ChromeOS)

Wymagania dotyczące kombinacji klawiszy

  • Skróty poleceń rozszerzeń muszą zawierać Ctrl lub Alt.

    • Modyfikatorów nie można używać w połączeniu z klawiszami multimedialnymi.

  • W systemie macOS Ctrl jest automatycznie konwertowany na Command.

    • Aby używać klawisza Control w systemie macOS, podczas definiowania skrótu "mac" zastąp Ctrl klawiszem MacCtrl.

    • Użycie MacCtrl w kombinacji dla innej platformy spowoduje błąd weryfikacji i uniemożliwi zainstalowanie rozszerzenia.

  • Shift jest opcjonalnym modyfikatorem na wszystkich platformach.

  • Search to opcjonalny modyfikator dostępny tylko w ChromeOS.

  • Niektóre skróty systemu operacyjnego i Chrome (np. zarządzanie oknami) zawsze mają pierwszeństwo przed skrótami poleceń rozszerzeń i nie można ich zastąpić.

Obsługa zdarzeń poleceń

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"
      }
    }
  },
  ...
}

W skrypcie service worker możesz powiązać moduł obsługi z każdym poleceniem zdefiniowanym w pliku manifestu za pomocą onCommand.addListener. Na przykład:

service-worker.js:

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command: ${command}`);
});

Polecenia dotyczące działań

Polecenia _execute_action (Manifest V3), _execute_browser_action (Manifest V2) i _execute_page_action (Manifest V2) są zarezerwowane odpowiednio dla działania wyzwalającego działanie, działanie przeglądarki lub działanie strony. Te polecenia nie wysyłają zdarzeń command.onCommand jak standardowe polecenia.

Jeśli chcesz podjąć działanie na podstawie otwarcia wyskakującego okienka, rozważ nasłuchiwanie zdarzenia DOMContentLoaded w kodzie JavaScript wyskakującego okienka.

Zakres

Domyślnie polecenia są ograniczone do przeglądarki Chrome. Oznacza to, że gdy przeglądarka nie jest aktywna, skróty poleceń są nieaktywne. Począwszy od Chrome 35, deweloperzy rozszerzeń mogą opcjonalnie oznaczać polecenia jako „globalne”. Polecenia globalne działają również wtedy, gdy Chrome nie jest aktywny.

Sugestie skrótów klawiszowych dla poleceń globalnych są ograniczone do Ctrl+Shift+[0..9]. Jest to środek ochronny, który minimalizuje ryzyko zastąpienia skrótów w innych aplikacjach. Jeśli na przykład skrót Alt+P byłby dozwolony jako globalny, skrót klawiszowy do otwierania okna drukowania mógłby nie działać w innych aplikacjach.

Użytkownicy mogą zmienić mapowanie poleceń globalnych na preferowaną kombinację klawiszy za pomocą interfejsu dostępnego na stronie chrome://extensions/shortcuts.

Przykład:

manifest.json:

{
  "name": "My extension",
  ...
  "commands": {
    "toggle-feature-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+5"
      },
      "description": "Toggle feature foo",
      "global": true
    }
  },
  ...
}

Przykłady

Poniższe przykłady pokazują główną funkcjonalność interfejsu Commands API.

Polecenie podstawowe

Polecenia umożliwiają rozszerzeniom mapowanie logiki na skróty klawiszowe, które mogą być wywoływane przez użytkownika. W najprostszym przypadku polecenie wymaga tylko deklaracji polecenia w pliku manifestu rozszerzenia i rejestracji detektora, jak w przykładzie poniżej.

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

Polecenie działania

Jak opisano w sekcji Użycie, możesz też zmapować polecenie na działanie rozszerzenia. Poniższy przykład wstrzykuje skrypt treści, który wyświetla alert na bieżącej stronie, gdy użytkownik kliknie działanie rozszerzenia lub aktywuje skrót klawiszowy.

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

Sprawdzanie zarejestrowanych poleceń

Jeśli rozszerzenie spróbuje zarejestrować skrót, który jest już używany przez inne rozszerzenie, skrót drugiego rozszerzenia nie zostanie zarejestrowany zgodnie z oczekiwaniami. Możesz zapewnić użytkownikom lepsze wrażenia, przewidując taką możliwość i sprawdzając, czy nie występują kolizje podczas instalacji.

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

Typy

Command

Właściwości

  • opis

    ciąg znaków opcjonalny

    Opis polecenia rozszerzenia

  • nazwa

    ciąg znaków opcjonalny

    Nazwa polecenia rozszerzenia

  • skrót

    ciąg znaków opcjonalny

    Skrót aktywny dla tego polecenia lub puste pole, jeśli nie jest aktywny.

Metody

getAll()

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

Zwraca wszystkie zarejestrowane polecenia rozszerzenia i ich skróty (jeśli są aktywne). W wersjach Chrome starszych niż 110 to polecenie nie zwracało wartości _execute_action.

Parametry

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    (commands: Command[]) => void

Zwroty

  • Promise<Command[]>

    Chrome 96 lub nowsza wersja

    Zwraca listę zarejestrowanych poleceń.

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

Wydarzenia

onCommand

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

Uruchamiane, gdy zarejestrowane polecenie jest aktywowane za pomocą skrótu klawiszowego.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

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

    • polecenie

      tekst

    • karta

      tabs.Tab opcjonalny