小组件开发指南

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

目录

  1. 小组件目录结构
  2. 小组件配置说明
  3. 小组件类型
  4. 创建第一个小组件
  5. 构建工具
  6. 常见问题与注意事项

小组件目录结构

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

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

小组件配置说明

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

字段名类型描述
idstring小组件 ID
namestring小组件名称
authorstring小组件作者
versionstring小组件版本
agcplayer-requirestring最低支持的 AGC Player 版本号
typestring小组件类型, 详见
platformstring支持平台，如 all 表示全平台支持
summarystring小组件概览
descriptionstring小组件描述
disclaimerstring免责声明

小组件类型

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

创建第一个小组件

  1. 创建widget.json

示例代码：

{
    "id": "widget.agcplayer.hello",
    "author": "AGC Player",
    "version": "0.0.1",
    "agcplayer-require": "^0.0.1",
    "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."
}
  1. 创建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
    }
}

  1. 添加小组件封面图，icon.png

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

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

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

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

构建工具

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

常见问题与注意事项

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

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

Last Updated: