chrome.commands

Opis

Plik manifestu

Pojęcia i wykorzystanie

Interfejs Commands API pozwala programistom rozszerzeń definiować określone polecenia i wiązać je z wartościami domyślnymi kombinacji klawiszy. Każde akceptowane przez rozszerzenie polecenie musi być zadeklarowane jako właściwości "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 jego pominięcia nie jest już 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ć we wszystkich platform.

• Wartość obiektu umożliwia deweloperowi rozszerzenia dostosowanie skrótu klawiszowego do każdego platformy. Jeśli podajesz skróty na określonych platformach, 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 pojawia się w interfejsie zarządzania skrótami klawiszowymi rozszerzeń. W przypadku reklam standardowych opisy są wymagane , ale są ignorowane w poleceniach działań.

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 załadowanie rozszerzenia z nieprawidłowo dobranym kluczem spowoduje błąd analizy pliku manifestu w 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)

.

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 "mac" zastąp Ctrl klawiszem MacCtrl skrótu.

  • 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 systemu operacyjnego i skrótów w Chrome (np. zarządzanie oknami) zawsze mają wyższy priorytet Skróty dotyczące polecenia rozszerzenia 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 mechanizmie Service Worker możesz powiązać moduł obsługi z każdym z poleceń zdefiniowanych w pliku manifestu za pomocą funkcji onCommand.addListener. Na przykład:

service-worker.js:

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

Polecenia działań

_execute_action (Manifest V3), _execute_browser_action (Manifest V2) i Polecenia _execute_page_action (Manifest V2) są zarezerwowane do wywołania działania, działanie przeglądarki i działanie strony. Te polecenia nie są wysyłane command.onCommand.

Jeśli w związku z otwarciem wyskakującego okienka musisz podjąć jakieś działanie, DOMContentLoaded w kodzie JavaScript wyskakującego okienka.

Zakres

Domyślnie polecenia są ograniczone do przeglądarki Chrome. Oznacza to, że jeśli przeglądarka nie Zaznaczenie, skróty poleceń są nieaktywne. Od wersji Chrome 35 programiści rozszerzeń mogą opcjonalnie oznacz polecenie jako „globalne”. Polecenia globalne również działają, gdy Chrome nie jest aktywny.

Sugestie skrótów klawiszowych dla poleceń globalnych są ograniczone do Ctrl+Shift+[0..9]. To jest środków zabezpieczających w celu zminimalizowania ryzyka zastąpienia skrótów w innych aplikacjach, ponieważ jeśli np. Alt+P można było mieć jako globalny, skrót klawiszowy do otwierania okna drukowania może nie działać w innych aplikacjach.

Użytkownicy mogą zmienić mapowanie poleceń globalnych na preferowaną kombinację klawiszy w widocznym interfejsie o 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. Jest jest najbardziej podstawowy, polecenie wymaga jedynie deklaracji polecenia w pliku manifestu rozszerzenia i odbiornika rejestracji, jak pokazano w poniższym 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ż zmapować polecenie na działania. Poniższy przykład zawiera skrypt treści, który pokazuje tag 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`);
});

Sprawdź zarejestrowane polecenia

Jeśli rozszerzenie próbuje zarejestrować skrót, który jest już używany przez inne rozszerzenie, skrót do drugiego rozszerzenia nie zostanie zarejestrowany zgodnie z oczekiwaniami. Możesz zapewnić bardziej zaawansowanemu użytkownikowi przewidując tę możliwość i sprawdzając, czy nie występują kolizje 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.
    }
  });
}

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

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