81. .xwp 文件格式 · 玄武屏使用手册

.xwp 是玄武屏演示文稿的文件格式。本节是开发者参考——文件结构、字段定义、版本兼容性。

文件结构

.xwp 是一个 zip 压缩包：

my-deck.xwp/
├── manifest.json          ← 元信息（版本、标题、作者）
├── deck.json              ← 主结构（页面 / 元素 / 动画）
├── master.json            ← 母版定义
├── theme.json             ← 主题（颜色 / 字体）
├── notes.json             ← 演讲者备注
├── assets/                ← 嵌入的素材
│   ├── img-001.png
│   ├── video-002.mp4
│   ├── ggb-003.ggb
│   └── ...
└── refs.json              ← 外部资源引用（platform workIds）

manifest.json

{
  "version": "1.0",
  "format": "xwp",
  "title": "我的产品发布会",
  "author": "user-id-12345",
  "created": "2026-04-25T10:00:00Z",
  "modified": "2026-04-26T15:30:00Z",
  "description": "Q4 新品发布",
  "tags": ["产品", "发布会"],
  "industry": "enterprise",
  "language": ["zh", "en"],
  "checksum": "sha256:..."
}

deck.json

主结构：

{
  "canvas": {
    "width": 1280,
    "height": 720,
    "backgroundColor": "#ffffff"
  },
  "pages": [
    {
      "id": "page-001",
      "master": "master-default",
      "transition": { "type": "fade", "duration": 0.4 },
      "elements": [...],
      "background": { ... },
      "audio": null
    }
  ]
}

元素结构

每个元素的通用字段：

{
  "id": "el-001",
  "type": "text",
  "x": 0.10,
  "y": 0.20,
  "width": 0.80,
  "height": 0.10,
  "rotation": 0,
  "opacity": 1.0,
  "zIndex": 1,
  "locked": false,
  "hidden": false,
  "link": null,
  "animation": {
    "entrance": "fade-in",
    "trigger": "click",
    "order": 1,
    "duration": 0.4,
    "delay": 0,
    "easing": "ease-out"
  },
  "data": { /* 元素特定字段 */ }
}

各元素类型字段

text 元素

{
  "type": "text",
  "data": {
    "content": "标题文字",
    "fontSize": 48,
    "fontFamily": "思源黑体",
    "color": "#252422",
    "bold": false,
    "align": "left"
  }
}

image 元素

{
  "type": "image",
  "data": {
    "src": "assets/img-001.png",
    "alt": "产品图",
    "fit": "contain",
    "filters": { "brightness": 1.0, "contrast": 1.0 }
  }
}

ggb 元素

{
  "type": "ggb",
  "data": {
    "workId": "BGeo24100033",
    "ggbContent": "base64...",
    "viewState": "saved-base64...",
    "interactable": true,
    "reportVars": ["v0", "result"]
  }
}

html 元素

{
  "type": "html",
  "data": {
    "workId": "BHtml24050001",
    "props": { ... },
    "interactable": true
  }
}

formula 元素

{
  "type": "formula",
  "data": {
    "latex": "E = mc^2",
    "displayMode": "block"
  }
}

详见「11-21 元素详解」章节。

资源引用

内嵌资源

直接放在 assets/ 目录下，相对路径引用：

{ "src": "assets/img-001.png" }

平台资源（workId 引用）

不直接打包，运行时鉴权拉取：

{ "workId": "BGeo24100033" }

refs.json 记录所有 workId：

{
  "ggb": ["BGeo24100033", "BGeo24100034"],
  "html": ["BHtml24050001"]
}

版本兼容

major.minor 语义化版本：

升级	兼容
minor 升级（1.0 → 1.1）	新增字段，旧版客户端忽略未知字段，前向兼容
major 升级（1.x → 2.0）	结构性变更，自动迁移器逐步升级

自动迁移

旧版 .xwp 在新客户端打开时：

检测版本（manifest.version）
   ↓
低于当前 → 启动迁移器
   ↓
逐步升级：1.0 → 1.1 → 1.2 → ... → 当前
   ↓
保存为新版本（提示用户）

字符编码

全部 UTF-8
文件名 ASCII 安全（assets 内）
字符串值任意 Unicode

文件大小限制

项	限制
总大小	≤ 200MB
单文件（asset）	≤ 50MB
视频文件	≤ 500MB（建议外链）
单页元素数	≤ 200
总页数	≤ 500

超出推荐用"按章节拆分"。

文件操作

解包查看

# .xwp 本质是 zip
unzip my-deck.xwp -d my-deck/
ls my-deck/

命令行工具

xwp-cli 提供：

xwp-cli inspect my-deck.xwp     # 查看结构
xwp-cli validate my-deck.xwp    # 校验完整性
xwp-cli upgrade my-deck.xwp     # 升级版本
xwp-cli export my-deck.xwp pdf  # 导出 PDF
xwp-cli optimize my-deck.xwp    # 优化资源

程序化创建

通过 API：

POST /api/xwp/create
{
  "title": "...",
  "deck": { ... }
}

详见「83. 开发者 API」。

兼容性

跨版本

新版编辑器可打开旧版 .xwp，自动迁移。旧版编辑器打开新版 .xwp 时会警告"格式较新"，部分字段可能丢失。

跨平台

Windows / macOS / Linux：完全一致
iPad / iOS：完全一致（编辑功能略简）
网页 / 桌面客户端：完全一致

文件验证

打开 .xwp 时自动验证：

结构完整性（必填字段）
资源引用（assets 是否存在）
校验和（checksum 防止文件损坏）
版本兼容（自动迁移）

损坏修复

文件损坏时：

自动尝试用历史版本恢复
用户可手动选择"忽略错误打开"（部分内容可能丢失）
客服技术支持（专业版起）

下一节讲错误码与诊断。