ibook-widget-packer（ibook 小部件打包程序）

iBook Widget Packer Skill

概述

本 Skill 将任意 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/...）

执行步骤

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

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

• 询问或从上下文确认：

- 源项目目录（包含 index.html 的目录） - Widget 名称（将作为 .wdgt 文件夹名，建议英文+连字符，如 my-game） - 游戏显示名称（中文可以，用于 Info.plist 的 CFBundleDisplayName） - 版本号（默认 1.0） - 默认尺寸（默认 1024×768，适合 iPad 横屏）

Step 2：分析源项目结构

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

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

Step 3：创建 Widget 目录结构

# 创建 wdgt 文件夹
WDGT_DIR="/path/to/output/your-game.wdgt"
mkdir -p "$WDGT_DIR/peresources"

# 将 CSS、JS 等资源文件复制到 peresources/
cp source/style.css source/game.js source/*.js "$WDGT_DIR/peresources/"

路径修正规则：

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

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

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

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

<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />

Step 5：生成 Info.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>CFBundleDisplayName</key>
  <string>【游戏中文名】</string>
  <key>CFBundleIdentifier</key>
  <string>com.【英文名小写】.widget</string>
  <key>CFBundleName</key>
  <string>【英文名驼峰】</string>
  <key>CFBundleShortVersionString</key>
  <string>【版本号，如 1.0】</string>
  <key>CFBundleVersion</key>
  <string>【版本号，如 1.0】</string>
  <key>MainHTML</key>
  <string>index.html</string>
  <key>AllowNetworkAccess</key>
  <false/>
  <key>Width</key>
  <integer>1024</integer>
  <key>Height</key>
  <integer>768</integer>
</dict>
</plist>

Step 6：生成缩略图

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

from PIL import Image, ImageDraw

def make_thumb(size, path, game_name):
    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(game_name)*7, cy - 10), game_name, 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 绘制更精美的预览图。

Step 7：打包成 zip

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

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

Step 8：验证包体结构

# 查看压缩包内容，确认结构正确
unzip -l your-game.wdgt.zip | head -20

期望看到：

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

Step 9：提供下载链接

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

iBook 使用方式（告知用户）

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

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 中加入响应式断点，确保游戏在不同设备上自适应：

/* 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 加入：

html, body {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
}

常见问题排查

输出清单

每次打包完成，向用户说明：

• ✅ Widget 名称和版本
• ✅ 包体文件列表（find your-game.wdgt -type f | sort）
• ✅ zip 文件大小
• ✅ 下载链接
• ✅ iBook 导入使用步骤