# mm_excel

**Repository Path**: qiuwenwu91/mm_excel

## Basic Information

- **Project Name**: mm_excel
- **Description**: No description available
- **Primary Language**: NodeJS
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-02-17
- **Last Updated**: 2025-04-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mm_excel 开发文档

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

## 安装
```bash
npm install mm_excel
```

## 基础用法

### 初始化
```javascript
const Excel = require('mm_excel');

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

## 配置项说明

### 基础配置
```javascript
{
    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<Array> - 数据列表

#### save(jarr, func, file)
保存数据到 Excel 文件
- 参数：
  - jarr: Array - 数据数组
  - func: Function - 可选，数据处理函数
  - file: String - 可选，保存的文件路径
- 返回：Promise<String> - 保存成功返回文件路径

### 工作表操作

#### new_sheet(name, tpl)
创建新工作表
- 参数：
  - name: String - 工作表名称
  - tpl: Object - 可选，模板配置
- 返回：Promise<Worksheet>

#### 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 模板：
```javascript
const config = {
    tpl: {
        head: "./tpl/head.xlsx",    // 表头模板
        body: "./tpl/body.xlsx",    // 表体模板
        foot: "./tpl/foot.xlsx"     // 表尾模板
    }
};
```

### 数据格式化

通过 `format` 配置实现数据格式化：
```javascript
const config = {
    format: [
        {
            key: "status",
            list: ["启用", "禁用"],
            type: "number"
        }
    ]
};
```

### 自定义样式

可以通过 `set_cell_func` 实现自定义样式：
```javascript
excel.set_cell_func = function(cell, style) {
    if (cell.value < 0) {
        cell.font = {
            color: { argb: 'FFFF0000' }
        };
    }
};
```

## 示例

### 基础读写
```javascript
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);
}
```

### 使用模板
```javascript
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