Edit

Share via

Office.Actions interface

  • Reference
Package:
office

Manages actions and keyboard shortcuts.

Methods

areShortcutsInUse(shortcuts)

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.
associate(actionId, actionFunction)

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

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.
replaceShortcuts(shortcuts)

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

Method Details

areShortcutsInUse(shortcuts)

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

shortcuts

string[]

An array of shortcut combinations. For example, ["Ctrl+1", "Ctrl+2"].

Returns

Promise<Array<{shortcut: string, inUse: boolean}>>

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:

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

associate(actionId, actionFunction)

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

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

Parameters

actionId

string

The ID of an action that is defined in the manifest.

actionFunction

(arg?: any) => void

The function that is run when the action is invoked.

Returns

void

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

getShortcuts()

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

Promise<{[actionId: string]: string|null}>

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:

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

replaceShortcuts(shortcuts)

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

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

Parameters

shortcuts

{[actionId: string]: string}

An object of custom shortcuts with keys being the IDs of the actions and values being the shortcut combinations. For example, {"SetItalic": "Ctrl+1", "SetBold": "Ctrl+2"}. To learn how to specify a valid action ID and a key combination, see Add custom keyboard shortcuts to your Office Add-ins. (Note that a key combination can be null, in which case, the action keeps the key combination specified in the JSON file.)

Returns

Promise<void>

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:

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