tor-univer-sheet

TorUniverSheet 项目笔记整理（完整版）

📦 项目概述

项目名称: tor-univer-sheet
版本: 1.0.5
描述: 基于 Univer 的 Vue3 电子表格组件
作者: tortormore
许可证: MIT

🏗️ 技术栈

📁 项目结构

src/
├── components/
│   ├── ContentWrap/          # 内容包装组件
│   ├── Form/                 # 表单组件
│   ├── GlobalLoading/        # 全局加载组件
│   ├── IndicatorPointSelect/ # 指标选择组件
│   └── UniverSheet/          # 核心表格组件
│       ├── plugins/          # 自定义插件
│       │   ├── importFile/           # 文件导入插件
│       │   ├── indicatorsContextMenu/ # 指标右键菜单插件
│       │   ├── saveButton/           # 保存按钮插件
│       │   ├── syncContextMenu/      # 同步右键菜单插件
│       │   └── timeConfigContextMenu/ # 时间配置右键菜单插件
│       ├── UniverSheet.vue   # 主组件
│       ├── UniverSheet.data.ts # 数据类型定义
│       └── data.ts           # 数据工具
├── hooks/                    # 组合式函数
├── types/                    # 类型定义
├── utils/                    # 工具函数
├── index.ts                  # 入口文件
└── main.ts                   # 应用入口

🔌 核心组件 API

UniverSheet 组件

<template>
  <UniverSheet
    :mode="ModeEnum.edit"
    :license="''"
    show-import-file-plugin
    show-indicators-context-menu-plugin
    show-time-config-context-menu-plugin
  />
</template>

Props

Exposed Methods

Events

🔧 自定义插件系统

插件列表

注册外部组件

// main.ts
import { registerExternalComponents } from 'tor-univer-sheet'
import IndicatorPointSelect from './components/IndicatorPointSelect.vue'

registerExternalComponents({
  IndicatorPointSelect,
})

📝 表单配置 Schema

指标配置表单 (indicatorsFormSchemas)

{
  title: '基本信息',
  schemas: [
    { field: 'indicatorName', label: '指标名称', component: 'Input' },
    { field: 'indicatorCode', label: '指标编码', component: 'Input', disabled: true },
    { field: 'indicatorId', label: '指标 ID', component: 'Input', disabled: true },
    { field: 'indicatorDimensionName', label: '维度名称', component: 'Input', disabled: true },
    { field: 'indicatorDimensionConfig', label: '维度编码', component: 'Input', disabled: true },
    { field: 'required', label: '是否必填', component: 'ElCheckbox' }
  ]
}

时间配置表单 ([timeConfigFormSchemas])

{
  title: '时间条件',
  schemas: [
    { field: 'cycleType', label: '周期类型', component: 'Select' },
    { field: 'timeIncrement', label: '时间递增量', component: 'InputNumber' },
    { field: 'defaultShift', label: '默认排班班次', component: 'ElCheckbox' },
    { field: 'forwardPush', label: '向前推 7 天', component: 'ElCheckbox' }
  ]
},
{
  title: '拓展形式',
  schemas: [
    { field: 'copyType', label: '复制方式', component: 'Select' },
    { field: 'copyInterval', label: '跨多少 (行/列) 复制', component: 'InputNumber' }
  ]
}

周期类型枚举 ([CycleTypeEnum])

enum CycleTypeEnum {
  无 = 'no',
  年 = 'year',
  月 = 'month',
  周 = 'week',
  天 = 'day',
  班组 = 'shift',
  小时 = 'hour',
  半小时 = 'half_hour',
}

🛠️ 工具函数

decimal.ts - 数值计算

import { decimal } from 'tor-univer-sheet'

// 链式调用
const result = decimal(100).add(50).multiply(2).toNumber() // 300

fileHelp.ts - 文件处理

is.ts - 类型判断

🚀 使用示例

基础用法

<template>
  <div style="width: 100%; height: 100vh">
    <UniverSheet ref="sheetRef" :mode="ModeEnum.edit" :license="''" />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { UniverSheet, ModeEnum } from 'tor-univer-sheet'

const sheetRef = ref()

// 获取工作簿数据
const saveData = () => {
  const data = sheetRef.value.getWorkbookData()
  console.log(data)
}
</script>

启用插件

<template>
  <UniverSheet
    show-import-file-plugin
    show-indicators-context-menu-plugin
    show-time-config-context-menu-plugin
    show-sync-context-menu-plugin
  />
</template>

批量更新单元格

const cells = {
  0: {
    0: {
      v: 'Hello',
      custom: {
        cellType: 'indicator',
        indicatorName: '测试指标',
        businessDate: '2024-01-01',
      },
    },
  },
}

await sheetRef.value.batchUpdateCells(cells, sheetId)

📋 开发命令

# 开发
npm run dev

# 构建
npm run build

# 类型检查
npm run type-check

# 测试
npm run test:unit

# 代码检查
npm run lint

# 代码格式化
npm run format

# 发布
npm publish

⚠️ 注意事项

1. Peer Dependencies: 使用方需自行安装 [vue], [element-plus], [xlsx], [decimal.js], [dayjs]
2. 样式引入: 需要单独引入 import 'tor-univer-sheet/dist/style.css'
3. 许可证: Univer Advanced 功能需要有效的 license
4. Node 版本: 要求 Node.js ^20.19.0 || >=22.12.0
5. 外部组件注册: 使用 [IndicatorPointSelect] 等组件前需通过 [registerExternalComponents] 注册
6. 2FA 认证: 发布时需准备 2FA 验证码，建议保存备用代码
7. 版本管理: 遵循语义化版本规范，发布前更新 [package.json] 版本号

📝 版本记录

🔗 相关资源

• npm: https://www.npmjs.com/package/tor-univer-sheet
• Univer 官方: https://univer.ai/
• Element Plus: https://element-plus.org/
• Vue 3: https://vuejs.org/
• NPM 文档: https://docs.npmjs.com/