refactor: 重构文档结构，采用渐进式信息披露模式
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
This commit is contained in:
17
docs/elements/_index.md
Normal file
17
docs/elements/_index.md
Normal file
@@ -0,0 +1,17 @@
|
||||
# 元素类型文档
|
||||
|
||||
本目录包含各种元素类型的详细说明。
|
||||
|
||||
## 元素类型
|
||||
|
||||
- [文本元素](text.md) - 文本框和字体配置
|
||||
- [图片元素](image.md) - 图片插入和配置
|
||||
- [形状元素](shape.md) - 几何形状绘制
|
||||
- [表格元素](table.md) - 表格创建和样式
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [字体主题系统](../fonts.md) - 字体配置和主题管理
|
||||
- [坐标系统](../reference/coordinates.md) - 位置和尺寸单位
|
||||
|
||||
[返回文档索引](../README.md)
|
||||
100
docs/elements/image.md
Normal file
100
docs/elements/image.md
Normal file
@@ -0,0 +1,100 @@
|
||||
# 图片元素
|
||||
|
||||
图片元素用于在幻灯片中插入图片。
|
||||
|
||||
## 基本语法
|
||||
|
||||
```yaml
|
||||
- type: image
|
||||
box: [x, y, width, height]
|
||||
src: "path/to/image.png" # 支持相对路径和绝对路径
|
||||
```
|
||||
|
||||
## 属性
|
||||
|
||||
| 属性 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `type` | 字符串 | 是 | 必须为 "image" |
|
||||
| `box` | 数组 | 是 | 位置和尺寸 [x, y, width, height]（英寸） |
|
||||
| `src` | 字符串 | 是 | 图片文件路径 |
|
||||
|
||||
## 图片路径
|
||||
|
||||
支持相对路径和绝对路径：
|
||||
|
||||
```yaml
|
||||
# 相对路径（相对于 YAML 文件位置）
|
||||
- type: image
|
||||
src: "images/logo.png"
|
||||
box: [1, 1, 2, 2]
|
||||
|
||||
# 绝对路径
|
||||
- type: image
|
||||
src: "/Users/username/pictures/photo.jpg"
|
||||
box: [1, 1, 4, 3]
|
||||
```
|
||||
|
||||
## 示例
|
||||
|
||||
### 基本图片
|
||||
|
||||
```yaml
|
||||
slides:
|
||||
- elements:
|
||||
- type: image
|
||||
src: "photo.jpg"
|
||||
box: [1, 1, 4, 3]
|
||||
```
|
||||
|
||||
### 多个图片
|
||||
|
||||
```yaml
|
||||
slides:
|
||||
- elements:
|
||||
- type: image
|
||||
src: "logo.png"
|
||||
box: [0.5, 0.5, 2, 2]
|
||||
|
||||
- type: image
|
||||
src: "banner.jpg"
|
||||
box: [3, 0.5, 6.5, 2]
|
||||
```
|
||||
|
||||
### 与文本组合
|
||||
|
||||
```yaml
|
||||
slides:
|
||||
- elements:
|
||||
- type: text
|
||||
content: "项目 Logo"
|
||||
box: [1, 3, 3, 0.5]
|
||||
font:
|
||||
size: 24
|
||||
align: center
|
||||
|
||||
- type: image
|
||||
src: "logo.png"
|
||||
box: [1, 3.5, 3, 3]
|
||||
```
|
||||
|
||||
## 支持的格式
|
||||
|
||||
支持常见图片格式，包括：
|
||||
- PNG (.png)
|
||||
- JPEG (.jpg, .jpeg)
|
||||
- GIF (.gif)
|
||||
- BMP (.bmp)
|
||||
- 其他 PowerPoint 支持的格式
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 图片路径相对于 YAML 文件位置
|
||||
- 建议使用高分辨率图片以获得最佳显示效果
|
||||
- 图片会按照 box 指定的尺寸进行缩放
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [坐标系统](../reference/coordinates.md) - 位置和尺寸单位
|
||||
- [形状元素](shape.md) - 几何形状绘制
|
||||
|
||||
[返回文档索引](../README.md)
|
||||
139
docs/elements/shape.md
Normal file
139
docs/elements/shape.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# 形状元素
|
||||
|
||||
形状元素用于在幻灯片中绘制几何形状。
|
||||
|
||||
## 基本语法
|
||||
|
||||
```yaml
|
||||
- type: shape
|
||||
box: [x, y, width, height]
|
||||
shape: rectangle # rectangle/ellipse/rounded_rectangle
|
||||
fill: "#4a90e2" # 填充颜色
|
||||
line:
|
||||
color: "#000000" # 边框颜色
|
||||
width: 2 # 边框宽度（磅）
|
||||
```
|
||||
|
||||
## 属性
|
||||
|
||||
| 属性 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `type` | 字符串 | 是 | 必须为 "shape" |
|
||||
| `box` | 数组 | 是 | 位置和尺寸 [x, y, width, height]（英寸） |
|
||||
| `shape` | 字符串 | 是 | 形状类型 |
|
||||
| `fill` | 字符串 | 否 | 填充颜色（#RRGGBB 或 #RGB） |
|
||||
| `line` | 对象 | 否 | 边框配置 |
|
||||
|
||||
## 形状类型
|
||||
|
||||
### rectangle（矩形）
|
||||
|
||||
```yaml
|
||||
- type: shape
|
||||
box: [1, 1, 4, 2]
|
||||
shape: rectangle
|
||||
fill: "#4a90e2"
|
||||
```
|
||||
|
||||
### ellipse（椭圆）
|
||||
|
||||
```yaml
|
||||
- type: shape
|
||||
box: [1, 1, 4, 2]
|
||||
shape: ellipse
|
||||
fill: "#e74c3c"
|
||||
```
|
||||
|
||||
### rounded_rectangle（圆角矩形）
|
||||
|
||||
```yaml
|
||||
- type: shape
|
||||
box: [1, 1, 4, 2]
|
||||
shape: rounded_rectangle
|
||||
fill: "#2ecc71"
|
||||
```
|
||||
|
||||
## 边框配置
|
||||
|
||||
```yaml
|
||||
line:
|
||||
color: "#000000" # 边框颜色
|
||||
width: 2 # 边框宽度（磅）
|
||||
```
|
||||
|
||||
## 示例
|
||||
|
||||
### 简单矩形
|
||||
|
||||
```yaml
|
||||
slides:
|
||||
- elements:
|
||||
- type: shape
|
||||
box: [1, 1, 4, 2]
|
||||
shape: rectangle
|
||||
fill: "#4a90e2"
|
||||
```
|
||||
|
||||
### 带边框的形状
|
||||
|
||||
```yaml
|
||||
slides:
|
||||
- elements:
|
||||
- type: shape
|
||||
box: [1, 1, 4, 2]
|
||||
shape: rectangle
|
||||
fill: "#ffffff"
|
||||
line:
|
||||
color: "#000000"
|
||||
width: 2
|
||||
```
|
||||
|
||||
### 多个形状组合
|
||||
|
||||
```yaml
|
||||
slides:
|
||||
- elements:
|
||||
# 背景矩形
|
||||
- type: shape
|
||||
box: [0, 0, 10, 5.625]
|
||||
shape: rectangle
|
||||
fill: "#f5f5f5"
|
||||
|
||||
# 装饰圆形
|
||||
- type: shape
|
||||
box: [1, 1, 2, 2]
|
||||
shape: ellipse
|
||||
fill: "#3498db"
|
||||
|
||||
# 文本
|
||||
- type: text
|
||||
box: [3.5, 1.5, 5, 1]
|
||||
content: "欢迎"
|
||||
font:
|
||||
size: 44
|
||||
```
|
||||
|
||||
### 无填充形状
|
||||
|
||||
```yaml
|
||||
- type: shape
|
||||
box: [1, 1, 4, 2]
|
||||
shape: rectangle
|
||||
fill: "transparent" # 透明填充
|
||||
line:
|
||||
color: "#000000"
|
||||
width: 2
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 形状会按照 box 指定的尺寸进行绘制
|
||||
- 填充颜色和边框颜色使用相同的格式
|
||||
- 边框宽度单位为磅（pt）
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [坐标系统](../reference/coordinates.md) - 位置和尺寸单位
|
||||
- [颜色格式](../reference/colors.md) - 颜色表示方法
|
||||
|
||||
[返回文档索引](../README.md)
|
||||
147
docs/elements/table.md
Normal file
147
docs/elements/table.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# 表格元素
|
||||
|
||||
表格元素用于在幻灯片中创建表格。
|
||||
|
||||
## 基本语法
|
||||
|
||||
```yaml
|
||||
- type: table
|
||||
position: [x, y]
|
||||
col_widths: [2, 2, 2] # 每列宽度（英寸）
|
||||
data:
|
||||
- ["表头1", "表头2", "表头3"]
|
||||
- ["数据1", "数据2", "数据3"]
|
||||
- ["数据4", "数据5", "数据6"]
|
||||
font:
|
||||
family: "Arial"
|
||||
size: 14
|
||||
color: "#333333"
|
||||
header_font:
|
||||
bold: true
|
||||
color: "#ffffff"
|
||||
style:
|
||||
header_bg: "#4a90e2"
|
||||
```
|
||||
|
||||
## 属性
|
||||
|
||||
| 属性 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `type` | 字符串 | 是 | 必须为 "table" |
|
||||
| `position` | 数组 | 是 | 表格位置 [x, y]（英寸） |
|
||||
| `col_widths` | 数组 | 是 | 每列宽度（英寸） |
|
||||
| `data` | 数组 | 是 | 表格数据（二维数组） |
|
||||
| `font` | 对象 | 否 | 数据单元格字体样式 |
|
||||
| `header_font` | 对象 | 否 | 表头单元格字体样式 |
|
||||
| `style` | 对象 | 否 | 表格样式 |
|
||||
|
||||
## 字体配置
|
||||
|
||||
### font（数据单元格）
|
||||
|
||||
数据单元格的字体样式：
|
||||
|
||||
```yaml
|
||||
font:
|
||||
family: "Arial"
|
||||
size: 14
|
||||
color: "#333333"
|
||||
bold: false
|
||||
```
|
||||
|
||||
### header_font（表头单元格）
|
||||
|
||||
表头单元格的字体样式。如果未定义，继承 `font` 的配置：
|
||||
|
||||
```yaml
|
||||
header_font:
|
||||
bold: true
|
||||
color: "#ffffff"
|
||||
# 其他属性继承自 font
|
||||
```
|
||||
|
||||
### style（表格样式）
|
||||
|
||||
```yaml
|
||||
style:
|
||||
header_bg: "#4a90e2" # 表头背景色
|
||||
```
|
||||
|
||||
## 示例
|
||||
|
||||
### 基本表格
|
||||
|
||||
```yaml
|
||||
slides:
|
||||
- elements:
|
||||
- type: table
|
||||
position: [1, 1]
|
||||
col_widths: [2, 2, 2]
|
||||
data:
|
||||
- ["姓名", "年龄", "城市"]
|
||||
- ["张三", "25", "北京"]
|
||||
- ["李四", "30", "上海"]
|
||||
```
|
||||
|
||||
### 样式化表格
|
||||
|
||||
```yaml
|
||||
slides:
|
||||
- elements:
|
||||
- type: table
|
||||
position: [1, 1]
|
||||
col_widths: [2.5, 2.5, 2.5]
|
||||
data:
|
||||
- ["产品", "价格", "库存"]
|
||||
- ["产品A", "100元", "50"]
|
||||
- ["产品B", "200元", "30"]
|
||||
font:
|
||||
family: "sans"
|
||||
size: 14
|
||||
color: "#333333"
|
||||
header_font:
|
||||
bold: true
|
||||
color: "#ffffff"
|
||||
style:
|
||||
header_bg: "#3498db"
|
||||
```
|
||||
|
||||
### 使用字体主题
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
fonts:
|
||||
table-font:
|
||||
family: "sans"
|
||||
size: 14
|
||||
color: "#333333"
|
||||
|
||||
slides:
|
||||
- elements:
|
||||
- type: table
|
||||
position: [1, 1]
|
||||
col_widths: [2, 2, 2]
|
||||
data:
|
||||
- ["列1", "列2"]
|
||||
- ["数据1", "数据2"]
|
||||
font: "@table-font"
|
||||
header_font:
|
||||
parent: "@table-font"
|
||||
bold: true
|
||||
color: "#ffffff"
|
||||
style:
|
||||
header_bg: "#4a90e2"
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- `col_widths` 数组长度必须与每行的列数一致
|
||||
- 所有行的列数必须相同
|
||||
- 第一行默认为表头
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [字体主题系统](../fonts.md) - 字体配置和主题管理
|
||||
- [坐标系统](../reference/coordinates.md) - 位置和尺寸单位
|
||||
|
||||
[返回文档索引](../README.md)
|
||||
121
docs/elements/text.md
Normal file
121
docs/elements/text.md
Normal file
@@ -0,0 +1,121 @@
|
||||
# 文本元素
|
||||
|
||||
文本元素用于在幻灯片中添加文本内容。
|
||||
|
||||
## 基本语法
|
||||
|
||||
```yaml
|
||||
- type: text
|
||||
box: [x, y, width, height] # 位置和尺寸（英寸）
|
||||
content: "文本内容"
|
||||
font:
|
||||
size: 18 # 字号（磅）
|
||||
bold: true # 粗体
|
||||
italic: false # 斜体
|
||||
color: "#ff0000" # 颜色
|
||||
align: center # left/center/right
|
||||
```
|
||||
|
||||
## 字体属性
|
||||
|
||||
### 基础属性
|
||||
|
||||
| 属性 | 类型 | 说明 | 默认值 |
|
||||
|------|------|------|--------|
|
||||
| `size` | 数字 | 字号（磅） | 18 |
|
||||
| `bold` | 布尔 | 粗体 | false |
|
||||
| `italic` | 布尔 | 斜体 | false |
|
||||
| `color` | 字符串 | 颜色（#RRGGBB 或 #RGB） | #000000 |
|
||||
| `align` | 字符串 | 对齐方式 | left |
|
||||
| `family` | 字符串 | 字体族或预设类别 | Arial |
|
||||
|
||||
### 对齐方式
|
||||
|
||||
- `left` - 左对齐
|
||||
- `center` - 居中对齐
|
||||
- `right` - 右对齐
|
||||
|
||||
### 高级字体样式
|
||||
|
||||
- `underline` - 下划线（true/false）
|
||||
- `strikethrough` - 删除线（true/false）
|
||||
|
||||
### 段落属性
|
||||
|
||||
- `line_spacing` - 行距倍数（如 1.5）
|
||||
- `space_before` - 段前间距（磅）
|
||||
- `space_after` - 段后间距（磅）
|
||||
|
||||
### 高级属性
|
||||
|
||||
- `baseline` - 基线位置（normal/superscript/subscript）
|
||||
- `caps` - 大小写转换（normal/allcaps/smallcaps）
|
||||
|
||||
## 示例
|
||||
|
||||
### 简单文本
|
||||
|
||||
```yaml
|
||||
slides:
|
||||
- elements:
|
||||
- type: text
|
||||
box: [1, 1, 8, 1]
|
||||
content: "Hello, World!"
|
||||
font:
|
||||
size: 44
|
||||
bold: true
|
||||
```
|
||||
|
||||
### 多行文本
|
||||
|
||||
```yaml
|
||||
- type: text
|
||||
box: [1, 1, 8, 2]
|
||||
content: "第一行\n第二行\n第三行"
|
||||
font:
|
||||
size: 18
|
||||
```
|
||||
|
||||
### 样式化文本
|
||||
|
||||
```yaml
|
||||
- type: text
|
||||
box: [1, 1, 8, 1]
|
||||
content: "标题文本"
|
||||
font:
|
||||
size: 32
|
||||
bold: true
|
||||
color: "#2c3e50"
|
||||
underline: true
|
||||
```
|
||||
|
||||
### 使用字体主题
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
fonts:
|
||||
title:
|
||||
family: "cjk-sans"
|
||||
size: 44
|
||||
bold: true
|
||||
color: "#2c3e50"
|
||||
|
||||
slides:
|
||||
- elements:
|
||||
- type: text
|
||||
content: "标题文本"
|
||||
box: [1, 1, 8, 1]
|
||||
font: "@title" # 引用字体主题
|
||||
```
|
||||
|
||||
## 特性
|
||||
|
||||
文本框默认启用自动换行，文字超出宽度时会自动换行。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [字体主题系统](../fonts.md) - 字体配置和主题管理
|
||||
- [坐标系统](../reference/coordinates.md) - 位置和尺寸单位
|
||||
- [颜色格式](../reference/colors.md) - 颜色表示方法
|
||||
|
||||
[返回文档索引](../README.md)
|
||||
Reference in New Issue
Block a user