🎉 v0.5.0 版本已发布。查看详情 →
指南Univer Sheets进阶使用自定义 UI

自定义 UI

新增菜单项

在 Univer 中，无论是顶部的工具栏菜单还是右键菜单，都可以通过编写插件来实现扩展。下面将介绍如何使用依赖注入系统中的 IMenuManagerService 来注册菜单项。

1. 插件环境

确保你对插件机制有所了解，并且已经通过 @univerjs/create-cli 新建了一个插件。

首先构造一个 controller 类，用于注册菜单项命令、菜单项图标、菜单项配置。

// src/plugin/controllers/custom-menu.controller.ts
export class CustomMenuController extends Disposable {
  constructor(
    @Inject(Injector) private readonly _injector: Injector,
    @ICommandService private readonly _commandService: ICommandService,
    @IMenuManagerService private readonly _menuManagerService: IMenuManagerService,
    @Inject(ComponentManager) private readonly _componentManager: ComponentManager,
  ) {
    super();
 
    this._initCommands();
    this._registerComponents();
    this._initMenus();
  }
 
  /**
   * register commands
  */
  private _initCommands(): void { }
 
  /**
   * register icon components
  */
  private _registerComponents(): void { }
 
  /**
   * register menu items
  */
  private _initMenus(): void { }
}

将这个 controller 注册到插件中

// src/plugin/plugin.ts
const SHEET_CUSTOM_MENU_PLUGIN = 'SHEET_CUSTOM_MENU_PLUGIN';
 
export class UniverSheetsCustomMenuPlugin extends Plugin {
  static override type = UniverInstanceType.UNIVER_SHEET;
  static override pluginName = SHEET_CUSTOM_MENU_PLUGIN;
 
  constructor(
    @Inject(Injector) protected readonly _injector: Injector
  ) {
    super();
  }
 
  override onStarting(injector: Injector): void {
    ([
      [CustomMenuController],
    ] as Dependency[]).forEach((d) => injector.add(d));
  }
}

2. 菜单项命令

注册菜单之前，需要构造一个 Command，这个 Command 会在菜单被点击时执行。

// src/plugin/commands/operations/single-button.operation.ts
export const SingleButtonOperation: ICommand = {
  id: 'custom-menu.operation.single-button',
  type: CommandType.OPERATION,
  handler: async (accessor: IAccessor) => {
    alert('Single button operation');
    return true;
  },
};

将这个 Command 注册到 ICommandService

// src/plugin/controllers/custom-menu.controller.ts
private _initCommands(): void {
  [
    SingleButtonOperation
  ].forEach((c) => {
    this.disposeWithMe(this._commandService.registerCommand(c));
  });
}

3. 菜单项图标

如果你的菜单项需要图标，也需要提前注册图标。

先构造一个图标 tsx 组件

// src/plugin/components/button-icon/ButtonIcon.tsx
export function ButtonIcon() {
  return (
    <svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24">
      <path fill="currentColor" d="M12 2c5.523 0 10 4.477 10 10s-4.477 10-10 10S2 17.523 2 12S6.477 2 12 2m.16 14a6.981 6.981 0 0 0-5.147 2.256A7.966 7.966 0 0 0 12 20a7.97 7.97 0 0 0 5.167-1.892A6.979 6.979 0 0 0 12.16 16M12 4a8 8 0 0 0-6.384 12.821A8.975 8.975 0 0 1 12.16 14a8.972 8.972 0 0 1 6.362 2.634A8 8 0 0 0 12 4m0 1a4 4 0 1 1 0 8a4 4 0 0 1 0-8m0 2a2 2 0 1 0 0 4a2 2 0 0 0 0-4" />
    </svg>
  );
};

将这个图标注册到 ComponentManager

// src/plugin/controllers/custom-menu.controller.ts
private _registerComponents(): void {
  this.disposeWithMe(this._componentManager.register("ButtonIcon", ButtonIcon));
}

4. 菜单项国际化

如果你的菜单项需要国际化，需要提前添加好国际化资源。

// src/plugin/locale/zh-CN.ts
export default {
  customMenu: {
    button: '按钮',
    singleButton: '单个按钮',
  },
};
// src/plugin/locale/en-US.ts
export default {
  customMenu: {
    button: 'Button',
    singleButton: 'Single button',
  },
};

将这个国际化资源注册到 ILocaleService

// src/plugin/plugin.ts
export class UniverSheetsCustomMenuPlugin extends Plugin {
  static override type = UniverInstanceType.UNIVER_SHEET;
  static override pluginName = SHEET_CUSTOM_MENU_PLUGIN;
 
  constructor(
    @Inject(Injector) protected readonly _injector: Injector,
    @Inject(LocaleService) private readonly _localeService: LocaleService
  ) {
    super();
 
    this._localeService.load({
      zhCN,
      enUS
    });
  }
}

5. 菜单项配置

定义一个菜单项配置工厂函数，返回一个菜单项配置对象。

export function CustomMenuItemSingleButtonFactory(): IMenuButtonItem<string> {
  return {
    // 绑定 Command id，单击该按钮将触发该命令
    id: SingleButtonOperation.id,
    // 菜单项的类型，在本例中，它是一个按钮
    type: MenuItemType.BUTTON,
    // 按钮的图标，需要在 ComponentManager 中注册
    icon: 'ButtonIcon',
    // 按钮的提示，优先匹配国际化，如果没有匹配到，将显示原始字符串
    tooltip: 'customMenu.singleButton',
    // 按钮的标题，优先匹配国际化，如果没有匹配到，将显示原始字符串
    title: 'customMenu.button',
  };
}

将这些菜单项构造成成 Schema 并通过 IMenuManagerService 合并到菜单中。

// src/plugin/controllers/custom-menu.controller.ts
private _initMenus(): void {
  this._menuManagerService.mergeMenu({
    [RibbonStartGroup.OTHERS]: {
      [SingleButtonOperation.id]: {
        order: 0,
        menuItemFactory: CustomMenuItemSingleButtonFactory,
      },
    },
    [ContextMenuPosition.MAIN_AREA]: {
      [ContextMenuGroup.OTHERS]: {
        [SingleButtonOperation.id]: {
          order: 0,
          menuItemFactory: CustomMenuItemSingleButtonFactory,
        },
      },
    },
  })
}

6. 下拉列表

除了添加单个按钮的菜单项，还可以添加一个下拉菜单项，具体实现方式类似，只在构造菜单 Schema 时有所区别：

  • 将菜单项配置返回类型 IMenuButtonItem<string> 替换为 IMenuSelectorItem<string>
  • 将菜单项类型 MenuItemType.BUTTON 替换为 MenuItemType.SUBITEMS
  • 下拉列表主按钮需要自定义一个 id，作为下拉列表的唯一标识，用于关联下拉列表的子菜单项，子菜单项的 positions 需要填写主按钮的 id
// src/plugin/controllers/menu/dropdown-list.menu.ts
const CUSTOM_MENU_DROPDOWN_LIST_OPERATION_ID = 'custom-menu.operation.dropdown-list';
 
export function CustomMenuItemDropdownListMainButtonFactory(): IMenuSelectorItem<string> {
  return {
    id: CUSTOM_MENU_DROPDOWN_LIST_OPERATION_ID,
    type: MenuItemType.SUBITEMS,
    icon: 'MainButtonIcon',
    tooltip: 'customMenu.dropdownList',
    title: 'customMenu.dropdown',
  };
}
 
export function CustomMenuItemDropdownListFirstItemFactory(): IMenuButtonItem<string> {
  return {
    id: DropdownListFirstItemOperation.id,
    type: MenuItemType.BUTTON,
    title: 'customMenu.itemOne',
    icon: 'ItemIcon',
  };
}

构造菜单 Schema：

// src/plugin/controllers/custom-menu.controller.ts
private _initMenus(): void {
  this._menuManagerService.mergeMenu({
    [ContextMenuPosition.MAIN_AREA]: {
      [ContextMenuGroup.OTHERS]: {
        [CUSTOM_MENU_DROPDOWN_LIST_OPERATION_ID]: {
          order: 0,
          menuItemFactory: CustomMenuItemDropdownListMainButtonFactory,
          [DropdownListFirstItemOperation.id]: {
            order: 0,
            menuItemFactory: CustomMenuItemDropdownListFirstItemFactory,
          }
        }
      }
    }
  })
}

更多细节请参考 自定义菜单 Playground。

覆盖内置业务组件

Univer 中部分业务组件是可以被覆盖的，例如右侧的菜单面板、弹窗、图标等。这些组件在 Univer 的内部经由 ComponentManager 进行注册，你可以通过注册同名的组件来覆盖默认的组件。

export class CustomMenuController extends Disposable {
  constructor(
+   @Inject(ComponentManager) private readonly _componentManager: ComponentManager,
  ) {
    super();
 
    // 替换默认的 BoldSingle 图标
+   this._componentManager.register('BoldSingle', YourBoldIconComponent);
  }
}

定制菜单项（隐藏菜单项）

在 Univer 中定制或隐藏菜单项是一种常见需求，我们为所有包含了菜单项的插件提供了配置项。只要知道菜单项对应的命令 ID，你就可以非常轻松地通过配置项来实现这一需求。

例如，隐藏加粗的菜单项：

import { UniverSheetsUIPlugin, SetRangeBoldCommand } from '@univerjs/sheets-ui';
 
univer.registerPlugin(UniverSheetsUIPlugin, {
  menu: {
    [SetRangeBoldCommand.id]: {
      hidden: true,
    },
  },
});

关于如何获取命令 ID，可以参考教程如何查找命令 ID。

扩展 Canvas扩展命令