小组件开发指南

本指南介绍了如何为 AGC Player 开发小组件。文档涵盖了小组件的结构、配置、方法定义及返回值说明。

小组件目录结构

小组件文件夹应包含以下内容：

hello
├── widget.json
├── widget.js
└── icon.png

widget.json: 配置小组件信息（详见小组件配置说明）。
widget.js: 小组件入口文件，定义插件逻辑（详见小组件类型）。
icon.png: 小组件封面图。

小组件配置说明

以下是 widget.json 的字段定义：

字段名	类型	描述
id	string	小组件 ID
name	string	小组件名称
author	string	小组件作者
version	string	小组件版本
agcplayer-require	string	最低支持的 AGC Player 版本号
type	string	小组件类型, 详见
platform	string	支持平台，如 `all` 表示全平台支持
summary	string	小组件概览
description	string	小组件描述
disclaimer	string	免责声明
history	boolean	是否显示最近观看列表

小组件类型

类型	描述
video-hub	影视类型小组件
video-live	直播类型小组件

创建第一个小组件

创建widget.json

示例代码：

{
    "id": "widget.agcplayer.hello",
    "author": "AGC Player",
    "version": "0.0.1",
    "agcplayer-require": "^2.2.0",
    "name": "Hello",
    "type": "video-hub",
    "platform": "all",
    "summary": "This is a video list widget.",
    "description": "This is a video list widget, JavaScript script.",
    "disclaimer": "For demonstration only."
}

创建widget.js

根据不同的小组件类型，导出不一样的方法，下面以video-hub类型的小组件为例。

注意
由于没有DOM API，对html解析的时候，需要自行解析，例如用xpath.js

示例代码：

module.export.home = async () => {
    const response = await fetch('http://you-target-url')
    const json = await response.json();
    const result = [
        // 参考home方法返回值类型
    ]

    return {
        code: 0,
        data: result
    }
}

module.export.list = async (type_id, page) => {
    const response = await fetch('http://you-target-url')
    const json = await response.json();
    const result = {
        // 参考list方法返回值类型
    }

    return {
        code: 0,
        data: result
    }
}

module.export.search = async (keyword, page) => {
    const response = await fetch('http://you-target-url')
    const json = await response.json();
    const result = {
        // 参考search方法返回值类型
    }

    return {
        code: 0,
        data: result
    }
}

module.export.detail = async ({ vod_id }) => {
    const response = await fetch('http://you-target-url')
    const json = await response.json();
    const result = {
        // 参考detail方法返回值类型
    }

    return {
        code: 0,
        data: result
    }
}

module.export.play = async ({ url }) => {
    const response = await fetch('http://you-target-url')
    const json = await response.json();
    const result = ''

    return {
        code: 0,
        data: result
    }
}

添加小组件封面图，icon.png
将上述文件与封面图 icon.png 一并打包成 zip 文件，即可导入应用进行测试。

⚠️注意
打包zip的时候，直接打包资源文件，不需要包一层文件夹，结构如下

demo.zip
├── widget.json
├── widget.js
└── icon.png

上述示例代码使用的是cjs规范，不需要构建流程，如果想用esm规范或者需要构建流程，可以参考下面的构建工具。

构建工具

如需使用构建工具，可以使用@agcplayer/cli，小组件模板可参考模板

常见问题与注意事项

字段类型一致性：所有返回字段需严格遵循文档定义，避免数据类型错误。
错误处理：当接口出错时，需返回 code: -1 并提供 msg 字段说明错误原因。
环境依赖：小组件运行环境完全支持 ECMAScript 5.1，使用 cjs 模块规范，无法使用浏览器的 WebAPI。

如有疑问，请参考官方示例或联系支持团队。