# pptx-generate-plugin

**Repository Path**: CRESCENT007/pptx-generate-plugin

## Basic Information

- **Project Name**: pptx-generate-plugin
- **Description**: cool-admin midway 后端插件开发脚手架，用于开发cool-admin后端插件，pptx生成插件
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://cool-js.com
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 13
- **Created**: 2026-02-04
- **Last Updated**: 2026-02-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PPTX 生成插件

基于 `pptx-automizer` 的 PowerPoint 文档自动生成插件，支持通过 JSON 数据文件和模板文件自动生成 PPTX 演示文稿。

## 介绍

该插件提供了便捷的 PPTX 文件生成功能，可以根据 JSON 数据文件和 PPTX 模板文件自动生成包含表格、图片、文本等元素的演示文稿。支持在 Cool-Admin 项目中作为插件使用，也支持命令行方式独立使用。

## 标识

调用插件的时候需要用到标识，标识是唯一的，不能重复，建议使用英文，不要使用中文，对应插件 `plugin.json` 中的 `key` 字段

- **标识**：`test`

## 安装

### 在 Cool-Admin 项目中使用

1. 将插件安装到 Cool-Admin 项目的 `src/plugin` 目录下
2. 在项目配置中启用插件


## 配置

插件配置文件 `plugin.json`：

```json
{
  "name": "PPTX生成插件",
  "key": "test",
  "version": "1.0.0",
  "description": "基于模板和数据文件生成PPTX文档",
  "config": {
    "appId": "@baseDir/1.md",
    "appSecret": "xxxxx",
    "filePath": "@baseDir/xxxxx"
  }
}
```

## API 方法

### generatePPTX

生成 PPTX 文件的核心方法。

```typescript
/**
 * 生成PPTX文件
 * @param templatePath 模板文件路径（.pptx文件）
 * @param dataPath 数据文件路径（JSON文件）
 * @param outputPath 输出文件路径（.pptx文件）
 * @returns Promise<void>
 */
async generatePPTX(templatePath: string, dataPath: string, outputPath: string): Promise<void>
```

**参数说明：**

- `templatePath`: PPTX 模板文件的完整路径
- `dataPath`: 包含数据的 JSON 文件路径
- `outputPath`: 生成的 PPTX 文件输出路径

**功能特性：**

- 自动检查模板文件和数据文件是否存在
- 自动创建输出目录（如果不存在）
- 支持错误处理和异常提示
- 自动处理文件路径和目录结构

## 使用示例

### 1. 在 Cool-Admin 项目中作为插件调用

```typescript
import { Inject } from '@midwayjs/core';
import { PluginService } from '@cool-midway/plugin';

export class YourService {
  @Inject()
  pluginService: PluginService;

  async generateReport() {
    // 获取插件实例
    const plugin = await this.pluginService.getInstance('test');
    
    // 初始化插件
    await plugin.ready();
    
    // 调用生成方法
    await plugin.generatePPTX(
      '/path/to/template.pptx',  // 模板文件路径
      '/path/to/data.json',       // 数据文件路径
      '/path/to/output.pptx'      // 输出文件路径
    );
  }
}
```

### 2. 命令行方式使用

```bash
# 编译项目
npm run build

# 运行命令行工具
node dist/src/cli.js <template.pptx> <input.json> [output.pptx]

# 示例
node dist/src/cli.js templates/template.pptx input/data.json output/result.pptx
```

**命令行参数：**

- `template.pptx`: 模板文件路径（必需）
- `input.json`: 数据文件路径（必需）
- `output.pptx`: 输出文件路径（可选，默认为 `output/result.pptx`）

### 3. 本地测试

使用项目自带的测试文件进行测试：

```bash
# 运行测试
npm run dev

# 或使用 ts-node 直接运行
npx ts-node test/index.ts
```

**测试文件配置** (`test/index.ts`)：

```typescript
import { Plugin } from "../src/index";
import pluginInfo from "../plugin.json";
import * as path from "path";

const instance = new Plugin();
instance.init(pluginInfo);

(async () => {
  await instance.ready();
  
  const templatePath = path.join(__dirname, "template.pptx");
  const dataPath = path.join(__dirname, "test1231.json");
  const outputPath = path.join(__dirname, "../output/result.pptx");
  
  await instance.generatePPTX(templatePath, dataPath, outputPath);
})();
```


## 注意事项

1. **文件路径**：确保模板文件和数据文件的路径正确，支持绝对路径和相对路径
2. **输出目录**：如果输出目录不存在，插件会自动创建
3. **文件权限**：确保对输出目录有写入权限
4. **文件占用**：生成文件时，确保目标文件没有被其他程序（如 PowerPoint）打开
5. **图片路径**：图片路径可以是相对路径（相对于 JSON 文件）或绝对路径
6. **JSON 格式**：确保 JSON 文件格式正确，否则会抛出解析错误

## 错误处理

插件会抛出以下类型的错误：

- **文件不存在错误**：模板文件或数据文件不存在
- **JSON 解析错误**：数据文件格式不正确
- **目录创建失败**：无法创建输出目录
- **文件生成失败**：PPTX 生成过程中的其他错误

建议在使用时使用 try-catch 进行错误处理：

```typescript
try {
  await plugin.generatePPTX(templatePath, dataPath, outputPath);
} catch (error) {
  console.error('生成失败:', error.message);
}
```

## 项目结构

```
pptx-generate-plugin/
├── src/
│   ├── index.ts           # 插件主文件（提供 generatePPTX 方法）
│   ├── cli.ts             # 命令行入口文件
│   └── generate_pptx.ts   # PPTX 生成核心逻辑
├── test/
│   ├── index.ts           # 测试文件
│   ├── template.pptx      # 测试模板文件
│   └── test1231.json      # 测试数据文件
├── dist/                  # 编译输出目录
├── plugin.json            # 插件配置文件
├── package.json           # 项目依赖配置
└── README.md              # 本文档
```



## 更新日志

### v1.0.0 (2024-12-XX)

- 初始版本
- 实现 `generatePPTX` 方法，支持通过参数传递模板文件、数据文件和输出路径
- 支持命令行方式使用
- 支持作为 Cool-Admin 插件使用
- 自动创建输出目录
- 完善的错误处理机制

## 许可证

MIT

## 相关链接

- [Cool-Admin 官网](https://cool-js.com)
- [插件开发文档](https://cool-js.com/admin/node/core/plugin.html#使用插件)
- [pptx-automizer 文档](https://github.com/singerla/pptx-automizer)