mirror of
https://github.com/larksuite/cli.git
synced 2026-07-03 14:02:43 +08:00
feat(slides): add slides +create shortcut with --slides one-step creation (#389)
Co-authored-by: caichengjie.viper <caichengjie.viper@bytedance.com>
This commit is contained in:
ethan-zhx
@@ -6,14 +6,14 @@
|
||||
|
||||
[中文版](./README.zh.md) | [English](./README.md)
|
||||
|
||||
The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by the [larksuite](https://github.com/larksuite) team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200+ commands and 20 AI Agent [Skills](./skills/).
|
||||
The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by the [larksuite](https://github.com/larksuite) team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Slides, Calendar, Mail, Tasks, Meetings, and more, with 200+ commands and 21 AI Agent [Skills](./skills/).
|
||||
|
||||
[Install](#installation--quick-start) · [AI Agent Skills](#agent-skills) · [Auth](#authentication) · [Commands](#three-layer-command-system) · [Advanced](#advanced-usage) · [Security](#security--risk-warnings-read-before-use) · [Contributing](#contributing)
|
||||
|
||||
## Why lark-cli?
|
||||
|
||||
- **Agent-Native Design** — 20 structured [Skills](./skills/) out of the box, compatible with popular AI tools — Agents can operate Lark with zero extra setup
|
||||
- **Wide Coverage** — 12 business domains, 200+ curated commands, 20 AI Agent [Skills](./skills/)
|
||||
- **Agent-Native Design** — 21 structured [Skills](./skills/) out of the box, compatible with popular AI tools — Agents can operate Lark with zero extra setup
|
||||
- **Wide Coverage** — 13 business domains, 200+ curated commands, 21 AI Agent [Skills](./skills/)
|
||||
- **AI-Friendly & Optimized** — Every command is tested with real Agents, featuring concise parameters, smart defaults, and structured output to maximize Agent call success rates
|
||||
- **Open Source, Zero Barriers** — MIT license, ready to use, just `npm install`
|
||||
- **Up and Running in 3 Minutes** — One-click app creation, interactive login, from install to first API call in just 3 steps
|
||||
@@ -30,6 +30,7 @@ The official [Lark/Feishu](https://www.larksuite.com/) CLI tool, maintained by t
|
||||
| 📁 Drive | Upload and download files, search docs & wiki, manage comments |
|
||||
| 📊 Base | Create and manage tables, fields, records, views, dashboards, workflows, forms, roles & permissions, data aggregation & analytics |
|
||||
| 📈 Sheets | Create, read, write, append, find, and export spreadsheet data |
|
||||
| 🖼️ Slides | Create and manage presentations, read presentation content, and add or remove slides |
|
||||
| ✅ Tasks | Create, query, update, and complete tasks; manage task lists, subtasks, comments & reminders |
|
||||
| 📚 Wiki | Create and manage knowledge spaces, nodes, and documents |
|
||||
| 👤 Contact | Search users by name/email/phone, get user profiles |
|
||||
@@ -136,6 +137,7 @@ lark-cli auth status
|
||||
| `lark-doc` | Create, read, update, search documents (Markdown-based) |
|
||||
| `lark-drive` | Upload, download files, manage permissions & comments |
|
||||
| `lark-sheets` | Create, read, write, append, find, export spreadsheets |
|
||||
| `lark-slides` | Create and manage presentations, read presentation content, and add or remove slides |
|
||||
| `lark-base` | Tables, fields, records, views, dashboards, data aggregation & analytics |
|
||||
| `lark-task` | Tasks, task lists, subtasks, reminders, member assignment |
|
||||
| `lark-mail` | Browse, search, read emails, send, reply, forward, draft management, watch new mail |
|
||||
|
||||
@@ -6,14 +6,14 @@
|
||||
|
||||
[中文版](./README.zh.md) | [English](./README.md)
|
||||
|
||||
飞书官方 CLI 工具，由 [larksuite](https://github.com/larksuite) 团队维护 — 让人类和 AI Agent 都能在终端中操作飞书。覆盖消息、文档、多维表格、电子表格、日历、邮箱、任务、会议等核心业务域，提供 200+ 命令及 20 个 AI Agent [Skills](./skills/)。
|
||||
飞书官方 CLI 工具，由 [larksuite](https://github.com/larksuite) 团队维护 — 让人类和 AI Agent 都能在终端中操作飞书。覆盖消息、文档、多维表格、电子表格、幻灯片、日历、邮箱、任务、会议等核心业务域，提供 200+ 命令及 21 个 AI Agent [Skills](./skills/)。
|
||||
|
||||
[安装](#安装与快速开始) · [AI Agent Skills](#agent-skills) · [认证](#认证) · [命令](#三层命令调用) · [进阶用法](#进阶用法) · [安全](#安全与风险提示使用前必读) · [贡献](#贡献)
|
||||
|
||||
## 为什么选 lark-cli？
|
||||
|
||||
- **为 Agent 原生设计** — [Skills](./skills/) 开箱即用，适配主流 AI 工具，Agent 无需额外适配即可操作飞书
|
||||
- **覆盖面广** — 12 大业务域、200+ 精选命令、 20 个 AI Agent [Skills](./skills/)
|
||||
- **为 Agent 原生设计** — 21 个 [Skills](./skills/) 开箱即用，适配主流 AI 工具，Agent 无需额外适配即可操作飞书
|
||||
- **覆盖面广** — 13 大业务域、200+ 精选命令、21 个 AI Agent [Skills](./skills/)
|
||||
- **AI 友好调优** — 每条命令经过 Agent 实测验证，提供更友好的参数、智能默认值和结构化输出，大幅提升 Agent 调用成功率
|
||||
- **开源零门槛** — MIT 协议，开箱即用，`npm install` 即可使用
|
||||
- **三分钟上手** — 一键创建应用、交互式登录授权，从安装到第一次 API 调用只需三步
|
||||
@@ -30,6 +30,7 @@
|
||||
| 📁 云空间 | 上传和下载文件、搜索文档与知识库、管理评论 |
|
||||
| 📊 多维表格 | 创建和管理数据表、字段、记录、视图、仪表盘、自动化流程、表单、角色权限，数据聚合分析 |
|
||||
| 📈 电子表格 | 创建、读取、写入、追加、查找和导出表格数据 |
|
||||
| 🖼️ 幻灯片 | 创建和管理演示文稿、读取演示文稿内容，以及新增或删除幻灯片页面 |
|
||||
| ✅ 任务 | 创建、查询、更新和完成任务；管理任务清单、子任务、评论与提醒 |
|
||||
| 📚 知识库 | 创建和管理知识空间、节点和文档 |
|
||||
| 👤 通讯录 | 按姓名/邮箱/手机号搜索用户、获取用户信息 |
|
||||
@@ -137,6 +138,7 @@ lark-cli auth status
|
||||
| `lark-doc` | 创建、读取、更新、搜索文档（基于 Markdown） |
|
||||
| `lark-drive` | 上传、下载文件，管理权限与评论 |
|
||||
| `lark-sheets` | 创建、读取、写入、追加、查找、导出电子表格 |
|
||||
| `lark-slides` | 创建和管理演示文稿、读取演示文稿内容，以及新增或删除幻灯片页面 |
|
||||
| `lark-base` | 多维表格、字段、记录、视图、仪表盘、数据聚合分析 |
|
||||
| `lark-task` | 任务、任务清单、子任务、提醒、成员分配 |
|
||||
| `lark-mail` | 浏览、搜索、阅读邮件，发送、回复、转发，草稿管理，监听新邮件 |
|
||||
|
||||
@@ -43,6 +43,10 @@
|
||||
"en": { "title": "Sheets", "description": "Spreadsheet operations" },
|
||||
"zh": { "title": "电子表格", "description": "电子表格操作" }
|
||||
},
|
||||
"slides": {
|
||||
"en": { "title": "Slides", "description": "Create and manage presentations, read content, and add or remove slides" },
|
||||
"zh": { "title": "幻灯片", "description": "创建和管理演示文稿、读取内容，以及新增或删除幻灯片页面" }
|
||||
},
|
||||
"task": {
|
||||
"en": { "title": "Task", "description": "Task, task list, and subtask management" },
|
||||
"zh": { "title": "任务", "description": "任务、清单、子任务管理" }
|
||||
|
||||
@@ -120,6 +120,8 @@ func permissionTargetLabel(resourceType string) string {
|
||||
return "spreadsheet"
|
||||
case "bitable", "base":
|
||||
return "base"
|
||||
case "slides":
|
||||
return "presentation"
|
||||
case "file":
|
||||
return "file"
|
||||
case "folder":
|
||||
|
||||
@@ -19,6 +19,7 @@ import (
|
||||
"github.com/larksuite/cli/shortcuts/mail"
|
||||
"github.com/larksuite/cli/shortcuts/minutes"
|
||||
"github.com/larksuite/cli/shortcuts/sheets"
|
||||
"github.com/larksuite/cli/shortcuts/slides"
|
||||
"github.com/larksuite/cli/shortcuts/task"
|
||||
"github.com/larksuite/cli/shortcuts/vc"
|
||||
"github.com/larksuite/cli/shortcuts/whiteboard"
|
||||
@@ -38,6 +39,7 @@ func init() {
|
||||
allShortcuts = append(allShortcuts, base.Shortcuts()...)
|
||||
allShortcuts = append(allShortcuts, event.Shortcuts()...)
|
||||
allShortcuts = append(allShortcuts, mail.Shortcuts()...)
|
||||
allShortcuts = append(allShortcuts, slides.Shortcuts()...)
|
||||
allShortcuts = append(allShortcuts, minutes.Shortcuts()...)
|
||||
allShortcuts = append(allShortcuts, task.Shortcuts()...)
|
||||
allShortcuts = append(allShortcuts, vc.Shortcuts()...)
|
||||
|
||||
13
shortcuts/slides/shortcuts.go
Normal file
13
shortcuts/slides/shortcuts.go
Normal file
@@ -0,0 +1,13 @@
|
||||
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
||||
// SPDX-License-Identifier: MIT
|
||||
|
||||
package slides
|
||||
|
||||
import "github.com/larksuite/cli/shortcuts/common"
|
||||
|
||||
// Shortcuts returns all slides shortcuts.
|
||||
func Shortcuts() []common.Shortcut {
|
||||
return []common.Shortcut{
|
||||
SlidesCreate,
|
||||
}
|
||||
}
|
||||
191
shortcuts/slides/slides_create.go
Normal file
191
shortcuts/slides/slides_create.go
Normal file
@@ -0,0 +1,191 @@
|
||||
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
||||
// SPDX-License-Identifier: MIT
|
||||
|
||||
package slides
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"strings"
|
||||
|
||||
"github.com/larksuite/cli/internal/output"
|
||||
"github.com/larksuite/cli/internal/validate"
|
||||
"github.com/larksuite/cli/shortcuts/common"
|
||||
)
|
||||
|
||||
const (
|
||||
defaultPresentationWidth = 960
|
||||
defaultPresentationHeight = 540
|
||||
maxSlidesPerCreate = 10
|
||||
)
|
||||
|
||||
// SlidesCreate creates a new Lark Slides presentation with bot auto-grant.
|
||||
var SlidesCreate = common.Shortcut{
|
||||
Service: "slides",
|
||||
Command: "+create",
|
||||
Description: "Create a Lark Slides presentation",
|
||||
Risk: "write",
|
||||
AuthTypes: []string{"user", "bot"},
|
||||
Scopes: []string{"slides:presentation:create", "slides:presentation:write_only"},
|
||||
Flags: []common.Flag{
|
||||
{Name: "title", Desc: "presentation title"},
|
||||
{Name: "slides", Desc: "slide content JSON array (each element is a <slide> XML string, max 10; for more pages, create first then add via xml_presentation.slide.create)"},
|
||||
},
|
||||
Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
|
||||
if slidesStr := runtime.Str("slides"); slidesStr != "" {
|
||||
var slides []string
|
||||
if err := json.Unmarshal([]byte(slidesStr), &slides); err != nil {
|
||||
return common.FlagErrorf("--slides invalid JSON, must be an array of XML strings")
|
||||
}
|
||||
if len(slides) > maxSlidesPerCreate {
|
||||
return common.FlagErrorf("--slides array exceeds maximum of %d slides; create the presentation first, then add slides via xml_presentation.slide.create", maxSlidesPerCreate)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
},
|
||||
DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
|
||||
title := effectiveTitle(runtime.Str("title"))
|
||||
slidesStr := runtime.Str("slides")
|
||||
createBody := map[string]interface{}{
|
||||
"xml_presentation": map[string]interface{}{"content": buildPresentationXML(title)},
|
||||
}
|
||||
|
||||
dry := common.NewDryRunAPI()
|
||||
|
||||
if slidesStr == "" {
|
||||
dry.Desc("Create empty presentation").
|
||||
POST("/open-apis/slides_ai/v1/xml_presentations").
|
||||
Body(createBody)
|
||||
} else {
|
||||
var slides []string
|
||||
_ = json.Unmarshal([]byte(slidesStr), &slides)
|
||||
n := len(slides)
|
||||
total := n + 1
|
||||
|
||||
dry.Desc(fmt.Sprintf("Create presentation + add %d slide(s)", n)).
|
||||
POST("/open-apis/slides_ai/v1/xml_presentations").
|
||||
Desc(fmt.Sprintf("[1/%d] Create presentation", total)).
|
||||
Body(createBody)
|
||||
|
||||
for i, slideXML := range slides {
|
||||
dry.POST("/open-apis/slides_ai/v1/xml_presentations/<xml_presentation_id>/slide").
|
||||
Desc(fmt.Sprintf("[%d/%d] Add slide %d", i+2, total, i+1)).
|
||||
Body(map[string]interface{}{
|
||||
"slide": map[string]interface{}{"content": slideXML},
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
if runtime.IsBot() {
|
||||
dry.Desc("After creation succeeds in bot mode, the CLI will also try to grant the current CLI user full_access (可管理权限) on the new presentation.")
|
||||
}
|
||||
return dry
|
||||
},
|
||||
Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
|
||||
title := effectiveTitle(runtime.Str("title"))
|
||||
content := buildPresentationXML(title)
|
||||
slidesStr := runtime.Str("slides")
|
||||
|
||||
// Step 1: Create presentation
|
||||
data, err := runtime.CallAPI(
|
||||
"POST",
|
||||
"/open-apis/slides_ai/v1/xml_presentations",
|
||||
nil,
|
||||
map[string]interface{}{
|
||||
"xml_presentation": map[string]interface{}{
|
||||
"content": content,
|
||||
},
|
||||
},
|
||||
)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
presentationID := common.GetString(data, "xml_presentation_id")
|
||||
if presentationID == "" {
|
||||
return output.Errorf(output.ExitAPI, "api_error", "slides create returned no xml_presentation_id")
|
||||
}
|
||||
|
||||
result := map[string]interface{}{
|
||||
"xml_presentation_id": presentationID,
|
||||
"title": title,
|
||||
}
|
||||
if revisionID := common.GetFloat(data, "revision_id"); revisionID > 0 {
|
||||
result["revision_id"] = int(revisionID)
|
||||
}
|
||||
|
||||
// Step 2: Add slides if provided
|
||||
if slidesStr != "" {
|
||||
var slides []string
|
||||
_ = json.Unmarshal([]byte(slidesStr), &slides) // already validated
|
||||
|
||||
if len(slides) > 0 {
|
||||
slideURL := fmt.Sprintf(
|
||||
"/open-apis/slides_ai/v1/xml_presentations/%s/slide",
|
||||
validate.EncodePathSegment(presentationID),
|
||||
)
|
||||
|
||||
var slideIDs []string
|
||||
for i, slideXML := range slides {
|
||||
slideData, err := runtime.CallAPI(
|
||||
"POST",
|
||||
slideURL,
|
||||
map[string]interface{}{"revision_id": -1},
|
||||
map[string]interface{}{
|
||||
"slide": map[string]interface{}{"content": slideXML},
|
||||
},
|
||||
)
|
||||
if err != nil {
|
||||
return output.Errorf(output.ExitAPI, "api_error",
|
||||
"slide %d/%d failed: %v (presentation %s was created; %d slide(s) added before failure)",
|
||||
i+1, len(slides), err, presentationID, i)
|
||||
}
|
||||
if sid := common.GetString(slideData, "slide_id"); sid != "" {
|
||||
slideIDs = append(slideIDs, sid)
|
||||
}
|
||||
}
|
||||
|
||||
result["slide_ids"] = slideIDs
|
||||
result["slides_added"] = len(slideIDs)
|
||||
}
|
||||
}
|
||||
|
||||
if grant := common.AutoGrantCurrentUserDrivePermission(runtime, presentationID, "slides"); grant != nil {
|
||||
result["permission_grant"] = grant
|
||||
}
|
||||
|
||||
runtime.Out(result, nil)
|
||||
return nil
|
||||
},
|
||||
}
|
||||
|
||||
// effectiveTitle returns the title to use, falling back to "Untitled".
|
||||
func effectiveTitle(title string) string {
|
||||
if title == "" {
|
||||
return "Untitled"
|
||||
}
|
||||
return title
|
||||
}
|
||||
|
||||
// buildPresentationXML builds the minimal XML for a new empty presentation.
|
||||
func buildPresentationXML(title string) string {
|
||||
escapedTitle := xmlEscape(title)
|
||||
if escapedTitle == "" {
|
||||
escapedTitle = "Untitled"
|
||||
}
|
||||
return fmt.Sprintf(
|
||||
`<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="%d" height="%d"><title>%s</title></presentation>`,
|
||||
defaultPresentationWidth, defaultPresentationHeight, escapedTitle,
|
||||
)
|
||||
}
|
||||
|
||||
// xmlEscape escapes special XML characters in text content.
|
||||
func xmlEscape(s string) string {
|
||||
s = strings.ReplaceAll(s, "&", "&")
|
||||
s = strings.ReplaceAll(s, "<", "<")
|
||||
s = strings.ReplaceAll(s, ">", ">")
|
||||
s = strings.ReplaceAll(s, "\"", """)
|
||||
s = strings.ReplaceAll(s, "'", "'")
|
||||
return s
|
||||
}
|
||||
582
shortcuts/slides/slides_create_test.go
Normal file
582
shortcuts/slides/slides_create_test.go
Normal file
@@ -0,0 +1,582 @@
|
||||
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
||||
// SPDX-License-Identifier: MIT
|
||||
|
||||
package slides
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/spf13/cobra"
|
||||
|
||||
"github.com/larksuite/cli/internal/cmdutil"
|
||||
"github.com/larksuite/cli/internal/core"
|
||||
"github.com/larksuite/cli/internal/httpmock"
|
||||
"github.com/larksuite/cli/shortcuts/common"
|
||||
)
|
||||
|
||||
// TestSlidesCreateBasic verifies that slides +create returns the presentation ID and title in user mode.
|
||||
func TestSlidesCreateBasic(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
|
||||
reg.Register(&httpmock.Stub{
|
||||
Method: "POST",
|
||||
URL: "/open-apis/slides_ai/v1/xml_presentations",
|
||||
Body: map[string]interface{}{
|
||||
"code": 0,
|
||||
"msg": "ok",
|
||||
"data": map[string]interface{}{
|
||||
"xml_presentation_id": "pres_abc123",
|
||||
"revision_id": 1,
|
||||
},
|
||||
},
|
||||
})
|
||||
|
||||
err := runSlidesCreateShortcut(t, f, stdout, []string{
|
||||
"+create",
|
||||
"--title", "项目汇报",
|
||||
"--as", "user",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
data := decodeSlidesCreateEnvelope(t, stdout)
|
||||
if data["xml_presentation_id"] != "pres_abc123" {
|
||||
t.Fatalf("xml_presentation_id = %v, want pres_abc123", data["xml_presentation_id"])
|
||||
}
|
||||
if data["title"] != "项目汇报" {
|
||||
t.Fatalf("title = %v, want 项目汇报", data["title"])
|
||||
}
|
||||
if _, ok := data["permission_grant"]; ok {
|
||||
t.Fatalf("did not expect permission_grant in user mode")
|
||||
}
|
||||
}
|
||||
|
||||
// TestSlidesCreateBotAutoGrant verifies that bot mode grants the current user full_access on the new presentation.
|
||||
func TestSlidesCreateBotAutoGrant(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, "ou_current_user"))
|
||||
reg.Register(&httpmock.Stub{
|
||||
Method: "POST",
|
||||
URL: "/open-apis/slides_ai/v1/xml_presentations",
|
||||
Body: map[string]interface{}{
|
||||
"code": 0,
|
||||
"msg": "ok",
|
||||
"data": map[string]interface{}{
|
||||
"xml_presentation_id": "pres_bot",
|
||||
"revision_id": 1,
|
||||
},
|
||||
},
|
||||
})
|
||||
reg.Register(&httpmock.Stub{
|
||||
Method: "POST",
|
||||
URL: "/open-apis/drive/v1/permissions/pres_bot/members",
|
||||
Body: map[string]interface{}{
|
||||
"code": 0,
|
||||
"msg": "ok",
|
||||
"data": map[string]interface{}{
|
||||
"member": map[string]interface{}{
|
||||
"member_id": "ou_current_user",
|
||||
"member_type": "openid",
|
||||
"perm": "full_access",
|
||||
},
|
||||
},
|
||||
},
|
||||
})
|
||||
|
||||
err := runSlidesCreateShortcut(t, f, stdout, []string{
|
||||
"+create",
|
||||
"--title", "Bot PPT",
|
||||
"--as", "bot",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
data := decodeSlidesCreateEnvelope(t, stdout)
|
||||
grant, _ := data["permission_grant"].(map[string]interface{})
|
||||
if grant["status"] != common.PermissionGrantGranted {
|
||||
t.Fatalf("permission_grant.status = %v, want %q", grant["status"], common.PermissionGrantGranted)
|
||||
}
|
||||
if !strings.Contains(grant["message"].(string), "presentation") {
|
||||
t.Fatalf("permission_grant.message = %q, want 'presentation' mention", grant["message"])
|
||||
}
|
||||
}
|
||||
|
||||
// TestSlidesCreateBotSkippedWithoutCurrentUser verifies that permission grant is skipped when no user open_id is configured.
|
||||
func TestSlidesCreateBotSkippedWithoutCurrentUser(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
|
||||
reg.Register(&httpmock.Stub{
|
||||
Method: "POST",
|
||||
URL: "/open-apis/slides_ai/v1/xml_presentations",
|
||||
Body: map[string]interface{}{
|
||||
"code": 0,
|
||||
"msg": "ok",
|
||||
"data": map[string]interface{}{
|
||||
"xml_presentation_id": "pres_no_user",
|
||||
"revision_id": 1,
|
||||
},
|
||||
},
|
||||
})
|
||||
|
||||
err := runSlidesCreateShortcut(t, f, stdout, []string{
|
||||
"+create",
|
||||
"--title", "No User PPT",
|
||||
"--as", "bot",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
data := decodeSlidesCreateEnvelope(t, stdout)
|
||||
grant, _ := data["permission_grant"].(map[string]interface{})
|
||||
if grant["status"] != common.PermissionGrantSkipped {
|
||||
t.Fatalf("permission_grant.status = %v, want %q", grant["status"], common.PermissionGrantSkipped)
|
||||
}
|
||||
}
|
||||
|
||||
// TestSlidesCreateDryRunDefaultTitle verifies that dry-run also normalizes an empty title to "Untitled".
|
||||
func TestSlidesCreateDryRunDefaultTitle(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
|
||||
err := runSlidesCreateShortcut(t, f, stdout, []string{
|
||||
"+create",
|
||||
"--dry-run",
|
||||
"--as", "user",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
out := stdout.String()
|
||||
if !strings.Contains(out, "Untitled") {
|
||||
t.Fatalf("dry-run should contain Untitled in XML payload, got: %s", out)
|
||||
}
|
||||
if !strings.Contains(out, "xml_presentations") {
|
||||
t.Fatalf("dry-run should show API path, got: %s", out)
|
||||
}
|
||||
}
|
||||
|
||||
// TestSlidesCreateDefaultTitle verifies that omitting --title outputs "Untitled" (matching the actual resource).
|
||||
func TestSlidesCreateDefaultTitle(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
|
||||
reg.Register(&httpmock.Stub{
|
||||
Method: "POST",
|
||||
URL: "/open-apis/slides_ai/v1/xml_presentations",
|
||||
Body: map[string]interface{}{
|
||||
"code": 0,
|
||||
"msg": "ok",
|
||||
"data": map[string]interface{}{
|
||||
"xml_presentation_id": "pres_default",
|
||||
"revision_id": 1,
|
||||
},
|
||||
},
|
||||
})
|
||||
|
||||
err := runSlidesCreateShortcut(t, f, stdout, []string{
|
||||
"+create",
|
||||
"--as", "user",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
data := decodeSlidesCreateEnvelope(t, stdout)
|
||||
if data["title"] != "Untitled" {
|
||||
t.Fatalf("title = %v, want Untitled", data["title"])
|
||||
}
|
||||
}
|
||||
|
||||
// TestSlidesCreateMissingPresentationID verifies the error when the API returns no xml_presentation_id.
|
||||
func TestSlidesCreateMissingPresentationID(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
|
||||
reg.Register(&httpmock.Stub{
|
||||
Method: "POST",
|
||||
URL: "/open-apis/slides_ai/v1/xml_presentations",
|
||||
Body: map[string]interface{}{
|
||||
"code": 0,
|
||||
"msg": "ok",
|
||||
"data": map[string]interface{}{
|
||||
"revision_id": 1,
|
||||
},
|
||||
},
|
||||
})
|
||||
|
||||
err := runSlidesCreateShortcut(t, f, stdout, []string{
|
||||
"+create",
|
||||
"--title", "Missing ID",
|
||||
"--as", "user",
|
||||
})
|
||||
if err == nil {
|
||||
t.Fatal("expected error when xml_presentation_id is missing, got nil")
|
||||
}
|
||||
if !strings.Contains(err.Error(), "xml_presentation_id") {
|
||||
t.Fatalf("error = %q, want mention of xml_presentation_id", err.Error())
|
||||
}
|
||||
}
|
||||
|
||||
// TestSlidesCreateWithSlides verifies that slides +create with --slides creates the presentation and adds slides.
|
||||
func TestSlidesCreateWithSlides(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
|
||||
reg.Register(&httpmock.Stub{
|
||||
Method: "POST",
|
||||
URL: "/open-apis/slides_ai/v1/xml_presentations",
|
||||
Body: map[string]interface{}{
|
||||
"code": 0,
|
||||
"msg": "ok",
|
||||
"data": map[string]interface{}{
|
||||
"xml_presentation_id": "pres_with_slides",
|
||||
"revision_id": 1,
|
||||
},
|
||||
},
|
||||
})
|
||||
reg.Register(&httpmock.Stub{
|
||||
Method: "POST",
|
||||
URL: "/open-apis/slides_ai/v1/xml_presentations/pres_with_slides/slide",
|
||||
Body: map[string]interface{}{
|
||||
"code": 0,
|
||||
"msg": "ok",
|
||||
"data": map[string]interface{}{
|
||||
"slide_id": "slide_001",
|
||||
"revision_id": 2,
|
||||
},
|
||||
},
|
||||
})
|
||||
reg.Register(&httpmock.Stub{
|
||||
Method: "POST",
|
||||
URL: "/open-apis/slides_ai/v1/xml_presentations/pres_with_slides/slide",
|
||||
Body: map[string]interface{}{
|
||||
"code": 0,
|
||||
"msg": "ok",
|
||||
"data": map[string]interface{}{
|
||||
"slide_id": "slide_002",
|
||||
"revision_id": 3,
|
||||
},
|
||||
},
|
||||
})
|
||||
|
||||
slidesJSON := `["<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>","<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"]`
|
||||
err := runSlidesCreateShortcut(t, f, stdout, []string{
|
||||
"+create",
|
||||
"--title", "With Slides",
|
||||
"--slides", slidesJSON,
|
||||
"--as", "user",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
data := decodeSlidesCreateEnvelope(t, stdout)
|
||||
if data["xml_presentation_id"] != "pres_with_slides" {
|
||||
t.Fatalf("xml_presentation_id = %v, want pres_with_slides", data["xml_presentation_id"])
|
||||
}
|
||||
slideIDs, ok := data["slide_ids"].([]interface{})
|
||||
if !ok || len(slideIDs) != 2 {
|
||||
t.Fatalf("slide_ids = %v, want 2 elements", data["slide_ids"])
|
||||
}
|
||||
if slideIDs[0] != "slide_001" || slideIDs[1] != "slide_002" {
|
||||
t.Fatalf("slide_ids = %v, want [slide_001, slide_002]", slideIDs)
|
||||
}
|
||||
if data["slides_added"] != float64(2) {
|
||||
t.Fatalf("slides_added = %v, want 2", data["slides_added"])
|
||||
}
|
||||
}
|
||||
|
||||
// TestSlidesCreateWithSlidesPartialFailure verifies error reporting when a slide fails to create.
|
||||
func TestSlidesCreateWithSlidesPartialFailure(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
|
||||
reg.Register(&httpmock.Stub{
|
||||
Method: "POST",
|
||||
URL: "/open-apis/slides_ai/v1/xml_presentations",
|
||||
Body: map[string]interface{}{
|
||||
"code": 0,
|
||||
"msg": "ok",
|
||||
"data": map[string]interface{}{
|
||||
"xml_presentation_id": "pres_partial",
|
||||
"revision_id": 1,
|
||||
},
|
||||
},
|
||||
})
|
||||
// First slide succeeds
|
||||
reg.Register(&httpmock.Stub{
|
||||
Method: "POST",
|
||||
URL: "/open-apis/slides_ai/v1/xml_presentations/pres_partial/slide",
|
||||
Body: map[string]interface{}{
|
||||
"code": 0,
|
||||
"msg": "ok",
|
||||
"data": map[string]interface{}{
|
||||
"slide_id": "slide_ok",
|
||||
"revision_id": 2,
|
||||
},
|
||||
},
|
||||
})
|
||||
// Second slide fails
|
||||
reg.Register(&httpmock.Stub{
|
||||
Method: "POST",
|
||||
URL: "/open-apis/slides_ai/v1/xml_presentations/pres_partial/slide",
|
||||
Body: map[string]interface{}{
|
||||
"code": 400,
|
||||
"msg": "invalid xml",
|
||||
},
|
||||
})
|
||||
|
||||
slidesJSON := `["<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>","<bad-xml>"]`
|
||||
err := runSlidesCreateShortcut(t, f, stdout, []string{
|
||||
"+create",
|
||||
"--title", "Partial",
|
||||
"--slides", slidesJSON,
|
||||
"--as", "user",
|
||||
})
|
||||
if err == nil {
|
||||
t.Fatal("expected error for partial failure, got nil")
|
||||
}
|
||||
errMsg := err.Error()
|
||||
if !strings.Contains(errMsg, "pres_partial") {
|
||||
t.Fatalf("error should contain presentation ID, got: %s", errMsg)
|
||||
}
|
||||
if !strings.Contains(errMsg, "slide 2/2") {
|
||||
t.Fatalf("error should indicate slide 2/2 failed, got: %s", errMsg)
|
||||
}
|
||||
if !strings.Contains(errMsg, "1 slide(s) added") {
|
||||
t.Fatalf("error should report 1 slide added before failure, got: %s", errMsg)
|
||||
}
|
||||
}
|
||||
|
||||
// TestSlidesCreateWithSlidesInvalidJSON verifies validation rejects non-JSON slides input.
|
||||
func TestSlidesCreateWithSlidesInvalidJSON(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
|
||||
err := runSlidesCreateShortcut(t, f, stdout, []string{
|
||||
"+create",
|
||||
"--title", "Bad JSON",
|
||||
"--slides", "not json",
|
||||
"--as", "user",
|
||||
})
|
||||
if err == nil {
|
||||
t.Fatal("expected validation error for invalid JSON, got nil")
|
||||
}
|
||||
if !strings.Contains(err.Error(), "--slides invalid JSON") {
|
||||
t.Fatalf("error = %q, want --slides invalid JSON mention", err.Error())
|
||||
}
|
||||
}
|
||||
|
||||
// TestSlidesCreateWithSlidesExceedsMax verifies validation rejects arrays exceeding the limit.
|
||||
func TestSlidesCreateWithSlidesExceedsMax(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
// Build a JSON array with 11 elements (exceeds maxSlidesPerCreate = 10)
|
||||
elems := make([]string, 11)
|
||||
for i := range elems {
|
||||
elems[i] = `"<slide/>"` //nolint:goconst
|
||||
}
|
||||
slidesJSON := "[" + strings.Join(elems, ",") + "]"
|
||||
|
||||
f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
|
||||
err := runSlidesCreateShortcut(t, f, stdout, []string{
|
||||
"+create",
|
||||
"--title", "Too Many",
|
||||
"--slides", slidesJSON,
|
||||
"--as", "user",
|
||||
})
|
||||
if err == nil {
|
||||
t.Fatal("expected validation error for exceeding max, got nil")
|
||||
}
|
||||
if !strings.Contains(err.Error(), "exceeds maximum") {
|
||||
t.Fatalf("error = %q, want 'exceeds maximum' mention", err.Error())
|
||||
}
|
||||
}
|
||||
|
||||
// TestSlidesCreateWithSlidesEmptyArray verifies that --slides '[]' behaves like no --slides.
|
||||
func TestSlidesCreateWithSlidesEmptyArray(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
|
||||
reg.Register(&httpmock.Stub{
|
||||
Method: "POST",
|
||||
URL: "/open-apis/slides_ai/v1/xml_presentations",
|
||||
Body: map[string]interface{}{
|
||||
"code": 0,
|
||||
"msg": "ok",
|
||||
"data": map[string]interface{}{
|
||||
"xml_presentation_id": "pres_empty_slides",
|
||||
"revision_id": 1,
|
||||
},
|
||||
},
|
||||
})
|
||||
|
||||
err := runSlidesCreateShortcut(t, f, stdout, []string{
|
||||
"+create",
|
||||
"--title", "Empty Slides",
|
||||
"--slides", "[]",
|
||||
"--as", "user",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
data := decodeSlidesCreateEnvelope(t, stdout)
|
||||
if data["xml_presentation_id"] != "pres_empty_slides" {
|
||||
t.Fatalf("xml_presentation_id = %v, want pres_empty_slides", data["xml_presentation_id"])
|
||||
}
|
||||
if _, ok := data["slide_ids"]; ok {
|
||||
t.Fatalf("did not expect slide_ids for empty slides array")
|
||||
}
|
||||
if _, ok := data["slides_added"]; ok {
|
||||
t.Fatalf("did not expect slides_added for empty slides array")
|
||||
}
|
||||
}
|
||||
|
||||
// TestSlidesCreateWithSlidesDryRun verifies dry-run output shows multi-step labels.
|
||||
func TestSlidesCreateWithSlidesDryRun(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
f, stdout, _, _ := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
|
||||
slidesJSON := `["<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>","<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data></data></slide>"]`
|
||||
err := runSlidesCreateShortcut(t, f, stdout, []string{
|
||||
"+create",
|
||||
"--title", "DryRun Slides",
|
||||
"--slides", slidesJSON,
|
||||
"--dry-run",
|
||||
"--as", "user",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
out := stdout.String()
|
||||
if !strings.Contains(out, "[1/3]") {
|
||||
t.Fatalf("dry-run should contain [1/3] step label, got: %s", out)
|
||||
}
|
||||
if !strings.Contains(out, "[2/3]") {
|
||||
t.Fatalf("dry-run should contain [2/3] step label, got: %s", out)
|
||||
}
|
||||
if !strings.Contains(out, "[3/3]") {
|
||||
t.Fatalf("dry-run should contain [3/3] step label, got: %s", out)
|
||||
}
|
||||
if !strings.Contains(out, "xml_presentation_id") {
|
||||
t.Fatalf("dry-run should contain placeholder xml_presentation_id, got: %s", out)
|
||||
}
|
||||
}
|
||||
|
||||
// TestSlidesCreateWithoutSlidesUnchanged verifies existing behavior when --slides is not passed.
|
||||
func TestSlidesCreateWithoutSlidesUnchanged(t *testing.T) {
|
||||
t.Parallel()
|
||||
|
||||
f, stdout, _, reg := cmdutil.TestFactory(t, slidesTestConfig(t, ""))
|
||||
reg.Register(&httpmock.Stub{
|
||||
Method: "POST",
|
||||
URL: "/open-apis/slides_ai/v1/xml_presentations",
|
||||
Body: map[string]interface{}{
|
||||
"code": 0,
|
||||
"msg": "ok",
|
||||
"data": map[string]interface{}{
|
||||
"xml_presentation_id": "pres_no_slides",
|
||||
"revision_id": 1,
|
||||
},
|
||||
},
|
||||
})
|
||||
|
||||
err := runSlidesCreateShortcut(t, f, stdout, []string{
|
||||
"+create",
|
||||
"--title", "No Slides",
|
||||
"--as", "user",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
data := decodeSlidesCreateEnvelope(t, stdout)
|
||||
if data["xml_presentation_id"] != "pres_no_slides" {
|
||||
t.Fatalf("xml_presentation_id = %v, want pres_no_slides", data["xml_presentation_id"])
|
||||
}
|
||||
if data["title"] != "No Slides" {
|
||||
t.Fatalf("title = %v, want No Slides", data["title"])
|
||||
}
|
||||
if _, ok := data["slide_ids"]; ok {
|
||||
t.Fatalf("did not expect slide_ids when --slides not passed")
|
||||
}
|
||||
if _, ok := data["slides_added"]; ok {
|
||||
t.Fatalf("did not expect slides_added when --slides not passed")
|
||||
}
|
||||
if _, ok := data["permission_grant"]; ok {
|
||||
t.Fatalf("did not expect permission_grant in user mode")
|
||||
}
|
||||
}
|
||||
|
||||
// TestXmlEscape verifies that XML special characters are properly escaped.
|
||||
func TestXmlEscape(t *testing.T) {
|
||||
t.Parallel()
|
||||
tests := []struct {
|
||||
input, want string
|
||||
}{
|
||||
{"hello", "hello"},
|
||||
{"a&b", "a&b"},
|
||||
{"<script>", "<script>"},
|
||||
{`"quoted"`, ""quoted""},
|
||||
{"it's", "it's"},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
got := xmlEscape(tt.input)
|
||||
if got != tt.want {
|
||||
t.Errorf("xmlEscape(%q) = %q, want %q", tt.input, got, tt.want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// slidesTestConfig returns a CliConfig for testing with the given user open ID.
|
||||
func slidesTestConfig(t *testing.T, userOpenID string) *core.CliConfig {
|
||||
t.Helper()
|
||||
replacer := strings.NewReplacer("/", "-", " ", "-")
|
||||
suffix := replacer.Replace(strings.ToLower(t.Name()))
|
||||
return &core.CliConfig{
|
||||
AppID: "test-slides-create-" + suffix,
|
||||
AppSecret: "secret-slides-create-" + suffix,
|
||||
Brand: core.BrandFeishu,
|
||||
UserOpenId: userOpenID,
|
||||
}
|
||||
}
|
||||
|
||||
// runSlidesCreateShortcut mounts and executes the slides +create shortcut with the given args.
|
||||
func runSlidesCreateShortcut(t *testing.T, f *cmdutil.Factory, stdout *bytes.Buffer, args []string) error {
|
||||
t.Helper()
|
||||
parent := &cobra.Command{Use: "slides"}
|
||||
SlidesCreate.Mount(parent, f)
|
||||
parent.SetArgs(args)
|
||||
parent.SilenceErrors = true
|
||||
parent.SilenceUsage = true
|
||||
if stdout != nil {
|
||||
stdout.Reset()
|
||||
}
|
||||
return parent.Execute()
|
||||
}
|
||||
|
||||
// decodeSlidesCreateEnvelope parses the JSON output and returns the data map.
|
||||
func decodeSlidesCreateEnvelope(t *testing.T, stdout *bytes.Buffer) map[string]interface{} {
|
||||
t.Helper()
|
||||
var envelope map[string]interface{}
|
||||
if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
|
||||
t.Fatalf("failed to decode output: %v\nraw=%s", err, stdout.String())
|
||||
}
|
||||
data, _ := envelope["data"].(map[string]interface{})
|
||||
if data == nil {
|
||||
t.Fatalf("missing data in output envelope: %#v", envelope)
|
||||
}
|
||||
return data
|
||||
}
|
||||
326
skills/lark-slides/SKILL.md
Normal file
326
skills/lark-slides/SKILL.md
Normal file
@@ -0,0 +1,326 @@
|
||||
---
|
||||
name: lark-slides
|
||||
version: 1.0.0
|
||||
description: "飞书幻灯片：以 XML 格式读取和管理 PPT 页面。创建演示文稿优先用 `+create`；XML API 主要用于读取 PPT 全文信息、创建和删除幻灯片页面。当用户需要创建 PPT、读取 PPT 内容、管理幻灯片页面时使用。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["lark-cli"]
|
||||
cliHelp: "lark-cli slides --help"
|
||||
---
|
||||
|
||||
# slides (v1)
|
||||
|
||||
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
|
||||
|
||||
**CRITICAL — 生成任何 XML 之前，MUST 先用 Read 工具读取 [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md)，禁止凭记忆猜测 XML 结构。**
|
||||
|
||||
## 身份选择
|
||||
|
||||
飞书幻灯片通常是用户自己的内容资源。**默认应优先显式使用 `--as user`（用户身份）执行 slides 相关操作**，始终显式指定身份。
|
||||
|
||||
- **`--as user`（推荐）**：以当前登录用户身份创建、读取、管理演示文稿。执行前先完成用户授权：
|
||||
|
||||
```bash
|
||||
lark-cli auth login --domain slides
|
||||
```
|
||||
|
||||
- **`--as bot`**：仅在用户明确要求以应用身份操作，或需要让 bot 持有/创建资源时使用。使用 bot 身份时，要额外确认 bot 是否真的有目标演示文稿的访问权限。
|
||||
|
||||
**执行规则**：
|
||||
|
||||
1. 创建、读取、增删 slide、按用户给出的链接继续编辑已有 PPT，默认都先用 `--as user`。
|
||||
2. 如果出现权限不足，先检查当前是否误用了 bot 身份；不要默认回退到 bot。
|
||||
3. 只有在用户明确要求“用应用身份 / bot 身份操作”，或当前工作流就是 bot 创建资源后再做协作授权时，才切换到 `--as bot`。
|
||||
|
||||
## 快速开始
|
||||
|
||||
一条命令创建包含页面内容的 PPT（推荐）：
|
||||
|
||||
```bash
|
||||
lark-cli slides +create --title "演示文稿标题" --slides '[
|
||||
"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><style><fill><fillColor color=\"rgb(245,245,245)\"/></fill></style><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"100\"><content textType=\"title\"><p>页面标题</p></content></shape><shape type=\"text\" topLeftX=\"80\" topLeftY=\"200\" width=\"800\" height=\"200\"><content textType=\"body\"><p>正文内容</p><ul><li><p>要点一</p></li><li><p>要点二</p></li></ul></content></shape></data></slide>"
|
||||
]'
|
||||
```
|
||||
|
||||
也可以分两步（先创建空白 PPT，再逐页添加），详见 [+create 参考文档](references/lark-slides-create.md)。
|
||||
|
||||
> 以上是最小可用示例。更丰富的页面效果（渐变背景、卡片、图表、表格等），参考下方 Workflow 和 XML 模板。
|
||||
|
||||
## 执行前必做
|
||||
|
||||
> **重要**：`references/slides_xml_schema_definition.xml` 是此 skill 唯一正确的 XML 协议来源；其他 md 仅是对它和 CLI schema 的摘要。
|
||||
|
||||
### 必读（每次创建前）
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md) | **XML 元素和属性速查，必读** |
|
||||
|
||||
### 选读（需要时查阅）
|
||||
|
||||
| 场景 | 文档 |
|
||||
|------|------|
|
||||
| 需要了解详细 XML 结构 | [xml-format-guide.md](references/xml-format-guide.md) |
|
||||
| 需要 CLI 调用示例 | [examples.md](references/examples.md) |
|
||||
| 需要参考真实 PPT 的 XML | [slides_demo.xml](references/slides_demo.xml) |
|
||||
| 需要用 table/chart 等复杂元素 | [slides_xml_schema_definition.xml](references/slides_xml_schema_definition.xml)（完整 Schema） |
|
||||
| 需要了解某个命令的详细参数 | 对应命令的 reference 文档（见下方参考文档章节） |
|
||||
|
||||
## Workflow
|
||||
|
||||
> **这是演示文稿，不是文档。** 每页 slide 是独立的视觉画面，信息密度要低，排版要留白。
|
||||
|
||||
```text
|
||||
Step 1: 需求澄清 & 读取知识
|
||||
- 澄清用户需求：主题、受众、页数、风格偏好
|
||||
- 如果用户没有明确风格，根据主题推荐（见下方风格判断表）
|
||||
- 读取 XML Schema 参考：
|
||||
· xml-schema-quick-ref.md — 元素和属性速查
|
||||
· xml-format-guide.md — 详细结构与示例
|
||||
· slides_demo.xml — 真实 XML 示例
|
||||
|
||||
Step 2: 生成大纲 → 用户确认 → 创建
|
||||
- 生成结构化大纲（每页标题 + 要点 + 布局描述），交给用户确认
|
||||
- 10 页以内：用 slides +create --slides '[...]' 一步创建 PPT 并添加所有页面
|
||||
- 超过 10 页：先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide.create` 逐页添加
|
||||
- 每页 slide 需要完整的 XML：背景、文本、图形、配色
|
||||
- 复杂元素（table、chart）需参考 XSD 原文
|
||||
|
||||
Step 3: 审查 & 交付
|
||||
- 创建完成后，用 xml_presentations.get 读取全文 XML，确认：
|
||||
· 页数是否正确？每页内容是否完整？
|
||||
· 配色是否统一？字号层级是否合理？
|
||||
- 有问题 → 用 xml_presentation.slide.delete 删除问题页，重新创建
|
||||
- 没问题 → 交付：告知用户演示文稿 ID 和访问方式
|
||||
```
|
||||
|
||||
### jq 命令模板（编辑已有 PPT 时使用）
|
||||
|
||||
新建 PPT 推荐用 `+create --slides`。以下 jq 模板适用于向已有演示文稿追加页面的场景，可以避免手动转义双引号：
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentation.slide create \
|
||||
--as user \
|
||||
--params '{"xml_presentation_id":"YOUR_ID"}' \
|
||||
--data "$(jq -n --arg content '<slide xmlns="http://www.larkoffice.com/sml/2.0">
|
||||
<style><fill><fillColor color="BACKGROUND_COLOR"/></fill></style>
|
||||
<data>
|
||||
在这里放置 shape、line、table、chart 等元素
|
||||
</data>
|
||||
</slide>' '{slide:{content:$content}}')"
|
||||
```
|
||||
|
||||
### 风格快速判断表
|
||||
|
||||
> **注意**：渐变色必须使用 `rgba()` 格式并带百分比停靠点，如 `linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)`。使用 `rgb()` 或省略停靠点会导致服务端回退为白色。
|
||||
|
||||
| 场景/主题 | 推荐风格 | 背景 | 主色 | 文字色 |
|
||||
|----------|---------|------|------|-------|
|
||||
| 科技/AI/产品 | 深色科技风 | 深蓝渐变 `linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)` | 蓝色系 `rgb(59,130,246)` | 白色 |
|
||||
| 商务汇报/季度总结 | 浅色商务风 | 浅灰 `rgb(248,250,252)` | 深蓝 `rgb(30,60,114)` | 深灰 `rgb(30,41,59)` |
|
||||
| 教育/培训 | 清新明亮风 | 白色 `rgb(255,255,255)` | 绿色系 `rgb(34,197,94)` | 深灰 `rgb(51,65,85)` |
|
||||
| 创意/设计 | 渐变活力风 | 紫粉渐变 `linear-gradient(135deg,rgba(88,28,135,1) 0%,rgba(190,24,93,1) 100%)` | 粉紫色系 | 白色 |
|
||||
| 周报/日常汇报 | 简约专业风 | 浅灰 `rgb(248,250,252)` + 顶部彩色渐变条 | 蓝色 `rgb(59,130,246)` | 深色 `rgb(15,23,42)` |
|
||||
| 用户未指定 | 默认简约专业风 | 同上 | 同上 | 同上 |
|
||||
|
||||
### 页面布局建议
|
||||
|
||||
| 页面类型 | 布局要点 |
|
||||
|---------|---------|
|
||||
| 封面页 | 居中大标题 + 副标题 + 底部信息，背景用渐变或深色 |
|
||||
| 数据概览页 | 指标卡片横排（rect 背景 + 大号数字 + 小号说明），下方列表或图表 |
|
||||
| 内容页 | 左侧竖线装饰 + 标题，下方分栏或列表 |
|
||||
| 对比/表格页 | table 元素或并列卡片，表头深色背景白字 |
|
||||
| 图表页 | chart 元素（column/line/pie），配合文字说明 |
|
||||
| 结尾页 | 居中感谢语 + 装饰线，风格与封面呼应 |
|
||||
|
||||
### 大纲模板
|
||||
|
||||
生成大纲时使用以下格式，交给用户确认：
|
||||
|
||||
```text
|
||||
[PPT 标题] — [定位描述]，面向 [目标受众]
|
||||
|
||||
页面结构（N 页）：
|
||||
1. 封面页：[标题文案]
|
||||
2. [页面主题]：[要点1]、[要点2]、[要点3]
|
||||
3. [页面主题]：[要点描述]
|
||||
...
|
||||
N. 结尾页：[结尾文案]
|
||||
|
||||
风格：[配色方案]，[排版风格]
|
||||
```
|
||||
|
||||
### 常用 Slide XML 模板
|
||||
|
||||
可直接复制使用的模板（封面页、内容页、数据卡片页、结尾页）：[slide-templates.md](references/slide-templates.md)
|
||||
|
||||
---
|
||||
|
||||
## 核心概念
|
||||
|
||||
### URL 格式与 Token
|
||||
|
||||
| URL 格式 | 示例 | Token 类型 | 处理方式 |
|
||||
|----------|------|-----------|----------|
|
||||
| `/slides/` | `https://example.larkoffice.com/slides/xxxxxxxxxxxxx` | `xml_presentation_id` | URL 路径中的 token 直接作为 `xml_presentation_id` 使用 |
|
||||
| `/wiki/` | `https://example.larkoffice.com/wiki/wikcnxxxxxxxxx` | `wiki_token` | ⚠️ **不能直接使用**，需要先查询获取真实的 `obj_token` |
|
||||
|
||||
### Wiki 链接特殊处理（关键！）
|
||||
|
||||
知识库链接（`/wiki/TOKEN`）背后可能是云文档、电子表格、幻灯片等不同类型的文档。**不能直接假设 URL 中的 token 就是 `xml_presentation_id`**，必须先查询实际类型和真实 token。
|
||||
|
||||
#### 处理流程
|
||||
|
||||
1. **使用 `wiki.spaces.get_node` 查询节点信息**
|
||||
```bash
|
||||
lark-cli wiki spaces get_node --as user --params '{"token":"wiki_token"}'
|
||||
```
|
||||
|
||||
2. **从返回结果中提取关键信息**
|
||||
- `node.obj_type`：文档类型，幻灯片对应 `slides`
|
||||
- `node.obj_token`：**真实的演示文稿 token**（用于后续操作）
|
||||
- `node.title`：文档标题
|
||||
|
||||
3. **确认 `obj_type` 为 `slides` 后，使用 `obj_token` 作为 `xml_presentation_id`**
|
||||
|
||||
#### 查询示例
|
||||
|
||||
```bash
|
||||
# 查询 wiki 节点
|
||||
lark-cli wiki spaces get_node --as user --params '{"token":"wikcnxxxxxxxxx"}'
|
||||
```
|
||||
|
||||
返回结果示例：
|
||||
```json
|
||||
{
|
||||
"node": {
|
||||
"obj_type": "slides",
|
||||
"obj_token": "xxxxxxxxxxxx",
|
||||
"title": "2026 产品年度总结",
|
||||
"node_type": "origin",
|
||||
"space_id": "1234567890"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
# 用 obj_token 读取幻灯片内容
|
||||
lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"xxxxxxxxxxxx"}'
|
||||
```
|
||||
|
||||
### 资源关系
|
||||
|
||||
```text
|
||||
Wiki Space (知识空间)
|
||||
└── Wiki Node (知识库节点, obj_type: slides)
|
||||
└── obj_token → xml_presentation_id
|
||||
|
||||
Slides (演示文稿)
|
||||
├── xml_presentation_id (演示文稿唯一标识)
|
||||
├── revision_id (版本号)
|
||||
└── Slide (幻灯片页面)
|
||||
└── slide_id (页面唯一标识)
|
||||
```
|
||||
|
||||
## Shortcuts（推荐优先使用）
|
||||
|
||||
Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`）。有 Shortcut 的操作优先使用。
|
||||
|
||||
| Shortcut | 说明 |
|
||||
|----------|------|
|
||||
| [`+create`](references/lark-slides-create.md) | 创建 PPT（可选 `--slides` 一步添加页面），bot 模式自动授权 |
|
||||
|
||||
## API Resources
|
||||
|
||||
```bash
|
||||
lark-cli schema slides.<resource>.<method> # 调用 API 前必须先查看参数结构
|
||||
lark-cli slides <resource> <method> [flags] # 调用 API
|
||||
```
|
||||
|
||||
> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
|
||||
|
||||
### xml_presentations
|
||||
|
||||
- `get` — 读取ppt全文信息，xml格式返回
|
||||
|
||||
### xml_presentation.slide
|
||||
|
||||
- `create` — 在指定 xml 演示文稿下创建页面
|
||||
- `delete` — 删除指定 xml 演示文稿下的页面
|
||||
|
||||
## 核心规则
|
||||
|
||||
1. **先出大纲再动手**：创建 PPT 前先生成大纲交给用户确认，避免返工
|
||||
2. **创建流程**：10 页以内推荐 `slides +create --slides '[...]'` 一步创建；超过 10 页先 `slides +create` 创建空白 PPT，再用 `xml_presentation.slide.create` 逐页添加
|
||||
3. **`<slide>` 直接子元素只有 `<style>`、`<data>`、`<note>`**：文本和图形必须放在 `<data>` 内
|
||||
4. **文本通过 `<content>` 表达**：必须用 `<content><p>...</p></content>`，不能把文字直接写在 shape 内
|
||||
5. **保存关键 ID**：后续操作需要 `xml_presentation_id`、`slide_id`、`revision_id`
|
||||
6. **删除谨慎**：删除操作不可逆，且至少保留一页幻灯片
|
||||
|
||||
## 权限表
|
||||
|
||||
| 方法 | 所需 scope |
|
||||
|------|-----------|
|
||||
| `slides +create` | `slides:presentation:create`, `slides:presentation:write_only` |
|
||||
| `xml_presentations.get` | `slides:presentation:read` |
|
||||
| `xml_presentation.slide.create` | `slides:presentation:update` 或 `slides:presentation:write_only` |
|
||||
| `xml_presentation.slide.delete` | `slides:presentation:update` 或 `slides:presentation:write_only` |
|
||||
|
||||
## 常见错误速查
|
||||
|
||||
| 错误码 | 含义 | 解决方案 |
|
||||
|--------|------|----------|
|
||||
| 400 | XML 格式错误 | 检查 XML 语法，确保标签闭合 |
|
||||
| 400 | create 内容超出支持范围 | `xml_presentations.create` 仅用于创建空白 PPT，不要在这里传完整 slide 内容 |
|
||||
| 400 | 请求包装错误 | 检查 `--data` 是否按 schema 传入 `xml_presentation.content` 或 `slide.content` |
|
||||
| 404 | 演示文稿不存在 | 检查 `xml_presentation_id` 是否正确 |
|
||||
| 404 | 幻灯片不存在 | 检查 `slide_id` 是否正确 |
|
||||
| 403 | 权限不足 | 检查是否拥有对应的 scope |
|
||||
| 400 | 无法删除唯一幻灯片 | 演示文稿至少保留一页幻灯片 |
|
||||
|
||||
## 创建前自查
|
||||
|
||||
逐页生成 XML 前，快速检查：
|
||||
|
||||
- [ ] 每页背景色/渐变是否设置？风格是否与整体一致？
|
||||
- [ ] 标题用大字号（28-48），正文用小字号（13-16），层级分明？
|
||||
- [ ] 同类元素配色一致？（如所有指标卡片同色系、所有正文同色）
|
||||
- [ ] 装饰元素（分割线、色块、竖线）颜色是否与主色协调？
|
||||
- [ ] 文本框尺寸是否足够容纳内容？（宽度 × 高度）
|
||||
- [ ] shape 的 `type` 是否正确？（文本框用 `text`，装饰用 `rect`）
|
||||
- [ ] XML 标签是否全部正确闭合？特殊字符（`&`、`<`、`>`）是否转义？
|
||||
|
||||
## 症状 → 修复表
|
||||
|
||||
| 看到的问题 | 改什么 |
|
||||
|-----------|--------|
|
||||
| 文字被截断/看不全 | 增大 shape 的 `width` 或 `height` |
|
||||
| 元素重叠 | 调整 `topLeftX`/`topLeftY`，拉开间距 |
|
||||
| 页面大面积空白 | 缩小元素间距，或增加内容填充 |
|
||||
| 文字和背景色太接近 | 深色背景用浅色文字，浅色背景用深色文字 |
|
||||
| 表格列宽不合理 | 调整 `colgroup` 中 `col` 的 `width` 值 |
|
||||
| 图表没有显示 | 检查 `chartPlotArea` 和 `chartData` 是否都包含，`dim1`/`dim2` 数据数量是否匹配 |
|
||||
| 渐变背景变成白色 | 渐变必须用 `rgba()` 格式 + 百分比停靠点，如 `linear-gradient(135deg,rgba(30,60,114,1) 0%,rgba(59,130,246,1) 100%)`；用 `rgb()` 或省略停靠点会被回退为白色 |
|
||||
| 渐变方向不对 | 调整 `linear-gradient` 的角度（`90deg` 水平、`180deg` 垂直、`135deg` 对角线） |
|
||||
| 整体风格不统一 | 封面页和结尾页用同一背景，内容页保持一致的配色和字号体系 |
|
||||
| API 返回 400 | 检查 XML 语法：标签闭合、属性引号、特殊字符转义 |
|
||||
| API 返回 3350001 | `xml_presentation_id` 不是通过 `xml_presentations.create` 创建的，或 token 不正确 |
|
||||
|
||||
## 参考文档
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| [lark-slides-create.md](references/lark-slides-create.md) | **+create Shortcut：创建 PPT（支持 `--slides` 一步添加页面）** |
|
||||
| [xml-schema-quick-ref.md](references/xml-schema-quick-ref.md) | **XML Schema 精简速查（必读）** |
|
||||
| [slide-templates.md](references/slide-templates.md) | 可复制的 Slide XML 模板 |
|
||||
| [xml-format-guide.md](references/xml-format-guide.md) | XML 详细结构与示例 |
|
||||
| [examples.md](references/examples.md) | CLI 调用示例 |
|
||||
| [slides_demo.xml](references/slides_demo.xml) | 真实 PPT 的完整 XML |
|
||||
| [slides_xml_schema_definition.xml](references/slides_xml_schema_definition.xml) | **完整 Schema 定义**（唯一协议依据） |
|
||||
| [lark-slides-xml-presentations-create.md](references/lark-slides-xml-presentations-create.md) | 创建空白 PPT 命令详情 |
|
||||
| [lark-slides-xml-presentations-get.md](references/lark-slides-xml-presentations-get.md) | 读取 PPT 命令详情 |
|
||||
| [lark-slides-xml-presentation-slide-create.md](references/lark-slides-xml-presentation-slide-create.md) | 添加幻灯片命令详情 |
|
||||
| [lark-slides-xml-presentation-slide-delete.md](references/lark-slides-xml-presentation-slide-delete.md) | 删除幻灯片命令详情 |
|
||||
|
||||
> **注意**：如果 md 内容与 `slides_xml_schema_definition.xml` 或 `lark-cli schema slides.<resource>.<method>` 输出不一致，以后两者为准。
|
||||
179
skills/lark-slides/references/examples.md
Normal file
179
skills/lark-slides/references/examples.md
Normal file
@@ -0,0 +1,179 @@
|
||||
# 完整操作示例
|
||||
|
||||
本文档提供与 CLI schema 一致的调用示例，XML 内容均遵循 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)。
|
||||
|
||||
> **重要**：创建 PPT 请优先使用 `slides +create`；实际页面内容请使用 `xml_presentation.slide.create` 逐页添加。
|
||||
|
||||
## 目录
|
||||
|
||||
- [示例 1: 使用 Shortcut 创建空白演示文稿](#示例-1-使用-shortcut-创建空白演示文稿)
|
||||
- [示例 2: 创建后添加第一页](#示例-2-创建后添加第一页)
|
||||
- [示例 3: 读取 XML 内容](#示例-3-读取-xml-内容)
|
||||
- [示例 4: 在指定页面前插入新幻灯片](#示例-4-在指定页面前插入新幻灯片)
|
||||
- [示例 5: 删除幻灯片](#示例-5-删除幻灯片)
|
||||
- [示例 6: 从文件读取 XML 后添加页面](#示例-6-从文件读取-xml-后添加页面)
|
||||
|
||||
## 示例 1: 使用 Shortcut 创建空白演示文稿
|
||||
|
||||
```bash
|
||||
lark-cli slides +create --title "项目汇报"
|
||||
```
|
||||
|
||||
预期返回结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"xml_presentation_id": "slides_example_presentation_id",
|
||||
"title": "项目汇报",
|
||||
"revision_id": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 示例 2: 创建后添加第一页
|
||||
|
||||
```bash
|
||||
PRESENTATION_ID=$(lark-cli slides +create --title "季度复盘" | jq -r '.data.xml_presentation_id')
|
||||
|
||||
lark-cli slides xml_presentation.slide create --as user --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" --data '{
|
||||
"slide": {
|
||||
"content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><style><fill><fillColor color=\"rgb(245, 245, 245)\"/></fill></style><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"72\" width=\"760\" height=\"90\"><content textType=\"title\"><p>2024 Q3 季度复盘</p></content></shape><shape type=\"text\" topLeftX=\"80\" topLeftY=\"190\" width=\"520\" height=\"220\"><content textType=\"body\"><p>关键结论</p><ul><li><p>收入增长 30%</p></li><li><p>重点项目全部上线</p></li><li><p>用户满意度持续提升</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>"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## 示例 3: 读取 XML 内容
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentations get --as user --params '{
|
||||
"xml_presentation_id": "slides_example_presentation_id"
|
||||
}'
|
||||
```
|
||||
|
||||
提取 XML 内容：
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentations get --as user --params '{
|
||||
"xml_presentation_id": "slides_example_presentation_id"
|
||||
}' | jq -r '.xml_presentation.content'
|
||||
```
|
||||
|
||||
预期返回结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"xml_presentation": {
|
||||
"presentation_id": "slides_example_presentation_id",
|
||||
"revision_id": 3,
|
||||
"content": "<presentation xmlns=\"http://www.larkoffice.com/sml/2.0\" height=\"540\" width=\"960\">...</presentation>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 示例 4: 在指定页面前插入新幻灯片
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentation.slide create --as user --params '{
|
||||
"xml_presentation_id": "slides_example_presentation_id"
|
||||
}' --data '{
|
||||
"slide": {
|
||||
"content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新增页面</p></content></shape><shape type=\"text\" topLeftX=\"80\" topLeftY=\"200\" width=\"800\" height=\"180\"><content textType=\"body\"><p>这是新增页面的正文。</p></content></shape></data></slide>"
|
||||
},
|
||||
"before_slide_id": "sld_before_target"
|
||||
}'
|
||||
```
|
||||
|
||||
预期返回结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"slide_id": "slide_example_id",
|
||||
"revision_id": 100
|
||||
}
|
||||
```
|
||||
|
||||
## 示例 5: 删除幻灯片
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentation.slide delete --as user --params '{
|
||||
"xml_presentation_id": "slides_example_presentation_id",
|
||||
"slide_id": "slide_example_id"
|
||||
}'
|
||||
```
|
||||
|
||||
预期返回结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"revision_id": 101
|
||||
}
|
||||
```
|
||||
|
||||
## 示例 6: 从文件读取 XML 后添加页面
|
||||
|
||||
先准备 `slide.xml`：
|
||||
|
||||
```xml
|
||||
<slide xmlns="http://www.larkoffice.com/sml/2.0">
|
||||
<data>
|
||||
<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
|
||||
<content textType="title">
|
||||
<p>从文件加载</p>
|
||||
</content>
|
||||
</shape>
|
||||
</data>
|
||||
</slide>
|
||||
```
|
||||
|
||||
先创建演示文稿：
|
||||
|
||||
```bash
|
||||
PRESENTATION_ID=$(lark-cli slides +create --title "从文件添加页面" | jq -r '.data.xml_presentation_id')
|
||||
```
|
||||
|
||||
再用 `jq` 组装请求体，从文件添加页面：
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentation.slide create --as user \
|
||||
--params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" \
|
||||
--data "$(jq -n --arg content "$(cat slide.xml)" '{slide:{content:$content}}')"
|
||||
```
|
||||
|
||||
## 常见处理技巧
|
||||
|
||||
### 获取最新 revision_id
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentations get --as user --params '{
|
||||
"xml_presentation_id": "slides_example_presentation_id"
|
||||
}' | jq -r '.xml_presentation.revision_id'
|
||||
```
|
||||
|
||||
### 批量插入多页
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
PRESENTATION_ID="slides_example_presentation_id"
|
||||
|
||||
slides=(
|
||||
'<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 1</p></content></shape></data></slide>'
|
||||
'<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 2</p></content></shape></data></slide>'
|
||||
)
|
||||
|
||||
for slide_xml in "${slides[@]}"; do
|
||||
payload=$(jq -n --arg content "$slide_xml" '{slide:{content:$content}}')
|
||||
lark-cli slides xml_presentation.slide create --as user --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" --data "$payload"
|
||||
done
|
||||
```
|
||||
|
||||
### 本地校验 XML 基本语法
|
||||
|
||||
```bash
|
||||
xmllint --noout presentation.xml
|
||||
```
|
||||
|
||||
### 真实示例
|
||||
|
||||
- [slides_demo.xml](slides_demo.xml) 提供了更完整的页面示例，包含 `theme`、渐变填充、图片、图标和备注内容。
|
||||
98
skills/lark-slides/references/lark-slides-create.md
Normal file
98
skills/lark-slides/references/lark-slides-create.md
Normal file
@@ -0,0 +1,98 @@
|
||||
|
||||
# slides +create（创建飞书幻灯片）
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
创建一个新的飞书幻灯片演示文稿，可选一步添加页面内容。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 创建空白 PPT
|
||||
lark-cli slides +create --title "项目汇报"
|
||||
|
||||
# 创建 PPT + 添加 slide 页面
|
||||
lark-cli slides +create --title "项目汇报" --slides '[
|
||||
"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>封面</p></content></shape></data></slide>",
|
||||
"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>第二页</p></content></shape></data></slide>"
|
||||
]'
|
||||
|
||||
# 以应用身份创建（自动授权当前用户）
|
||||
lark-cli slides +create --title "项目汇报" --as bot
|
||||
|
||||
# 预览（不执行）
|
||||
lark-cli slides +create --title "项目汇报" --slides '[...]' --dry-run
|
||||
```
|
||||
|
||||
## 返回值
|
||||
|
||||
工具成功执行后，返回一个 JSON 对象，包含以下字段：
|
||||
|
||||
- **`xml_presentation_id`**（string）：演示文稿的唯一标识符，后续添加页面时需要此 ID
|
||||
- **`title`**（string）：演示文稿标题
|
||||
- **`revision_id`**（integer）：演示文稿版本号
|
||||
- **`slide_ids`**（string[]，可选）：仅传 `--slides` 时返回，成功添加的页面 ID 列表
|
||||
- **`slides_added`**（integer，可选）：仅传 `--slides` 时返回，成功添加的页面数量
|
||||
- **`permission_grant`**（object，可选）：仅 `--as bot` 时返回，说明是否已自动为当前 CLI 用户授予可管理权限
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 不传 `--slides` 时，`slides +create` 只创建空白演示文稿。创建后需要使用 `xml_presentation.slide create` 逐页添加 slide 内容。
|
||||
>
|
||||
> 传了 `--slides` 时，CLI 先创建空白演示文稿，再逐页调用 `xml_presentation.slide create` 添加页面。如果某一页添加失败，CLI 会停止并报错，已创建的演示文稿和已添加的页面会保留。
|
||||
>
|
||||
> 如果演示文稿是**以应用身份（bot）创建**的，如 `lark-cli slides +create --as bot`，CLI 会**尝试为当前 CLI 用户自动授予该演示文稿的 `full_access`（可管理权限）**。
|
||||
>
|
||||
> 以应用身份创建时，结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
|
||||
> - `status = granted`：当前 CLI 用户已获得该演示文稿的可管理权限
|
||||
> - `status = skipped`：本地没有可用的当前用户 `open_id`，因此不会自动授权
|
||||
> - `status = failed`：演示文稿已创建成功，但自动授权用户失败
|
||||
>
|
||||
> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--title` | 否 | 演示文稿标题（不传则默认 "Untitled"） |
|
||||
| `--slides` | 否 | slide 内容 JSON 数组，每个元素是一个 `<slide>` XML 字符串（最多 10 个；超过 10 页请先用 `+create` 创建空白 PPT，再用 `xml_presentation.slide create` 逐页添加） |
|
||||
|
||||
## `--slides` 参数格式
|
||||
|
||||
```json
|
||||
[
|
||||
"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\">...第1页XML...</slide>",
|
||||
"<slide xmlns=\"http://www.larkoffice.com/sml/2.0\">...第2页XML...</slide>"
|
||||
]
|
||||
```
|
||||
|
||||
JSON string 数组，每个元素是一页 slide 的完整 XML。CLI 内部负责包装成 API 所需的 `{"slide": {"content": "..."}}` 格式并逐页调用。
|
||||
|
||||
## 创建后续步骤
|
||||
|
||||
如果没有使用 `--slides`，`slides +create` 返回的 `xml_presentation_id` 用于后续操作：
|
||||
|
||||
```bash
|
||||
# 第 1 步：创建空白 PPT
|
||||
PRES_ID=$(lark-cli slides +create --title "项目汇报" | jq -r '.data.xml_presentation_id')
|
||||
|
||||
# 第 2 步：添加页面（使用返回的 xml_presentation_id）
|
||||
lark-cli slides xml_presentation.slide create --as user \
|
||||
--params "{\"xml_presentation_id\":\"$PRES_ID\"}" \
|
||||
--data '{
|
||||
"slide": {
|
||||
"content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\">...</slide>"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## 常见错误
|
||||
|
||||
| 错误码 | 含义 | 解决方案 |
|
||||
|--------|------|----------|
|
||||
| 400 | 参数错误 | 检查参数格式是否正确 |
|
||||
| 403 | 权限不足 | 检查是否拥有 `slides:presentation:create` 和 `slides:presentation:write_only` scope |
|
||||
|
||||
## 相关命令
|
||||
|
||||
- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) — 添加幻灯片页面
|
||||
- [xml_presentations get](lark-slides-xml-presentations-get.md) — 读取 PPT 内容
|
||||
@@ -0,0 +1,210 @@
|
||||
# lark-slides xml_presentation.slide create
|
||||
|
||||
## 用途
|
||||
|
||||
在指定的 XML 演示文稿中创建新的幻灯片页面，通常用于给 `slides +create` 创建出的空白 PPT 逐页补充内容。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentation.slide create --as user --params '<json_params>' --data '<json_data>'
|
||||
```
|
||||
|
||||
## 参数说明
|
||||
|
||||
| 参数 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `--params` | JSON string | 是 | 路径参数与查询参数 |
|
||||
| `--data` | JSON string | 是 | 请求体，包含新页面内容 |
|
||||
|
||||
### params JSON 结构
|
||||
|
||||
```json
|
||||
{
|
||||
"xml_presentation_id": "slides_example_presentation_id",
|
||||
"revision_id": -1,
|
||||
"tid": "idMock"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `xml_presentation_id` | string | 是 | 目标演示文稿的唯一标识符 |
|
||||
| `revision_id` | integer | 否 | 演示文稿版本号，`-1` 表示最新版本 |
|
||||
| `tid` | string | 否 | 锁的事务 ID |
|
||||
|
||||
### data JSON 结构
|
||||
|
||||
```json
|
||||
{
|
||||
"slide": {
|
||||
"slide_id": "slide_example_id",
|
||||
"content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\">...</slide>"
|
||||
},
|
||||
"before_slide_id": "slide_before_target"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `slide.slide_id` | string | 否 | 幻灯片页面 short ID |
|
||||
| `slide.content` | string | 否 | 新幻灯片的 XML 内容 |
|
||||
| `before_slide_id` | string | 否 | 插入到指定页面之前 |
|
||||
|
||||
## slide XML 结构
|
||||
|
||||
`slide.content` 是一个完整的 `<slide>` 元素，遵循 SML 2.0 Schema：
|
||||
|
||||
```xml
|
||||
<slide xmlns="http://www.larkoffice.com/sml/2.0">
|
||||
<data>
|
||||
<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
|
||||
<content textType="title">
|
||||
<p>标题</p>
|
||||
</content>
|
||||
</shape>
|
||||
</data>
|
||||
</slide>
|
||||
```
|
||||
|
||||
详细格式请参考 [xml-format-guide.md](xml-format-guide.md) 和 [xml-schema-quick-ref.md](xml-schema-quick-ref.md)。
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 在末尾添加幻灯片
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentation.slide create --as user --params '{
|
||||
"xml_presentation_id": "slides_example_presentation_id"
|
||||
}' --data '{
|
||||
"slide": {
|
||||
"content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新页面标题</p></content></shape><shape type=\"text\" topLeftX=\"80\" topLeftY=\"200\" width=\"800\" height=\"180\"><content textType=\"body\"><p>内容文本</p></content></shape></data></slide>"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### 在指定页面前插入幻灯片
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentation.slide create --as user --params '{
|
||||
"xml_presentation_id": "slides_example_presentation_id"
|
||||
}' --data '{
|
||||
"slide": {
|
||||
"content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>插入的标题页</p></content></shape></data></slide>"
|
||||
},
|
||||
"before_slide_id": "slide_before_target"
|
||||
}'
|
||||
```
|
||||
|
||||
### 带图形元素的幻灯片
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentation.slide create --as user --params '{
|
||||
"xml_presentation_id": "slides_example_presentation_id"
|
||||
}' --data '{
|
||||
"slide": {
|
||||
"content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"520\" height=\"120\"><content textType=\"title\"><p>数据展示</p></content></shape><shape type=\"rect\" topLeftX=\"700\" topLeftY=\"100\" width=\"200\" height=\"150\"><fill><fillColor color=\"rgb(100, 149, 237)\"/></fill></shape></data></slide>"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### 从文件读取 XML
|
||||
|
||||
```bash
|
||||
# 先创建 slide.xml 文件
|
||||
cat > slide.xml << 'EOF'
|
||||
<slide xmlns="http://www.larkoffice.com/sml/2.0">
|
||||
<data>
|
||||
<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
|
||||
<content textType="title">
|
||||
<p>从文件加载</p>
|
||||
</content>
|
||||
</shape>
|
||||
<shape type="text" topLeftX="80" topLeftY="200" width="800" height="180">
|
||||
<content textType="body">
|
||||
<p>这是从文件读取的幻灯片内容</p>
|
||||
</content>
|
||||
</shape>
|
||||
</data>
|
||||
</slide>
|
||||
EOF
|
||||
|
||||
# 然后创建幻灯片
|
||||
lark-cli slides xml_presentation.slide create --as user \
|
||||
--params '{"xml_presentation_id":"slides_example_presentation_id"}' \
|
||||
--data "$(jq -n --arg content "$(cat slide.xml)" '{slide:{content:$content}}')"
|
||||
```
|
||||
|
||||
## 返回值
|
||||
|
||||
成功时返回创建的幻灯片信息：
|
||||
|
||||
```json
|
||||
{
|
||||
"slide_id": "slide_example_id",
|
||||
"revision_id": 100
|
||||
}
|
||||
```
|
||||
|
||||
### 返回字段说明
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `slide_id` | string | 新幻灯片的唯一标识 |
|
||||
| `revision_id` | integer | 演示文稿最新版本号 |
|
||||
|
||||
## slide 元素可用子元素
|
||||
|
||||
| 元素 | 说明 |
|
||||
|------|------|
|
||||
| `<style>` | 页面样式（背景填充） |
|
||||
| `<data>` | 图形元素容器（shape、img、table、chart 等） |
|
||||
| `<note>` | 演讲者备注 |
|
||||
|
||||
## 常见错误
|
||||
|
||||
| 错误码 | 含义 | 解决方案 |
|
||||
|--------|------|----------|
|
||||
| 404 | 演示文稿不存在 | 检查 `xml_presentation_id` 是否正确 |
|
||||
| 400 | XML 格式错误 | 检查 `slide.content` 是否是完整 `<slide>` 元素 |
|
||||
| 400 | 请求体结构错误 | 检查是否按 `slide.content` 和 `before_slide_id` 包装 |
|
||||
| 403 | 权限不足 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope |
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **执行前必做**: 使用 `lark-cli schema slides.xml_presentation.slide.create` 查看最新的参数结构
|
||||
2. **slide.content 格式**: 必须是完整的 `<slide>` 元素，不是整个 presentation
|
||||
3. **命名空间建议**: 协议标准写法应带 `xmlns`，例如 `<slide xmlns="http://www.larkoffice.com/sml/2.0">`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证
|
||||
4. **fill / border 写法**: 颜色填充使用 `<fill><fillColor color="..."/></fill>`，边框常用 `<border color="..." width="2"/>`
|
||||
5. **插入位置**: 通过 `before_slide_id` 指定插入目标，而不是用 `position`
|
||||
6. **JSON 转义**: 如果直接内联 XML，需要正确转义双引号
|
||||
7. **建议**: 先使用 `xml_presentations.get` 获取现有结构，再添加新页面
|
||||
|
||||
## 批量添加建议
|
||||
|
||||
如果需要添加多张幻灯片，建议先明确每一页的 `before_slide_id`，或直接按最终顺序逐页追加：
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
PRESENTATION_ID="slides_example_presentation_id"
|
||||
|
||||
declare -a slides=(
|
||||
'<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 1</p></content></shape></data></slide>'
|
||||
'<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 2</p></content></shape></data></slide>'
|
||||
'<slide xmlns="http://www.larkoffice.com/sml/2.0"><data><shape type="text" topLeftX="80" topLeftY="80" width="800" height="120"><content textType="title"><p>页面 3</p></content></shape></data></slide>'
|
||||
)
|
||||
|
||||
for slide_xml in "${slides[@]}"; do
|
||||
payload=$(jq -n --arg content "$slide_xml" '{slide:{content:$content}}')
|
||||
lark-cli slides xml_presentation.slide create --as user --params "{\"xml_presentation_id\":\"$PRESENTATION_ID\"}" --data "$payload"
|
||||
done
|
||||
```
|
||||
|
||||
## 相关命令
|
||||
|
||||
- [slides +create](lark-slides-create.md) - 创建空白 PPT
|
||||
- [xml_presentations get](lark-slides-xml-presentations-get.md) - 读取 PPT 内容
|
||||
- [xml_presentation.slide delete](lark-slides-xml-presentation-slide-delete.md) - 删除幻灯片页面
|
||||
- [xml-format-guide.md](xml-format-guide.md) - XML 格式详细规范
|
||||
- [xml-schema-quick-ref.md](xml-schema-quick-ref.md) - Schema 快速参考
|
||||
@@ -0,0 +1,119 @@
|
||||
# lark-slides xml_presentation.slide delete
|
||||
|
||||
## 用途
|
||||
|
||||
删除指定 XML 演示文稿中的幻灯片页面。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentation.slide delete --as user --params '<json_params>'
|
||||
```
|
||||
|
||||
## 参数说明
|
||||
|
||||
| 参数 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `--params` | JSON string | 是 | 路径参数与查询参数 |
|
||||
|
||||
### params JSON 结构
|
||||
|
||||
```json
|
||||
{
|
||||
"xml_presentation_id": "slides_example_presentation_id",
|
||||
"slide_id": "slide_example_id",
|
||||
"revision_id": -1,
|
||||
"tid": "idMock"
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `xml_presentation_id` | string | 是 | 演示文稿的唯一标识符 |
|
||||
| `slide_id` | string | 是 | 要删除的幻灯片唯一标识符 |
|
||||
| `revision_id` | integer | 否 | 演示文稿版本号，`-1` 表示最新版本 |
|
||||
| `tid` | string | 否 | 锁的事务 ID |
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 删除指定幻灯片
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentation.slide delete --as user --params '{
|
||||
"xml_presentation_id": "slides_example_presentation_id",
|
||||
"slide_id": "slide_example_id"
|
||||
}'
|
||||
```
|
||||
|
||||
### 结合查询删除（使用 jq）
|
||||
|
||||
```bash
|
||||
# 先读取 XML 内容，确认待删除页面
|
||||
lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}' | jq -r '.xml_presentation.content'
|
||||
|
||||
# 然后按已知 slide_id 删除
|
||||
lark-cli slides xml_presentation.slide delete --as user --params '{"xml_presentation_id":"slides_example_presentation_id","slide_id":"slide_example_id"}'
|
||||
```
|
||||
|
||||
## 返回值
|
||||
|
||||
成功时返回删除确认信息：
|
||||
|
||||
```json
|
||||
{
|
||||
"revision_id": 100
|
||||
}
|
||||
```
|
||||
|
||||
### 返回字段说明
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `revision_id` | integer | 删除后的最新版本号 |
|
||||
|
||||
## 常见错误
|
||||
|
||||
| 错误码 | 含义 | 解决方案 |
|
||||
|--------|------|----------|
|
||||
| 404 | 演示文稿不存在 | 检查 `xml_presentation_id` 是否正确 |
|
||||
| 404 | 幻灯片不存在 | 检查 `slide_id` 是否正确，或该幻灯片已被删除 |
|
||||
| 400 | 无法删除唯一幻灯片 | 演示文稿至少保留一页幻灯片 |
|
||||
| 403 | 权限不足 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope |
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **执行前必做**: 使用 `lark-cli schema slides.xml_presentation.slide.delete` 查看最新的参数结构
|
||||
2. **删除不可逆**: 删除操作无法撤销，请确保已备份重要内容
|
||||
3. **至少保留一页**: 演示文稿必须至少保留一页幻灯片，删除最后一页会报错
|
||||
4. **版本控制**: 如果依赖版本号并发控制，删除前先确认 `revision_id`
|
||||
5. **获取 slide_id**: 创建幻灯片时请保存返回值；仅靠 `get` 返回的 XML 无法直接推导服务端 short ID
|
||||
|
||||
## 如何获取 slide_id
|
||||
|
||||
### 方法 1: 创建时保存
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentation.slide create --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}' --data '{
|
||||
"slide": {
|
||||
"content": "<slide xmlns=\"http://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新页面</p></content></shape></data></slide>"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
返回结果中的 `slide_id` 就是后续删除所需的值。
|
||||
|
||||
## 批量删除建议
|
||||
|
||||
如果需要删除多张幻灯片，建议先整理好待删 `slide_id` 列表，再逐个删除：
|
||||
|
||||
```bash
|
||||
for slide_id in sld_a sld_b sld_c; do
|
||||
lark-cli slides xml_presentation.slide delete --as user --params "{\"xml_presentation_id\":\"slides_example_presentation_id\",\"slide_id\":\"$slide_id\"}"
|
||||
done
|
||||
```
|
||||
|
||||
## 相关命令
|
||||
|
||||
- [slides +create](lark-slides-create.md) - 创建空白 PPT
|
||||
- [xml_presentations get](lark-slides-xml-presentations-get.md) - 读取 PPT 内容
|
||||
- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) - 添加幻灯片页面
|
||||
@@ -0,0 +1,94 @@
|
||||
# lark-slides xml_presentations get
|
||||
|
||||
## 用途
|
||||
|
||||
读取飞书幻灯片（PPT）演示文稿的完整 XML 内容信息。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentations get --as user --params '<json_params>'
|
||||
```
|
||||
|
||||
## 参数说明
|
||||
|
||||
| 参数 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `--params` | JSON string | 是 | 路径参数与查询参数，结构以 schema 为准 |
|
||||
|
||||
### params JSON 结构
|
||||
|
||||
```json
|
||||
{
|
||||
"xml_presentation_id": "slides_example_presentation_id",
|
||||
"revision_id": -1
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `xml_presentation_id` | string | 是 | 演示文稿的唯一标识符 |
|
||||
| `revision_id` | integer | 否 | 版本号，`-1` 表示最新版本 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 基础示例
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}'
|
||||
```
|
||||
|
||||
### 结合 jq 格式化输出
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}' | jq -r '.xml_presentation.content'
|
||||
```
|
||||
|
||||
### 保存到文件
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"slides_example_presentation_id"}' > presentation_data.json
|
||||
```
|
||||
|
||||
## 返回值
|
||||
|
||||
成功时返回演示文稿的完整信息：
|
||||
|
||||
```json
|
||||
{
|
||||
"xml_presentation": {
|
||||
"presentation_id": "slides_example_presentation_id",
|
||||
"revision_id": 1,
|
||||
"content": "<presentation xmlns=\"http://www.larkoffice.com/sml/2.0\" height=\"540\" width=\"960\"></presentation>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 返回字段说明
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `xml_presentation.presentation_id` | string | 演示文稿唯一标识 |
|
||||
| `xml_presentation.revision_id` | integer | 版本号 |
|
||||
| `xml_presentation.content` | string | XML 格式的完整内容 |
|
||||
|
||||
## 常见错误
|
||||
|
||||
| 错误码 | 含义 | 解决方案 |
|
||||
|--------|------|----------|
|
||||
| 404 | 演示文稿不存在 | 检查 `xml_presentation_id` 是否正确 |
|
||||
| 403 | 权限不足 | 检查是否拥有 `slides:presentation:read` scope，或是否有访问权限 |
|
||||
| 400 | 参数格式错误 | 确保 `--params` 是合法的 JSON 字符串 |
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **执行前必做**: 使用 `lark-cli schema slides.xml_presentations.get` 查看最新的参数结构
|
||||
2. 返回的 XML 在 `xml_presentation.content` 字段中
|
||||
3. 如果只需要部分信息，可以使用 `jq` 等工具过滤返回结果
|
||||
4. 建议将获取的 XML 保存为文件，便于后续编辑或备份
|
||||
|
||||
## 相关命令
|
||||
|
||||
- [slides +create](lark-slides-create.md) - 创建空白 PPT
|
||||
- [xml_presentation.slide create](lark-slides-xml-presentation-slide-create.md) - 添加幻灯片页面
|
||||
- [xml_presentation.slide delete](lark-slides-xml-presentation-slide-delete.md) - 删除幻灯片页面
|
||||
99
skills/lark-slides/references/slide-templates.md
Normal file
99
skills/lark-slides/references/slide-templates.md
Normal file
@@ -0,0 +1,99 @@
|
||||
# Slide XML 模板
|
||||
|
||||
可直接复制使用的 slide XML 模板。使用 `jq` 包装后传给 `xml_presentation.slide.create`：
|
||||
|
||||
```bash
|
||||
lark-cli slides xml_presentation.slide create --as user \
|
||||
--params '{"xml_presentation_id":"YOUR_ID"}' \
|
||||
--data "$(jq -n --arg content 'PASTE_XML_HERE' '{slide:{content:$content}}')"
|
||||
```
|
||||
|
||||
## 深色封面页
|
||||
|
||||
```xml
|
||||
<slide xmlns="http://www.larkoffice.com/sml/2.0">
|
||||
<style><fill><fillColor color="linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)"/></fill></style>
|
||||
<data>
|
||||
<shape type="text" topLeftX="80" topLeftY="160" width="800" height="70">
|
||||
<content><p textAlign="center"><strong><span color="rgb(255,255,255)" fontSize="44">主标题</span></strong></p></content>
|
||||
</shape>
|
||||
<shape type="text" topLeftX="80" topLeftY="250" width="800" height="35">
|
||||
<content><p textAlign="center"><span color="rgb(148,163,184)" fontSize="20">副标题</span></p></content>
|
||||
</shape>
|
||||
<shape type="text" topLeftX="80" topLeftY="420" width="800" height="25">
|
||||
<content><p textAlign="center"><span color="rgb(100,116,139)" fontSize="14">底部信息</span></p></content>
|
||||
</shape>
|
||||
</data>
|
||||
</slide>
|
||||
```
|
||||
|
||||
## 浅色内容页
|
||||
|
||||
```xml
|
||||
<slide xmlns="http://www.larkoffice.com/sml/2.0">
|
||||
<style><fill><fillColor color="rgb(248,250,252)"/></fill></style>
|
||||
<data>
|
||||
<shape type="rect" topLeftX="60" topLeftY="40" width="4" height="35">
|
||||
<fill><fillColor color="rgb(59,130,246)"/></fill>
|
||||
</shape>
|
||||
<shape type="text" topLeftX="76" topLeftY="36" width="600" height="45">
|
||||
<content><p><strong><span color="rgb(15,23,42)" fontSize="28">页面标题</span></strong></p></content>
|
||||
</shape>
|
||||
<shape type="text" topLeftX="60" topLeftY="100" width="840" height="380">
|
||||
<content textType="body" lineSpacing="multiple:1.8">
|
||||
<p><span color="rgb(51,65,85)" fontSize="15">正文段落</span></p>
|
||||
<ul>
|
||||
<li><p><span color="rgb(51,65,85)" fontSize="15">要点一</span></p></li>
|
||||
<li><p><span color="rgb(51,65,85)" fontSize="15">要点二</span></p></li>
|
||||
<li><p><span color="rgb(51,65,85)" fontSize="15">要点三</span></p></li>
|
||||
</ul>
|
||||
</content>
|
||||
</shape>
|
||||
</data>
|
||||
</slide>
|
||||
```
|
||||
|
||||
## 数据卡片页（横排指标）
|
||||
|
||||
```xml
|
||||
<slide xmlns="http://www.larkoffice.com/sml/2.0">
|
||||
<style><fill><fillColor color="rgb(248,250,252)"/></fill></style>
|
||||
<data>
|
||||
<shape type="text" topLeftX="60" topLeftY="36" width="600" height="45">
|
||||
<content><p><strong><span color="rgb(15,23,42)" fontSize="28">数据概览</span></strong></p></content>
|
||||
</shape>
|
||||
<!-- 卡片 1 -->
|
||||
<shape type="rect" topLeftX="60" topLeftY="100" width="260" height="140">
|
||||
<fill><fillColor color="rgb(255,255,255)"/></fill>
|
||||
<border color="rgba(0,0,0,0.08)" width="1"/>
|
||||
</shape>
|
||||
<shape type="text" topLeftX="60" topLeftY="115" width="260" height="50">
|
||||
<content><p textAlign="center"><strong><span color="rgb(59,130,246)" fontSize="36">数值</span></strong></p></content>
|
||||
</shape>
|
||||
<shape type="text" topLeftX="60" topLeftY="175" width="260" height="25">
|
||||
<content><p textAlign="center"><span color="rgb(100,116,139)" fontSize="14">指标名称</span></p></content>
|
||||
</shape>
|
||||
<!-- 卡片 2：topLeftX="350" -->
|
||||
<!-- 卡片 3：topLeftX="640" -->
|
||||
</data>
|
||||
</slide>
|
||||
```
|
||||
|
||||
## 深色结尾页
|
||||
|
||||
```xml
|
||||
<slide xmlns="http://www.larkoffice.com/sml/2.0">
|
||||
<style><fill><fillColor color="linear-gradient(135deg,rgba(15,23,42,1) 0%,rgba(56,97,140,1) 100%)"/></fill></style>
|
||||
<data>
|
||||
<shape type="text" topLeftX="80" topLeftY="190" width="800" height="55">
|
||||
<content><p textAlign="center"><strong><span color="rgb(255,255,255)" fontSize="36">感谢语或行动号召</span></strong></p></content>
|
||||
</shape>
|
||||
<line startX="410" startY="260" endX="550" endY="260">
|
||||
<border color="rgb(59,130,246)" width="2"/>
|
||||
</line>
|
||||
<shape type="text" topLeftX="80" topLeftY="280" width="800" height="30">
|
||||
<content><p textAlign="center"><span color="rgb(148,163,184)" fontSize="16">补充说明</span></p></content>
|
||||
</shape>
|
||||
</data>
|
||||
</slide>
|
||||
```
|
||||
226
skills/lark-slides/references/slides_demo.xml
Normal file
226
skills/lark-slides/references/slides_demo.xml
Normal file
@@ -0,0 +1,226 @@
|
||||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<presentation xmlns="http://www.larkoffice.com/sml/2.0" height="540" width="960">
|
||||
<title>制造端智能升级</title>
|
||||
<theme>
|
||||
<textStyles>
|
||||
<headline fontColor="rgb(255,255,255)" fontFamily="思源黑体" fontSize="36"/>
|
||||
<sub-headline fontColor="rgb(229,231,235)" fontFamily="思源黑体" fontSize="20"/>
|
||||
<body fontColor="rgb(229,231,235)" fontFamily="思源黑体" fontSize="16"/>
|
||||
</textStyles>
|
||||
</theme>
|
||||
<slide>
|
||||
<style>
|
||||
<fill>
|
||||
<fillColor color="linear-gradient(180deg, rgb(47, 79, 79) 0%, rgb(26, 26, 26) 100%)"/>
|
||||
</fill>
|
||||
</style>
|
||||
<data>
|
||||
<shape height="36" rotation="0" topLeftX="48" topLeftY="40" type="text" width="300">
|
||||
<content>
|
||||
<p>
|
||||
<strong>
|
||||
<span color="rgb(255, 215, 0)" fontFamily="黑体" fontSize="28">时代背景</span>
|
||||
</strong>
|
||||
</p>
|
||||
</content>
|
||||
</shape>
|
||||
<shape height="200" rotation="0" topLeftX="48" topLeftY="85" type="rect" width="864">
|
||||
<fill>
|
||||
<fillColor color="rgba(0,0,0,0.2)"/>
|
||||
</fill>
|
||||
</shape>
|
||||
<img alpha="0.4" alt="十月革命场景" height="180" rotation="0" src="https://example.com/images/scene-1.png" topLeftX="48" topLeftY="95" width="288">
|
||||
<crop type="rect"/>
|
||||
</img>
|
||||
<img alpha="0.4" alt="列宁演讲油画" height="180" rotation="0" src="https://example.com/images/scene-2.png" topLeftX="336" topLeftY="95" width="288">
|
||||
<crop type="rect"/>
|
||||
</img>
|
||||
<img alpha="0.4" alt="十月革命战斗场面" height="180" rotation="0" src="https://example.com/images/scene-3.png" topLeftX="624" topLeftY="95" width="288">
|
||||
<crop type="rect"/>
|
||||
</img>
|
||||
<shape height="2" rotation="0" topLeftX="90" topLeftY="180" type="rect" width="780">
|
||||
<fill>
|
||||
<fillColor color="rgba(255, 215, 0, 0.3)"/>
|
||||
</fill>
|
||||
</shape>
|
||||
<shape height="10" rotation="0" topLeftX="120" topLeftY="176" type="ellipse" width="10">
|
||||
<fill>
|
||||
<fillColor color="rgb(196, 30, 58)"/>
|
||||
</fill>
|
||||
<border color="rgb(255, 215, 0)" width="1"/>
|
||||
</shape>
|
||||
<shape height="24" rotation="0" topLeftX="60" topLeftY="140" type="text" width="200">
|
||||
<content>
|
||||
<p textAlign="center">
|
||||
<strong>
|
||||
<span color="rgb(255, 215, 0)" fontFamily="黑体" fontSize="20">1917</span>
|
||||
</strong>
|
||||
</p>
|
||||
</content>
|
||||
</shape>
|
||||
<shape height="22" rotation="0" topLeftX="60" topLeftY="200" type="text" width="200">
|
||||
<content>
|
||||
<p textAlign="center">
|
||||
<span color="rgb(230, 230, 230)" fontFamily="宋体" fontSize="16">十月革命</span>
|
||||
</p>
|
||||
</content>
|
||||
</shape>
|
||||
<shape height="40" rotation="0" topLeftX="60" topLeftY="225" type="text" width="200">
|
||||
<content verticalAlign="top">
|
||||
<p textAlign="center">
|
||||
<span color="rgb(156, 163, 175)" fontSize="12">沙皇专制终结，苏维埃政权建立</span>
|
||||
</p>
|
||||
</content>
|
||||
</shape>
|
||||
<shape height="10" rotation="0" topLeftX="475" topLeftY="176" type="ellipse" width="10">
|
||||
<fill>
|
||||
<fillColor color="rgb(196, 30, 58)"/>
|
||||
</fill>
|
||||
<border color="rgb(255, 215, 0)" width="1"/>
|
||||
</shape>
|
||||
<shape height="24" rotation="0" topLeftX="380" topLeftY="140" type="text" width="200">
|
||||
<content>
|
||||
<p textAlign="center">
|
||||
<strong>
|
||||
<span color="rgb(255, 215, 0)" fontFamily="黑体" fontSize="20">1920s</span>
|
||||
</strong>
|
||||
</p>
|
||||
</content>
|
||||
</shape>
|
||||
<shape height="22" rotation="0" topLeftX="380" topLeftY="200" type="text" width="200">
|
||||
<content>
|
||||
<p textAlign="center">
|
||||
<span color="rgb(230, 230, 230)" fontFamily="宋体" fontSize="16">国内战争</span>
|
||||
</p>
|
||||
</content>
|
||||
</shape>
|
||||
<shape height="40" rotation="0" topLeftX="380" topLeftY="225" type="text" width="200">
|
||||
<content verticalAlign="top">
|
||||
<p textAlign="center">
|
||||
<span color="rgb(156, 163, 175)" fontSize="12">革命与反革命的残酷斗争</span>
|
||||
</p>
|
||||
</content>
|
||||
</shape>
|
||||
<shape height="10" rotation="0" topLeftX="830" topLeftY="176" type="ellipse" width="10">
|
||||
<fill>
|
||||
<fillColor color="rgb(196, 30, 58)"/>
|
||||
</fill>
|
||||
<border color="rgb(255, 215, 0)" width="1"/>
|
||||
</shape>
|
||||
<shape height="24" rotation="0" topLeftX="740" topLeftY="140" type="text" width="200">
|
||||
<content>
|
||||
<p textAlign="center">
|
||||
<strong>
|
||||
<span color="rgb(255, 215, 0)" fontFamily="黑体" fontSize="20">1930s</span>
|
||||
</strong>
|
||||
</p>
|
||||
</content>
|
||||
</shape>
|
||||
<shape height="22" rotation="0" topLeftX="740" topLeftY="200" type="text" width="200">
|
||||
<content>
|
||||
<p textAlign="center">
|
||||
<span color="rgb(230, 230, 230)" fontFamily="宋体" fontSize="16">社会主义建设</span>
|
||||
</p>
|
||||
</content>
|
||||
</shape>
|
||||
<shape height="40" rotation="0" topLeftX="740" topLeftY="225" type="text" width="200">
|
||||
<content verticalAlign="top">
|
||||
<p textAlign="center">
|
||||
<span color="rgb(156, 163, 175)" fontSize="12">新经济政策与工业化探索</span>
|
||||
</p>
|
||||
</content>
|
||||
</shape>
|
||||
<shape height="1" rotation="0" topLeftX="48" topLeftY="300" type="rect" width="864">
|
||||
<fill>
|
||||
<fillColor color="rgba(255, 215, 0, 0.2)"/>
|
||||
</fill>
|
||||
</shape>
|
||||
<shape height="24" rotation="0" topLeftX="48" topLeftY="320" type="text" width="280">
|
||||
<content>
|
||||
<p>
|
||||
<span color="rgb(230, 230, 230)" fontFamily="宋体" fontSize="18">作者：奥斯特洛夫斯基</span>
|
||||
</p>
|
||||
</content>
|
||||
</shape>
|
||||
<icon height="16" iconType="iconpark/Peoples/user.svg" topLeftX="52" topLeftY="360" width="16">
|
||||
<fill>
|
||||
<fillColor color="rgb(196, 30, 58)"/>
|
||||
</fill>
|
||||
</icon>
|
||||
<shape height="20" topLeftX="76" topLeftY="358" type="text" width="260">
|
||||
<content verticalAlign="middle">
|
||||
<p>
|
||||
<span color="rgb(209, 213, 219)" fontSize="13">工人家庭出身，投身革命浪潮</span>
|
||||
</p>
|
||||
</content>
|
||||
</shape>
|
||||
<icon height="16" iconType="iconpark/Sports/torch.svg" topLeftX="52" topLeftY="390" width="16">
|
||||
<fill>
|
||||
<fillColor color="rgb(196, 30, 58)"/>
|
||||
</fill>
|
||||
</icon>
|
||||
<shape height="20" topLeftX="76" topLeftY="388" type="text" width="260">
|
||||
<content verticalAlign="middle">
|
||||
<p>
|
||||
<span color="rgb(209, 213, 219)" fontSize="13">战场负伤致残，生命陷入黑暗</span>
|
||||
</p>
|
||||
</content>
|
||||
</shape>
|
||||
<icon height="16" iconType="iconpark/Health/first-aid-kit.svg" topLeftX="52" topLeftY="420" width="16">
|
||||
<fill>
|
||||
<fillColor color="rgb(196, 30, 58)"/>
|
||||
</fill>
|
||||
</icon>
|
||||
<shape height="20" topLeftX="76" topLeftY="418" type="text" width="260">
|
||||
<content verticalAlign="middle">
|
||||
<p>
|
||||
<span color="rgb(209, 213, 219)" fontSize="13">全身瘫痪、双目失明</span>
|
||||
</p>
|
||||
</content>
|
||||
</shape>
|
||||
<icon height="16" iconType="iconpark/Edit/edit.svg" topLeftX="52" topLeftY="450" width="16">
|
||||
<fill>
|
||||
<fillColor color="rgb(196, 30, 58)"/>
|
||||
</fill>
|
||||
</icon>
|
||||
<shape height="20" topLeftX="76" topLeftY="448" type="text" width="260">
|
||||
<content verticalAlign="middle">
|
||||
<p>
|
||||
<span color="rgb(209, 213, 219)" fontSize="13">以文学为武器，口述完成创作</span>
|
||||
</p>
|
||||
</content>
|
||||
</shape>
|
||||
<img alt="奥斯特洛夫斯基青年时期" height="213" rotation="0" src="https://example.com/images/ostrovsky.png" topLeftX="360" topLeftY="320" width="160">
|
||||
<border color="rgba(255, 215, 0, 0.5)" width="2"/>
|
||||
<crop type="rect"/>
|
||||
</img>
|
||||
<shape height="24" rotation="0" topLeftX="552" topLeftY="320" type="text" width="360">
|
||||
<content>
|
||||
<p>
|
||||
<span color="rgb(230, 230, 230)" fontFamily="宋体" fontSize="18">创作动机</span>
|
||||
</p>
|
||||
</content>
|
||||
</shape>
|
||||
<shape height="16" rotation="0" topLeftX="552" topLeftY="350" type="rect" width="2">
|
||||
<fill>
|
||||
<fillColor color="rgb(196, 30, 58)"/>
|
||||
</fill>
|
||||
</shape>
|
||||
<shape height="120" rotation="0" topLeftX="562" topLeftY="350" type="text" width="350">
|
||||
<content lineSpacing="multiple:1.6" verticalAlign="top">
|
||||
<p>
|
||||
<span color="rgb(209, 213, 219)" fontSize="13">在双目失明、全身瘫痪的逆境中，奥斯特洛夫斯基以自身经历为蓝本，用顽强的意志口述完成了这部不朽巨著。他将文学创作视为生命的延续和战斗的武器，旨在通过保尔·柯察金的形象，向青年一代传递坚不可摧的革命信念和超越个人痛苦的崇高人生价值观。</span>
|
||||
</p>
|
||||
</content>
|
||||
</shape>
|
||||
</data>
|
||||
<note>
|
||||
<content>
|
||||
<p>各位好，这一页将我们带回《钢铁是怎样炼成的》这部巨著诞生的波澜壮阔的时代。</p>
|
||||
<p>上半部分展示了从1917年十月革命到1930年代苏联社会主义建设的宏大历史画卷。这是一个充满剧烈社会变革和残酷斗争的年代，也是英雄主义和理想主义精神熊熊燃烧的年代。正是这样的背景，孕育了小说的灵魂。</p>
|
||||
<p>下半部分，我们聚焦于作者奥斯特洛夫斯基的个人经历。他的一生，本身就是一部比小说更震撼人心的传奇。从投身革命的青年，到因伤致残的战士，再到与命运抗争的文学巨匠。他的创作动机源于自身不屈的战斗精神，他希望用保尔的故事激励后人，在任何困境中都不要放弃理想，要将有限的生命投入到无限的为人类解放而斗争的事业中去。</p>
|
||||
<p>通过了解这段历史和作者的生平，我们能更深刻地理解《钢铁是怎样炼成的》这部作品的伟大之处。</p>
|
||||
</content>
|
||||
</note>
|
||||
</slide>
|
||||
</presentation>
|
||||
3004
skills/lark-slides/references/slides_xml_schema_definition.xml
Normal file
3004
skills/lark-slides/references/slides_xml_schema_definition.xml
Normal file
File diff suppressed because it is too large
Load Diff
355
skills/lark-slides/references/xml-format-guide.md
Normal file
355
skills/lark-slides/references/xml-format-guide.md
Normal file
@@ -0,0 +1,355 @@
|
||||
# XML 格式指南
|
||||
|
||||
本文档基于 [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml) 整理，说明飞书 Slides XML Schema（SML 2.0）的核心结构和常用写法。
|
||||
|
||||
## 基本结构
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
|
||||
<title>演示文稿标题</title>
|
||||
<slide>
|
||||
<style>
|
||||
<fill>
|
||||
<fillColor color="rgb(245, 245, 245)"/>
|
||||
</fill>
|
||||
</style>
|
||||
<data>
|
||||
<shape type="text" topLeftX="80" topLeftY="80" width="800" height="120">
|
||||
<content textType="title">
|
||||
<p>主标题</p>
|
||||
</content>
|
||||
</shape>
|
||||
</data>
|
||||
<note>
|
||||
<content textType="body">
|
||||
<p>这是演讲者备注。</p>
|
||||
</content>
|
||||
</note>
|
||||
</slide>
|
||||
</presentation>
|
||||
```
|
||||
|
||||
## 根元素
|
||||
|
||||
### `<presentation>`
|
||||
|
||||
协议标准写法应带命名空间 `http://www.larkoffice.com/sml/2.0`；当前服务端实现可能兼容不带 `xmlns` 的输入，但不作为协议保证。
|
||||
|
||||
**属性：**
|
||||
|
||||
| 属性 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `width` | positiveInteger | 是 | 演示文稿宽度，如 `960` |
|
||||
| `height` | positiveInteger | 是 | 演示文稿高度，如 `540` |
|
||||
| `id` | string | 否 | 演示文稿标识 |
|
||||
|
||||
**子元素：**
|
||||
|
||||
| 元素 | 必需 | 说明 |
|
||||
|------|------|------|
|
||||
| `<title>` | 否 | 演示文稿标题 |
|
||||
| `<theme>` | 否 | 全局主题 |
|
||||
| `<slide>` | 是 | 幻灯片页面，至少 1 页，最多 100 页 |
|
||||
|
||||
## 主题
|
||||
|
||||
### `<theme>`
|
||||
|
||||
`<theme>` 当前包含两部分：
|
||||
|
||||
- `<background>`：演示文稿级背景填充
|
||||
- `<textStyles>`：主题文本样式集合
|
||||
|
||||
`<textStyles>` 下可选子元素：
|
||||
|
||||
- `<title>`
|
||||
- `<headline>`
|
||||
- `<sub-headline>`
|
||||
- `<body>`
|
||||
- `<caption>`
|
||||
|
||||
这些元素定义的是主题默认样式，不是页面结构。常用属性：
|
||||
|
||||
| 属性 | 说明 |
|
||||
|------|------|
|
||||
| `fontFamily` | 字体 |
|
||||
| `fontSize` | 字号 |
|
||||
| `fontColor` | 字体颜色 |
|
||||
|
||||
## 幻灯片元素
|
||||
|
||||
### `<slide>`
|
||||
|
||||
单张幻灯片的结构比较严格。
|
||||
|
||||
**属性：**
|
||||
|
||||
| 属性 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `id` | string | 否 | 幻灯片标识 |
|
||||
|
||||
**直接子元素只有：**
|
||||
|
||||
| 元素 | 必需 | 说明 |
|
||||
|------|------|------|
|
||||
| `<style>` | 否 | 页面样式 |
|
||||
| `<data>` | 否 | 页面元素容器 |
|
||||
| `<note>` | 否 | 演讲者备注 |
|
||||
|
||||
这意味着 `<title>`、`<headline>`、`<body>`、`<caption>` 不能直接放在 `<slide>` 下。
|
||||
|
||||
## 文本内容模型
|
||||
|
||||
### `<content>`
|
||||
|
||||
实际页面文本通常通过 `<content>` 表达，常见位置有：
|
||||
|
||||
- `shape` 内部
|
||||
- `table/td` 内部
|
||||
- `note` 内部
|
||||
|
||||
**常用属性：**
|
||||
|
||||
| 属性 | 说明 |
|
||||
|------|------|
|
||||
| `textType` | `title` / `headline` / `sub-headline` / `body` / `caption` |
|
||||
| `verticalAlign` | 垂直对齐 |
|
||||
| `textAlign` | 水平对齐 |
|
||||
| `lineSpacing` | 行间距 |
|
||||
| `fontSize` | 字号 |
|
||||
| `fontFamily` | 字体 |
|
||||
| `color` | 字体颜色 |
|
||||
| `bold` / `italic` / `underline` / `strikethrough` | 内容级样式 |
|
||||
| `wrap` | 是否自动换行 |
|
||||
|
||||
**可包含的子元素：**
|
||||
|
||||
- `<p>`
|
||||
- `<ul>`
|
||||
- `<ol>`
|
||||
|
||||
### `<p>`
|
||||
|
||||
`<p>` 是段落元素，可混排纯文本和内联标签：
|
||||
|
||||
- `<br/>`
|
||||
- `<strong>`
|
||||
- `<em>`
|
||||
- `<u>`
|
||||
- `<span>`
|
||||
- `<del>`
|
||||
- `<a>`
|
||||
- `<shadow>`
|
||||
- `<outline>`
|
||||
|
||||
示例：
|
||||
|
||||
```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>`
|
||||
|
||||
`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="700" topLeftY="120" width="180" height="120">
|
||||
<fill>
|
||||
<fillColor color="rgba(100, 149, 237, 0.25)"/>
|
||||
</fill>
|
||||
<border color="rgb(100, 149, 237)" width="2"/>
|
||||
</shape>
|
||||
```
|
||||
|
||||
**属性：**
|
||||
|
||||
| 属性 | 必需 | 说明 |
|
||||
|------|------|------|
|
||||
| `type` | 是 | 形状类型，`text` 表示文本框 |
|
||||
| `topLeftX` | 是 | 左上角 X 坐标 |
|
||||
| `topLeftY` | 是 | 左上角 Y 坐标 |
|
||||
| `width` | 是 | 宽度 |
|
||||
| `height` | 是 | 高度 |
|
||||
| `rotation` | 否 | 旋转角度 |
|
||||
| `flipX` / `flipY` | 否 | 翻转 |
|
||||
| `alpha` | 否 | 透明度 |
|
||||
|
||||
**可选子元素：**
|
||||
|
||||
- `<fill>`
|
||||
- `<border>`
|
||||
- `<reflection>`
|
||||
- `<shadow>`
|
||||
- `<content>`
|
||||
|
||||
### `<line>`
|
||||
|
||||
```xml
|
||||
<line startX="100" startY="200" endX="420" endY="200">
|
||||
<border color="rgb(43, 47, 54)" width="2"/>
|
||||
</line>
|
||||
```
|
||||
|
||||
`line` 使用的是 `startX` / `startY` / `endX` / `endY`，不是 `x1` / `y1` / `x2` / `y2`。
|
||||
|
||||
### `<img>`
|
||||
|
||||
```xml
|
||||
<img src="file_token_or_url" topLeftX="100" topLeftY="220" width="320" height="180"/>
|
||||
```
|
||||
|
||||
`img` 使用 `topLeftX` / `topLeftY`，不是 `x` / `y`。
|
||||
|
||||
### `<icon>`
|
||||
|
||||
```xml
|
||||
<icon iconType="iconpark/Base/setting.svg" topLeftX="440" topLeftY="220" width="32" height="32"/>
|
||||
```
|
||||
|
||||
### `<table>`
|
||||
|
||||
表格结构为：
|
||||
|
||||
- `<table>`
|
||||
- `<colgroup>` / `<tr>`
|
||||
- `<tr>` 内为 `<td>`
|
||||
- `<td>` 内可放 `<content>`
|
||||
|
||||
### `<chart>`
|
||||
|
||||
图表元素必须至少包含：
|
||||
|
||||
- `<chartPlotArea>`
|
||||
- `<chartData>`
|
||||
|
||||
同时还可以包含：
|
||||
|
||||
- `<chartTitle>`
|
||||
- `<chartSubTitle>`
|
||||
- `<chartStyle>`
|
||||
- `<chartLegend>`
|
||||
- `<chartTooltip>`
|
||||
|
||||
如果要写图表 XML，建议直接以 XSD 为准，不要自行发明更简化的 chart DSL。
|
||||
|
||||
## 样式元素
|
||||
|
||||
### `<fill>`
|
||||
|
||||
```xml
|
||||
<fill>
|
||||
<fillColor color="rgb(100, 149, 237)"/>
|
||||
</fill>
|
||||
```
|
||||
|
||||
### `<border>`
|
||||
|
||||
```xml
|
||||
<border color="rgb(0, 0, 0)" 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%)"/>
|
||||
```
|
||||
|
||||
## 演讲者备注
|
||||
|
||||
### `<note>`
|
||||
|
||||
```xml
|
||||
<note>
|
||||
<content textType="body">
|
||||
<p>这是演讲者备注内容。</p>
|
||||
</content>
|
||||
</note>
|
||||
```
|
||||
|
||||
## 完整示例
|
||||
|
||||
```xml
|
||||
<?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` 颜色格式
|
||||
5. 特殊字符按 XML 规则转义
|
||||
6. 标准 16:9 页面建议使用 `width="960"` 和 `height="540"`
|
||||
|
||||
## 参考文档
|
||||
|
||||
- [xml-schema-quick-ref.md](xml-schema-quick-ref.md)
|
||||
- [slides_xml_schema_definition.xml](slides_xml_schema_definition.xml)
|
||||
- [examples.md](examples.md)
|
||||
- [slides_demo.xml](slides_demo.xml)
|
||||
211
skills/lark-slides/references/xml-schema-quick-ref.md
Normal file
211
skills/lark-slides/references/xml-schema-quick-ref.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# 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`、`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"/>
|
||||
```
|
||||
|
||||
### icon
|
||||
|
||||
```xml
|
||||
<icon iconType="iconpark/Base/setting.svg" topLeftX="80" topLeftY="120" width="32" height="32"/>
|
||||
```
|
||||
|
||||
## 颜色与样式
|
||||
|
||||
### 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
|
||||
Reference in New Issue
Block a user