browser.commands

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"

Pojęcia i użycie

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 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 dla 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 przeznaczenia 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, Shift, MacCtrl (tylko macOS), Option (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.

    • Na wielu klawiaturach macOS Alt oznacza klawisz Option.

    • W systemie macOS zamiast Ctrl można użyć Command lub MacCtrl, a zamiast Alt można użyć klawisza Option (patrz następny punkt).

  • W systemie macOS Ctrl jest automatycznie konwertowany na Command.

    • W skrócie "mac" można też użyć Command, aby wyraźnie odwołać się do klawisza Command.

    • Aby użyć 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 sprawdzania poprawności 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:

browser.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, działania przeglądarki i działania 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. 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. Gdyby na przykład skrót Alt+P 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 pokazano w poniższym przykładzie.

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:

browser.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" triggered`);
});

Polecenie działania

Jak opisano w sekcji Pojęcia i użycie, możesz też zmapować polecenie na działanie rozszerzenia. W poniższym przykładzie wstrzykiwany jest skrypt treści, który wyświetla alert na bieżącej stronie, gdy użytkownik kliknie działanie rozszerzenia lub użyje skrótu klawiszowego.

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:

browser.action.onClicked.addListener((tab) => {
  browser.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"
browser.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 tę możliwość i sprawdzając, czy nie występują kolizje podczas instalacji.

service-worker.js:

browser.runtime.onInstalled.addListener((details) => {
  if (details.reason === browser.runtime.OnInstalledReason.INSTALL) {
    checkCommandShortcuts();
  }
});

// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
  browser.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()

browser.commands.getAll(): 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.

Zwroty

  • Promise<Command[]>

    Chrome 96 lub nowsza wersja browser.* od Chrome 148

    Zwraca listę zarejestrowanych poleceń.

Wydarzenia

onCommand

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