chrome.commands

Opis

Za pomocą interfejsu API poleceń możesz dodawać skróty klawiszowe wywołujące działania w rozszerzeniu, np. działanie powodujące otwarcie działania w przeglądarce lub wysłanie do rozszerzenia polecenia.

Plik manifestu

Aby można było używać tego interfejsu API, następujące klucze muszą być zadeklarowane w pliku manifestu.

"commands"

Pojęcia i zastosowanie

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

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

suggested_key

Opcjonalna właściwość, która określa domyślne skróty klawiszowe polecenia. Jeśli go pominiesz, polecenie pozostanie usunięte. Ta właściwość może przyjmować wartość ciągu 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ótów klawiszowych do poszczególnych platform. W przypadku skrótów na poszczególnych platformach prawidłowymi właściwościami obiektu są default, chromeos, linux, mac i windows.

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

description

Ciąg tekstowy służący do przekazania użytkownikowi krótkiego opisu przeznaczenia polecenia. Ten ciąg pojawia się w interfejsie zarządzania skrótami klawiszowymi w rozszerzeniu. Opisy są wymagane w przypadku standardowych poleceń, ale są one ignorowane w przypadku poleceń działania.

Rozszerzenie może mieć wiele poleceń, ale możesz określić 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

Podane niżej klawisze to przydatne skróty poleceń. W głównych definicjach wielkość liter ma znaczenie. Próba wczytania rozszerzenia z nieprawidłowo zastosowanym kluczem spowoduje wyświetlenie błędu analizy pliku manifestu podczas instalacji.

Klucze 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 klawiszy modyfikujących

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

Wymagania dotyczące kombinacji kluczy

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

    • Modyfikatorów nie można używać razem z kluczami multimediów.

  • W systemie macOS Ctrl jest automatycznie konwertowany na Command.

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

    • Użycie połączenia 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 Chrome (np. zarządzanie oknami) zawsze mają wyższy priorytet niż skróty poleceń rozszerzeń i nie można ich zastąpić.

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

service-worker.js:

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

Polecenia działania

Polecenia _execute_action (plik manifestu w wersji 3), _execute_browser_action (Manifest V2) i _execute_page_action (Manifest V2) są zarezerwowane odpowiednio dla działania wywołującego działanie, przeglądarkę lub stronę. Polecenia te nie wysyłają zdarzeń command.onCommand takich jak standardowe polecenia.

Jeśli musisz podjąć działanie zależnie od 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 nie jest zaznaczone w przeglądarce, skróty poleceń są nieaktywne. Począwszy od Chrome 35, deweloperzy rozszerzeń mogą opcjonalnie oznaczać polecenie jako „globalne”. Polecenia globalne działają też wtedy, gdy nie jest zaznaczone w Chrome.

Sugestie skrótów klawiszowych dla poleceń globalnych są ograniczone do Ctrl+Shift+[0..9]. Jest to środek ochronny mający na celu zminimalizowanie ryzyka zastąpienia skrótów w innych aplikacjach. Gdyby na przykład Alt+P był przyznany jako globalny, skrót klawiszowy otwierający okno drukowania może nie działać w innych aplikacjach.

Użytkownicy mogą zmieniać polecenia globalne na preferowaną kombinację klawiszy, korzystając z 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 podanych niżej przykładach udoskonalono podstawową 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. Ogólnie rzecz biorąc, polecenie wymaga deklaracji polecenia w pliku manifestu rozszerzenia i rejestracji odbiornika, tak jak 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 Użycie, możesz też zmapować polecenie na działanie rozszerzenia. Poniższy przykład wprowadza 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ź, czy polecenia zostały zarejestrowane

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 zwiększyć bezpieczeństwo użytkowników, przewidując taką 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 dla tego polecenia lub pusty, jeśli nie jest aktywny.

Metody

getAll()

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

Zwraca wszystkie zarejestrowane polecenia rozszerzenia związane z danym rozszerzeniem oraz jego skrót (jeśli jest aktywny). Przed Chrome 110 to polecenie nie zwracało wartości _execute_action.

Parametry

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (commands: Command[])=>void

Akcje powrotne

  • Obietnica<Command[]>

    Chrome 96 i nowsze wersje

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

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 wygląda tak: 

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

    • polecenie

      string,

    • tab

      tabs.Tab opcjonalnie