Excel生成器库 (ExcelGenerator)

一个用于HarmonyOS应用的Excel文件生成库，支持创建、验证和保存Excel文件。

功能特性

• ✅ 数据验证: 完整的数据格式验证和错误提示
• ✅ Excel生成: 生成标准的Excel XML格式文件
• ✅ 样式支持: 支持标题、表头、数据的自定义样式
• ✅ 文件保存: 支持保存到用户选择的本地位置
• ✅ 类型安全: 完整的TypeScript类型定义
• ✅ 错误处理: 详细的错误信息和异常处理

安装使用

1. 导入库文件

import { 
  ExcelGenerator, 
  ExcelTableData, 
  ExcelCellData,
  ExcelGenerateOptions,
  ExcelGenerateResult 
} from './_Excel';

2. 创建生成器实例

const context = getContext(this) as common.UIAbilityContext;
const excelGenerator = new ExcelGenerator(context);

数据格式规范

ExcelTableData 接口

interface ExcelTableData {
  title: string;                    // 表格标题（必填）
  headers?: string[];               // 表头数组（可选）
  data: ExcelCellData[][];         // 二维数据数组（必填）
  titleStyle?: ExcelCellStyle;     // 标题样式（可选）
  headerStyle?: ExcelCellStyle;    // 表头样式（可选）
  dataStyle?: ExcelCellStyle;      // 数据样式（可选）
}

ExcelCellData 接口

interface ExcelCellData {
  value: string;                   // 单元格内容（必填）
  style?: ExcelCellStyle;         // 单元格样式（可选）
}

ExcelCellStyle 接口

interface ExcelCellStyle {
  fontWeight?: 'normal' | 'bold'; // 字体粗细
  fontSize?: number;               // 字体大小
  fontColor?: string;             // 字体颜色
  backgroundColor?: string;        // 背景颜色
  alignment?: 'left' | 'center' | 'right'; // 对齐方式
}

数据验证规则

标题验证

• 不能为空
• 长度不能超过100个字符

数据验证

• 必须是二维数组
• 不能为空
• 行数不能超过1000行
• 列数不能超过50列
• 每行列数必须一致
• 单元格内容长度不能超过1000个字符

表头验证

• 如果提供表头，列数必须与数据列数一致
• 表头内容必须是字符串

使用示例

基础用法

// 1. 创建简单表格数据
const tableData = ExcelGenerator.createSimpleTableData(
  '员工信息表',
  ['姓名', '年龄', '部门'],
  [
    ['张三', '25', '技术部'],
    ['李四', '30', '销售部'],
    ['王五', '28', '人事部']
  ]
);

// 2. 生成Excel文件
const result = await excelGenerator.generateExcel(tableData);

if (result.success) {
  console.log('生成成功:', result.message);
  // 3. 保存到本地
  const saveResult = await excelGenerator.saveToLocal(result.filePath!, result.fileName!);
  console.log('保存结果:', saveResult.message);
} else {
  console.error('生成失败:', result.message);
}

高级用法（带样式）

// 1. 创建带样式的表格数据
const styledTableData = ExcelGenerator.createStyledTableData(
  '销售报表',
  ['产品名称', '销售额', '增长率'],
  [
    ['产品A', '100000', '15%'],
    ['产品B', '80000', '8%'],
    ['产品C', '120000', '22%']
  ],
  {
    titleStyle: {
      fontWeight: 'bold',
      fontSize: 18,
      backgroundColor: '#4CAF50'
    },
    headerStyle: {
      fontWeight: 'bold',
      fontSize: 14,
      backgroundColor: '#E8F5E8'
    },
    dataStyle: {
      fontSize: 12
    }
  }
);

// 2. 生成选项
const options: ExcelGenerateOptions = {
  fileName: '销售报表_2024.xls',
  author: '销售部',
  sheetName: '月度报表'
};

// 3. 生成Excel文件
const result = await excelGenerator.generateExcel(styledTableData, options);

手动构建数据

// 1. 手动构建复杂数据
const complexTableData: ExcelTableData = {
  title: '项目进度表',
  headers: ['项目名称', '负责人', '进度', '状态'],
  data: [
    [
      { value: '项目A' },
      { value: '张三' },
      { value: '80%' },
      { value: '进行中', style: { fontColor: '#FF9800' } }
    ],
    [
      { value: '项目B' },
      { value: '李四' },
      { value: '100%' },
      { value: '已完成', style: { fontColor: '#4CAF50' } }
    ]
  ],
  titleStyle: {
    fontWeight: 'bold',
    fontSize: 16,
    backgroundColor: '#2196F3'
  }
};

// 2. 验证数据
const validation = excelGenerator.validateTableData(complexTableData);
if (!validation.isValid) {
  console.error('数据验证失败:', validation.errors);
  return;
}

// 3. 生成文件
const result = await excelGenerator.generateExcel(complexTableData);

API 参考

ExcelGenerator 类

构造函数

constructor(context: common.UIAbilityContext)

方法

validateTableData(tableData: ExcelTableData): ExcelValidationResult

验证表格数据格式

参数:

• tableData: 要验证的表格数据

返回:

• ExcelValidationResult: 验证结果，包含是否有效和错误信息

generateExcel(tableData: ExcelTableData, options?: ExcelGenerateOptions): Promise

生成Excel文件

参数:

• tableData: 表格数据
• options: 生成选项（可选）

返回:

• Promise<ExcelGenerateResult>: 生成结果

saveToLocal(filePath: string, fileName: string): Promise

保存文件到用户选择的位置

参数:

• filePath: 源文件路径
• fileName: 文件名

返回:

• Promise<ExcelGenerateResult>: 保存结果

静态方法

createSimpleTableData(title: string, headers: string[], data: string[][]): ExcelTableData

创建简单表格数据

createStyledTableData(title: string, headers: string[], data: string[][], styles: object): ExcelTableData

创建带样式的表格数据

错误处理

常见错误及解决方案

1. "表格标题不能为空"

   • 确保提供有效的标题字符串

2. "表格数据必须是二维数组"

   • 检查数据格式，确保是 ExcelCellData[][] 类型

3. "第X行列数与第一行列数不一致"

   • 确保所有行的列数相同

4. "单元格内容长度不能超过1000个字符"

   • 检查单元格内容长度

5. "表头列数与数据列数不一致"

   • 确保表头数量与数据列数匹配

限制说明

• 最大行数：1000行
• 最大列数：50列
• 标题长度：100个字符
• 单元格内容长度：1000个字符
• 支持的文件格式：Excel XML (.xls)

兼容性

• HarmonyOS: API 12+
• 文件格式: Excel XML (.xls)
• 支持的应用: WPS Office, Microsoft Excel, LibreOffice Calc

更新日志

v1.0.0

• 初始版本发布
• 支持基础Excel生成功能
• 完整的数据验证
• 样式支持
• 文件保存功能

许可证

MIT License

贡献

欢迎提交Issue和Pull Request来改进这个库。

联系方式

如有问题或建议，请通过以下方式联系：

• 提交Issue
• 发送邮件

注意: 这是一个专为HarmonyOS设计的Excel生成库，使用前请确保您的开发环境支持相关API。