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

View File

@@ -0,0 +1,154 @@
# 坐标系统
yaml2pptx 使用英寸inch作为位置和尺寸的单位。
## 基本概念
- **单位**:英寸 (inch)
- **原点**:幻灯片左上角 (0, 0)
- **方向**X 轴向右Y 轴向下
## 幻灯片尺寸
### 16:9 宽高比
- 尺寸10" × 5.625"
- 宽度10 英寸
- 高度5.625 英寸
### 4:3 宽高比
- 尺寸10" × 7.5"
- 宽度10 英寸
- 高度7.5 英寸
## box 属性
`box` 属性用于指定元素的位置和尺寸:
```yaml
box: [x, y, width, height]
```
| 参数 | 说明 | 单位 |
|------|------|------|
| `x` | 左上角 X 坐标 | 英寸 |
| `y` | 左上角 Y 坐标 | 英寸 |
| `width` | 元素宽度 | 英寸 |
| `height` | 元素高度 | 英寸 |
## 示例
```yaml
# 位置:(1", 2"),尺寸:宽 8",高 1"
box: [1, 2, 8, 1]
```
这表示:
- 元素左上角位于 (1", 2")
- 元素宽度为 8"
- 元素高度为 1"
## position 属性(表格)
表格元素使用 `position` 属性指定位置:
```yaml
position: [x, y]
```
| 参数 | 说明 | 单位 |
|------|------|------|
| `x` | 左上角 X 坐标 | 英寸 |
| `y` | 左上角 Y 坐标 | 英寸 |
## 定位示例
### 居中文本
```yaml
# 16:9 幻灯片
# 宽度 10",要居中一个 8" 宽的元素
# x = (10 - 8) / 2 = 1
- type: text
box: [1, 2, 8, 1]
content: "居中文本"
font:
align: center
```
### 全屏背景
```yaml
# 16:9 幻灯片
- type: shape
box: [0, 0, 10, 5.625] # 完全覆盖
shape: rectangle
fill: "#ffffff"
```
### 四个象限
```yaml
slides:
- elements:
# 左上象限
- type: text
box: [0.25, 0.25, 4.5, 2.5]
content: "左上"
# 右上象限
- type: text
box: [5.25, 0.25, 4.5, 2.5]
content: "右上"
# 左下象限
- type: text
box: [0.25, 3, 4.5, 2.5]
content: "左下"
# 右下象限
- type: text
box: [5.25, 3, 4.5, 2.5]
content: "右下"
```
## 坐标计算
### 水平居中
```python
x = (slide_width - element_width) / 2
```
### 垂直居中
```python
y = (slide_height - element_height) / 2
```
### 完全居中
```yaml
# 16:9 幻灯片,居中 4" × 2" 的元素
# x = (10 - 4) / 2 = 3
# y = (5.625 - 2) / 2 = 1.8125
- type: shape
box: [3, 1.8125, 4, 2]
shape: rectangle
fill: "#3498db"
```
## 注意事项
- 所有坐标和尺寸必须为正数
- 元素可以超出页面边界(会发出警告)
- 浮点数精度建议保留 2-3 位小数
## 相关文档
- [颜色格式](colors.md) - 颜色表示方法
[返回文档索引](../README.md)