介绍
# TRMNL Content Generator
为 TRMNL 电子墨水屏设备生成 HTML 内容。
## 前置条件
**将 `trmnl` CLI 安装到最新版本：** ```bash npm install -g trmnl-cli@latest ```
**配置一个 webhook 插件（一次性设置）：** ```bash # Add a plugin trmnl plugin add home "https://trmnl.com/api/custom_plugins/{uuid}"
# Verify it's configured trmnl plugin ```
## 快速开始工作流
1. **安装/更新 CLI：** 运行 `npm install -g trmnl-cli@latest` 2. **检查插件：** 运行 `trmnl plugin` - 如果没有，提示用户添加一个 3. 确认设备类型（默认：TRMNL OG, 2-bit, 800x480） 4. 根据内容需求阅读相关参考文档 5. 使用 TRMNL 框架类生成 HTML 6. 将 HTML 写入临时文件并发送： ```bash trmnl send --file /tmp/trmnl-content.html # Or to a specific plugin: trmnl send --file /tmp/trmnl-content.html --plugin office ``` 7. **仅进行最小确认** - 不要将内容回显到聊天中
## 发送内容
**从文件发送（推荐）：** ```bash # Write HTML content to file first cat > /tmp/trmnl-content.html << 'EOF' <div class="layout layout--col gap--space-between"> <div class="item"> <span class="value value--xlarge value--tnums">Hello TRMNL!</span> </div> </div> <div class="title_bar"> <span class="title">My Plugin</span> </div> EOF
# Send to display trmnl send --file /tmp/trmnl-content.html ```
**发送前验证：** ```bash trmnl validate --file /tmp/trmnl-content.html ```
**查看发送历史：** ```bash trmnl history trmnl history --today trmnl history --failed ```
## Webhook 限制
| 等级 | 载荷大小 | 速率限制 | |------|--------------|------------| | Free | **2 KB** (2,048 bytes) | 12 requests/hour | | TRMNL+ | **5 KB** (5,120 bytes) | 30 requests/hour |
全局设置等级以进行准确验证： ```bash trmnl tier plus # or "free" ```
## 参考文档
根据需要阅读这些文件：
| 文件 | 何时阅读 | |------|--------------| | `references/patterns.md` | **从这里开始** - 常用插件模式 | | `references/framework-overview.md` | 设备规格，电子墨水屏限制 | | `references/css-utilities.md` | 颜色、排版、尺寸、间距 | | `references/layout-systems.md` | Flexbox、Grid、溢出引擎 | | `references/components.md` | 标题栏、分隔线、项目、表格 | | `references/webhook-api.md` | 载荷格式、故障排除 | | `assets/anti-patterns.md` | 需避免的常见错误 |
## 标准插件结构
**每个插件都遵循此模式：**
```html <div class="layout layout--col gap--space-between"> <!-- Content sections separated by dividers --> </div> <div class="title_bar"> <img class="image" src="icon.svg"> <span class="title">Plugin Name</span> <span class="instance">Context</span> </div> ```
- `layout` + `layout--col` = 垂直 Flex 容器 - `gap--space-between` = 将各部分推至边缘 - `title_bar` = 始终位于底部，在布局之外 - `divider` = 分隔主要部分 - **关键：** 每个视图仅限一个 `.layout` 元素
## 快速参考
### 网格系统（10 列）
```html <div class="grid"> <div class="col--span-3">30%</div> <div class="col--span-7">70%</div> </div> ```
### 项目组件
```html <div class="item"> <div class="content"> <span class="value value--xlarge value--tnums">$159,022</span> <span class="label">Total Sales</span> </div> </div> ```
### 数值排版
**数字请务必使用 `value--tnums`。**
| 类 | 用法 | |-------|-------| | `value--xxxlarge` | 核心 KPI | | `value--xxlarge` | 大号价格 | | `value--xlarge` | 次要指标 | | `value--tnums` | **数字必需** |
### 灰度类
使用抖动类，而不是内联颜色： - `bg--black`, `bg--gray-60`, `bg--gray-30`, `bg--gray-10`, `bg--white` - `text--black`, `text--gray-50`
### 数据属性
| 属性 | 目的 | |-----------|---------| | `data-fit-value="true"` | 自动调整文本大小以适应 | | `data-clamp="N"` | 限制为 N 行 | | `data-overflow="true"` | 启用溢出管理 |
## 最佳实践
1. 使用 `layout` + `title_bar` 结构 2. 数字始终使用 `value--tnums` 3. 在主要指标上使用 `data-fit-value` 4. 使用 `bg--gray-*` 抖动类 5. 保持载荷在等级限制之下 6. **最小确认** - 仅输出“Sent to TRMNL”
## 故障排除
| 问题 | 解决方案 | |---------|----------| | `trmnl: command not found` | 运行 `npm install -g trmnl-cli@latest` | | 未配置插件 | 运行 `trmnl plugin add <name> <url>` | | Webhook 失败 | 运行 `trmnl config` - 验证插件 URL | | 载荷过大 | 运行 `trmnl validate --file` - 检查大小 | | 数字未对齐 | 添加 `value--tnums` 类 | | 发送历史 | 运行 `trmnl history --failed` |