chrome.commands

Opis

Użyj interfejsu API poleceń, aby dodać skróty klawiszowe, które uruchamiają działania w rozszerzeniu, na przykład działanie otwierające działanie przeglądarki lub wysłanie polecenia do rozszerzenia.

Plik manifestu

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

"commands"

Pojęcia i wykorzystanie

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

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

suggested_key

Opcjonalna właściwość deklarująca domyślne skróty klawiszowe dla polecenia. W przypadku pominięcia tego polecenia polecenie nie jest powiązane. Ta właściwość może przyjąć wartość w postaci ciągu znaków lub obiektu.

• Wartość ciągu określa domyślny skrót klawiszowy, którego należy używać na wszystkich platformach.

• Wartość obiektu umożliwia deweloperowi rozszerzenia dostosowanie skrótu klawiszowego do każdej platformy. Jeśli udostępniasz skróty na poziomie platformy, prawidłowe właściwości obiektów to default, chromeos, linux, mac i windows.

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

description

Ciąg znaków używany do przedstawienia użytkownikowi krótkiego opisu przeznaczenia polecenia. Ten ciąg znaków jest widoczny w interfejsie zarządzania skrótami klawiszowymi rozszerzeń. W przypadku poleceń standardowych opisy są wymagane, ale w poleceniach działań są ignorowane.

Rozszerzenie może mieć wiele poleceń, ale może zawierać 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

Poniższe klawisze są użytecznymi skrótami poleceń. Wielkość liter w kluczowych definicjach ma znaczenie. Próba wczytania rozszerzenia z nieprawidłowo dobranym kluczem spowoduje błąd analizy pliku manifestu podczas instalacji.

Klawisze alfa

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 kluczowe modyfikatora

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

Uwaga: ze względu na ułatwienia dostępu Tab został usunięty z listy obsługiwanych kluczy w Chrome 33.

Wymagania dotyczące kombinacji kluczy

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

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

• W systemie macOS Ctrl jest automatycznie konwertowany na Command.

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

  • Użycie tagu MacCtrl w połączeniu z inną platformą 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) zawsze mają wyższy priorytet niż skróty polecenia rozszerzenia i nie można ich zastąpić.

Uwaga: aby uniknąć konfliktów z kluczem AltGr, nie zezwalamy na kombinacje klawiszy, które obejmują Ctrl+Alt.

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 określonym w pliku manifestu za pomocą onCommand.addListener. Na przykład:

service-worker.js:

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

Polecenia działań

Polecenia _execute_action (Manifest V3), _execute_browser_action (Manifest V2) i _execute_page_action (Manifest V2) są zarezerwowane do odpowiednio wywołania działania, działania przeglądarki lub działania na stronie. Te polecenia nie wysyłają zdarzeń command.onCommand, jak polecenia standardowe.

Jeśli w związku z otwarciem wyskakującego okienka musisz podjąć jakieś działanie, spróbuj nasłuchiwać 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 programiści rozszerzeń mogą opcjonalnie oznaczać polecenie jako „globalne”. Polecenia globalne również działają, gdy Chrome nie jest aktywny.

Uwaga: ChromeOS nie obsługuje poleceń globalnych.

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, ponieważ jeśli na przykład zezwolono na dostęp do funkcji Alt+P jako globalne, skrót klawiszowy otwierający okno drukowania może 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 pozwalają dostosować główną funkcjonalność interfejsu Commands API.

Polecenie podstawowe

Polecenia pozwalają rozszerzeniom mapować logikę na skróty klawiszowe, które może wywołać użytkownik. Ogólnie rzecz biorąc, polecenie wymaga tylko deklaracji polecenia w pliku manifestu rozszerzenia i rejestracji detektora, 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

Zgodnie z opisem w sekcji Użycie możesz też zmapować polecenie na działanie rozszerzenia. Ten przykład ilustruje skrypt treści, który wyświetla alert na bieżącej stronie, gdy użytkownik kliknie działanie rozszerzenia lub uruchomi 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`);
});

Sprawdź zarejestrowane polecenia

Jeśli rozszerzenie próbuje zarejestrować skrót, który jest już używany przez inne rozszerzenie, drugi skrót nie zostanie zarejestrowany zgodnie z oczekiwaniami. Możesz zwiększyć wygodę użytkowników, przewidując tę możliwość i sprawdzając występowanie kolizji podczas 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

  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 w przypadku tego polecenia lub pusty, jeśli nie jest aktywny.

Metody

getAll()

Obiecujemy

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

Zwraca wszystkie zarejestrowane polecenia rozszerzenia wraz z ich skrótami (jeśli są aktywne). Przed wersją Chrome 110 to polecenie nie zwracało _execute_action.

Parametry

• wywołanie zwrotne

  funkcja optional

  Parametr callback wygląda tak:

  (commands: Command[]) => void

  • Polecenia

    Command[]

Zwroty

• Obietnica<Command[]>

  Chrome 96 lub nowszy

  Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są obsługiwane na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica jest realizowana z tym samym typem, który jest przekazywany do wywołania zwrotnego.

Wydarzenia

onCommand

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

Uruchamiane po aktywowaniu zarejestrowanego polecenia za pomocą skrótu klawiszowego.

Parametry

• wywołanie zwrotne

  funkcja

  Parametr callback wygląda tak:

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

  • polecenie

    string,

  • tab

    tabs.Tab opcjonalnie