iBook Widget Packer 技能

概述

本技能可将任意 H5 游戏项目打包成符合 Apple iBook Author Widget 规范的 .wdgt 格式压缩包，直接导入 iBook Author 使用。

Widget 包体规范

Apple iBook Widget（.wdgt）本质是一个特定结构的文件夹，在 macOS 上显示为 bundle 包。标准结构如下：

your-game.wdgt/
├── index.html ← 主入口文件（必须）
├── Info.plist ← Widget 配置文件（必须）
├── Default.png ← 缩略图 1024×768（必须）
├── Default@2x.png ← 高清缩略图 2048×1536（必须）
└── peresources/ ← 资源文件夹（推荐命名，存放 CSS/JS/图片等）
├── style.css
├── game.js
└── ...（其他资源）

关键约束：

• - index.html 必须在根目录
• Info.plist 必须在根目录，且包含 MainHTML 字段指向 index.html
• 所有资源路径使用相对路径（如 peresources/style.css）
• 压缩时文件夹本身要在 zip 顶层（即 zip 内容为 your-game.wdgt/...）

执行步骤

收到用户的打包请求后，按以下步骤执行：

第1步：确认源项目路径和输出名称

• - 询问或从上下文确认：

第2步：分析源项目结构

读取源项目的 index.html，确认：

• - 引用了哪些 CSS/JS 文件及其路径
• 是否已经有 peresources 子目录，还是所有文件平铺在根目录
• 特殊资源（图片、音频、字体等）的位置

第3步：创建 Widget 目录结构

bash

创建 wdgt 文件夹

将 CSS、JS 等资源文件复制到 peresources/

路径修正规则：

• - 若源 index.html 中引用路径为 style.css（平铺），则复制到 peresources/ 后，index.html 中需改为 peresources/style.css
• 若源 index.html 中已经是 peresources/style.css，则路径无需修改，直接复制资源文件到对应位置

第4步：生成 index.html（根目录版本）

将修正了资源引用路径的 index.html 写入 your-game.wdgt/index.html。

必须包含的 meta 标签（用于全屏适配）：
html

第5步：生成 Info.plist

xml

http://www.apple.com/DTDs/PropertyList-1.0.dtd>


CFBundleDisplayName
【游戏中文名】
CFBundleIdentifier
com.【英文名小写】.widget
CFBundleName
【英文名驼峰】
CFBundleShortVersionString
【版本号，如 1.0】
CFBundleVersion
【版本号，如 1.0】
MainHTML
index.html
AllowNetworkAccess

Width
1024
Height
768

第6步：生成缩略图

使用 Python3 + Pillow 生成渐变缩略图（若 Pillow 未安装，先执行 pip3 install Pillow）：

python
from PIL import Image, ImageDraw

def makethumb(size, path, gamename):
w, h = size
img = Image.new(RGB, (w, h))
draw = ImageDraw.Draw(img)
# 渐变背景（紫色系）
for i in range(h):
r = int(102 + (150-102)*i/h)
g = int(51 + (75-51)*i/h)
b = int(153 + (210-153)*i/h)
draw.line([(0,i),(w,i)], fill=(r,g,b))
# 中心文字
cx, cy = w//2, h//2
draw.text((cx - len(gamename)*7, cy - 10), gamename, fill=white)
img.save(path)

make_thumb((1024, 768), your-game.wdgt/Default.png, 游戏名称)
make_thumb((2048, 1536), your-game.wdgt/Default@2x.png, 游戏名称)

如果需要更好的缩略图效果，可以请用户提供截图，或用 PIL 绘制更精美的预览图。

第7步：打包成 zip

bash
cd /path/to/output/parent
zip -r your-game.wdgt.zip your-game.wdgt/

注意： 必须先 cd 到 wdgt 文件夹的父目录，再执行 zip，确保压缩包内顶层是 your-game.wdgt/ 文件夹。

第8步：验证包体结构

bash

查看压缩包内容，确认结构正确

期望看到：

Archive: your-game.wdgt.zip
your-game.wdgt/
your-game.wdgt/index.html
your-game.wdgt/Info.plist
your-game.wdgt/Default.png
your-game.wdgt/Default@2x.png
your-game.wdgt/peresources/style.css
your-game.wdgt/peresources/game.js
...

第9步：提供下载链接

使用 displaydownloadlinks 工具为用户提供 zip 文件的下载链接。

iBook 使用方式（告知用户）

打包完成后，请告知用户以下使用步骤：

1. 1. 下载 your-game.wdgt.zip 到本地 Mac
2. 解压得到 your-game.wdgt 文件夹
3. 重命名确认：确保文件夹后缀为 .wdgt（macOS 会将其识别为 Widget bundle）
4. 导入 iBook Author：打开 iBook Author → 插入菜单 → Widget → HTML → 拖入 .wdgt 文件
5. 预览：在 iBook Author 中点击预览，或导出到 iPad 的 iBooks App 查看

⚠️ 注意：iBook Author 已于 2020 年停止更新，仅支持旧版 macOS。若用户使用新版系统，建议使用 Apple Pages 或第三方工具替代。

屏幕适配最佳实践

在 style.css 中加入响应式断点，确保游戏在不同设备上自适应：

css
/ iPad Pro 横屏 (≥1000pt) /
@media screen and (min-width: 1000px) { ... }

/ iPad Pro 竖屏 (768-999pt) /
@media screen and (min-width: 768px) and (max-width: 999px) { ... }

/ iPhone 竖屏 (≤480pt) /
@media screen and (max-width: 480px) { ... }

/ 横屏低高度兼容 /
@media screen and (max-height: 500px) { ... }

同时在 html, body 加入：
css
html, body {
padding-top: env(safe-area-inset-top);
padding-bottom: env(safe-area-inset-bottom);
}

常见问题排查

| 问题 | 原因 | 解决方案 |
|------|------|