Skip to content

commands.md

Latest commit

 

History

History
127 lines (89 loc) · 3.87 KB

commands.md

File metadata and controls

127 lines (89 loc) · 3.87 KB
Raw

commands

Documentation: Chrome Commands API

A promise-based wrapper for the Chrome commands API.

Methods

Events

isAvailableCommands

isAvailableCommands(method?: ApiMethodName<typeof chrome.commands>): boolean

The optional method is a native function name, for example isAvailableCommands("getAll"). Import the public ApiMethodName type from @addon-core/browser for your own typed helpers. This checks callable presence without invoking the method; permissions and argument support still require handling.

Returns true when the commands namespace is present on the API selected by browser() in the current context. Returns false if the namespace or WebExtension environment is absent, or if accessing it throws. The check is synchronous, does not log, and reads the current API on every call without caching. Without an argument, it checks namespace presence only. Pass a native method name to also check that it is callable. Neither form verifies permissions, argument support, or a successful operation. See method availability.

import {isAvailableCommands} from "@addon-core/browser";

if (isAvailableCommands()) {
    // The namespace is present; handle operation-specific failures when using it.
}

getAllCommands

getAllCommands(): Promise<chrome.commands.Command[]>

Retrieves all registered extension commands.

onCommand

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

Adds a listener for extension command events. Returns an unsubscribe function.

onSpecificCommand

onSpecificCommand(
    command: string,
    callback: (tab?: chrome.tabs.Tab) => any
): () => void

Adds a listener that triggers only when the specified command is invoked. The name match is exact and case-sensitive. Returns an unsubscribe function that removes only this subscription.

The callback receives the tab supplied by the event, or undefined if no tab was supplied. It may be async; synchronous errors and rejected Promises are logged by the listener wrapper.

import {onSpecificCommand} from "@addon-core/browser";

const unsubscribe = onSpecificCommand("sync", async tab => {
    console.log("Sync tab:", tab?.id);
    await syncData();
});

// Remove this subscription when it is no longer needed.
unsubscribe();

onSpecificCommands

onSpecificCommands(handlers: Record<string, (tab?: chrome.tabs.Tab) => any>): () => void

Subscribes to several named commands using one object: each key is a command name and each value is its callback. When a command is invoked, the handler whose key exactly matches its name receives the tab supplied by the event, or undefined if no tab was supplied. Names are case-sensitive. Unmatched names and inherited properties are ignored; an empty object is also accepted.

Uses one underlying onCommand subscription for the entire object and returns one unsubscribe function that removes it. Callbacks may be async; synchronous errors and rejected Promises are logged by the listener wrapper.

import {onSpecificCommands} from "@addon-core/browser";

const unsubscribe = onSpecificCommands({
    sync: async tab => {
        console.log("Sync tab:", tab?.id);
        await syncData();
    },
    cleanup: async tab => {
        console.log("Cleanup tab:", tab?.id);
        await cleanupData();
    },
});

// Remove the subscription for all handlers in this object.
unsubscribe();