mm_excel 开发文档

简介

mm_excel 是一个基于 exceljs 的 Excel 操作模块，提供了丰富的 Excel 文件读写、样式设置、模板应用等功能。

安装

npm install mm_excel

基础用法

初始化

const Excel = require('mm_excel');

const excel = new Excel({
    // 配置项
});

配置项说明

基础配置

{
    path: __dirname,        // 文件路径
    file: './number.xlsx',  // 默认文件名
    convert: true,         // 是否进行数据转换
    sheet: 1,              // 工作表索引或名称
    
    // Excel 文件属性
    excel: {
        creator: 'MM',      // 创建者
        editor: 'MM',       // 最后修改者
        create_time: time,   // 创建时间
        edit_time: time,     // 修改时间
        last_time: time      // 最后修改时间
    },
    
    // 页面设置
    pageSetup: {
        orientation: 'landscape',  // 纸张方向：横向('landscape')或纵向('portrait')
        fitToPage: true,          // 自适应页面
        fitWidth: 1,             // 宽度缩放比例
        fitHeight: 1,            // 高度缩放比例
        margins: {               // 页边距(单位：英寸)
            left: 0.25,
            right: 0.25,
            top: 0.75,
            bottom: 0.75,
            header: 0.3,
            footer: 0.3
        }
    },
    
    // 单元格默认样式
    cell_style: {
        alignment: {
            vertical: 'middle',
            horizontal: 'center'
        },
        font: {
            name: "宋体",
            size: 11,
            color: {
                argb: 'FF333333'
            }
        },
        border: {
            top: { style: 'thin', color: { argb: 'FF808080' } },
            bottom: { style: 'thin', color: { argb: 'FF808080' } },
            left: { style: 'thin', color: { argb: 'FF808080' } },
            right: { style: 'thin', color: { argb: 'FF808080' } }
        }
    },
    
    // 数据格式化配置
    format: [],
    
    // 数据列定义
    params: [],
    
    // 模板配置
    tpl: {
        head: "",   // 表头模板
        body: "",   // 表体模板
        foot: ""    // 表尾模板
    }
}

API 文档

核心方法

init(config)

初始化 Excel 配置

• 参数：
  • config: Object - 配置对象

load(func, nameOrId, toList = true)

读取 Excel 文件内容

• 参数：
  • func: Function - 可选，数据处理函数
  • nameOrId: String|Number - 工作表名称或索引
  • toList: Boolean - 是否转换为列表格式
• 返回：Promise - 数据列表

save(jarr, func, file)

保存数据到 Excel 文件

• 参数：
  • jarr: Array - 数据数组
  • func: Function - 可选，数据处理函数
  • file: String - 可选，保存的文件路径
• 返回：Promise - 保存成功返回文件路径

工作表操作

new_sheet(name, tpl)

创建新工作表

• 参数：
  • name: String - 工作表名称
  • tpl: Object - 可选，模板配置
• 返回：Promise

merge_sheet(sheet1, sheet2, bl = true)

合并两个工作表

• 参数：
  • sheet1: Worksheet - 目标工作表
  • sheet2: Worksheet - 源工作表
  • bl: Boolean - 是否保留源表样式
• 返回：Worksheet

单元格操作

set_cell_func(cell, style)

设置单元格特殊样式

• 参数：
  • cell: Cell - 单元格对象
  • style: Object - 样式对象

merge(posAB, value)

合并单元格

• 参数：
  • posAB: String - 单元格范围，如 'A1:B2'
  • value: any - 可选，合并后的单元格值

数据转换

convert(prop, key, value, name = 'name')

键值转换

• 参数：
  • prop: String - 属性名
  • key: String - 键名
  • value: any - 值
  • name: String - 结果字段名
• 返回：any

工具方法

colname(col)

获取列名

• 参数：
  • col: Number - 列序号
• 返回：String - 列名（如：'A', 'B', 'AA'等）

clear()

清理缓存数据

高级特性

模板使用

可以通过配置 tpl 属性使用 Excel 模板：

const config = {
    tpl: {
        head: "./tpl/head.xlsx",    // 表头模板
        body: "./tpl/body.xlsx",    // 表体模板
        foot: "./tpl/foot.xlsx"     // 表尾模板
    }
};

数据格式化

通过 format 配置实现数据格式化：

const config = {
    format: [
        {
            key: "status",
            list: ["启用", "禁用"],
            type: "number"
        }
    ]
};

自定义样式

可以通过 set_cell_func 实现自定义样式：

excel.set_cell_func = function(cell, style) {
    if (cell.value < 0) {
        cell.font = {
            color: { argb: 'FFFF0000' }
        };
    }
};

示例

基础读写

const Excel = require('mm_excel');

// 创建实例
const excel = new Excel({
    file: './data.xlsx'
});

// 读取数据
async function readExcel() {
    const data = await excel.load();
    console.log(data);
}

// 写入数据
async function writeExcel() {
    const data = [
        { name: '张三', age: 20 },
        { name: '李四', age: 25 }
    ];
    await excel.save(data);
}

使用模板

const config = {
    tpl: {
        head: './tpl/head.xlsx',
        body: './tpl/body.xlsx',
        foot: './tpl/foot.xlsx'
    },
    params: [
        {
            name: 'name',
            title: '姓名',
            type: 'string'
        },
        {
            name: 'age',
            title: '年龄',
            type: 'number'
        }
    ]
};

const excel = new Excel(config);

// 使用模板保存数据
async function saveWithTemplate() {
    const data = [
        { name: '张三', age: 20 },
        { name: '李四', age: 25 }
    ];
    await excel.save(data, null, './output.xlsx');
}

注意事项

1. 文件路径建议使用绝对路径
2. 大数据量操作时注意内存使用
3. 使用模板时确保模板文件存在
4. 保存前检查文件是否被其他程序占用

常见问题

1. 文件保存失败

   • 检查文件路径是否正确
   • 确认文件未被其他程序占用
   • 检查文件夹写入权限

2. 样式不生效

   • 检查样式配置格式
   • 确认单元格样式优先级

3. 数据格式化问题

   • 检查 format 配置
   • 确认数据类型匹配

更新日志

1.2.0

• 优化模板处理逻辑
• 增加样式配置选项
• 修复已知问题

许可证

ISC License