@univerjs/ui 包深度解析：Univer 共享 UI 框架、工作台服务与 Facade UI API 完全指南

univerjs/ui 包深度解析Univer 共享 UI 框架、工作台服务与 Facade UI API 完全指南【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univeruniverjs/ui是 Univer 全栈办公框架表格 / 文档 / 演示文稿的共享应用 UI 层它为所有业务 UI 插件如univerjs/sheets-ui、univerjs/docs-ui提供工作台Workbench渲染、菜单基础设施、对话框、剪贴板、快捷键等通用能力。本文以该包的官方 README 为骨架结合仓库源码逐层拆解其安装配置、插件注册、内置服务与 Facade UI API读完即可在真实项目中正确集成并扩展 Univer 的界面体系。包定位一个包四类能力univerjs/ui在 Univer 插件体系中扮演壳的角色——它自身不实现任何业务编辑能力而是提供所有业务插件共享的应用框架。根据官方 README 的说明它包含四大能力共享应用 UI 框架Shared Application UI Framework即工作台Workbench负责把头部header、工具栏toolbar、Ribbon、侧边栏、状态栏等 UI 部件组装成一个完整的编辑界面工作台服务Workbench Services围绕工作台提供布局、部件显隐、主题切换等运行时服务菜单基础设施Menu Infrastructure统一的菜单注册、排序、分组与渲染体系供各业务插件注入自己的菜单项对话框与剪贴板服务Dialogs, Clipboard Services桌面端对话框、确认框、侧边栏、消息通知以及浏览器剪贴板读写能力。其包级概览如表所示PackageUMD globalCSSLocalesFacade entryuniverjs/uiUniverUiYesYesYes该包同时提供独立 CSS、多语言文案Locale以及独立的 Facade 入口univerjs/ui/facade在 package.json 的exports字段中分别映射为./lib/es/index.css、./locale/*与./facade。安装包管理器与版本约束安装命令与官方 README 一致支持 pnpm 与 npm 两种方式pnpm add univerjs/ui # or npm install univerjs/ui安装时有两点值得注意版本一致性官方文档明确要求保持所有univerjs/*包处于同一版本Keep alluniverjs/*packages on the same version。Univer 采用 monorepo 同步发版策略混用不同版本可能导致依赖服务或类型定义错位。peer 依赖从 package.json 可以看到univerjs/ui声明了react、react-dom支持^16.9.0至^19.0.0以及rxjs 7.0.0作为 peerDependencies宿主项目需自行提供这些运行时依赖。其自身依赖则包括univerjs/core、univerjs/design、univerjs/engine-render、univerjs/icons与依赖注入框架wendellhu/redi。快速上手三步完成 UI 层接入官方 README 给出的最小使用示例为import univerjs/ui/lib/index.css; import EnUS from univerjs/ui/locale/en-US; import { UniverUIPlugin } from univerjs/ui; univer.registerPlugin(UniverUIPlugin); // Merge EnUS into your Univer locale map when this package contributes UI text.拆解为三个步骤引入样式import univerjs/ui/lib/index.css加载包内置的全局样式源码入口 src/index.ts 中通过import ./global.css引入。合并语言包该包贡献了 UI 文案官方注释建议当此包贡献 UI 文本时将EnUS合并进你的 Univer locale map。仓库 src/locale 目录下共提供 20 种语言en-US、zh-CN、zh-TW、zh-HK、ja-JP、ko-KR、de-DE、fr-FR、es-ES、pt-BR、ru-RU、ar-SA、it-IT、vi-VN、pl-PL、id-ID、fa-IR、ca-ES、sk-SK 等可直接按需导入。注册插件univer.registerPlugin(UniverUIPlugin)将 UI 层挂载到 Univer 实例上。在真实项目中插件通常携带配置项注册例如仓库示例 examples/src/sheets/main.tsuniver.registerPlugin(UniverUIPlugin, { container: app, ribbonType: grid, customFontFamily: { list: [ { value: PingFang SC, label: 苹方简, category: sans-serif }, { value: Helvetica Neue, label: Helvetica Neue, category: sans-serif }, ], // override: true, }, });插件配置详解IUniverUIConfig 与工作台选项UniverUIPlugin的构造参数类型为PartialIUniverUIConfig其完整定义位于 src/config/config.ts配置项类型说明containerstring \| HTMLElement工作台挂载的 DOM 容器传入元素 id 或元素本身headerboolean是否显示头部栏默认显示toolbarboolean是否显示工具栏ribbonTypecollapsed \| simple \| classic \| gridRibbon 展示类型grid为网格化布局customFontFamilyIFontConfig[] \| { override?: boolean; list: IFontConfig[] }追加自定义字体列表传{ override: true }可覆盖内置字体表footerboolean是否显示底部状态栏contextMenuboolean是否启用右键菜单headerMenuboolean是否显示头部菜单disableAutoFocustrue禁用 Univer 启动时的自动聚焦overrideDependencyOverride覆盖包内依赖注入绑定高级用法menuMenuConfig注入或覆盖菜单配置popupRootIdstring弹出层Popup Portal的根元素 id默认自动生成avatarFallbackstring用户头像的兜底图以上配置在插件构造时通过merge合并到默认配置上其中menu会以merge: true的方式写入IConfigService其余部分以ui.config为 key 存储见 src/plugin.ts。如果设置了disableAutoFocus插件会把DISABLE_AUTO_FOCUS上下文值写入IContextService。桌面与移动双插件UniverUIPlugin 与 UniverMobileUIPlugin官方 README 明确导出了两个插件类UniverUIPlugin—— 桌面端DesktopUI 插件UniverMobileUIPlugin—— 移动端MobileUI 插件。两者在源码中结构高度一致见 src/mobile-plugin.ts插件名分别为UNIVER_UI_PLUGIN与UNIVER_MOBILE_UI_PLUGIN都通过DependentOn(UniverRenderEnginePlugin)声明对渲染引擎的依赖即必须先注册univerjs/engine-render的插件关键差异在于注入的控制器不同——桌面版使用DesktopUIController移动版使用MobileUIController从而适配不同终端的交互形态。两个插件均实现了 Univer 插件的三阶段生命周期onStarting()通过registerDependencies注册全部服务绑定并touchDependencies立即激活ComponentsController、IUIController、ErrorControlleronReady()激活SharedController与FeatureSearchControlleronSteady()激活ShortcutPanelController。菜单基础设施从 schema 到服务的完整链路univerjs/ui的菜单体系由services/menu目录下的若干服务与类型支撑并在 src/index.ts 导出UIMenuSchema。相关核心导出包括类型体系IMenuItem、IMenuButtonItem、IMenuSelectorItem、IDisplayMenuItem、IMenuItemFactory、MenuConfig、MenuItemConfig等src/index.ts服务IMenuManagerService/MenuManagerService负责菜单项的注册、分组与排序src/index.ts位置常量MenuManagerPosition、RibbonPosition、RibbonStartGroup、RibbonInsertGroup、RibbonFormulasGroup、RibbonViewGroup、RibbonOthersGroup、ContextMenuPosition等src/index.ts业务插件通过它们把菜单插入到 Ribbon、右键菜单或工具栏的指定分组菜单项类型MenuItemType枚举src/index.ts。此外包内还提供mergeMenuConfigs工具函数用于合并菜单配置src/index.ts以及getMenuHiddenObservable/getHeaderFooterMenuHiddenObservable用于监听菜单显隐变化src/index.ts。服务层全景剪贴板、对话框、弹层与协作 UI插件在onStarting阶段集中注册了大量服务详见 src/plugin.ts按职责可划分为几组服务接口说明剪贴板IClipboardInterfaceService→BrowserClipboardServicelazy浏览器剪贴板读写支持纯文本、HTML、PNG/SVG/JPEG/WebP/BMP 等 MIME 类型常量如PLAIN_TEXT_CLIPBOARD_MIME_TYPE、HTML_CLIPBOARD_MIME_TYPE均从 src/index.ts 导出对话框IDialogService→DesktopDialogServicelazy桌面对话框的打开与关闭确认框IConfirmService→DesktopConfirmServicelazy确认弹窗侧边栏ISidebarService→DesktopSidebarServicelazy侧边栏面板消息IMessageService→DesktopMessageServicelazy轻量消息提示通知INotificationService→DesktopNotificationServicelazy通知横幅画廊IGalleryService→DesktopGalleryServicelazy图片画廊预览本地存储ILocalStorageService→DesktopLocalStorageServicelazylocalStorage 封装工作台IWorkbenchService→WorkbenchService工作台管理布局ILayoutService→DesktopLayoutService布局状态部件IUIPartsService→UIPartsService内置 UI 部件注册与显隐控制上下文菜单IContextMenuService/IContextMenuHostService右键菜单快捷键IShortcutService→ShortcutService快捷键注册与分发平台IPlatformService→PlatformService平台环境探测字体IFontService→FontService字体表管理关闭前IBeforeCloseService→DesktopBeforeCloseService页面关闭前的拦截协作IUnitPresenceUIAdapterRegistry协作者在线状态 UI 适配器注册表RibbonIRibbonService/IRibbonOverrideServiceRibbon 渲染与覆盖运行时作用域IUIRuntimeScopeServiceUI 运行时作用域其中相当一部分服务以lazy: true方式绑定如剪贴板、对话框、消息、通知等意味着只有在首次被注入时才实例化从而降低启动开销。剪贴板相关命令CopyCommand、CutCommand、PasteCommand与SheetPasteShortKeyCommandName也从 src/index.ts 导出供业务层直接触发复制粘贴流程。Facade UI API用一行代码操作界面univerjs/ui提供了独立的 Facade 入口univerjs/ui/facade将 UI 能力暴露给FUniverAPI 对象使用时需先导入import univerjs/ui/facade;该入口src/facade/index.ts通过FUniver.extend(FUniverUIMixin)混入能力实现位于 src/facade/f-univer.ts。常用方法示例// 获取快捷键控制器启用 / 禁用快捷键 const fShortcut univerAPI.getShortcut(); fShortcut.disableShortcut(); fShortcut.enableShortcut(); // 复制 / 粘贴当前选中内容基于剪贴板命令 await univerAPI.copy(); await univerAPI.paste(); // 动态创建菜单并插入到 Ribbon 的指定分组 univerAPI.createMenu({ id: custom-menu, title: Custom Menu, action: () console.log(Custom Menu Clicked), }).appendTo(ribbon.start.others); // 打开侧边栏与对话框 univerAPI.openSidebar({ id: sidebar-1, header: { label: Header }, children: { label: Content } }); univerAPI.openDialog({ id: dialog-1, title: { label: Title }, children: { label: Content } }); // 控制内置 UI 部件显隐 univerAPI.setUIVisible(univerAPI.Enum.BuiltInUIPart.HEADER, false); univerAPI.isUIVisible(univerAPI.Enum.BuiltInUIPart.HEADER); // false // 注册自定义组件与 UI 部件 univerAPI.registerComponent(custom-menu-icon, SmileIcon); univerAPI.registerUIPart(univerAPI.Enum.BuiltInUIPart.CUSTOM_HEADER, () React.createElement(h1, null, Custom Header)); // 追加自定义字体、切换当前渲染单元 univerAPI.addFonts([{ value: CustomFont, label: Custom Font, category: sans-serif }]); univerAPI.setCurrent(unit2);从实现上看这些 API 都是对包内服务的薄封装copy()/paste()执行CopyCommand/PasteCommandsrc/facade/f-univer.tsopenSidebar()/openDialog()分别调用ISidebarService与IDialogServicesrc/facade/f-univer.tssetUIVisible()/isUIVisible()委托IUIPartsServicesrc/facade/f-univer.tsaddFonts()则逐个交给IFontServicesrc/facade/f-univer.ts。与业务 UI 插件的协作关系在 Univer 的插件体系中univerjs/ui处于最底层业务 UI 插件如univerjs/sheets-ui、univerjs/docs-ui依赖它提供的菜单、对话框、剪贴板等服务来呈现自己的界面。以官方示例 examples/src/sheets/main.ts 的注册顺序为证先注册UniverRenderEnginePlugin渲染引擎再注册UniverUIPluginUI 层依赖渲染引擎随后注册UniverDocsPlugin、UniverSheetsPlugin等业务插件最后注册UniverDocsUIPlugin、UniverSheetsUIPlugin等业务 UI 插件。同时示例中通过import univerjs/ui/facade激活 UI 的 Facade APIexamples/src/sheets/main.ts并在创建 Univer 实例时配置locale与localesexamples/src/sheets/main.ts对应 README 中将 UI 语言包合并进 locale map的要求。总结univerjs/ui是 Univer 界面体系的基石它以UniverUIPlugin/UniverMobileUIPlugin两个插件承载桌面与移动端的工作台以IUIController区分平台实现通过IMenuManagerService、IUIPartsService、IDialogService、IClipboardInterfaceService等十余个服务为上层业务插件提供菜单、部件、弹层与剪贴板能力并借助univerjs/ui/facade将上述能力以univerAPI的链式方法开放给开发者。无论你是要集成 Univer 的完整 UI还是仅为自己的业务插件注册一个菜单、弹出一个对话框、追加一个自定义字体这个包都是绕不开的入口。【免费下载链接】univerUniver is a full-stack framework for creating and editing spreadsheets / word processor / presentation on both web and server.项目地址: https://gitcode.com/GitHub_Trending/un/univer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考