chrome.commands

Opis

Plik manifestu

Pojęcia i zastosowanie

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 ten parametr zostanie pominięty, 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 specyficznych dla 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 używany do podania użytkownikowi krótkiego opisu celu polecenia. Ten ciąg znaków jest widoczny w interfejsie zarządzania skrótami klawiszowymi rozszerzeń. 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

Poniższe klawisze mogą służyć jako skróty do poleceń. W definicjach kluczy jest rozróżniana wielkość liter. Próba wczytania rozszerzenia z kluczem o nieprawidłowej wielkości liter spowoduje błąd analizowania 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 znaków klawiszy modyfikujących

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

Wymagania dotyczące kombinacji klawiszy

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

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

  • Na wielu klawiaturach macOS symbol Alt oznacza klawisz Option.

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

• W systemie macOS znak Ctrl jest automatycznie konwertowany na Command.

  • Symbolu Command można też używać w skrócie "mac", 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 znakiem 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 systemu operacyjnego i Chrome (np. zarządzanie oknami) zawsze mają wyższy priorytet niż skróty 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 usłudze 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 działania

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

Jeśli musisz 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 oznaczyć polecenie jako „globalne”. Polecenia globalne działają też wtedy, gdy Chrome nie jest aktywny.

Sugestie skrótów klawiszowych do poleceń globalnych są ograniczone do Ctrl+Shift+[0..9]. Jest to środek ochronny, który ma zminimalizować ryzyko zastąpienia skrótów w innych aplikacjach. Jeśli na przykład znak 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ą zmieniać przypisanie poleceń globalnych do wybranej kombinacji klawiszy za pomocą interfejsu dostępnego pod adresem 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ą 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. W najprostszej postaci polecenie wymaga tylko deklaracji polecenia w pliku manifestu rozszerzenia i rejestracji odbiornika, jak pokazano 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 Pojęcia i użycie, możesz też przypisać polecenie do działania rozszerzenia. W tym przykładzie wstrzykiwany jest skrypt treści, który wyświetla alert na bieżącej stronie, gdy użytkownik kliknie działanie rozszerzenia lub wywoła 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 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.
    }
  });
}

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

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