univer-integrate

Univer 集成

在应用中嵌入 Univer，并通过公开的 Facade API 操作它。

源码基线：Univer 1.0.0-beta.0，与当前 dream-num/univer 源码同步。修改现有项目时，先检查用户已安装的 @univerjs/* 版本和现有配置；保留该版本。

1.0 产品边界

UniverInstanceType 所代表的产品矩阵现在涵盖 Sheets、Docs、Slides、Bases、Boards 和 PDFs。此 OSS 技能负责 Sheets 和 Docs 预设集成，以及 OSS Slides 包的边界。对于当前获得许可的 Slides 产品，以及 Bases、Boards 或 PDFs，请使用 univer-pro-integrate；这些产品使用单独的 Pro 插件、Facade 入口、CSS 和单元快照。

选择集成模式

• 新应用或常规集成请使用 预设模式。预设会组合所需的插件和 Facade 注册；浏览器样式和区域设置包仍需显式导入。
• 只有当应用需要自定义加载、更小的包、替换插件或精确控制注册时，才使用 插件模式。手动组合插件前，请阅读 references/plugin-registry.md。
• 专用无头 Node.js 工作流请使用 univer-node-backend。

快速开始：Sheets 预设

让每个 @univerjs/* 依赖都使用同一精确版本：

npm install @univerjs/[email protected] @univerjs/[email protected] [email protected] [email protected] [email protected]

import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core';
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US';
import { createUniver, defaultTheme, LocaleType, mergeLocales } from '@univerjs/presets';

import '@univerjs/preset-sheets-core/lib/index.css';

const { univer, univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(UniverPresetSheetsCoreEnUS),
  },
  theme: defaultTheme,
  presets: [
    UniverSheetsCorePreset({
      container: 'app',
    }),
  ],
});

const workbook = univerAPI.createWorkbook({
  id: 'workbook-1',
  name: 'Demo',
  sheetOrder: ['sheet-1'],
  sheets: {
    'sheet-1': {
      id: 'sheet-1',
      name: 'Sheet1',
      rowCount: 100,
      columnCount: 20,
    },
  },
});

workbook.getActiveSheet()!.getRange('A1:B2').setValues([
  ['Hello', 'Univer'],
  [1, 2],
]);

window.addEventListener('pagehide', () => univer.dispose(), { once: true });

在组件框架中，应在组件自身的销毁流程中调用 univer.dispose()。

页面需要一个指定尺寸的容器：

<div id="app" style="height: 100vh"></div>

使用预设添加功能

以与 @univerjs/presets 相同的版本安装每项功能，导入其区域设置包，并追加其预设：

import { UniverSheetsDataValidationPreset } from '@univerjs/preset-sheets-data-validation';
import UniverPresetSheetsDataValidationEnUS from '@univerjs/preset-sheets-data-validation/locales/en-US';

import '@univerjs/preset-sheets-data-validation/lib/index.css';

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsDataValidationEnUS,
    ),
  },
  presets: [
    UniverSheetsCorePreset({ container: 'app' }),
    UniverSheetsDataValidationPreset(),
  ],
});

可用的 OSS 预设列于 references/plugin-registry.md。导入每个浏览器预设所需的样式表。不要同时注册某个预设及其底层插件。

Facade API 规则

预设包会注册其 Facade 扩展。在插件模式中，请为使用的每项功能显式导入 /facade 入口：

import { FUniver } from '@univerjs/core/facade';

import '@univerjs/engine-formula/facade';
import '@univerjs/sheets/facade';
import '@univerjs/sheets-formula/facade';
import '@univerjs/ui/facade';

const univerAPI = FUniver.newAPI(univer);

优先使用面向功能的 Facade 方法和构建器，而不是内部服务：

const workbook = univerAPI.getActiveWorkbook();
if (!workbook) throw new Error('No active workbook');

const worksheet = workbook.getActiveSheet();
if (!worksheet) throw new Error('No active worksheet');

worksheet.getRange('A1')
  .setValue('Hello')
  .setBackground('#ff0000')
  .setFontColor('#ffffff');

const snapshot = workbook.save();

当前方法名称和功能导入映射请参阅 references/facade-api-guide.md。

版本策略

1. 检查 package.json、锁文件或 node_modules/@univerjs/core/package.json。
2. 所有 @univerjs/* 包都复用项目已安装的精确版本。
3. 新项目若基于此源码基线，请使用 1.0.0-beta.0。
4. 不要混用 OSS 或预设包的版本。如果项目中存在 Pro，也要让 @univerjs-pro/* 与同一发布系列保持一致。

运行时兼容性

当前 Univer 支持 Edge 88+、Firefox 90+、Chrome 88+、Safari 14.1+ 和 Electron 12+。无头 Univer 支持 Node.js 18.17+。如果目标运行时未提供 Intl.Segmenter，请添加相应的 polyfill。

主题和区域设置

在 createUniver 中设置初始主题。当前源码也支持通过 Facade 在运行时切换主题：

univerAPI.setTheme(defaultTheme);
univerAPI.toggleDarkMode(true);
univerAPI.setLocale(LocaleType.EN_US);

对于品牌调色板、暗色模式、插件 CSS 变量、六种产品的主题边界，以及当前主题方法的已安装版本门槛，请使用 univer-customize-theme。

在输出 setTheme()、getCurrentTheme() 或 isDarkMode() 之前，请核实已安装的 FUniver 声明；携带当前源码预发布版本标签的已发布 npm 包可能尚未包含这些方法。初始化仍是可移植的主题选择方式。

加载所注册预设或插件拥有的每个区域设置包。不要自行缓存翻译后的字符串。

核心模型

• univerAPI.createWorkbook(data) 创建并返回一个 FWorkbook。
• univerAPI.getWorkbook(id) 获取指定的工作簿。
• workbook.getActiveSheet() 和 workbook.getSheetByName(name) 返回 FWorksheet 对象。
• worksheet.getRange('A1:B2') 返回一个 FRange。
• workbook.save() 返回当前的 IWorkbookData 快照。
• univerAPI.disposeUnit(id) 释放一个单元；univer.dispose() 拆除应用。

只有在注册相应的 Docs 预设/插件后，才能使用 createDocument。不要将 Bases、Boards、PDF 或当前的 Pro Slides 产品表示为工作簿；请使用 univer-pro-integrate 文档中对应产品专用的 Facade 创建方法。

反模式

• 不要直接修改 Workbook 或 Worksheet 模型。请使用 Facade 方法或 Commands，以确保撤销/重做和响应式更新保持一致。
• 不要臆造旧版本中的 Facade 方法。请检查已安装的包源码或类型；若干 0.x 方法名在 1.0.0-beta.0 中发生了变化。
• 如果现有预设已包含相同的组合，不要在新应用中复制手动插件列表。
• 在浏览器构建中，不要遗漏预设或插件的 CSS。
• 单元或 Univer 实例释放后，不要保留工作簿、工作表或范围句柄。
• 不要仅为添加另一个工作簿而创建单独的 Univer 实例。除非页面确实需要相互独立的编辑器容器，否则请使用多个单元。

常见操作

const workbook = univerAPI.getActiveWorkbook()!;
const worksheet = workbook.getActiveSheet()!;

worksheet.getRange('A1:D2').setValues([
  ['Product', 'Qty', 'Price', 'Total'],
  ['Apple', 2, 3, '=B2*C2'],
]);

worksheet.setColumnWidth(0, 140);
worksheet.setRowHeight(0, 32);
workbook.undo();
workbook.redo();

参考

• references/facade-api-guide.md — 当前 Facade 层级、方法名、导入方式和功能示例
• references/common-tasks.md — 持久化、格式设置、超链接、事件、CSV、主题和大型数据集
• references/plugin-registry.md — 当前的 OSS 预设和手动插件
• references/framework-integration.md — React、Vue 3、Web Component、iframe 和 Node 生命周期模式
• references/worker-setup.md — 当前浏览器和 Node Worker 预设
• references/custom-functions.md — 同步和异步自定义公式函数
• references/permissions.md — 工作簿、工作表和范围权限 Facade
• references/multi-unit-management.md — 创建、获取、聚焦和释放多个单元
• references/network-and-others.md — Network、Watermark、Action Recorder 和 Telemetry 的边界

模板

从 assets/templates/ 中复制最符合需求的模板：

• react-vite/
• vue3-vite/
• plain-html/
• node/