Office.Ribbon interface

Package:

office

An interface that contains all the functionality provided to manage the state of the Office ribbon.

Remarks

Requirement set: RibbonAPI 1.1

Methods

requestCreateControls(tabDefinition)	Registers a custom contextual tab with Office and defines the tab's controls.
requestUpdate(input)	Sends a request to Office to update the ribbon.

Method Details

requestCreateControls(tabDefinition)

Registers a custom contextual tab with Office and defines the tab's controls.

requestCreateControls(tabDefinition: Object): Promise<void>;

Parameters

tabDefinition

Object

Specifies the tab's properties and child controls and their properties. This parameter isn't strongly typed because its shape is defined by a JSON schema that can be versioned. To create the parameter object, pass a JSON string that conforms to the Office dynamic-ribbon JSON schema to JSON.parse, and then pass the returned object to this method. To get IntelliSense for the JSON in Visual Studio Code, see Editing JSON with Visual Studio Code - JSON schemas and settings.

Returns

Promise<void>

Remarks

Requirement set: RibbonAPI 1.2

This method only requests that the tab be registered. The actual registration is controlled by the Office application and may not be complete when the returned Promise object is resolved. For more information and code examples, see Create custom contextual tabs.

Examples

// Registers a custom contextual tab with Office.
Office.onReady(async () => {
    const contextualTabJSON = ` ... `; // Assign the JSON string.
    const contextualTab = JSON.parse(contextualTabJSON);
    await Office.ribbon.requestCreateControls(contextualTab);
});

requestUpdate(input)

Sends a request to Office to update the ribbon.

requestUpdate(input: RibbonUpdaterData): Promise<void>;

Parameters

input

Office.RibbonUpdaterData

Represents the updates to be made to the ribbon. Note that only the changes specified in the input parameter are made.

Returns

Promise<void>

Remarks

Requirement set: RibbonAPI 1.1

Note that this API is only to request an update. The actual UI update to the ribbon is controlled by the Office application and hence the exact timing of the ribbon update (or refresh) cannot be determined by the completion of this API.

For code examples, see Enable and Disable Add-in Commands and Create custom contextual tabs.

Examples

// Office.Tab objects are properties of ribbon updater objects that are passed to the 
// Office.ribbon.requestUpdate method. The following shows how to set the visibility of 
// a custom contextual tab.

async function showDataTab() {
    await Office.ribbon.requestUpdate({
        tabs: [
            {
                id: "CtxTab1",
                visible: true
            }
        ]});
}

// The following does the same thing in TypeScript.

const showDataTab = async () => {
    const myContextualTab: Office.Tab = { id: "CtxTab1", visible: true };
    const ribbonUpdater: Office.RibbonUpdaterData = { tabs: [ myContextualTab ] };
    await Office.ribbon.requestUpdate(ribbonUpdater);
}