Canva Connect

# Canva Connect

通过 Connect API 管理 Canva 设计、资源和文件夹。

## 此功能可以做什么（以及不能做什么）

| ✅ 可以做 | ❌ 不能做 | |-----------|--------------| | 列出/搜索设计 | 向设计添加内容 | | 创建空白设计 | 编辑现有设计内容 | | 导出设计 (PNG/PDF/JPG) | 上传文档（仅限图片） | | 创建/管理文件夹 | AI 生成设计 | | 在文件夹之间移动项目 | | | 上传图片作为资源 | | | 自动填充品牌模板 | |

## 实际用例

**1. 资源流水线** 🖼️ ``` Generate diagram → upload to Canva → organize in project folder ```

**2. 导出自动化** 📤 ``` Design finished in Canva → export via CLI → use in docs/website ```

**3. 设计整理** 📁 ``` Create project folders → move related designs → keep Canva tidy ```

**4. 品牌模板自动填充** 📋 ``` Set up template in Canva → pass data via API → get personalized output ```

## 快速开始

```bash # Authenticate (opens browser for OAuth) {baseDir}/scripts/canva.sh auth

# List your designs {baseDir}/scripts/canva.sh designs list

# Create a new design {baseDir}/scripts/canva.sh designs create --type doc --title "My Document"

# Export a design {baseDir}/scripts/canva.sh export <design_id> --format pdf ```

## 设置

### 1. 创建 Canva 集成

1. 前往 [canva.com/developers/integrations](https://canva.com/developers/integrations) 2. 点击 **Create an integration** 3. 设置作用域： - `design:content` (Read + Write) - `design:meta` (Read) - `asset` (Read + Write) - `brandtemplate:meta` (Read) - `brandtemplate:content` (Read) - `profile` (Read) 4. 设置 OAuth 重定向：`http://127.0.0.1:3001/oauth/redirect` 5. 记录 **Client ID** 并生成 **Client Secret**

### 2. 配置环境

添加到 `~/.clawdbot/clawdbot.json` 中的 `skills.entries` 下：

```json { "skills": { "entries": { "canva": { "clientId": "YOUR_CLIENT_ID", "clientSecret": "YOUR_CLIENT_SECRET" } } } } ```

或者设置环境变量： ```bash export CANVA_CLIENT_ID="your_client_id" export CANVA_CLIENT_SECRET="your_client_secret" ```

### 3. 身份验证

```bash {baseDir}/scripts/canva.sh auth ```

打开浏览器进行 OAuth 授权。Token 存储在 `~/.clawdbot/canva-tokens.json` 中。

## 命令

### 身份验证 | 命令 | 描述 | |---------|-------------| | `auth` | 启动 OAuth 流程（打开浏览器） | | `auth status` | 检查身份验证状态 | | `auth logout` | 清除存储的 Token |

### 设计 | 命令 | 描述 | |---------|-------------| | `designs list [--limit N]` | 列出你的设计 | | `designs get <id>` | 获取设计详情 | | `designs create --type <type> --title <title>` | 创建新设计 | | `designs delete <id>` | 将设计移至回收站 |

**设计类型：** `doc`, `presentation`, `whiteboard`, `poster`, `instagram_post`, `facebook_post`, `video`, `logo`, `flyer`, `banner`

### 导出 | 命令 | 描述 | |---------|-------------| | `export <design_id> --format <fmt>` | 导出设计 | | `export status <job_id>` | 检查导出任务状态 |

**格式：** `pdf`, `png`, `jpg`, `gif`, `pptx`, `mp4`

### 资源 | 命令 | 描述 | |---------|-------------| | `assets list` | 列出已上传的资源 | | `assets upload <file> [--name <name>]` | 上传资源 | | `assets get <id>` | 获取资源详情 | | `assets delete <id>` | 删除资源 |

### 品牌模板 | 命令 | 描述 | |---------|-------------| | `templates list` | 列出品牌模板 | | `templates get <id>` | 获取模板详情 | | `autofill <template_id> --data <json>` | 使用数据自动填充模板 |

### 文件夹 | 命令 | 描述 | |---------|-------------| | `folders list` | 列出文件夹 | | `folders create <name>` | 创建文件夹 | | `folders get <id>` | 获取文件夹内容 |

### 用户 | 命令 | 描述 | |---------|-------------| | `me` | 获取当前用户资料 |

## 示例

### 创建并导出海报 ```bash # Create {baseDir}/scripts/canva.sh designs create --type poster --title "Event Poster"

# Export as PNG {baseDir}/scripts/canva.sh export DAF... --format png --output ./poster.png ```

### 上传品牌资源 ```bash # Upload logo {baseDir}/scripts/canva.sh assets upload ./logo.png --name "Company Logo"

# Upload multiple for f in ./brand/*.png; do {baseDir}/scripts/canva.sh assets upload "$f" done ```

### 自动填充模板 ```bash # List available templates {baseDir}/scripts/canva.sh templates list

# Autofill with data {baseDir}/scripts/canva.sh autofill TEMPLATE_ID --data '{ "title": "Q1 Report", "subtitle": "Financial Summary", "date": "January 2026" }' ```

## API 参考

Base URL: `https://api.canva.com/rest`

详细端点文档请参阅 [references/api.md](references/api.md)。

## 故障排除

### Token 已过期 ```bash {baseDir}/scripts/canva.sh auth # Re-authenticate ```

### 速率限制 API 对每个端点都有速率限制。脚本会自动处理退避重试。

### 缺少作用域 如果操作失败并返回 403，请确保你的集成已启用所需的作用域。

## 数据文件

| 文件 | 用途 | |------|---------| | `~/.clawdbot/canva-tokens.json` | OAuth Token（加密） | | `~/.clawdbot/canva-cache.json` | 响应缓存 |