# 附录一：Forward Widget 开发者支持

本章节将介绍由第三方开发者开发的的开发工具库 [`@forward-widget/libs`](https://www.npmjs.com/package/@forward-widget/libs)，帮助你高效开发、测试和调试属于自己的模块。

***

### 🚀 工具库简介

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

* 提供类型定义（支持 TypeScript 和 JSDoc）
* 提供 `WidgetAdaptor` 用于模拟运行环境
* 支持 TMDB 接口测试
* 适配 `@rstest/core` 单元测试框架

***

### 🛠️ 类型定义支持

#### TypeScript 项目

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

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

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

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

#### JavaScript 项目（使用 JSDoc）

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

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

***

### 🧪 单元测试支持

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

搭配 `@rstest/core` 使用示例：

```ts
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
env复制编辑TMDB_API_KEY=your_tmdb_key_here
```

#### 在测试配置中启用环境：

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

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

***

### 🤝 参与贡献

欢迎提交 Issue 或 Pull Request：

* GitHub 仓库地址：<https://github.com/baranwang/forward-widget-libs>
* 包管理地址：<https://www.npmjs.com/package/@forward-widget/libs>

***

### 📄 许可证

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