`、`<theme>`、`<slide>` 3. `<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>` 4. 页面中的文本通常通过 `<content>` 表达，而不是把 `<title>`、`<body>` 直接挂在 `<slide>` 下 ## 最小可用示例 ```xml <presentation xmlns="https://www.larkoffice.com/sml/2.0" width="960" height="540"> <slide> <data> <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"> <content autoFit="normal-auto-fit" wrap="true" textType="title"> <p>标题</p> </content> </shape> </data> </slide> </presentation> ``` ## presentation 根元素 | 属性 | 必需 | 说明 | |------|------|------| | `width` | 是 | 演示文稿宽度，正整数，标准 16:9 页面建议使用 `960` | | `height` | 是 | 演示文稿高度，正整数，标准 16:9 页面建议使用 `540` | | `id` | 否 | 演示文稿标识 | **子元素：** `<title>?`, `<theme>?`, `<slide>+` `<slide>` 至少 1 页，最多 100 页。 ## theme 与文本类型 `<theme>` 当前包含两部分： - `<background>`：演示文稿级背景填充 - `<textStyles>`：主题文本样式集合 `<textStyles>` 下可选子元素包括 `<title>`、`<headline>`、`<sub-headline>`、`<body>`、`<caption>`。这些元素定义的是主题默认样式，不是页面结构。常用属性： | 属性 | 说明 | |------|------| | `fontFamily` | 字体 | | `fontSize` | 字号 | | `fontColor` | 字体颜色 | 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 | 默认字号是省略 `fontSize` 时的兜底字号，不是推荐值。字号必须显式设置 `<content>` 的 `fontSize` 属性，不要依赖 `textType` 的默认字号兜底，这些兜底值明显偏大。 ## slide 元素 | 属性 | 必需 | 说明 | |------|------|------| | `id` | 否 | 幻灯片标识 | **子元素：** - `<style>?` - 页面样式，目前可放 `<fill>` - `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`embed`、`chart`、`undefined` - `<note>?` - 演讲者备注，内部可放 `<content>` 这意味着 `<title>`、`<headline>`、`<body>`、`<caption>` 不能直接放在 `<slide>` 下。 ## content 内容模型 `<content>` 可出现在 `shape`、`table/td`、`note` 中，常用属性包括： | 属性 | 说明 | |------|------| | `textType` | `title` / `headline` / `sub-headline` / `body` / `caption` | | `verticalAlign` | 垂直对齐 | | `textAlign` | 文本对齐方式 | | `lineSpacing` | 行间距，schema 默认 `multiple:1.5` | | `fontSize` | 字号 | | `fontFamily` | 字体 | | `color` | 字体颜色 | | `bold` / `italic` / `underline` / `strikethrough` | 内容级样式 | | `wrap` | 是否自动换行 | | `autoFit` | 是否自动缩排 | 注意事项： - 字号必须显式设置 `<content>` 的 `fontSize` 属性，不要依赖 `textType` 的默认字号兜底，这些兜底值明显偏大。 - 大数字、字号大或字数多的 `<content>` 必须设置 `wrap="true" autoFit="normal-auto-fit"` 属性自动换行和缩排，避免文字溢出。 - 文字颜色必须用 `<content>` 的 `color` 属性而不是 `fontColor` 属性。 - 文字行间距必须设置 `<content>` 的 `lineSpacing="multiple:xx"` 或 `lineSpacing="fixed:xx"` 而不是 `lineSpacing="xx"`。 `<content>` 直接子元素只有： - `<p>` - `<ul>` - `<ol>` ### p 段落与内联标签 `<p>` 是段落元素，可混排纯文本和内联标签： - `<br/>` - `<strong>` - `<em>` - `<u>` - `<span>` - `<del>` - `<a>` - `<shadow>` - `<outline>` - `<formula>` 公式写法： ```xml <p>公式：<formula><latex><![CDATA[ E = mc^2 ]]></latex></formula></p> ``` `<formula>` 是内联元素；当前只支持一个 `<latex>` 子元素。LaTeX 内容必须放在 `CDATA` 中，且 `CDATA` 内不要写 XML 转义；宏只使用服务端支持范围内的写法，优先用基础运算符、`\frac`、`\sqrt`、`matrix`。示例： ```xml <content autoFit="normal-auto-fit" 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 常用元素所有页面元素都放在 `<data>` 中。 ### shape `shape` 可表示普通形状，也可表示文本框。文本框推荐使用 `type="text"`。 ```xml <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"> <content textType="title"> <p>主标题</p> </content> </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> ``` `<shape type="rect">` 只是形状不是容器，`<icon>`、`<img>`、`<shape type="text">` 和其他 `<shape>` 必须与它平级靠坐标叠放。 | 属性 | 必需 | 说明 | |------|------|------| | `type` | 是 | 形状类型，`text` 表示文本框 | | `topLeftX` | 是 | 左上角 X 坐标 | | `topLeftY` | 是 | 左上角 Y 坐标 | | `width` | 是 | 宽度 | | `height` | 是 | 高度 | | `rotation` | 否 | 旋转角度 | | `flipX` / `flipY` | 否 | 翻转 | | `alpha` | 否 | 透明度 | 可选子元素： - `<fill>` - `<border>` - `<reflection>` - `<shadow>` - `<content>` `type` 常用取值：`text`（文本框）、`rect`、`round-rect`（圆角矩形）、`ellipse`（椭圆/圆）、`triangle`、`diamond`、`parallelogram`、`trapezoid`、`custom`（配合 `path` 属性写 SVG 路径串）。箭头、星形、标注气泡、`chevron`、`flow-chart-*` 等更多形状见 XSD `ShapeType` 枚举。其它可选属性： - `presetHandlers`：控制点，用于圆角等。例如 `<shape type="rect" presetHandlers="60">` = 圆角半径 60px 的圆角矩形；多个控制点用逗号分隔。 - `path`：仅 `type="custom"` 时使用，SVG 路径串。 ### line ```xml <line startX="120" startY="120" endX="420" endY="120"> <border color="rgb(43, 47, 54)" width="2"/> </line> ``` `line` 使用的是 `startX` / `startY` / `endX` / `endY`，不是 `x1` / `y1` / `x2` / `y2`。 ### polyline 折线 / 曲线连接线，用外接矩形定位（`topLeftX` / `topLeftY` / `width` / `height`），不是端点坐标；`<border>` 必填（无 border 不可见）。`type` 默认 `bent-connector2`（可选 `bent-connector2-5` 折线 / `curved-connector2-5` 曲线）。 ```xml <polyline topLeftX="120" topLeftY="120" width="200" height="100"> <border color="rgb(43, 47, 54)" width="2"/> </polyline> ``` ### img ```xml <img src="file_token_或_@本地路径" topLeftX="80" topLeftY="120" width="320" height="180"/> ``` `img` 使用 `topLeftX` / `topLeftY`，不是 `x` / `y`。 `src` 只支持：`slides +media-upload` 返回的 `file_token`，或 `@<本地路径>` 占位符（`+create --slides` 和 `+add-slide` 会自动上传并替换）。**禁止使用 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)。本地图片的两种姿势： - 新建带图 PPT：`+create --slides` 里直接写 `src="@./pic.png"`，CLI 在创空白 PPT 后、加 slides 前自动上传并替换 token - 给已有 PPT 加带图新页：`+add-slide --slide` 的 XML 里直接写 `src="@./pic.png"`，CLI 上传后替换 token 再提交页面 > **注意**：`width`/`height` 是**裁剪后**的显示尺寸。比例和原图不一致时会自动裁剪（无法靠属性关闭），想避免裁剪就让 `width:height` 对齐原图比例。 ### icon ```xml <icon iconType="iconpark/Charts/chart-line.svg" topLeftX="80" topLeftY="120" width="32" height="32"> <fill> <fillColor color="rgba(37, 99, 235, 1)"/> </fill> </icon> ``` 图标必须填充颜色并和背景有足够对比。禁止盲猜 iconType，必须先检索 IconPark，再写 `<icon iconType="...">`。检索方式和更多规则见 [iconpark.md](iconpark.md)。 ### table 表格结构为： - `<table>` 直接子元素只有 `<colgroup>` 和 `<tr>`，`width` 和 `height` 分别表示表格的目标总宽度和总高度。 - `<colgroup>` 直接子元素只有 `<col width="...">`，width 定义列宽，默认 110。 - `<tr height="...">` 直接子元素只有 `<td>`，height 定义行高，默认 37。 - `<td>` 直接子元素只有 `<fill>`（背景）、`<content>`（文字）和边框配置（一般不用），不能嵌套 `<shape>`、`<img>`、`<icon>`。 - 合并单元格：`<td>` 上用 `colspan`（跨列，默认 1）和 `rowspan`（跨行，默认 1）；被合并覆盖的单元格不再写对应 `<td>`。表头默认的白底白字视觉效果极差，必须设置背景和文字颜色，需在首行每个 `<td>` 上加 `<fill>`（配合 `bold` 与对比文字色）与正文行区分。表格里的文字默认是居中对齐，可以设置 `textAlign` 调整对齐方式。表格宽高设置： - 已设置的列宽和行高优先保留，未设置的列宽、行高会使用表格的目标总宽度、总高度分配剩余空间 - **必须设置 `<table>` 的 `width` 和 `height` 固定表格大小，同时设置需要保留列宽或行高的 `<col>` 的 `width` 和 `<tr>` 的 `height`，其余自动分配。** 不同字号的行高参考： | `fontSize` | 内容行数 | 紧凑 `height` | 适中 `height` | 宽松 `height` | |------|------|------|------|------| | 10 | 单行 | 16 | 20 | 24 | | 12 | 单行 | 20 | 24 | 28 | | 10 | 双行 | 32 | 36 | 42 | | 12 | 双行 | 36 | 42 | 48 | 示例： ```xml <table topLeftX="80" topLeftY="140" width="520" height="52"> <colgroup> <col width="160"/> <col width="120"/> <col /> </colgroup> <tr height="28"> <td> <fill><fillColor color="rgba(30,60,114,1)"/></fill> <content textType="body" fontSize="12" bold="true" color="rgba(255,255,255,1)" textAlign="center"><p>项目</p></content> </td> <td> <fill><fillColor color="rgba(30,60,114,1)"/></fill> <content textType="body" fontSize="12" bold="true" color="rgba(255,255,255,1)" textAlign="right"><p>营收</p></content> </td> <td> <fill><fillColor color="rgba(30,60,114,1)"/></fill> <content textType="body" fontSize="12" bold="true" color="rgba(255,255,255,1)" textAlign="left"><p>备注说明</p></content> </td> </tr> <tr> <td><content textType="body" fontSize="10" textAlign="center"><p>线上业务</p></content></td> <td><content textType="body" fontSize="10" textAlign="right"><p>195</p></content></td> <td><content textType="body" fontSize="10" textAlign="left"><p>同比增长 8%，主要来自新客</p></content></td> </tr> </table> ``` ### chart 图表语法十分复杂，必须阅读 [slides_chart_demo.xml](slides_chart_demo.xml)，直接照抄其中的柱状、条形、折线、面积、饼（环）、雷达、组合图。 `<chart>` 直接子元素必须有 `<chartPlotArea>`（绘图区）和 `<chartData>`（数据）；`<chartTitle>`、`<chartSubTitle>`、`<chartStyle>`、`<chartLegend>`、`<chartTooltip>` 可选，如果想不展示标题、副标题、图例或悬浮提示，省略相应元素标签即可。 `<chartStyle>` 常用子元素： - `<chartBackground>`：`color` 省略时由渲染端决定默认背景；需要完全透明请显式写 `color="rgba(0, 0, 0, 0)"` - `<chartBorder>`：无边框可写 `width="0"`，或直接不写 `<chartBorder>` 元素 #### 图表渐变 `<fillGradient>` / `<strokeGradient>` 图表支持渐变填充/描边，`<fillGradient>` 用于面积、柱子、数据点、扇区填充，`<strokeGradient>` 用于线条、数据点边框、柱子边框。渐变只能挂在系列级或单元素级，不要挂在 `<chartPlot>` 全局层。可挂载位置： - 系列级：`<chartBars>` / `<chartPoints>` 支持 `<fillGradient>` 与 `<strokeGradient>`；`<chartLine>` 只支持 `<strokeGradient>`；`<chartArea>` / `<chartSectors>` 只支持 `<fillGradient>` - 单元素级：`<chartBar index="...">` / `<chartPoint index="...">` / `<chartSector index="...">` 只支持 `<fillGradient>` - 全局级：`<chartPlot>` 下的 `<chartLines>` / `<chartAreas>` / `<chartBars>` / `<chartPoints>` 不支持渐变结构要点：`type` 必填，可为 `linear` 或 `radial`；`linear` 用 `x0` / `y0` / `x1` / `y1`，`radial` 用 `r0` / `r1`；`<stops>` 至少包含 2 个 `<stop>`，`offset` 与 `opacity` 取值均为 `[0, 1]`。 ```xml <chartSeries index="1"> <chartBars> <fillGradient type="linear" x0="0" y0="0" x1="0" y1="1"> <stops> <stop offset="0" color="rgb(28, 71, 120)"/> <stop offset="1" color="rgb(28, 71, 120)" opacity="0.3"/> </stops> </fillGradient> </chartBars> </chartSeries> ``` 隐藏 `<chart>` 的图例只能通过不写或删除 `<chartLegend>` 实现，`<chartLegend>` 不支持 `position="none"`。详细用法见 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)。 ### embed 嵌入内容容器：外层 `<embed>` 承载 Slides 的摆放和效果属性（`topLeftX`/`topLeftY`/`width`/`height` 必填，`rotation`/`flipX`/`flipY`/`alpha` 可选），内层承载外部标准内容。当前内层内容为标准 SVG，`<svg>` 必须使用 `http://www.w3.org/2000/svg` 命名空间，且仅描述嵌入内容本身，不承载 Slides 布局属性。 ```xml <embed topLeftX="80" topLeftY="120" width="200" height="120"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 120"> <circle cx="100" cy="60" r="40" fill="rgba(37, 99, 235, 1)"/> </svg> </embed> ``` `<embed>` 直接子元素为一个 `<svg>`（必需），以及可选的 `<reflection>`（倒影）与 `<shadow>`（阴影）。 ## 颜色与样式 ### 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>  <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 autoFit="normal-auto-fit" textType="body"> <p>这是演讲者备注。</p> </content> </note> ``` ## 完整示例 ```xml <presentation xmlns="https://www.larkoffice.com/sml/2.0" width="960" height="540"> <title>季度报告

# XML Schema 快速参考本文档是 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) 的精简版摘要，并合并了常用 XML 格式写法；如果两者不一致，以 XSD 原文为准。 ## 最重要的规则 1. 协议标准写法应使用 ``；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证 2. `` 直接子元素只有 ``、`<theme>`、`<slide>` 3. `<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>` 4. 页面中的文本通常通过 `<content>` 表达，而不是把 `<title>`、`<body>` 直接挂在 `<slide>` 下 ## 最小可用示例 ```xml <presentation xmlns="https://www.larkoffice.com/sml/2.0" width="960" height="540"> <slide> <data> <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"> <content autoFit="normal-auto-fit" wrap="true" textType="title"> <p>标题</p> </content> </shape> </data> </slide> </presentation> ``` ## presentation 根元素 | 属性 | 必需 | 说明 | |------|------|------| | `width` | 是 | 演示文稿宽度，正整数，标准 16:9 页面建议使用 `960` | | `height` | 是 | 演示文稿高度，正整数，标准 16:9 页面建议使用 `540` | | `id` | 否 | 演示文稿标识 | **子元素：** `<title>?`, `<theme>?`, `<slide>+` `<slide>` 至少 1 页，最多 100 页。 ## theme 与文本类型 `<theme>` 当前包含两部分： - `<background>`：演示文稿级背景填充 - `<textStyles>`：主题文本样式集合 `<textStyles>` 下可选子元素包括 `<title>`、`<headline>`、`<sub-headline>`、`<body>`、`<caption>`。这些元素定义的是主题默认样式，不是页面结构。常用属性： | 属性 | 说明 | |------|------| | `fontFamily` | 字体 | | `fontSize` | 字号 | | `fontColor` | 字体颜色 | 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 | 默认字号是省略 `fontSize` 时的兜底字号，不是推荐值。字号必须显式设置 `<content>` 的 `fontSize` 属性，不要依赖 `textType` 的默认字号兜底，这些兜底值明显偏大。 ## slide 元素 | 属性 | 必需 | 说明 | |------|------|------| | `id` | 否 | 幻灯片标识 | **子元素：** - `<style>?` - 页面样式，目前可放 `<fill>` - `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`embed`、`chart`、`undefined` - `<note>?` - 演讲者备注，内部可放 `<content>` 这意味着 `<title>`、`<headline>`、`<body>`、`<caption>` 不能直接放在 `<slide>` 下。 ## content 内容模型 `<content>` 可出现在 `shape`、`table/td`、`note` 中，常用属性包括： | 属性 | 说明 | |------|------| | `textType` | `title` / `headline` / `sub-headline` / `body` / `caption` | | `verticalAlign` | 垂直对齐 | | `textAlign` | 文本对齐方式 | | `lineSpacing` | 行间距，schema 默认 `multiple:1.5` | | `fontSize` | 字号 | | `fontFamily` | 字体 | | `color` | 字体颜色 | | `bold` / `italic` / `underline` / `strikethrough` | 内容级样式 | | `wrap` | 是否自动换行 | | `autoFit` | 是否自动缩排 | 注意事项： - 字号必须显式设置 `<content>` 的 `fontSize` 属性，不要依赖 `textType` 的默认字号兜底，这些兜底值明显偏大。 - 大数字、字号大或字数多的 `<content>` 必须设置 `wrap="true" autoFit="normal-auto-fit"` 属性自动换行和缩排，避免文字溢出。 - 文字颜色必须用 `<content>` 的 `color` 属性而不是 `fontColor` 属性。 - 文字行间距必须设置 `<content>` 的 `lineSpacing="multiple:xx"` 或 `lineSpacing="fixed:xx"` 而不是 `lineSpacing="xx"`。 `<content>` 直接子元素只有： - `<p>` - `<ul>` - `<ol>` ### p 段落与内联标签 `<p>` 是段落元素，可混排纯文本和内联标签： - `<br/>` - `<strong>` - `<em>` - `<u>` - `<span>` - `<del>` - `<a>` - `<shadow>` - `<outline>` - `<formula>` 公式写法： ```xml <p>公式：<formula><latex><![CDATA[ E = mc^2 ]]></latex></formula></p> ``` `<formula>` 是内联元素；当前只支持一个 `<latex>` 子元素。LaTeX 内容必须放在 `CDATA` 中，且 `CDATA` 内不要写 XML 转义；宏只使用服务端支持范围内的写法，优先用基础运算符、`\frac`、`\sqrt`、`matrix`。示例： ```xml <content autoFit="normal-auto-fit" 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 常用元素所有页面元素都放在 `<data>` 中。 ### shape `shape` 可表示普通形状，也可表示文本框。文本框推荐使用 `type="text"`。 ```xml <shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"> <content textType="title"> <p>主标题</p> </content> </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> ``` `<shape type="rect">` 只是形状不是容器，`<icon>`、`<img>`、`<shape type="text">` 和其他 `<shape>` 必须与它平级靠坐标叠放。 | 属性 | 必需 | 说明 | |------|------|------| | `type` | 是 | 形状类型，`text` 表示文本框 | | `topLeftX` | 是 | 左上角 X 坐标 | | `topLeftY` | 是 | 左上角 Y 坐标 | | `width` | 是 | 宽度 | | `height` | 是 | 高度 | | `rotation` | 否 | 旋转角度 | | `flipX` / `flipY` | 否 | 翻转 | | `alpha` | 否 | 透明度 | 可选子元素： - `<fill>` - `<border>` - `<reflection>` - `<shadow>` - `<content>` `type` 常用取值：`text`（文本框）、`rect`、`round-rect`（圆角矩形）、`ellipse`（椭圆/圆）、`triangle`、`diamond`、`parallelogram`、`trapezoid`、`custom`（配合 `path` 属性写 SVG 路径串）。箭头、星形、标注气泡、`chevron`、`flow-chart-*` 等更多形状见 XSD `ShapeType` 枚举。其它可选属性： - `presetHandlers`：控制点，用于圆角等。例如 `<shape type="rect" presetHandlers="60">` = 圆角半径 60px 的圆角矩形；多个控制点用逗号分隔。 - `path`：仅 `type="custom"` 时使用，SVG 路径串。 ### line ```xml <line startX="120" startY="120" endX="420" endY="120"> <border color="rgb(43, 47, 54)" width="2"/> </line> ``` `line` 使用的是 `startX` / `startY` / `endX` / `endY`，不是 `x1` / `y1` / `x2` / `y2`。 ### polyline 折线 / 曲线连接线，用外接矩形定位（`topLeftX` / `topLeftY` / `width` / `height`），不是端点坐标；`<border>` 必填（无 border 不可见）。`type` 默认 `bent-connector2`（可选 `bent-connector2-5` 折线 / `curved-connector2-5` 曲线）。 ```xml <polyline topLeftX="120" topLeftY="120" width="200" height="100"> <border color="rgb(43, 47, 54)" width="2"/> </polyline> ``` ### img ```xml <img src="file_token_或_@本地路径" topLeftX="80" topLeftY="120" width="320" height="180"/> ``` `img` 使用 `topLeftX` / `topLeftY`，不是 `x` / `y`。 `src` 只支持：`slides +media-upload` 返回的 `file_token`，或 `@<本地路径>` 占位符（`+create --slides` 和 `+add-slide` 会自动上传并替换）。**禁止使用 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)。本地图片的两种姿势： - 新建带图 PPT：`+create --slides` 里直接写 `src="@./pic.png"`，CLI 在创空白 PPT 后、加 slides 前自动上传并替换 token - 给已有 PPT 加带图新页：`+add-slide --slide` 的 XML 里直接写 `src="@./pic.png"`，CLI 上传后替换 token 再提交页面 > **注意**：`width`/`height` 是**裁剪后**的显示尺寸。比例和原图不一致时会自动裁剪（无法靠属性关闭），想避免裁剪就让 `width:height` 对齐原图比例。 ### icon ```xml <icon iconType="iconpark/Charts/chart-line.svg" topLeftX="80" topLeftY="120" width="32" height="32"> <fill> <fillColor color="rgba(37, 99, 235, 1)"/> </fill> </icon> ``` 图标必须填充颜色并和背景有足够对比。禁止盲猜 iconType，必须先检索 IconPark，再写 `<icon iconType="...">`。检索方式和更多规则见 [iconpark.md](iconpark.md)。 ### table 表格结构为： - `<table>` 直接子元素只有 `<colgroup>` 和 `<tr>`，`width` 和 `height` 分别表示表格的目标总宽度和总高度。 - `<colgroup>` 直接子元素只有 `<col width="...">`，width 定义列宽，默认 110。 - `<tr height="...">` 直接子元素只有 `<td>`，height 定义行高，默认 37。 - `<td>` 直接子元素只有 `<fill>`（背景）、`<content>`（文字）和边框配置（一般不用），不能嵌套 `<shape>`、`<img>`、`<icon>`。 - 合并单元格：`<td>` 上用 `colspan`（跨列，默认 1）和 `rowspan`（跨行，默认 1）；被合并覆盖的单元格不再写对应 `<td>`。表头默认的白底白字视觉效果极差，必须设置背景和文字颜色，需在首行每个 `<td>` 上加 `<fill>`（配合 `bold` 与对比文字色）与正文行区分。表格里的文字默认是居中对齐，可以设置 `textAlign` 调整对齐方式。表格宽高设置： - 已设置的列宽和行高优先保留，未设置的列宽、行高会使用表格的目标总宽度、总高度分配剩余空间 - **必须设置 `<table>` 的 `width` 和 `height` 固定表格大小，同时设置需要保留列宽或行高的 `<col>` 的 `width` 和 `<tr>` 的 `height`，其余自动分配。** 不同字号的行高参考： | `fontSize` | 内容行数 | 紧凑 `height` | 适中 `height` | 宽松 `height` | |------|------|------|------|------| | 10 | 单行 | 16 | 20 | 24 | | 12 | 单行 | 20 | 24 | 28 | | 10 | 双行 | 32 | 36 | 42 | | 12 | 双行 | 36 | 42 | 48 | 示例： ```xml <table topLeftX="80" topLeftY="140" width="520" height="52"> <colgroup> <col width="160"/> <col width="120"/> <col /> </colgroup> <tr height="28"> <td> <fill><fillColor color="rgba(30,60,114,1)"/></fill> <content textType="body" fontSize="12" bold="true" color="rgba(255,255,255,1)" textAlign="center"><p>项目</p></content> </td> <td> <fill><fillColor color="rgba(30,60,114,1)"/></fill> <content textType="body" fontSize="12" bold="true" color="rgba(255,255,255,1)" textAlign="right"><p>营收</p></content> </td> <td> <fill><fillColor color="rgba(30,60,114,1)"/></fill> <content textType="body" fontSize="12" bold="true" color="rgba(255,255,255,1)" textAlign="left"><p>备注说明</p></content> </td> </tr> <tr> <td><content textType="body" fontSize="10" textAlign="center"><p>线上业务</p></content></td> <td><content textType="body" fontSize="10" textAlign="right"><p>195</p></content></td> <td><content textType="body" fontSize="10" textAlign="left"><p>同比增长 8%，主要来自新客</p></content></td> </tr> </table> ``` ### chart 图表语法十分复杂，必须阅读 [slides_chart_demo.xml](slides_chart_demo.xml)，直接照抄其中的柱状、条形、折线、面积、饼（环）、雷达、组合图。 `<chart>` 直接子元素必须有 `<chartPlotArea>`（绘图区）和 `<chartData>`（数据）；`<chartTitle>`、`<chartSubTitle>`、`<chartStyle>`、`<chartLegend>`、`<chartTooltip>` 可选，如果想不展示标题、副标题、图例或悬浮提示，省略相应元素标签即可。 `<chartStyle>` 常用子元素： - `<chartBackground>`：`color` 省略时由渲染端决定默认背景；需要完全透明请显式写 `color="rgba(0, 0, 0, 0)"` - `<chartBorder>`：无边框可写 `width="0"`，或直接不写 `<chartBorder>` 元素 #### 图表渐变 `<fillGradient>` / `<strokeGradient>` 图表支持渐变填充/描边，`<fillGradient>` 用于面积、柱子、数据点、扇区填充，`<strokeGradient>` 用于线条、数据点边框、柱子边框。渐变只能挂在系列级或单元素级，不要挂在 `<chartPlot>` 全局层。可挂载位置： - 系列级：`<chartBars>` / `<chartPoints>` 支持 `<fillGradient>` 与 `<strokeGradient>`；`<chartLine>` 只支持 `<strokeGradient>`；`<chartArea>` / `<chartSectors>` 只支持 `<fillGradient>` - 单元素级：`<chartBar index="...">` / `<chartPoint index="...">` / `<chartSector index="...">` 只支持 `<fillGradient>` - 全局级：`<chartPlot>` 下的 `<chartLines>` / `<chartAreas>` / `<chartBars>` / `<chartPoints>` 不支持渐变结构要点：`type` 必填，可为 `linear` 或 `radial`；`linear` 用 `x0` / `y0` / `x1` / `y1`，`radial` 用 `r0` / `r1`；`<stops>` 至少包含 2 个 `<stop>`，`offset` 与 `opacity` 取值均为 `[0, 1]`。 ```xml <chartSeries index="1"> <chartBars> <fillGradient type="linear" x0="0" y0="0" x1="0" y1="1"> <stops> <stop offset="0" color="rgb(28, 71, 120)"/> <stop offset="1" color="rgb(28, 71, 120)" opacity="0.3"/> </stops> </fillGradient> </chartBars> </chartSeries> ``` 隐藏 `<chart>` 的图例只能通过不写或删除 `<chartLegend>` 实现，`<chartLegend>` 不支持 `position="none"`。详细用法见 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)。 ### embed 嵌入内容容器：外层 `<embed>` 承载 Slides 的摆放和效果属性（`topLeftX`/`topLeftY`/`width`/`height` 必填，`rotation`/`flipX`/`flipY`/`alpha` 可选），内层承载外部标准内容。当前内层内容为标准 SVG，`<svg>` 必须使用 `http://www.w3.org/2000/svg` 命名空间，且仅描述嵌入内容本身，不承载 Slides 布局属性。 ```xml <embed topLeftX="80" topLeftY="120" width="200" height="120"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 120"> <circle cx="100" cy="60" r="40" fill="rgba(37, 99, 235, 1)"/> </svg> </embed> ``` `<embed>` 直接子元素为一个 `<svg>`（必需），以及可选的 `<reflection>`（倒影）与 `<shadow>`（阴影）。 ## 颜色与样式 ### 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>  <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 autoFit="normal-auto-fit" textType="body"> <p>这是演讲者备注。</p> </content> </note> ``` ## 完整示例 ```xml <presentation xmlns="https://www.larkoffice.com/sml/2.0" width="960" height="540"> <title>季度报告 <body fontFamily="思源黑体" fontSize="18" fontColor="rgba(43, 47, 54, 1)"/> </textStyles> </theme> <slide> <style> <fill> <fillColor color="rgb(245, 245, 245)"/> </fill> </style> <data> <shape type="text" topLeftX="80" topLeftY="72" width="760" height="100"> <content textType="title"> <p>2024 年第一季度报告</p> </content> </shape> <shape type="text" topLeftX="80" topLeftY="200" width="520" height="180"> <content textType="body"> <p>核心指标</p> <ul> <li><p>用户增长：+25%</p></li> <li><p>收入增长：+30%</p></li> <li><p>市场份额：15%</p></li> </ul> </content> </shape> <shape type="rect" topLeftX="660" topLeftY="180" width="180" height="140"> <fill> <fillColor color="rgba(100, 149, 237, 0.25)"/> </fill> <border color="rgb(100, 149, 237)" width="2"/> </shape> </data> <note> <content textType="body"> <p>讲到增长率时补充样本范围。</p> </content> </note> </slide> </presentation> ``` ## 最佳实践 1. 始终带上命名空间 `xmlns="https://www.larkoffice.com/sml/2.0"` 2. 用 `shape type="text"` + `content` 表达页面文本 3. 用 `topLeftX` / `topLeftY`、`startX` / `startY` 等 schema 中定义的属性名 4. 优先使用 `rgb` / `rgba` 颜色格式；渐变必须使用 `rgba()` 且带百分比停靠点 5. 特殊字符按 XML 规则转义 6. 标准 16:9 页面建议使用 `width="960"` 和 `height="540"` ## 详细参考 - [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) - [slides_chart_demo.xml](slides_chart_demo.xml) ## Schema 版本信息 - **版本**: 2.0.0 - **命名空间**: https://www.larkoffice.com/sml/2.0 - **发布日期**: 2025-11-03