1
0

refactor: 重构文档结构,采用渐进式信息披露模式

将 README.md 拆分为多个专题文档,减少认知负荷:
- 用户文档迁移到 docs/ (用户指南、元素、模板、参考等)
- 开发文档迁移到 docs/development/ (架构、模块、规范)
- README.md 精简至 ~290 行,仅保留概览和导航
- 删除 README_DEV.md,内容已迁移
- 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
This commit is contained in:
2026-03-06 15:11:36 +08:00
parent 98098dc911
commit 124ef0e5ce
41 changed files with 5238 additions and 2228 deletions

141
docs/reference/colors.md Normal file
View File

@@ -0,0 +1,141 @@
# 颜色格式
yaml2pptx 支持两种十六进制颜色格式。
## 支持的格式
### 短格式 #RGB
3 位十六进制,每位颜色值重复一次:
```yaml
color: "#fff" # 白色 (#ffffff)
color: "#000" # 黑色 (#000000)
color: "#f00" # 红色 (#ff0000)
color: "#0f0" # 绿色 (#00ff00)
color: "#00f" # 蓝色 (#0000ff)
```
### 完整格式 #RRGGBB
6 位十六进制,标准的颜色表示:
```yaml
color: "#ffffff" # 白色
color: "#000000" # 黑色
color: "#ff0000" # 红色
color: "#00ff00" # 绿色
color: "#0000ff" # 蓝色
```
## 常用颜色参考
### 基础颜色
| 颜色 | 短格式 | 完整格式 |
|------|--------|----------|
| 黑色 | `#000` | `#000000` |
| 白色 | `#fff` | `#ffffff` |
| 红色 | `#f00` | `#ff0000` |
| 绿色 | `#0f0` | `#00ff00` |
| 蓝色 | `#00f` | `#0000ff` |
### 常用色彩
| 颜色 | 完整格式 | 说明 |
|------|----------|------|
| 灰色 | `#808080` | 中性灰 |
| 深灰 | `#333333` | 深灰色 |
| 浅灰 | `#cccccc` | 浅灰色 |
| 黄色 | `#ffff00` | 纯黄色 |
| 青色 | `#00ffff` | 纯青色 |
| 品红 | `#ff00ff` | 纯品红 |
### Material Design 色彩
| 颜色 | 完整格式 | 说明 |
|------|----------|------|
| 红色 | `#f44336` | Material Red |
| 粉色 | `#e91e63` | Material Pink |
| 紫色 | `#9c27b0` | Material Purple |
| 深紫 | `#673ab7` | Material Deep Purple |
| 靛蓝 | `#3f51b5` | Material Indigo |
| 蓝色 | `#2196f3` | Material Blue |
| 浅蓝 | `#03a9f4` | Material Light Blue |
| 青色 | `#00bcd4` | Material Cyan |
| 蓝绿 | `#009688` | Material Teal |
| 绿色 | `#4caf50` | Material Green |
| 浅绿 | `#8bc34a` | Material Light Green |
| 橙色 | `#ff9800` | Material Orange |
| 深橙 | `#ff5722` | Material Deep Orange |
## 使用示例
### 文本颜色
```yaml
- type: text
content: "红色文本"
font:
color: "#ff0000"
```
### 形状填充
```yaml
- type: shape
box: [1, 1, 4, 2]
shape: rectangle
fill: "#3498db" # 蓝色
```
### 边框颜色
```yaml
- type: shape
box: [1, 1, 4, 2]
shape: rectangle
fill: "#ffffff"
line:
color: "#000000"
width: 2
```
### 表格样式
```yaml
- type: table
position: [1, 1]
col_widths: [2, 2, 2]
data: [...]
style:
header_bg: "#4a90e2"
header_font:
color: "#ffffff"
```
## 颜色验证
系统会自动验证颜色格式:
- **短格式**`/#[0-9a-fA-F]{3}/`
- **完整格式**`/#[0-9a-fA-F]{6}/`
无效的颜色格式会导致验证错误:
```
[幻灯片 1, 元素 1] 无效的颜色格式: red (应为 #RRGGBB)
```
## 注意事项
- 颜色代码必须以 `#` 开头
- 不支持颜色名称(如 `red``blue`
- 不支持 RGB/RGBA 格式(如 `rgb(255, 0, 0)`
- 大小写均可(`#fff``#FFF` 等效)
## 相关文档
- [坐标系统](coordinates.md) - 位置和尺寸单位
[返回文档索引](../README.md)