univer-plugin-dev

# Univer Plugin Development Guide for building custom plugins that extend Univer's functionality. > **Compatibility**: This skill is written for Univer `v0.21.x`. Core plugin patterns (lifecycle, DI, commands) remain stable, but specific service tokens and facade classes may shift. Prefer the user's existing codebase patterns when they differ from examples here. ## Quick Start ### Scaffold a new plugin Use the bundled script to generate a minimal plugin skeleton: ```bash # If installed to ~/.codex/skills/ npx tsx ~/.codex/skills/univer-plugin-dev/scripts/scaffold-plugin.ts my-plugin --path ./src/plugins # Or from this repo directly npx tsx ~/univer-sdk-skills/skills/univer-plugin-dev/scripts/scaffold-plugin.ts my-plugin --path ./src/plugins ``` This creates: ``` my-plugin/ ├── src/ │ ├── index.ts │ ├── plugin.ts │ ├── commands/ │ │ └── commands.my-command.ts │ ├── controllers/ │ │ └── my-menu.controller.ts │ └── facade/ │ └── f-univer.ts ├── package.json └── tsconfig.json ``` ### Register the plugin in your app ```ts import { MyPlugin } from './plugins/my-plugin/src'; import './plugins/my-plugin/src/facade/f-univer'; // side-effect import for Facade extension univer.registerPlugin(MyPlugin); ``` ## Core Concepts ### Plugin Lifecycle Plugins inherit from `Plugin` and override lifecycle hooks: | Hook | When | What to do | |------|------|------------| | `onStarting()` | Plugin mounted, no unit yet | Register commands, services, menus, shortcuts | | `onReady()` | Business unit created | Access workbook/doc instance | | `onRendered()` | UI rendered | DOM-dependent initialization | | `onSteady()` | Everything stable | Background tasks | Always use `disposeWithMe()` to register disposable resources so they auto-cleanup when the plugin is destroyed. ### Command System Three command types: - **COMMAND** — Business entry point. Orchestrates mutations and operations. Supports undo/redo if you manually push to `IUndoRedoService`. - **MUTATION** — Atomic data change. Persisted to snapshot. Automatically undoable. - **OPERATION** — UI state change. Not persisted. Not undoable. See `references/command-system.md` for full examples of each type and undo/redo construction. ### Dependency Injection Univer uses a custom DI container (`Injector`). Services are retrieved by: ```ts // Constructor injection @Inject(IMenuManagerService) private readonly _menuService: IMenuManagerService // Accessor injection (in command handlers) const service = accessor.get(IMenuManagerService); ``` Common service tokens: - `ICommandService` — register/execute commands - `IMenuManagerService` — add menus/toolbar items - `IShortcutService` — register keyboard shortcuts - `IContextMenuService` — context menus - `ComponentManager` — register React components/icons - `IUniverInstanceService` — get current workbook/doc/slide - `IUndoRedoService` — push undo/redo entries ### Facade Extension Extend Facade classes to expose plugin capabilities to end users: ```ts import { FWorksheet } from '@univerjs/sheets/facade'; class FWorksheetMyMixin extends FWorksheet { myMethod(): this { // implementation return this; } } FWorksheet.extend(FWorksheetMyMixin); declare module '@univerjs/sheets/facade' { interface FWorksheet extends FWorksheetMyMixin {} } ``` ## Common Tasks For full examples (submenus, context menus, Range Popup, component replacement, complete toolbar+command+shortcut pipeline), see `references/ui-customization.md`. ### Add a Toolbar Button ```ts this._menuManagerService.mergeMenu({ [RibbonOthersGroup.OTHERS]: { ['my-button']: { order: 10, menuItemFactory: () => ({ id: 'my-button', title: 'My Button', type: MenuItemType.BUTTON, }), }, }, }); ``` ### Register a Command ```ts const MyCommand: ICommand = { id: 'my.command.id', type: CommandType.COMMAND, handler: (accessor) => { // business logic return true; }, }; this._commandService.registerCommand(MyCommand); ``` ### Extend Facade ```ts class FWorksheetMyMixin extends FWorksheet { myMethod(): this { return this; } } FWorksheet.extend(FWorksheetMyMixin); declare module '@univerjs/sheets/facade' { interface FWorksheet extends FWorksheetMyMixin {} } ``` ## References - **Plugin architecture**: `references/plugin-architecture.md` — lifecycle, DI, service registration, controller pattern - **Command system**: `references/command-system.md` — COMMAND / MUTATION / OPERATION, undo/redo, mutation factories, custom mutations - **Facade extension**: `references/facade-extension.md` — extend FUniver, FWorkbook, FWorksheet, FRange, multiple extensions merge strategy - **UI customization**: `references/ui-customization.md` — menus, submenus, shortcuts, context menus, popups, component replacement - **Event system**: `references/event-system.md` — events, hooks, custom events, RxJS streams Also see `univer-integrate` skill for: - Custom formula functions (`univer-integrate` skill) - Permissions (`univer-integrate` skill) - Network layer (`univer-integrate` skill) ## Scripts - **Scaffold**: `scripts/scaffold-plugin.ts` — generate a new plugin skeleton