what is a custom element, how to use custom elements - Intelligent Media Management

The custom element object CommandBars.Controls is the switch for all custom elements. You can use the Controls method to obtain a collection of elements on a toolbar. This topic describes how to add a custom element, hide a custom element, and add a custom drop-down element.

Overview

In the following example, a custom button and a custom drop-down component are added to the Start tab.

Demonstration
- Before the customization
- After the customization
CommandBarId values
CommandBarId
Location
StartTab
Toolbar > the Start tab
InsertTab
Toolbar > the Insert tab
ReviewTab
Toolbar > the Review tab
PageTab
Toolbar > the Page tab
For more information, see Customizable components.
Syntax
expression.CommandBars(CommandBarId).Controls
expression: an Application object

Example

async function example() {
  await instance.ready();

  const app = instance.Application;
  
  // You can use CommandBars.Controls to obtain a collection of components on the toolbar. You can add new components to the toolbar or customize existing components.
  // Obtain the Start tab for element customization.
  const controls = await app.CommandBars('StartTab').Controls;
  
  // Add a custom button element.
  const controlButton = await controls.Add(1);
  controlButton.Caption = 'Button';

  // Add a custom drop-down element.
  const controlPopup = await controls.Add(10);
  controlPopup.Caption = 'Drop-down list';
}

Add custom elements

Use the Controls.Add() property to add a custom button and a custom drop-down component to the corresponding tab.

Demonstration
- Before the customization
- After the customization
Syntax
expression.CommandBars(CommandBarId).Controls.Add(Type)
expression: an Application object
Parameters
Parameter
Data type
Required
Description
Type
Enum
Yes
The type of the new custom element. Valid values of Enum.MsoControlType:
1 or msoControlButton: a command button.
10 or msoControlPopup: a drop-down list.

Example

async funcion example() {
  await instance.ready();

  const app = instance.Application;

  // Obtain the Start tab for element customization.
  const controls = await app.CommandBars('StartTab').Controls;
  
  // Add a custom button element.
  const controlButton = await controls.Add(1);
  controlButton.Caption = 'Button';

  // Add a custom drop-down list.
  const controlPopup = await controls.Add(10);
  controlPopup.Caption = 'Drop-down list';
}

A single custom element

Obtain and customize a single custom element including customizing the title and the click operation of the element.

Overview

In the following example, a button is added to and deleted from the Start tab.

Demonstration
- Add a button
- Delete a button
Syntax
expression.CommandBars(CommandBarId).Controls.Item(Index)
expression: an Application object
Parameters
Parameter
Data type
Required
Description
Index
Number
Yes
The index of the custom element.

Example

async function example() {
  await instance.ready();

  const app = instance.Application;

  // Obtain the Start tab for element customization.
  const controls = await app.CommandBars('StartTab').Controls;
  
  // Add a custom button.
  const controlButton = await controls.Add(1);
  controlButton.Caption = 'Button';

  // Delete the custom element after 6,000 milliseconds.
  setTimeout(() => {
    controlButton.Delete();
  }, 6000);
}

Set the title

Use the Caption property to set the title of the custom element.

Demonstration
Syntax
expression.CommandBars(CommandBarId).Controls.Add(Type).Caption
expression: an Application object

Example

async function example() {
  await instance.ready();

  const app = instance.Application;

  // Obtain the Start tab for element customization.
  const controls = await app.CommandBars('StartTab').Controls;
  
  // Add a button and set the title to "button".
  const controlButton = await controls.Add(1);
  controlButton.Caption = 'Button';
  
  // Add a drop-down list and set the title to "drop-down list".
  const controlPopup = await controls.Add(10);
  controlPopup.Caption = 'Drop-down list';
}

Delete a custom element

Use the Delete() property to delete a custom element.

Demonstration
- Before deletion
- After deletion
Syntax
expression.CommandBars(CommandBarId).Controls.Add(Type).Delete()
expression: an Application object

Example

async function example() {
  await instance.ready();

  const app = instance.Application;

  // Obtain the Start tab for element customization.
  const controls = await app.CommandBars('StartTab').Controls;
  
  // Add a button and set the title to "button".
  const controlButton = await controls.Add(1);
  controlButton.Caption = 'Button';
  
  // Add a drop-down list and set the title to "drop-down list".
  const controlPopup = await controls.Add(10);
  controlPopup.Caption = 'Drop-down list';

  // Delete the two custom elements after 6,000 milliseconds.
  setTimeout(() => {
    controlButton.Delete();
    controlPopup.Delete();
  }, 6000);
}

Disable a custom element

Use the Enabled property to disable an element.

Demonstration. The button is grayed out.
Syntax
expression.CommandBars(CommandBarId).Controls.Add(Type).Enabled
expression: an Application object

Example

async function example() {
  await instance.ready();

  const app = instance.Application;

  // Obtain the Start tab for element customization.
  const controls = await app.CommandBars('StartTab').Controls;
  
  // Add a button and disable it.
  const controlButton = await controls.Add(1);
  controlButton.Caption = 'Button';
  controlButton.Enabled = false;
  
  // Add a drop-down list and disable it.
  const controlPopup = await controls.Add(10);
  controlPopup.Caption = 'Drop-down list';
  controlPopup.Enabled = false;
}

Click a custom element

Use the Execute() property to click a custom element. You can listen to the click events of a custom element to check whether it is clicked. For more information, see Listen to the click events of a custom element.

Syntax
expression.CommandBars(CommandBarId).Controls.Add(Type).Execute()
expression: an Application object

Example

async function example() {
  await instance.ready();

  const app = instance.Application;

  // Obtain the Start tab for element customization.
  const controls = await app.CommandBars('StartTab').Controls;
  
  // Add a button and listen to the click events.
  const controlButton = await controls.Add(1);
  controlButton.Caption = 'Button';
  controlButton.OnAction = () => console.log('Button clicked');
  
  // Add a drop-down list and listen to the click events.
  const controlPopup = await controls.Add(10);
  controlPopup.Caption = 'Drop-down list';
  controlPopup.OnAction = () => console.log('Drop-down list clicked');

  // Click the element after 6,000 milliseconds.
  setTimeout( async () => {
    await controlButton.Execute();
    await controlPopup.Execute();
  }, 6000);
}

Listen to the click events of a custom element

After you start listening to the click events of an element, you can view the corresponding information in the console if the component is clicked. You can use this information for your business.

Syntax
expression.CommandBars(CommandBarId).Controls.Add(Type).OnAction() = Function
expression: an Application object

Example

async function example() {
  await instance.ready();

  const app = instance.Application;

  // Obtain the Start tab for element customization.
  const controls = await app.CommandBars('StartTab').Controls;
  
  // Add a button and listen to the click events.
  const controlButton = await controls.Add(1);
  controlButton.Caption = 'Button';
  controlButton.OnAction = () => console.log('Button clicked');
  
  // Add a drop-down list and listen to the click events.
  const controlPopup = await controls.Add(10);
  controlPopup.Caption = 'Drop-down list';
  controlPopup.OnAction = () => console.log('Drop-down list clicked');
}

Customize the icon of an element

Use the Picture property to customize the icon of an element. In the following example, the icon of the element is set by using the Base64 encoding format.

Demonstration
Syntax
expression.CommandBars(CommandBarId).Controls.Add(Type).Picture
expression: an Application object

Example

async function example() {
  await instance.ready();

  const app = instance.Application;

  // Obtain the Start tab for element customization.
  const controls = await app.CommandBars('StartTab').Controls;
  
  // Add a button and set its icon.
  const controlButton = await controls.Add(1);
  controlButton.Caption = 'Button';
  controlButton.Picture = 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48ZyBmaWxsPSIjM0Q0NzU3IiBmaWxsLXJ1bGU9ImV2ZW5vZGQiPjxwYXRoIGQ9Ik04LjIxMyAxM0g2LjhsNi42MzYtNi42MzYtNC4yNDMtNC4yNDMtNy4wNyA3LjA3MUw1LjkyOCAxM0g0LjUxNUwxLjA2IDkuNTQ2YS41LjUgMCAwIDEgMC0uNzA3TDguODM5IDEuMDZhLjUuNSAwIDAgMSAuNzA3IDBsNC45NSA0Ljk1YS41LjUgMCAwIDEgMCAuNzA3TDguMjEzIDEzeiIgZmlsbC1ydWxlPSJub256ZXJvIi8+PHBhdGggZD0iTTQuNTM2IDYuMzY0bDQuOTUgNC45NS0uNzA3LjcwNy00Ljk1LTQuOTV6TTQuNTIxIDEzaDEwLjAzdjFINS40OTZ6Ii8+PC9nPjwvc3ZnPg==';
  
  // Add a drop-down list and set its icon.
  const controlPopup = await controls.Add(10);
  controlPopup.Caption = 'Drop-down list';
  controlPopup.Picture = 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48ZyBmaWxsPSJub25lIiBmaWxsLXJ1bGU9ImV2ZW5vZGQiPjxwYXRoIGQ9Ik03LjUgMnYyLjVINGEuNS41IDAgMCAwLS41LjV2MmEuNS41IDAgMCAwIC41LjVoOWEuNS41IDAgMCAwIC41LS41VjVhLjUuNSAwIDAgMC0uNS0uNUg5LjVWMmEuNS41IDAgMCAwLS41LS41SDhhLjUuNSAwIDAgMC0uNS41eiIgc3Ryb2tlPSIjM0Q0NzU3Ii8+PHBhdGggZmlsbD0iIzNENDc1NyIgZD0iTTEzIDdoMXY0aC0xeiIvPjxwYXRoIGQ9Ik0xMSAxM2EyIDIgMCAwIDAgMi0yVjguNzY0QTMgMyAwIDEgMSA4Ljc2NCAxM0gxMXoiIGZpbGw9IiMzRDQ3NTciLz48cGF0aCBmaWxsPSIjM0Q0NzU3IiBkPSJNMSAxM2gxMHYxSDF6Ii8+PHBhdGggZD0iTTEgMTNhMiAyIDAgMCAwIDItMlY4Ljc2NEEzIDMgMCAwIDEgMSAxNHYtMXoiIGZpbGw9IiMzRDQ3NTciLz48cGF0aCBmaWxsPSIjM0Q0NzU3IiBkPSJNMyA3aDF2NEgzeiIvPjwvZz48L3N2Zz4=';
}

Set focus on a custom element

Use the SetFocus property to move the cursor to the location of a custom element.

Demonstration
Syntax
expression.CommandBars(CommandBarId).Controls.Add(Type).SetFocus()
expression: an Application object

Example

async function example() {
  await instance.ready();

  const app = instance.Application;

  // Obtain the Start tab for element customization.
  const controls = await app.CommandBars('StartTab').Controls;
  
  // Add a button and set focus on it.
  const controlButton = await controls.Add(1);
  controlButton.Caption = 'Button';
  await controlButton.SetFocus();
  
  // Add a drop-down list and set focus on it.
  const controlPopup = await controls.Add(10);
  controlPopup.Caption = 'Drop-down list';
  await controlPopup.SetFocus();
}

Hide a custom element

Use the Visible property to hide or show an element.

Demonstration
- Show
- Hide
Syntax
expression.CommandBars(CommandBarId).Controls.Add(Type).Visible
expression: an Application object

Example

async function example() {
  await instance.ready();

  const app = instance.Application;

  // Obtain the Start tab for element customization.
  const controls = await app.CommandBars('StartTab').Controls;
  
  // Add a custom button.
  const controlButton = await controls.Add(1);
  controlButton.Caption = 'Button';

  // Add a custom drop-down list.
  const controlPopup = await controls.Add(10);
  controlPopup.Caption = 'Drop-down list';

  // Hide the custom elements after 6,000 milliseconds.
  setTimeout(() => {
    controlButton.Visible = false;
    controlPopup.Visible = false;
  }, 6000);
}

Customize the tooltip text of an element

Use the TooltipText property to set the tooltip text of a custom element.

Demonstration
- Button
- Drop-down list
Syntax
expression.CommandBars(CommandBarId).Controls.Add(Type).TooltipText
expression: an Application object

Example

async function example() {
  await instance.ready();

  const app = instance.Application;

  // Obtain the Start tab for element customization.
  const controls = await app.CommandBars('StartTab').Controls;
  
  // Add a button and set the tooltip text.
  const controlButton = await controls.Add(1);
  controlButton.Caption = 'Button';
  controlButton.TooltipText = 'Tooltip--button';

  // Add a drop-down list and set the tooltip text.
  const controlPopup = await controls.Add(10);
  controlPopup.Caption = 'Drop-down list';
  controlPopup.TooltipText = 'Tooltip-drop-down list';
}

Customize an element on the mobile toolbar

Use the Controls property to control attributes of the element, such as the caption text, icon, and click.

This section shows how to add a button to the bottom toolbar.

Add a custom element
Syntax
expression.CommandBars(CommandBarId).Controls.Add(Index)
expression: an Application object
Parameters

Parameter	Data type	Required	Description
Index	Number	Yes	To add a button to the mobile toolbar, set the index to 20.

Example

async function example() {
  await instance.ready();

  const app = instance.Application;

  const controls = window.instance.Application.CommandBars.Item('WriterHoverToolbars').Controls;
    // Add a custom button.
  const controlButton = await controls.Add(20);
  controlButton.Caption = 'Button'; // Specify the caption.

  controlButton.Picture = 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48ZyBmaWxsPSIjM0Q0NzU3IiBmaWxsLXJ1bGU9ImV2ZW5vZGQiPjxwYXRoIGQ9Ik04LjIxMyAxM0g2LjhsNi42MzYtNi42MzYtNC4yNDMtNC4yNDMtNy4wNyA3LjA3MUw1LjkyOCAxM0g0LjUxNUwxLjA2IDkuNTQ2YS41LjUgMCAwIDEgMC0uNzA3TDguODM5IDEuMDZhLjUuNSAwIDAgMSAuNzA3IDBsNC45NSA0Ljk1YS41LjUgMCAwIDEgMCAuNzA3TDguMjEzIDEzeiIgZmlsbC1ydWxlPSJub256ZXJvIi8+PHBhdGggZD0iTTQuNTM2IDYuMzY0bDQuOTUgNC45NS0uNzA3LjcwNy00Ljk1LTQuOTV6TTQuNTIxIDEzaDEwLjAzdjFINS40OTZ6Ii8+PC9nPjwvc3ZnPg==';
  
}

Specify a display style for the entire mobile bottom toolbar

You can specify a display style for the entire mobile bottom toolbar: only text visible, only icons visible, or icons and text visible.

Make only text visible
Make only icons visible
Syntax
expression.CommandBars.Item(CommandBarId).CommandBarMode(WdCommandBar)
expressions: an Application object. For more information about supported fields, see Enum.WdCommandBar

Example

async function example() {
  await instance.ready();

  const app = instance.Application;

  const controls = window.instance.Application.CommandBars.Item('WriterHoverToolbars').Controls;

  await commandBar.CommandBarMode(1);
  
}

Add a custom first-level or second-level item to Revision Settings

Add a custom first-level item to Revision Settings
Add a custom second-level item to Revision Settings
Syntax
expression.CommandBars(CommandBarId).Controls.Add(10)
expression: an Application object

Examples

Add a first-level item

async function example() {
    await instance.ready();

    const app = instance.Application;

    const controls = await app.CommandBars('RevisionSetting').Controls;

    const button = await controls.Add(10);
    // Specify the caption text.
    button.Caption = 'First-level Item';
    // Add a click event.
    button.OnAction = () => console.log('A click on first-level item');
    // Set the Enable attribute.
    button.Enable = false;
}

Add a second-level item

async function example() {
    await instance.ready();

    const app = instance.Application;

    const controls = app.CommandBars('RevisionSetting').Controls;
    const button = await controls.Add(10);
    button.Caption = 'First-level Item';
    const popupControls = await button.Controls;
    // Add a second-level item.
    const button1 = await popupControls.Add(1);
    // Specify the caption text of the second-level item.
    button1.Caption = 'Second-level Item';
    // Add a click event.
    button1.OnAction = () => console.log('A click on the second-level item');
}

Customize the elements of a drop-down list

If you set Enum to 10 in CommandBars(CommandBarId).Controls.Add(), you can add a drop-down list. You need to configure the drop-down list before you can use it on the toolbar. For example, Option 1 is added to the drop-down list in the following figure. For information about how to specify option settings, see A single custom element. 下拉定制

Add a custom element to a drop-down list

Use the Add() property to add a new custom element to the drop-down list.

Syntax
expression.CommandBars(CommandBarId).Controls.Add(10).Controls.Add()
expression: an Application object.

Example

async function example() {
  await instance.ready();

  const app = instance.Application;
  
  // Obtain the Start tab for element customization.
  const controls = await app.CommandBars('StartTab').Controls;

  // Add a drop-down list.
  const control = await controls.Add(10);
  control.Caption = 'Drop-down list';
  
  // Obtain the drop-down box.
  const popupControls = await control.Controls;

  // Add a custom element to the drop-down list.
  const button = await popupControls.Add(1);
  button.Caption = 'Drop-down button 1';
}

Set a single custom element of the drop-down list

Syntax
expression.CommandBars(CommandBarId).Controls.Add(10).Controls.Item(Index)
expression: an Application object.
Parameters
Parameter
Data type
Required
Description
Index
Number
Yes
The index of the custom element of the drop-down list.

Example

//@file=base.docx
async function example() {
  await instance.ready();

  const app = instance.Application;
  
  // Obtain the Start tab for element customization.
  const controls = await app.CommandBars('StartTab').Controls;

  // Add a drop-down list.
  const control = await controls.Add(10);
  control.Caption = 'Drop-down list';
  
  // Obtain the drop-down list.
  const popupControls = control.Controls;

  // Add an element to the drop-down list.
  const button = popupControls.Add(1);
  button.Caption = 'Drop-down button 1';

  // Obtain the first custom element of the drop-down list.
  const item1 = await popupControls.Item(1);
  item1.Caption = 'Modify the drop-down button';
}

CommandBarId	Location
StartTab	Toolbar > the Start tab
InsertTab	Toolbar > the Insert tab
ReviewTab	Toolbar > the Review tab
PageTab	Toolbar > the Page tab