chrome.commands

Opis

Plik manifestu

Pojęcia i zastosowanie

Interfejs Commands API umożliwia deweloperom rozszerzeń definiowanie konkretnych poleceń i przypisywanie ich do domyślnej kombinacji 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 argument 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 na każdej platformie. 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 pojawia się w interfejsie zarządzania skrótami klawiszowymi rozszerzeń. Opisy są wymagane w przypadku standardowych poleceń, ale są ignorowane w przypadku poleceń Action.

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 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), Option (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 można też użyć Command lub MacCtrl, a zamiast Alt można użyć klawisza Option (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ływać się do klawisza Command.

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

  • 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 wersji 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 Alt+P byłby dozwolony jako skrót globalny, skrót klawiszowy do otwierania okna drukowania mógłby nie działać w innych aplikacjach.

Użytkownicy mogą ponownie przypisać polecenia globalne 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ą podstawowe funkcje interfejsu Commands API.

Polecenie podstawowe

Polecenia umożliwiają rozszerzeniom mapowanie logiki na skróty klawiszowe, które użytkownik może wywoływać. W najprostszej postaci polecenie wymaga tylko deklaracji w pliku manifestu rozszerzenia i rejestracji odbiornika, 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 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 większą wygodę, 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(): Promise<Command[]>

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