univer.js 公共组件库

介绍

univer.js 公共组件库是基于 univer.ai 开发的表格组件封装，提供了丰富的功能和易用的 API，支持自定义样式、图标、批注等功能。

软件架构

基于 univer.ai 核心库进行封装，提供 Vue 组件接口，支持单元格自定义渲染、样式定制、事件回调等功能。

安装教程

1. 使用 npm 下载组件依赖

npm install univer-com@git+https://gitee.com/nstc/bi-pub-service.git#000000-nstc-univer

使用说明

组件引用

import univer from "univer-com/src/components/univer/index.vue";

基本使用

<univer ref="univer" :data="Data"></univer>

组件属性说明

组件内部提供两个核心属性，可通过 ref 访问：

// 访问 univer 实例
this.$refs.univer.univer;
// 访问 univerAPI 接口
this.$refs.univer.univerAPI;

初始化数据格式

数据结构参考官网文档：工作簿数据结构

const Data = {
  id: "workbook-01",
  name: "universheet",
  sheetOrder: ["sheet1"],
  appVersion: "3.0.0-alpha",
  defaultColumnWidth: 100, // 默认宽度
  defaultRowHeight: 25, // 默认高度

  // 工作表信息
  sheets: {
    sheet1: {
      id: "sheet1",

      // 冻结单元格设置
      freeze: {
        xSplit: 1, // 冻结 1 列，即 B 列
        ySplit: 1, // 冻结 1 行，即第 2 行
        startRow: 2, // 可滚动的起始行是第 3 行
        startColumn: 2, // 可滚动的起始列是第 C 列
      },

      // 单元格信息
      cellData: {
        0: {
          // 行号
          0: {
            // 列号
            v: "A1", // 渲染的值
            t: 1, // 单元格类型：1-字符串，2-数字，3-布尔值，4-强制文本
            // 样式
            s: {
              fs: 10,
              bg: { rgb: "#f87e2a" },
              cl: { rgb: "#f87e2a" },
            },
            // 自定义属性
            custom: {
              // 图标字段
              icon: {
                fs: 16, // 字体大小
                m: 5, // 图标间距
                ids: [
                  { id: "icon-lianghao", cl: "#f87e2a" },
                  { id: "icon-lianghao", cl: "#de2a" },
                  { id: "icon-lianghao", cl: "#82a" },
                ],
              },
              // 批注字段
              notes: {
                v: "这是一个批注的内容",
              },
            },
          },
        },
      },

      name: "监管报送测试1",

      // 合并单元格信息
      mergeData: [
        {
          startRow: 0,
          startColumn: 0,
          endRow: 1,
          endColumn: 1,
          rangeType: 0,
          unitId: "workbook-01",
          sheetId: "sheet1",
        },
      ],

      columnData: {
        0: { w: 125, hd: 0 },
        1: { w: 125, hd: 0 },
      },

      // 保护工作区格式
      range: {
        readOnly: [
          "A1:B3", // 范围区间A1到B3保护不可编辑
          "C4:D15", // 范围区间C4到D15保护不可编辑
        ],
        unreadable: ["c1:c1"],
      },

      // 数据验证，下拉框
      pullDown: [
        {
          option: ["类型1", "类型2", "类型3", "类型4", "类型5"],
          range: "H1:H10", // 渲染范围
        },
      ],
    },
  },
};

功能特性

一、表格区分只读/操作模式

通过 disabled 属性指定是否禁用表格组件：

<univer :disabled="true"></univer>

• disabled=true 表示只读模式
• disabled=false 表示操作模式（默认）

二、表格工具栏菜单项权限控制（1.控制菜单工具栏显示，2.控制工作簿功能）

1.控制菜单工具栏显示权限 通过 menuPermissions 属性控制菜单项的显示

<univer :menuPermissions="menuPermissions"></univer>

// 权限控制数组，传入菜单项 id 来控制是否显示 默认不传为显示，传则不显示
const menuPermissions = ["univer.command.undo", "univer.command.redo"];

菜单项 ID 列表可参考官方文档：菜单项 ID 列表

2.控制Workbook工作簿Worksheet工作表功能权限 通过WorkbookPermissions属性控制功能

<univer :WorkbookPermissions="WorkbookPermissions"></univer>

// 权限控制数组，传入 功能id 来控制禁用  默认不传功能启用，传功能禁用
const WorkbookPermissions = ["WorkbookEditablePermission", "WorksheetCopyPermission"];

Workbook工作簿Worksheet工作表 功能ID 列表可参考官方文档：功能 ID 列表

3.控制工作簿工具栏、右键菜单、公式栏、页脚是否显示 id如下 1.工具栏 toolbar
2.右键菜单 contextMenu 3.公式栏 formulaBar 4.页脚 footer

<univer :WorkbookUIController="WorkbookUIController"></univer>

// 权限控制数组，传入 功能id 来控制显示  默认不传显示，传隐藏
const WorkbookUIController = ["toolbar", "contextMenu"];

4.保护区域是否要阴影 protectedRangeShadow <Boolean>

<univer :protectedRangeShadow="true"></univer>

• protectedRangeShadow=true 表示有阴影
• protectedRangeShadow=false 表示不需要阴影

三、获取当前工作表数据

通过 getData 方法获取当前工作表的完整数据：

// 获取表格数据
const data = this.$refs.univer.getData();

四、获取当前单元格数据

通过 getPrecinctFn 方法获取当前选中单元格的数据：

// 获取选中单元格数据
const { data, PrecinctAreaArr } = this.$refs.univer.getPrecinctFn();

返回值说明：

• data：所有选中单元格的数据格式数组，如 [{n: "A1", t: 2, v: 1}]
• PrecinctAreaArr：单元格选区的坐标数组，如 ['A1:B1', 'c10']

五、写入单元格数据

通过 setPrecinctFn 方法设置单元格数据：

// 写入单元格数据
this.$refs.univer.setPrecinctFn(precinctDataArr);

precinctDataArr 数据格式示例：

[
  {
    n: "A1", // 单元格位置
    v: "单元格值", // 原始值
    t: 1, // 单元格类型
    s: {
      // 单元格样式
      // 样式属性
    },
    p: null, // 富文本（暂不需要）
    f: null, // 公式
    si: null, // 公式ID
    custom: {
      // 自定义字段
      icon: {
        fs: 16, // 字体大小
        m: 5, // 间距
        ids: [
          { id: "icon-lianghao", cl: "#f87e2a" },
          // 更多图标...
        ],
      },
    },
  },
  // 更多单元格...
];

六、清除选区内容和格式

通过 clearPrecinctFn 方法清除选区内容和格式：

// 清除选区
const rangeArr = ["format", "content", "style", "icon"];
this.$refs.univer.clearPrecinctFn(rangeArr);

参数说明：

• format：清除格式
• content：清除内容
• style：清除样式
• icon：清除图标
• 不传参数则默认清除所有选区

七、自定义快捷键设置

通过 keyboardArr 属性和 shortcutKeyFn 方法自定义快捷键：

<univer ref="univer" :shortcutKeyFn="shortcutKeyFn" :keyboardArr="keyboardArr">
</univer>

// 快捷键配置
const keyboardArr = [
  {
    key: ["Control", "Alt"], // 键盘组合数组（必传）
    id: 1223,
    name: "自定义快捷键1",
    // 其他自定义属性
  },
  {
    key: ["Control", "k"], // 键盘组合数组（必传）
    id: 1224,
    name: "自定义快捷键2",
    // 其他自定义属性
  },
];

// 快捷键触发方法
function shortcutKeyFn(data) {
  const { workbook, keyboards } = data;
  // 处理快捷键逻辑
  console.log("快捷键触发", workbook, keyboards);
}

八、导出方法

通过 exportAllData 方法导出表格数据：

// 导出数据
this.$refs.univer.exportAllData();

九、导入方法

通过 importFileFn 方法导入表格文件：

// 导入文件
this.$refs.univer.importFileFn(file);

十、图标使用

1. 引用图标库

• 使用阿里图标库的 symbol 类型文件
• 在 main.js 中引入 iconfont.js 文件
• 配置 iconFontId 属性

<univer :iconFontId="iconFontId"></univer>

// iconFontId 对应 iconfont.js 文件中的全局变量名
const iconFontId = "_iconfont_svg_string_4941244";

2. 单元格图标配置

通过单元格的 custom.icon 属性配置图标：

custom: {
  icon: {
    fs: 16,           // 字体大小
    m: 5,             // 间距
    ids: [
      { id: "icon-lianghao", cl: "#f87e2a" },
      { id: "icon-lianghao", cl: "#de2a" },
      { id: "icon-lianghao", cl: "#82a" }
    ]
  }
}

3. 修改单元格图标

使用 setPrecinctFn 方法更新单元格图标：

const precinctDataArr = [
  {
    n: "A1",
    // 其他属性...
    custom: {
      icon: {
        fs: 16,
        m: 5,
        ids: [
          { id: "icon-lianghao", cl: "#f87e2a" },
          // 更多图标...
        ],
      },
    },
  },
];

this.$refs.univer.setPrecinctFn(precinctDataArr);

十一、批注使用

通过单元格的 custom.notes 属性配置批注：

custom: {
  notes: {
    v: "这是一个批注的内容";
  }
}

十二、刷新工作表数据

通过 init 方法重新初始化工作表数据：

// 刷新数据
this.$refs.univer.init(data);

十三、编辑单元格后回调

通过 sheetEditEnded 属性配置单元格编辑后的回调方法：

<univer :sheetEditEnded="sheetEditEnded"></univer>

// 单元格编辑后回调方法
function sheetEditEnded(fWorkbook, sheetSnapshot, prevSheetSnapshot) {
  console.log(
    "单元格编辑后触发",
    fWorkbook, // 当前工作簿信息
    sheetSnapshot, // 当前工作表信息
    prevSheetSnapshot // 编辑单元格信息
  );
  // 处理编辑后的逻辑
}

十四、废弃行/启用行自定义菜单

1. 废弃行回调

通过 getAbandonRowFn 属性配置废弃行的回调方法：

<univer :getAbandonRowFn="getAbandonRowFn"></univer>

// 废弃行回调方法
function getAbandonRowFn(params) {
  const { workbookData, worksheetData, rowArr } = params;
  console.log(
    "废弃行触发",
    workbookData, // 当前工作簿信息
    worksheetData, // 当前工作表信息
    rowArr // 选择废弃的行坐标数组
  );
  // 处理废弃行逻辑
}

权限控制 ID：sheet.command.abandon-line

2. 启用废弃行回调

通过 getInvokeRowFn 属性配置启用废弃行的回调方法：

<univer :getInvokeRowFn="getInvokeRowFn"></univer>

// 启用废弃行回调方法
function getInvokeRowFn(params) {
  const { workbookData, worksheetData, rowArr } = params;
  console.log(
    "启用废弃行触发",
    workbookData, // 当前工作簿信息
    worksheetData, // 当前工作表信息
    rowArr // 启用废弃的行坐标数组
  );
  // 处理启用废弃行逻辑
}

权限控制 ID：sheet.command.invoke-row

参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request

特别说明

1. 支持使用 Readme_XXX.md 来展示不同语言的文档，如 Readme_en.md, Readme_zh.md
2. 更多使用指南可参考 univer.ai 官方文档