AxTps/Starlight_Lancher
2
2
Fork 1
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
50d62d8564c53ceed0e8868d166f661a2e60823c
Starlight_Lancher/.agents/skills/lark-slides/references/xml-schema-quick-ref.md

17 KiB
Raw Blame History

XML Schema 快速参考

本文档是 slides_xml_schema_definition.xml 的精简版摘要，并合并了常用 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 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 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、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>

公式写法：

<p>公式：<formula><latex><![CDATA[ E = mc^2 ]]></latex></formula></p>

<formula> 是内联元素；当前只支持一个 <latex> 子元素。LaTeX 内容必须放在 CDATA 中，且 CDATA 内不要写 XML 转义；宏只使用服务端支持范围内的写法，优先用基础运算符、\frac、\sqrt、matrix。

示例：

<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"。

<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
  <content textType="title">
    <p>主标题</p>
  </content>
</shape>

<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

<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 曲线）。

<polyline topLeftX="120" topLeftY="120" width="200" height="100">
  <border color="rgb(43, 47, 54)" width="2"/>
</polyline>

img

<img src="file_token_or_url" topLeftX="80" topLeftY="120" width="320" height="180"/>

img 使用 topLeftX / topLeftY，不是 x / y。

src 只支持：slides +media-upload 返回的 file_token，或 @<本地路径> 占位符（仅 +create --slides 自动上传并替换）。禁止使用 http(s) 外链 URL——飞书 slides 渲染端不会代理外链图，外链 src 在 PPT 里通常不显示。本地图片详见 lark-slides-create.md / lark-slides-media-upload.md。

本地图片的两种姿势：

  • 新建带图 PPT：+create --slides 里直接写 src="@./pic.png"，CLI 在创空白 PPT 后、加 slides 前自动上传并替换 token
  • 给已有 PPT 加带图新页：先 slides +media-upload --file ./pic.png --presentation $PID 拿 token，再用 token 写进 xml_presentation.slide create 的 XML

注意：width/height 是裁剪后的显示尺寸。比例和原图不一致时会自动裁剪（无法靠属性关闭），想避免裁剪就让 width:height 对齐原图比例。

icon

<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。

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

示例：

<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，直接照抄其中的柱状、条形、折线、面积、饼（环）、雷达、组合图。

<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]。

<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。

颜色与样式

fill

<fill>
  <fillColor color="rgb(255, 0, 0)"/>
</fill>

border

<border color="rgb(43, 47, 54)" width="2" dashArray="solid"/>

颜色格式

<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 均适用。

页面背景

<!-- 纯色背景 -->
<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>

备注示例

<note>
  <content autoFit="normal-auto-fit" textType="body">
    <p>这是演讲者备注。</p>
  </content>
</note>

完整示例

<?xml version="1.0" encoding="UTF-8"?>
<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
  <title>季度报告</title>
  <theme>
    <textStyles>
      <title fontFamily="思源黑体" fontSize="54" fontColor="rgba(0, 0, 0, 1)"/>
      <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="http://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"

详细参考

Schema 版本信息