附录二：Forward Widget 开发者支持

虽然 Forward 是面向普通用户的视频播放器，但其模块（Widget）系统也对开发者开放。

本章节将介绍由第三方开发者开发的的开发工具库 @forward-widget/libs，帮助你高效开发、测试和调试属于自己的模块。

---

🚀 工具库简介

@forward-widget/libs 是一个专为 Forward Widget 开发者设计的工具库，具备以下特性：

• 提供类型定义（支持 TypeScript 和 JSDoc）

• 提供 WidgetAdaptor 用于模拟运行环境

• 支持 TMDB 接口测试

• 适配 @rstest/core 单元测试框架

---

🛠️ 类型定义支持

TypeScript 项目

在项目中创建 .d.ts 文件，添加以下引用：

ts复制编辑// forward-widget-env.d.ts
/// <reference types="@forward-widget/libs/env" />

即可获得类型提示与补全，例如：

ts复制编辑const metadata: WidgetMetadata = {
  name: "My Widget",
  version: "1.0.0",
};

JavaScript 项目（使用 JSDoc）

若使用 JS 编写模块，可通过 JSDoc 获取类型提示：

js复制编辑/**
 * @type {import('@forward-widget/libs/env').WidgetMetadata}
 */
const WidgetMetadata = {
  name: "My Widget",
  version: "1.0.0",
};

---

🧪 单元测试支持

通过 WidgetAdaptor 可模拟 Forward Widget 的运行环境。

搭配 @rstest/core 使用示例：

ts复制编辑import { expect, test, beforeAll } from "@rstest/core";

beforeAll(async () => {
  const { WidgetAdaptor } = await import("@forward-widget/libs/widget-adaptor");
  rstest.stubGlobal("Widget", WidgetAdaptor);
});

test("测试 HTTP 请求", async () => {
  const response = await Widget.http.get("https://api.example.com/data");
  expect(response.status).toBe(200);
});

---

🎞️ 使用 TMDB 接口（可选）

若你的模块需要调用 TMDB（电影数据库）接口，需配置环境变量：

.env 文件中添加：

env复制编辑TMDB_API_KEY=your_tmdb_key_here

在测试配置中启用环境：

ts复制编辑// rstest.config.ts
import { defineConfig } from "@rstest/core";

export default defineConfig({
  testEnvironment: "node",
  pool: {
    type: "forks",
    execArgv: ["--env-file=.env"],
  },
});

---

模块加密工具

近期有部分 Widget 作者反馈，在 GitHub 上保存模块时，出现了 仓库被删除或账号被封禁 的情况。具体原因不明。

为避免类似情况带来的风险，Forward 提供了一个 模块加密工具。 开发者可以在发布或备份模块时，对模块文件进行加密处理。

加密为 可选功能，未加密的模块仍然可以正常使用。

目前 最新版 TestFlight 已支持 导入加密模块。

---

使用方式

模块加密工具目前提供三种使用方式：

1 在线工具

最简单的方式是使用在线加密工具。

打开以下页面，将模块文件拖入即可完成加密：

https://flux.inch.red/encrypt

---

2 命令行方式

如果你希望在自动化流程或脚本中使用，可以通过命令行调用接口进行加密：

curl -s -X POST https://widgetencrypt.inchmade.ai --data-binary @<filepath> -o <filepath>

说明：

参数	说明
<filepath>	需要加密的模块文件路径

执行后会在原路径输出加密后的文件。

---

3 AI Skill

官方 GitHub 仓库中提供了一个 AI Skill，可以让 AI 直接对模块进行处理。

开发者可以通过 AI 调用该 Skill 完成模块加密。

具体说明请查看官方仓库文档。

---

反馈与支持

如果在使用过程中遇到问题，欢迎随时反馈。🤝 参与贡献

欢迎提交 Issue 或 Pull Request：

• GitHub 仓库地址：https://github.com/baranwang/forward-widget-libs

• 包管理地址：https://www.npmjs.com/package/@forward-widget/libs

---

📄 许可证

本项目采用 MIT License，可自由使用、修改与发布。