ooodc
a7883dbed9
- 移除 TodoItem 中的 priority、created_at 和 updated_at 字段 - 强制每个任务都必须有唯一 id，且由用户负责生成 - 修改合并模式逻辑，merge=true 下保留未提及的旧任务 - 支持已完成和已取消任务重新激活（状态改回 pending 或 in_progress） - 禁止 in_progress 状态退回到 pending，必须标记为 completed 或 cancelled - 优化状态转换校验，允许特定状态间合法切换 - 简化任务变更消息，移除详细的新增/更新/移除统计 - 更新文档和示例，明确 id 必须由用户生成和使用 - 修复和补充测试，增强状态转换和合并模式验证 - 调整任务时间戳生成逻辑，统一使用当前时间及索引 - 该变更提供更合理的任务状态机械及管理模式，提升稳定性和易用性
246 lines
7.2 KiB
Markdown
246 lines
7.2 KiB
Markdown
# XML Schema 快速参考
|
||
|
||
本文档是 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) 的精简版摘要；如果两者不一致，以 XSD 原文为准。
|
||
|
||
## 最重要的规则
|
||
|
||
1. 协议标准写法应使用 `<presentation xmlns="http://www.larkoffice.com/sml/2.0">`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证
|
||
2. `<presentation>` 直接子元素只有 `<title>`、`<theme>`、`<slide>`
|
||
3. `<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`
|
||
4. 页面中的文本通常通过 `<content>` 表达，而不是把 `<title>`、`<body>` 直接挂在 `<slide>` 下
|
||
|
||
## 最小可用示例
|
||
|
||
```xml
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
|
||
<slide>
|
||
<data>
|
||
<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
|
||
<content textType="title">
|
||
<p>标题</p>
|
||
</content>
|
||
</shape>
|
||
</data>
|
||
</slide>
|
||
</presentation>
|
||
```
|
||
|
||
## presentation 根元素
|
||
|
||
| 属性 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `width` | 是 | 演示文稿宽度，正整数 |
|
||
| `height` | 是 | 演示文稿高度，正整数 |
|
||
| `id` | 否 | 演示文稿标识 |
|
||
|
||
**子元素：** `<title>?`, `<theme>?`, `<slide>+`
|
||
|
||
## slide 元素
|
||
|
||
| 属性 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `id` | 否 | 幻灯片标识 |
|
||
|
||
**子元素：**
|
||
- `<style>?` - 页面样式，目前可放 `<fill>`
|
||
- `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`chart`、`whiteboard`、`undefined`
|
||
- `<note>?` - 演讲者备注，内部可放 `<content>`
|
||
|
||
## theme 与文本类型
|
||
|
||
XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出现在：
|
||
|
||
- `<theme><textStyles>...</textStyles></theme>` 中，作为主题文本样式
|
||
- `<content textType="...">` 中，作为内容的文本类型
|
||
|
||
`textStyles` 的 schema 默认值如下：
|
||
|
||
| textType | 默认字号 |
|
||
|----------|----------|
|
||
| `title` | 54 |
|
||
| `headline` | 38 |
|
||
| `sub-headline` | 32 |
|
||
| `body` | 16 |
|
||
| `caption` | 12 |
|
||
|
||
## content 内容模型
|
||
|
||
`<content>` 可出现在 `shape`、`table/td`、`note` 中，常用属性包括：
|
||
|
||
| 属性 | 说明 |
|
||
|------|------|
|
||
| `textType` | `title` / `headline` / `sub-headline` / `body` / `caption` |
|
||
| `textAlign` | 文本对齐方式 |
|
||
| `lineSpacing` | 行间距，schema 默认 `multiple:1.5` |
|
||
| `fontSize` | 字号 |
|
||
| `fontFamily` | 字体 |
|
||
| `color` | 字体颜色 |
|
||
| `bold` / `italic` / `underline` / `strikethrough` | 文本样式 |
|
||
|
||
`<content>` 的子元素只能是：
|
||
|
||
- `<p>`
|
||
- `<ul>`
|
||
- `<ol>`
|
||
|
||
### content 示例
|
||
|
||
```xml
|
||
<content textType="body" textAlign="left">
|
||
<p>正文内容 <strong>加粗</strong> <em>斜体</em> <a href="https://example.com">链接</a></p>
|
||
<ul>
|
||
<li><p>列表项 1</p></li>
|
||
<li><p>列表项 2</p></li>
|
||
</ul>
|
||
</content>
|
||
```
|
||
|
||
## data 常用元素
|
||
|
||
### shape
|
||
|
||
```xml
|
||
<shape type="rect" topLeftX="120" topLeftY="120" width="240" height="120">
|
||
<fill>
|
||
<fillColor color="rgb(100, 149, 237)"/>
|
||
</fill>
|
||
<border color="rgb(0, 0, 0)" width="2"/>
|
||
</shape>
|
||
```
|
||
|
||
| 属性 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `type` | 是 | 形状类型，`text` 表示文本框 |
|
||
| `topLeftX` | 是 | 左上角 X 坐标 |
|
||
| `topLeftY` | 是 | 左上角 Y 坐标 |
|
||
| `width` | 是 | 宽度 |
|
||
| `height` | 是 | 高度 |
|
||
| `rotation` | 否 | 旋转角度 |
|
||
|
||
### line
|
||
|
||
```xml
|
||
<line startX="120" startY="120" endX="420" endY="120">
|
||
<border color="rgb(43, 47, 54)" width="2"/>
|
||
</line>
|
||
```
|
||
|
||
### img
|
||
|
||
```xml
|
||
<img src="file_token_or_url" topLeftX="80" topLeftY="120" width="320" height="180"/>
|
||
```
|
||
|
||
`src` 只支持：`slides +media-upload` 返回的 `file_token`，或 `@<本地路径>` 占位符（仅 `+create --slides` 自动上传并替换）。**禁止使用 http(s) 外链 URL**——飞书 slides 渲染端不会代理外链图，外链 src 在 PPT 里通常不显示。本地图片详见 [lark-slides-create.md](lark-slides-create.md#本地图片path-占位符) / [lark-slides-media-upload.md](lark-slides-media-upload.md)。
|
||
|
||
> **注意**：`width`/`height` 是**裁剪后**的显示尺寸。比例和原图不一致时会自动裁剪（无法靠属性关闭），想避免裁剪就让 `width:height` 对齐原图比例。
|
||
|
||
### icon
|
||
|
||
```xml
|
||
<icon iconType="iconpark/Base/setting.svg" topLeftX="80" topLeftY="120" width="32" height="32"/>
|
||
```
|
||
|
||
`iconType` 必须来自已验证的 IconPark 路径。需要语义图标时，先运行 `scripts/iconpark_tool.py search --query "<语义>"`，不要凭记忆拼路径。更多规则见 [iconpark.md](iconpark.md)。
|
||
|
||
### whiteboard
|
||
|
||
```xml
|
||
<!-- SVG 模式：数据图表、装饰元素 -->
|
||
<whiteboard topLeftX="580" topLeftY="120" width="340" height="280">
|
||
<svg xmlns="http://www.w3.org/2000/svg">
|
||
<rect x="60" y="80" width="40" height="140" rx="3" fill="rgba(59,130,246,0.85)"/>
|
||
<text x="80" y="238" text-anchor="middle" font-size="11" fill="rgba(100,116,139,1)">ABC</text>
|
||
</svg>
|
||
</whiteboard>
|
||
|
||
<!-- Mermaid 模式：流程图、时序图等结构化图表 -->
|
||
<whiteboard topLeftX="72" topLeftY="100" width="816" height="340">
|
||
<mermaid>
|
||
<![CDATA[
|
||
flowchart LR
|
||
A[开始] --> B{判断}
|
||
B -- 是 --> C[执行]
|
||
B -- 否 --> D[结束]
|
||
]]>
|
||
</mermaid>
|
||
</whiteboard>
|
||
```
|
||
|
||
SVG 模式：`<svg>` 需声明 `xmlns="http://www.w3.org/2000/svg"`，内容大小由子元素包围盒决定；`width`/`height`/`viewBox` 不影响渲染，仅当元素使用百分比属性值时需声明 `viewBox`。\
|
||
Mermaid 模式：内容用 `<![CDATA[...]]>` 包裹，避免 `[`、`>`、`-->` 等字符破坏 XML 解析。\
|
||
详细用法见 [lark-slides-whiteboard.md](lark-slides-whiteboard.md)。
|
||
|
||
## 颜色与样式
|
||
|
||
### fill
|
||
|
||
```xml
|
||
<fill>
|
||
<fillColor color="rgb(255, 0, 0)"/>
|
||
</fill>
|
||
```
|
||
|
||
### border
|
||
|
||
```xml
|
||
<border color="rgb(43, 47, 54)" width="2" dashArray="solid"/>
|
||
```
|
||
|
||
### 颜色格式
|
||
|
||
```xml
|
||
<fillColor color="rgb(255, 0, 0)"/>
|
||
<fillColor color="rgba(255, 0, 0, 0.5)"/>
|
||
<fillColor color="linear-gradient(90deg, rgb(255,0,0) 0%, rgb(0,0,255) 100%)"/>
|
||
<fillColor color="radial-gradient(circle at 50% 50%, rgb(255,0,0) 0%, rgb(0,0,255) 100%)"/>
|
||
```
|
||
|
||
> **注意**：渐变色必须使用 `rgba()` 格式并带百分比停靠点，例如 `linear-gradient(135deg,rgba(30,60,114,1) 0%,rgba(59,130,246,1) 100%)`。使用 `rgb()` 或省略停靠点会导致服务端将其回退为白色。此规则对页面背景和 shape fill 均适用。
|
||
|
||
### 页面背景
|
||
|
||
```xml
|
||
<!-- 纯色背景 -->
|
||
<slide>
|
||
<style>
|
||
<fill>
|
||
<fillColor color="rgb(245, 245, 245)"/>
|
||
</fill>
|
||
</style>
|
||
</slide>
|
||
|
||
<!-- 渐变背景（必须用 rgba + 百分比停靠点） -->
|
||
<slide>
|
||
<style>
|
||
<fill>
|
||
<fillColor color="linear-gradient(135deg,rgba(30,60,114,1) 0%,rgba(59,130,246,1) 100%)"/>
|
||
</fill>
|
||
</style>
|
||
</slide>
|
||
```
|
||
|
||
## 备注示例
|
||
|
||
```xml
|
||
<note>
|
||
<content textType="body">
|
||
<p>这是演讲者备注。</p>
|
||
</content>
|
||
</note>
|
||
```
|
||
|
||
## 详细参考
|
||
|
||
- [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)
|
||
- [xml-format-guide.md](xml-format-guide.md)
|
||
- [examples.md](examples.md)
|
||
- [slides_demo.xml](slides_demo.xml)
|
||
|
||
## Schema 版本信息
|
||
|
||
- **版本**: 2.0.0
|
||
- **命名空间**: http://www.larkoffice.com/sml/2.0
|
||
- **发布日期**: 2025-11-03
|