npm - @amaster.ai/pi-lark - Versions diffs - 0.1.6 → 0.1.8 - Mend

@amaster.ai/pi-lark 0.1.6 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (266) hide show

package/skills/lark-slides/references/xml-schema-quick-ref.md CHANGED Viewed

@@ -1,10 +1,10 @@
 # XML Schema 快速参考
-本文档是 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) 的精简版摘要；如果两者不一致，以 XSD 原文为准。
+本文档是 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) 的精简版摘要，并合并了常用 XML 格式写法；如果两者不一致，以 XSD 原文为准。
 ## 最重要的规则
-1. 协议标准写法应使用 `<presentation xmlns="http://www.larkoffice.com/sml/2.0">`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证
+1. 协议标准写法应使用 `<presentation xmlns="https://www.larkoffice.com/sml/2.0">`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证
 2. `<presentation>` 直接子元素只有 `<title>`、`<theme>`、`<slide>`
 3. `<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`
 4. 页面中的文本通常通过 `<content>` 表达，而不是把 `<title>`、`<body>` 直接挂在 `<slide>` 下
@@ -12,12 +12,11 @@
 ## 最小可用示例
 ```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
+<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 textType="title">
+        <content autoFit="normal-auto-fit" wrap="true" textType="title">
           <p>标题</p>
         </content>
       </shape>
@@ -30,24 +29,30 @@
 | 属性 | 必需 | 说明 |
 |------|------|------|
-| `width` | 是 | 演示文稿宽度，正整数 |
-| `height` | 是 | 演示文稿高度，正整数 |
+| `width` | 是 | 演示文稿宽度，正整数，标准 16:9 页面建议使用 `960` |
+| `height` | 是 | 演示文稿高度，正整数，标准 16:9 页面建议使用 `540` |
 | `id` | 否 | 演示文稿标识 |
 **子元素：** `<title>?`, `<theme>?`, `<slide>+`
-## slide 元素
+`<slide>` 至少 1 页，最多 100 页。
-| 属性 | 必需 | 说明 |
-|------|------|------|
-| `id` | 否 | 幻灯片标识 |
+## theme 与文本类型
-**子元素：**
-- `<style>?` - 页面样式，目前可放 `<fill>`
-- `<data>?` - 页面元素容器，可放 `shape`、`line`、`polyline`、`img`、`table`、`icon`、`chart`、`whiteboard`、`undefined`
-- `<note>?` - 演讲者备注，内部可放 `<content>`
+`<theme>` 当前包含两部分：
-## theme 与文本类型
+- `<background>`：演示文稿级背景填充
+- `<textStyles>`：主题文本样式集合
+`<textStyles>` 下可选子元素包括 `<title>`、`<headline>`、`<sub-headline>`、`<body>`、`<caption>`。这些元素定义的是主题默认样式，不是页面结构。
+常用属性：
+| 属性 | 说明 |
+|------|------|
+| `fontFamily` | 字体 |
+| `fontSize` | 字号 |
+| `fontColor` | 字体颜色 |
 XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出现在：
@@ -64,6 +69,22 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 | `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` 中，常用属性包括：
@@ -71,23 +92,56 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 | 属性 | 说明 |
 |------|------|
 | `textType` | `title` / `headline` / `sub-headline` / `body` / `caption` |
+| `verticalAlign` | 垂直对齐 |
 | `textAlign` | 文本对齐方式 |
 | `lineSpacing` | 行间距，schema 默认 `multiple:1.5` |
 | `fontSize` | 字号 |
 | `fontFamily` | 字体 |
 | `color` | 字体颜色 |
-| `bold` / `italic` / `underline` / `strikethrough` | 文本样式 |
+| `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>` 的子元素只能是：
+`<content>` 直接子元素只有：
 - `<p>`
 - `<ul>`
 - `<ol>`
-### content 示例
+### p 段落与内联标签
+`<p>` 是段落元素，可混排纯文本和内联标签：
+- `<br/>`
+- `<strong>`
+- `<em>`
+- `<u>`
+- `<span>`
+- `<del>`
+- `<a>`
+- `<shadow>`
+- `<outline>`
+- `<formula>`
+公式写法：
 ```xml
-<content textType="body" textAlign="left">
+<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>
@@ -98,8 +152,20 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 ## 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>
@@ -108,6 +174,8 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
   <border color="rgb(0, 0, 0)" width="2"/>
 </shape>
 ```
+`<shape type="rect">` 只是形状不是容器，`<icon>`、`<img>`、`<shape type="text">` 和其他 `<shape>` 必须与它平级靠坐标叠放。
 | 属性 | 必需 | 说明 |
 |------|------|------|
@@ -117,6 +185,23 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 | `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
@@ -126,55 +211,162 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 </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_or_url" topLeftX="80" topLeftY="120" width="320" height="180"/>
+<img src="file_token_或_@本地路径" 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)。
+`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/Base/setting.svg" topLeftX="80" topLeftY="120" width="32" height="32">
+<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 路径；视觉 lint 规范要求 `fillColor` 显式设置为非透明颜色，避免图标不可见。需要语义图标时，先运行 `scripts/iconpark_tool.py search --query "<语义>"`，不要凭记忆拼路径。更多规则见 [iconpark.md](iconpark.md)。
+图标必须填充颜色并和背景有足够对比。
+禁止盲猜 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` 调整对齐方式。
-### whiteboard
+表格宽高设置：
+- 已设置的列宽和行高优先保留，未设置的列宽、行高会使用表格的目标总宽度、总高度分配剩余空间
+- **必须设置 `<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
-<!-- SVG 模式：<chart> 不支持的图表或自定义视觉、装饰元素 -->
-<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>
+<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>` 全局层。
+可挂载位置：
-<!-- Mermaid 模式：流程图、时序图等结构化图表 -->
-<whiteboard topLeftX="72" topLeftY="100" width="816" height="340">
-  <mermaid>
-    <![CDATA[
-      flowchart LR
-          A[开始] --> B{判断}
-          B -- 是 --> C[执行]
-          B -- 否 --> D[结束]
-    ]]>
-  </mermaid>
-</whiteboard>
+- 系列级：`<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>
 ```
-SVG 模式：`<svg>` 需声明 `xmlns="http://www.w3.org/2000/svg"`，内容大小由子元素包围盒决定；`width`/`height`/`viewBox` 不影响渲染，仅当元素使用百分比属性值时需声明 `viewBox`。\
-Mermaid 模式：内容用 `<![CDATA[...]]>` 包裹，避免 `[`、`>`、`-->` 等字符破坏 XML 解析。\
-详细用法见 [lark-slides-whiteboard.md](lark-slides-whiteboard.md)。
+`<embed>` 直接子元素为一个 `<svg>`（必需），以及可选的 `<reflection>`（倒影）与 `<shadow>`（阴影）。
 ## 颜色与样式
@@ -229,21 +421,77 @@ Mermaid 模式：内容用 `<![CDATA[...]]>` 包裹，避免 `[`、`>`、`-->`
 ```xml
 <note>
-  <content textType="body">
+  <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>季度报告</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="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)
-- [xml-format-guide.md](xml-format-guide.md)
-- [examples.md](examples.md)
-- [slides_demo.xml](slides_demo.xml)
+- [slides_chart_demo.xml](slides_chart_demo.xml)
 ## Schema 版本信息
 - **版本**: 2.0.0
-- **命名空间**: http://www.larkoffice.com/sml/2.0
+- **命名空间**: https://www.larkoffice.com/sml/2.0
 - **发布日期**: 2025-11-03