Office.Actions interface

Checks if a set of shortcut combinations are currently in use for the user, as defined by another add-in or by the Office application. For more information, see Add custom keyboard shortcuts to your Office Add-ins.

areShortcutsInUse(shortcuts: string[]): Promise<Array<{shortcut: string, inUse: boolean}>>;

Parameters

Returns

A promise that resolves to an array of objects. Each object consists of a shortcut combination and Boolean value. The value is true if the shortcut combination conflicts with a shortcut of another add-in or with a shortcut of the Office application; otherwise, false. For example, [{shortcut:"Ctrl+1", inUse:true},{shortcut:"Ctrl+2", inUse:false}].

Remarks

Requirement sets:

• KeyboardShortcuts 1.1

• SharedRuntime 1.1

Examples

// Checks if a specific keyboard shortcut is in use.
const shortcuts = ["Ctrl+Shift+1", "Ctrl+Shift+2"];
Office.actions.areShortcutsInUse(shortcuts)
    .then((shortcutsInUse) => {
        const availableShortcuts = shortcutsInUse.filter((shortcut) => { return !shortcut.inUse; });
        console.log(`Available keyboard shortcuts: ${availableShortcuts}`);
        const usedShortcuts = shortcutsInUse.filter((shortcut) => { return shortcut.inUse; });
        console.log(`Shortcuts in use: ${usedShortcuts}`);
});

Associates the ID or name of an action with a function.

associate(actionId: string, actionFunction: (arg?: any) => void): void;

Parameters

Returns

Examples

// Maps the action ID to the showTaskPane function.
Office.actions.associate("ShowTaskpane", showTaskPane);

// Displays the add-in's task pane.
function showTaskPane() {
    return Office.addin.showAsTaskpane()
        .then(() => { console.log("Task pane is visible."); })
        .catch((error) => {
            console.log(error.code);
        });
}

Gets the existing shortcuts for the add-in. The set always includes (1) the shortcuts defined in the add-in's manifest for keyboard shortcuts and (2) the current user's custom shortcuts if those exist. The shortcut can be null if it conflicts with the shortcut of another add-in or with the Office application. Specifically, it would be null if, when prompted to choose which shortcut to use, the user didn't choose the action of the current add-in. For more information about conflicts with shortcuts, see Avoid key combinations in use by other add-ins.

getShortcuts(): Promise<{[actionId: string]: string|null}>;

Returns

A promise that resolves to an object of shortcuts, with keys being the IDs of the actions (as defined in an manifest) and values being the shortcut combinations. For example, {"SetItalic": "Ctrl+1", "SetBold": "Ctrl+2", "SetUnderline": null}.

Remarks

Requirement sets:

• KeyboardShortcuts 1.1

• SharedRuntime 1.1

Examples

// Gets the list of keyboard shortcuts for an add-in.
Office.actions.getShortcuts()
    .then((shortcuts) => {
        for (const action in shortcuts) {
            let shortcut = shortcuts[action];
            console.log(`${action}: ${shortcut}`);
        }
});

Replaces existing add-in shortcuts with custom shortcuts for the user.

replaceShortcuts(shortcuts: {[actionId: string]: string}): Promise<void>;

Parameters

Returns

A promise that resolves when every custom shortcut assignment in shortcuts has been registered. Even if there is a conflict with existing shortcuts, the customized shortcut will be registered. Otherwise, the promise will be rejected with error code and error message. An "InvalidOperation" error code is returned if any action ID in shortcuts does not exist, or if shortcut combination is invalid.

Remarks

Requirement sets:

• KeyboardShortcuts 1.1

• SharedRuntime 1.1

Examples

// Replaces the keyboard shortcuts of an add-in.
const customShortcuts = {
    ShowTaskpane:"Ctrl+Shift+1",
    HideTaskpane:"Ctrl+Shift+2"
};
Office.actions.replaceShortcuts(customShortcuts)
    .then(() => { console.log("Keyboard shortcuts successfully registered."); })
    .catch((error) => {
        if (error.code == "InvalidOperation") {
            console.log("ActionId does not exist or shortcut combination is invalid.");
        }
});