fitech-modern-sheet-editor

一个基于 Univer 电子表格引擎的 React 报表设计器组件库。

特性

• 🎨 可视化设计：直观的拖拽式报表设计界面
• 📊 多种模式：支持设计、报表、查看、权限四种模式
• 🔧 高度可配置：灵活的配置选项和回调机制
• 🚀 React 16+ 兼容：支持 React 16.8.0 及以上版本
• 📱 响应式设计：适配各种屏幕尺寸
• 🛠 TypeScript 友好：提供完整的类型定义

安装

npm install fitech-modern-sheet-editor
# 或
yarn add fitech-modern-sheet-editor

依赖要求

{
  "react": ">=16.8.0",
  "react-dom": ">=16.8.0"
}

基本用法

1. 导入样式文件

在您的应用入口文件中导入必要的样式：

// 必须导入的 Univer 样式
import '@univerjs/design/lib/index.css';
import '@univerjs/ui/lib/index.css';
import '@univerjs/docs-ui/lib/index.css';
import '@univerjs/sheets-ui/lib/index.css';
import '@univerjs/sheets-formula-ui/lib/index.css';

2. 使用组件

import React, { useState } from 'react';
import UniverCore from 'fitech-modern-sheet-editor';

function App() {
  const [currentMode, setCurrentMode] = useState('design');

  const handleReady = ({ univer, workbook }) => {
    console.log('报表设计器已就绪:', { univer, workbook });
  };

  const handleError = (error) => {
    console.error('初始化失败:', error);
  };

  const handleModeChange = (mode) => {
    console.log('模式切换:', mode);
    setCurrentMode(mode);
  };

  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <UniverCore
        mode={currentMode}
        onReady={handleReady}
        onError={handleError}
        onModeChange={handleModeChange}
      />
    </div>
  );
}

export default App;

API 文档

UniverCore Props

| 属性 | 类型 | 默认值 | 描述 | |------|------|--------|------| | mode | 'design' \| 'report' \| 'view' \| 'authority' | 'design' | 初始模式 | | workbookData | Object | null | 初始工作簿数据 | | className | string | '' | 自定义 CSS 类名 | | style | Object | {} | 自定义样式 | | onReady | Function | null | 组件就绪回调 | | onError | Function | null | 错误处理回调 | | onSave | Function | null | 保存操作回调 | | onModeChange | Function | null | 模式变化回调 |

模式说明

• design：设计模式，允许编辑和设计报表布局
• report：报表模式，查看和分析数据
• view：查看模式，只读模式，不允许编辑
• authority：权限模式，管理用户权限和访问控制

回调函数

onReady(instance)

组件初始化完成时触发。

const handleReady = ({ univer, workbook }) => {
  // univer: Univer 实例
  // workbook: 工作簿实例
};

onError(error)

组件初始化或运行时发生错误时触发。

const handleError = (error) => {
  console.error('错误:', error.message);
};

onModeChange(mode)

模式切换时触发。

const handleModeChange = (mode) => {
  console.log('当前模式:', mode);
};

onSave(data)

保存操作时触发。

const handleSave = (data) => {
  // 处理保存逻辑
  console.log('保存数据:', data);
};

高级用法

受控模式

import React, { useState } from 'react';
import UniverCore from 'fitech-modern-sheet-editor';

function ControlledExample() {
  const [mode, setMode] = useState('design');
  const [workbookData, setWorkbookData] = useState(null);

  const switchToReportMode = () => {
    setMode('report');
  };

  const loadData = (data) => {
    setWorkbookData(data);
  };

  return (
    <div>
      <div>
        <button onClick={switchToReportMode}>切换到报表模式</button>
        <button onClick={() => loadData(someData)}>加载数据</button>
      </div>
      
      <UniverCore
        mode={mode}
        workbookData={workbookData}
        onModeChange={setMode}
        onSave={(data) => {
          // 自定义保存逻辑
          console.log('保存:', data);
        }}
      />
    </div>
  );
}

工具函数

convertToUniverFormat(data)

将外部数据转换为 Univer 格式。

import { convertToUniverFormat } from 'fitech-modern-sheet-editor';

const univerData = convertToUniverFormat(externalData);

checkCompatibility()

检查环境兼容性。

import { checkCompatibility } from 'fitech-modern-sheet-editor';

const compatibility = checkCompatibility();
if (!compatibility.compatible) {
  console.error('兼容性问题:', compatibility.errors);
}

样式定制

自定义主题

/* 覆盖默认样式 */
.univer-container {
  --primary-color: #your-color;
  --border-radius: 8px;
}

响应式布局

.report-designer {
  width: 100%;
  height: 100vh;
  min-height: 600px;
}

@media (max-width: 768px) {
  .report-designer {
    min-height: 400px;
  }
}

兼容性

• React 16.8.0+
• 现代浏览器 (Chrome, Firefox, Safari, Edge)
• IE 11+ (需要 polyfills)

开发

本地开发

# 克隆项目
git clone https://github.com/fitech/fitech-report-designer.git

# 安装依赖
npm install

# 启动开发服务器
npm run dev

构建

# 构建所有格式
npm run build

# 仅构建 CommonJS
npm run build:lib

# 仅构建 ES modules
npm run build:es

# 仅构建 UMD
npm run build:dist

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

1.0.0

• 初始版本发布
• 支持基本的报表设计功能
• 多模式支持
• React 16.x 兼容性