chrome.commands

Opis

Plik manifestu

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

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.

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

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

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