# @chang-code-hub/univer-import-export 中文文档

规范地址：https://npmcn.com/package/%40chang-code-hub/univer-import-export/

版本：0\.1\.42
npm 元数据更新时间：2025-08-12T14:52:53.347Z
中文译文更新时间：2026-11-09T10:14:40.410Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40chang-code-hub/univer-import-export
原文对照：https://npmcn.com/package/%40chang-code-hub/univer-import-export/?lang=original
项目主页：https://github.com/chang-code-hub/univerjs-import-export
源码仓库：https://github.com/chang-code-hub/univerjs-import-export

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：3.1 MB，58 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：9 个
- 首次发布：2025-08-12T09:27:26.844Z
- 最新版本发布：2025-08-12T14:52:52.816Z
- 近 30 天下载量：7090（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）

## 中文简介

Excel/CSV 用于保存完整格式的Univer电子表格的导入和导出库

## 安装

```sh
npm install @chang-code-hub/univer-import-export
```

也可以使用：`pnpm add @chang-code-hub/univer-import-export`、`yarn add @chang-code-hub/univer-import-export`、`bun add @chang-code-hub/univer-import-export`

## README

# @mertdeveci55/univer-进口-出口

强大的Excel/CSV进出口库 [毕业](https://github.com/dream-num/univer) 带有完整格式保存的电子表格,包括公式、样式、图表和有条件的格式.

[![npm version](https://img.shields.io/npm/v/@mertdeveci55/univer-import-export.svg)](https://www.npmjs.com/package/@mertdeveci55/univer-import-export) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 特征

✅ **导入支持**

-   Excel 文件 (. xlsx, . xls)
-   CSV 文件 (.csv)
-   保存全部工作表(包括空工作表)
-   处理工作表名称中的特殊字符( 等)
-   维持精确的工作表顺序
-   完全样式保存( 字体、 颜色、 边框、 校正)
-   公式和计算值保留(包括TRANSOSE和数组公式)
-   合并单元格支持
-   图像和图表
-   有条件的格式
-   数据验证
-   超链接和丰富文本

✅ **导出支持**

-   Excel 文件 (.xlsx) (中文(简体) )
-   CSV 文件 (.csv)
-   完整格式保存
-   公式导出
-   命名范围
-   多个工作表

## 安装

```bash
npm install @mertdeveci55/univer-import-export
```

或者说

```bash
yarn add @mertdeveci55/univer-import-export
```

## 使用量

### 导入 Excel 到 Univer

```javascript
import { LuckyExcel } from '@mertdeveci55/univer-import-export';

// Handle file input
const fileInput = document.getElementById('file-input');
fileInput.addEventListener('change', (e) => {
    const file = e.target.files[0];
    
    LuckyExcel.transformExcelToUniver(
        file,
        (univerData) => {
            // Use the Univer data
            console.log('Converted data:', univerData);
            
            // Create Univer instance with the data
            univer.createUnit(UniverInstanceType.UNIVER_SHEET, univerData);
        },
        (error) => {
            console.error('Import error:', error);
        }
    );
});
```

### 导入 CSV 到 Univers

```javascript
import { LuckyExcel } from '@mertdeveci55/univer-import-export';

LuckyExcel.transformCsvToUniver(
    csvFile,
    (univerData) => {
        // Use the converted CSV data
        univer.createUnit(UniverInstanceType.UNIVER_SHEET, univerData);
    },
    (error) => {
        console.error('CSV import error:', error);
    }
);
```

### 导出大学到 Excel

```javascript
import { LuckyExcel } from '@mertdeveci55/univer-import-export';

// Get Univer snapshot
const snapshot = univer.getActiveWorkbook().save();

LuckyExcel.transformUniverToExcel({
    snapshot: snapshot,
    fileName: 'my-spreadsheet.xlsx',
    success: () => {
        console.log('Export successful');
    },
    error: (err) => {
        console.error('Export error:', err);
    }
});
```

### 导出大学到 CSV

```javascript
import { LuckyExcel } from '@mertdeveci55/univer-import-export';

const snapshot = univer.getActiveWorkbook().save();

LuckyExcel.transformUniverToCsv({
    snapshot: snapshot,
    fileName: 'my-data.csv',
    sheetName: 'Sheet1', // Optional: specific sheet to export
    success: () => {
        console.log('CSV export successful');
    },
    error: (err) => {
        console.error('CSV export error:', err);
    }
});
```

## API 参考

### `LuckyExcel.transformExcelToUniver(file, callback, errorHandler)`

将 Excel 文件转换为 Univers 格式.

-   **文件**数字 : `File` - Excel文件(.xlsx或.xls)
-   **回调**数字 : `(data: IWorkbookData) => void` - 使用转换数据成功召回
-   **处理错误**数字 : `(error: Error) => void` - 回调错误

### `LuckyExcel.transformCsvToUniver(file, callback, errorHandler)`

将 CSV 文件转换为 Univers 格式.

-   **文件**数字 : `File` - CSV档案
-   **回调**数字 : `(data: IWorkbookData) => void` - 成功回电
-   **处理错误**数字 : `(error: Error) => void` - 回调错误

### `LuckyExcel.transformUniverToExcel(params)`

导出 Univers 数据到 Excel 文件 .

**参数对象:**

-   **简介**数字 : `any` - 大学手册快照
-   **文件Name**数字 : `string` - 输出文件名(可选,默认: `excel_[timestamp].xlsx`(中文(简体) )
-   **获取缓冲**数字 : `boolean` - 返回缓冲器而不是下载(可选,默认:虚假)
-   **成功**数字 : `(buffer?: Buffer) => void` - 成功回电
-   **错误**数字 : `(err: Error) => void` - 回调错误

### `LuckyExcel.transformUniverToCsv(params)`

导出 Univer 数据到 CSV 文件 .

**参数对象:**

-   **简介**数字 : `any` - 大学手册快照
-   **文件Name**数字 : `string` - 输出文件名(可选,默认: `csv_[timestamp].csv`(中文(简体) )
-   **工作表Name**数字 : `string` - 要导出的特定工作表(如果未具体说明,则全部出口)
-   **获取缓冲**数字 : `boolean` - 返回内容而不是下载(可选,默认:虚假)
-   **成功**数字 : `(content?: string) => void` - 成功回电
-   **错误**数字 : `(err: Error) => void` - 回调错误

## 浏览器支持

该库在所有支持的现代浏览器中工作:

-   ES6 + 标准
-   文件 API
-   Blob API 软件

## 项目结构

```
src/
├── ToLuckySheet/         # Excel → LuckySheet conversion
│   ├── LuckyFile.ts      # Main file orchestrator - handles sheet discovery
│   ├── LuckySheet.ts     # Individual sheet processor
│   ├── ReadXml.ts        # XML parser with special character escaping
│   ├── LuckyCell.ts      # Cell data processor
│   └── ...
├── LuckyToUniver/        # LuckySheet → Univer conversion
│   ├── UniverWorkBook.ts # Workbook structure converter
│   ├── UniverSheet.ts    # Sheet data converter
│   └── ...
├── UniverToExcel/        # Univer → Excel export
│   ├── Workbook.ts       # Excel workbook builder using ExcelJS
│   └── ...
├── HandleZip.ts          # ZIP file operations using JSZip
└── main.ts               # Entry point with public API

dist/                     # Built output (ESM, CJS, UMD formats)
publish.sh                # Automated publishing script
gulpfile.js              # Build configuration
CLAUDE.md                # Detailed technical documentation
```

## 关键执行细节

### 特殊字符处理

有特殊字符的工作表名称( 如 `>>>`(a) 通过下列机制处理: `src/ToLuckySheet/ReadXml.ts`数字 :

```javascript
// Escapes ">" to "__GT__" before XML parsing
escapeXmlAttributes(xmlString)
// Restores "__GT__" back to ">" after parsing
unescapeXmlAttributes(xmlString)
```

### 空工作表保存

所有工作表在导入时都会被保存, 即使是完全空的 。 这保持了Excel文件结构的完整性.

### 公式支持

综合公式支持,包括:

-   标准公式(SUM、AVERAGE、IF、VLOOKUP等)
-   矩阵公式
-   带有正确数组处理的 TransactionPOSE 公式
-   共享公式
-   命名区域引用

## 发展

### 大楼

```bash
npm install
npm run build   # Uses gulp to compile TypeScript and bundle
```

### 出版

总是使用发布脚本发布 :

```bash
./publish.sh
```

此脚本 :

1.  构建工程
2.  增量版本
3.  提交更改
4.  推进到 GitHub
5.  发布到 npm

### 测试

```bash
npm test
```

## 密钥改进

### v0.1.40 (最晚) - 简化了导出系统

1.  **Excel 兼容性**: 完全取消Excel恢复警告
2.  **手术后处理**: 保存所有数据完整性的保守后端修正
3.  **生产安全**: 恢复导致腐败的实验性修正
4.  **文档**: 全面记录剩余的限制和工作变通办法

### v0.1.39 - 后端集成

1.  **opyxl 集成**: ExcelJS限制的完整后端处理系统
2.  **定义名称修正**: 使用 Python/ Django 后端对命名区域进行完整解析
3.  **双模式导出**: 前端 + 后端导出自动倒置

### v0.1.24 - 核心稳定性

1.  **特殊字符支持**: 处理工作表名称 `>>>` 和其他特殊人物通过逃脱/逃脱机制
2.  **空工作表保存**: 导入时从未跳出空工作表
3.  **无硬码解决方案**: 删除所有硬码工作表添加 - 所有解决方案都是通用的
4.  **工作表顺序**: 维护原始文件的精确工作表顺序
5.  **样式保存**: 完整样式映射,包括粗体、斜体、颜色、边框
6.  **公式处理**: 保留公式和计算值,包括TRANSOSE
7.  **XLS 支持**: 将.xls文件自动转换为.xlsx格式
8.  **更好的错误处理**: 综合错误信息和详细记录

## 依赖关系

### 核心依赖关系

-   [`@progress/jszip-esm`](https://www.npmjs.com/package/@progress/jszip-esm) - Excel 文件的 ZIP 文件处理
-   [`@zwight/exceljs`](https://www.npmjs.com/package/@zwight/exceljs) - Excel文件结构(导出)
-   [`@univerjs/core`](https://github.com/dream-num/univer) - 通用核心类型和接口
-   [`dayjs`](https://day.js.org/) - 对Excel日期进行日期操纵
-   [`papaparse`](https://www.papaparse.com/) - CSV分析
-   [`xlsx`](https://sheetjs.com/) - 额外的Excel格式支持

### 构建依赖

-   `gulp` - 构建管弦乐
-   `rollup` - 模块捆绑
-   `typescript` - 类型安全
-   `terser` - 消化(配置为保存控制台.logs)

## 相关项目和参考文献

### 核心依赖关系

-   **[毕业](https://github.com/dream-num/univer)** - 本库支持的电子表格引擎
-   **[幸运的羊排](https://github.com/mengshukeji/Luckysheet)** - 中间格式启发
-   **[幸运Excel](https://github.com/dream-num/Luckyexcel)** - 原始代码库 此叉基于

### 执行实例

-   **[α 前端](https://github.com/mertdeveci/alphafrontend)** - 生产实施
    -   见: `src/utils/excel-import.ts` 例如使用时
    -   见: `src/pages/SpreadsheetsPage.tsx` 用于UI 整合

### 文档

-   **[克劳德·姆德](https://npmcn.com/package/%40chang-code-hub/univer-import-export/CLAUDE.md)** - 人工智能助理的详细技术文件
-   **[发布.sh](https://npmcn.com/package/%40chang-code-hub/univer-import-export/publish.sh)** - 自动出版脚本
-   **[gulpfile.js (英语)](https://npmcn.com/package/%40chang-code-hub/univer-import-export/gulpfile.js)** - 构建配置

## 已知问题和解决方案

### 解决的问题

| 问题 | 解决方案 | 版本已固定 |
| --- | --- | --- |
| 带有特殊字符 (QQ) 不导入的工作表 | ReadXml.ts中的逃逸/逃逸机制 | v. 1.123+ 维基月球 |
| 属性列表未定义错误 | 防御性初始化 | 页:1 |
| 出现复制页 | 删除了硬码工作表添加 | (单位:千分之一) |
| TRANSOSE 公式无效 | 矩阵公式支持 | v. 1.18+ (中文(简体) ) |
| 不导入边框样式 | 在 UniversWorkBook 中添加样式收藏 | 页:1 |

### 导出限制和解决方案

由于基础的ExcelJS库的限制,一些高级的Excel功能在其中存在问题 **导出**然而,我们提供了全面的解决办法:

## 🔧 **后端处理后解决方案**

对于生产应用,我们建议使用后端后处理来实现 **100% Excel 兼容性**数字 :

### **建筑**

```
Frontend Export → Backend API → openpyxl Post-Processing → Fixed Excel File
```

### **Django 整合示例**

```python
from spreadsheets.import_export import UniverToExcelConverter, ExcelPostProcessor

# Step 1: Export with existing functionality (preserves all working features)
converter = UniverToExcelConverter()
excel_buffer = converter.convert(univer_data)

# Step 2: Apply surgical fixes for ExcelJS limitations
post_processor = ExcelPostProcessor()
fixed_buffer = post_processor.process_excel_buffer(
    excel_buffer.getvalue(), 
    univer_data
)
```

### **获得什么固定**

-   ✅ **定义名称**: 所有命名的区域在 Excel 中完美工作
-   ✅ **矩阵公式属性**: 溢出范围的适当 XML 属性
-   ✅ **Excel 365 兼容性**: 充分支持现代 Excel 特性
-   ✅ **业绩**: ~7ms 处理间接费用
-   ✅ **安全问题**: 保存所有现有的功能

### **前端整合**

```typescript
// Enhanced export with backend post-processing
const result = await exportToExcel({
  workbookData,
  fileName: 'spreadsheet.xlsx',
  useBackendExport: true,        // Enable backend processing
  enablePostProcessing: true,    // Fix ExcelJS limitations
  exportSpreadsheetToExcel: api.exportSpreadsheetToExcel
});

// Automatic fallback to frontend if backend unavailable
if (result.stats?.postProcessingApplied) {
  console.log('✅ Enhanced Excel compatibility applied!');
}
```

### **设置要求**

1.  **Python 后端** 与 `openpyxl` 已安装
2.  **API 终点** 用于后处理
3.  **可选**: 逐步推出的地物旗

## 📊 **当前出口状况(v0.1.40)**

### ✅ **完全工作特征**

-   ✅ **Excel 兼容性**: 打开文件而无需恢复警告
-   ✅ **数据完整性**: 保存完好的公式、值和结构
-   ✅ **命名范围**: 所有定义的名称都在 Excel 中正确工作(固定在后端)
-   ✅ **进口业务**:为所有 Excel 特性保留100%的功能

### ⚠️ **已知的视觉/演示问题**

| 问题 | 影响 | 状态 | 工作周边 |
| --- | --- | --- | --- |
| **翻译@ 符号** | 公式显示 `=@TRANSPOSE(@$N$43:$N$45)` | 只化妆 - 计算工作 | 文件为已知问题 |
| **边框样式变化** | 破旧的边界可能会变得坚固 | 仅视觉造型 | 导入中保存的原始设计 |
| **ExcelJS 核心限制** | 不支持一些高级 Excel 特性 | 图书馆限制 | 使用后端处理 |

### 🔧 **后端后处理( 建议)**

**状态**: 生产准备外科修复,以达到最大限度的Excel相容性.

**它能解决什么**数字 :

-   QQ 完全删除 Excel 恢复警告
-   QQ 确保所有命名区域完美工作
-   \* 保持100%的数据完整性和公式准确性

**无法修复的东西(按设计)**数字 :

-   QQ 翻译 @ 符号( 需要 ExcelJS 核心更改)
-   QQ 边框样式不一致( 需要 ExcelJS 改进)

**业绩**: ~7ms 为完全Excel相容性而进行高通.

**导入功能效果完美** - 这些限制只影响出口业务.

## 捐款

欢迎捐款! 请确保:

1.  **无硬码解决方案** - 所有修正必须通用
2.  **广泛伐木** - 为调试添加控制台.log
3.  **使用发布.sh** - 从不手工发布到npm
4.  **测试边缘大小写** - 包括特殊字符、空工作表
5.  **遵循现有模式** - 请检查date=中的日期值 (帮助)

## 许可证

麻省理工学院

## 贷项

-   原文 [幸运Excel](https://github.com/dream-num/Luckyexcel) 由 DreamNum 编辑
-   [毕业](https://github.com/dream-num/univer) 电子表格引擎
-   所有撰稿人和记者

## 支助

对于问题和专题请求:

-   [GitHub 问题](https://github.com/mertdeveci/univerjs-import-export/issues)
-   检查 [克劳德·姆德](https://npmcn.com/package/%40chang-code-hub/univer-import-export/CLAUDE.md) 技术细节
-   审查已解决的问题

## 常见问题

### @chang-code-hub/univer-import-export 是什么？

Excel/CSV 用于保存完整格式的Univer电子表格的导入和导出库

### 如何安装 @chang-code-hub/univer-import-export？

在项目目录运行 npm install @chang-code-hub/univer-import-export，或使用 pnpm add / yarn add / bun add。

### @chang-code-hub/univer-import-export 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @chang-code-hub/univer-import-export 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @chang-code-hub/univer-import-export 可以商用吗？

@chang-code-hub/univer-import-export 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @chang-code-hub/univer-import-export 的下载量有多少？

根据 npm 官方下载统计，@chang-code-hub/univer-import-export 在 2026/10/10 – 2026/11/08 这 30 天内被下载 7,090 次，日均约 236 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @chang-code-hub/univer-import-export 还在维护吗？

最新版本 0\.1\.42 发布于 2025/08/12（1\.2 年前）；至今共发布 3 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/08/12。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。