chrome.commands

Opis

Za pomocą interfejsu komend API możesz dodawać skróty klawiszowe, które wywołują działania w rozszerzeniu, np. otwierają działanie przeglądarki lub wysyłają polecenie do rozszerzenia.

Plik manifestu

Aby korzystać z tego interfejsu API, musisz zadeklarować te klucze w pliku manifestu.

"commands"

Pojęcia i zastosowanie

Interfejs Commands API umożliwia deweloperom rozszerzeń definiowanie konkretnych poleceń i wiązanie ich z domyślną kombinacją klawiszy. Każda komenda obsługiwana przez rozszerzenie musi być zadeklarowana jako właściwości 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 wią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 na każdej platformie. Podczas udostępniania skrótów dla poszczególnych platform prawidłowe właściwości obiektu to default, chromeos, linux, mac i windows.

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

description

Ciąg znaków, który zawiera krótki opis celu polecenia. Ten ciąg znaków jest wyświetlany w interfejsie zarządzania skrótami klawiszowymi rozszerzeń. Opis jest wymagany w przypadku standardowych poleceń, ale jest ignorowany w przypadku komend akcji.

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

Obsługiwane klucze

Poniższe klawisze to skróty poleceń. W definicjach kluczy wielkość liter ma znaczenie. Próba załadowania rozszerzenia z nieprawidłowo zapisanym kluczem spowoduje błąd analizy pliku manifestu podczas instalacji.

Klucze alfa

A … Z

Klawisze numeryczne

0 … 9

Standardowe ciągi znaków klucza

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 znaków klawiszy modyfikujących,

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

Wymagania dotyczące kombinacji klawiszy

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

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

  • Na wielu klawiaturach w systemie macOS klawisz Alt to klawisz Option.

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

• Na komputerach Mac Ctrl jest automatycznie konwertowane na Command.

  • Command może być też używany w skrótach "mac", aby wyraźnie odwoływać się do klawisza Command.

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

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

• Shift to opcjonalny modyfikator na wszystkich platformach.

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

• Niektóre skróty w systemie operacyjnym i w Chrome (np. zarządzanie oknami) mają zawsze wyższy priorytet niż skróty do poleceń rozszerzenia i nie można ich zastąpić.

Uwaga: kombinacje klawiszy, które zawierają Ctrl+Alt, są niedozwolone, aby uniknąć konfliktów z kluczem AltGr.

Obsługa zdarzeń związanych z poleceniami

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 usługowym pliku wykonywalnym możesz powiązać z poszczególnymi poleceniami zdefiniowanymi w pliku manifestu odpowiedni moduł obsługi za pomocą parametru onCommand.addListener. Na przykład:

service-worker.js:

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

Polecenia dotyczące działania

Polecenia _execute_action (Manifest V3), _execute_browser_action (Manifest V2) i _execute_page_action (Manifest V2) są zarezerwowane odpowiednio dla akcji trigger your action, browser action i page action. Te polecenia nie wysyłają zdarzeń command.onCommand, tak jak ma to miejsce w przypadku standardowych poleceń.

Jeśli chcesz podjąć działanie po otwarciu wyskakującego okienka, w kodzie JavaScript wyskakującego okienka możesz zastosować selektywne wywoływanie zdarzenia DOMContentLoaded.

Zakres

Domyślnie polecenia są ograniczone do przeglądarki Chrome. Oznacza to, że gdy przeglądarka nie ma aktywnego pola tekstowego, skróty klawiszowe są nieaktywne. Począwszy od wersji 35 Chrome deweloperzy rozszerzeń mogą opcjonalnie oznaczyć polecenie jako „globalne”. Polecenia globalne działają też wtedy, gdy Chrome nie jest aktywne.

Uwaga: system ChromeOS nie obsługuje poleceń globalnych.

Sugestie dotyczące skrótów klawiszowych dla poleceń globalnych są ograniczone do Ctrl+Shift+[0..9]. Jest to środek zapobiegawczy, który minimalizuje ryzyko zastąpienia skrótów w innych aplikacjach. Jeśli na przykład Alt+P zostanie dozwolone jako skrót globalny, skrót klawiaturowy do otwierania okna dialogowego drukowania może nie działać w innych aplikacjach.

Użytkownicy mogą swobodnie przypisywać polecenia globalne do ulubionych kombinacji 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

W tych przykładach wykorzystano podstawowe funkcje interfejsu Commands API.

Podstawowe polecenie

Polecenia umożliwiają rozszerzeniom mapowanie logiki na skróty klawiszowe, które użytkownik może wywołać. W najprostszej formie polecenie wymaga tylko deklaracji w pliku manifestu rozszerzenia i rejestracji listenera, jak pokazano w tym 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:

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

Polecenie działania

Jak opisano w sekcji Pojęcia i użytkowanie, możesz też mapować polecenia na działanie rozszerzenia. W tym przykładzie skrypt treści wstrzykuje skrypt treści, który wyświetla alert na bieżącej stronie, gdy użytkownik kliknie działanie rozszerzenia lub uruchomi skrót klawiaturowy.

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

Weryfikowanie 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 kolizje w momencie instalacji.

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

Typy

Command

Właściwości

• opis

  string opcjonalny

  Opis polecenia rozszerzenia

• nazwa

  string opcjonalny

  Nazwa polecenia rozszerzenia.

• skrót

  string opcjonalny

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

Metody

getAll()

Obietnice

chrome.commands.getAll(
  callback?: function,
)

Zwraca wszystkie zarejestrowane polecenia rozszerzenia dla tego rozszerzenia oraz ich skróty (jeśli są aktywne). Przed wersją 110 Chrome to polecenie nie zwracało wartości _execute_action.

Parametry

• wywołanie zwrotne

  function opcjonalny

  Parametr callback ma postać:

  (commands: Command[]) => void

  • poleceń

    Command[]

Zwroty

• Promise<Command[]>

  Chrome 96 i nowsze

  Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

Wydarzenia

onCommand

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

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

Parametry

• wywołanie zwrotne

  funkcja

  Parametr callback ma postać:

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

  • polecenie

    ciąg znaków

  • tabulator

    tabs.Tab opcjonalne