Electron

Android

iOS

Web

Electron

RESTful

2024/05/31 12:16:54

自定义插件

更新时间

2024/05/31 12:16:54

本文介绍灵动课堂插件机制的原理、灵动课堂内置插件、以及如何新增一个插件。

注意

本文仅针对 2.7.0 或之后版本。如需了解如何在 2.4.x、2.5.x、2.6.x 版本上自定义插件，请参考自定义插件（旧版）。

技术原理

灵动课堂提供插件机制，帮助开发者集成源代码时为业务需求扩展课堂能力。同时，通过插件机制，可以降低自定义业务与课堂的代码耦合程度，从而降低集成源代码的后期升级难度。

插件的技术原理分为：

插件的生命周期
插件的实例化
插件的挂载点
插件的通信机制
插件用于扩展教室能力
插件用于调用教室能力
插件的轨迹同步和多语言能力

详见插件的技术原理介绍。

内置插件

本节介绍灵动课堂内置的插件。它们扩展了教室能力，主要分为以下两类：

通用类插件
- 互动白板
- IM 模块
- 内嵌浏览器
- 视频同步播放器（目前仅支持 Youtube 视频）
- 水印插件
教具类插件
- 答题器
- 投票器
- 计时器

内置插件的源代码均位于 apaas-widgets-web 仓库的 src/gallery 目录下，具体为如下：

插件名称	源代码文件夹	UMD 模块名
互动白板（适配 AgoraEduSDK）	`classroom/whiteboard`	`FcrBoardWidget`
IM 模块（适配 AgoraEduSDK）	`classroom/im`	`AgoraHXChatWidget`
内嵌浏览器（适配 AgoraEduSDK）	`classroom/webview`	`FcrWebviewWidget`
视频同步播放器（适配 AgoraEduSDK）	`classroom/stream-media`	`FcrStreamMediaPlayerWidget`
答题器（适配 AgoraEduSDK）	`classroom/answer`	`AgoraSelector`
投票器（适配 AgoraEduSDK）	`classroom/vote`	`AgoraPolling`
计时器（适配 AgoraEduSDK）	`classroom/counter`	`AgoraCountdown`
水印插件（适配 AgoraEduSDK）	`classroom/watermark`	`FcrWatermarkWidget`
内嵌浏览器（适配 AgoraProctorSDK）	`proctor/webview`	`FcrWebviewWidget`
聊天室（适配 FcrUIScene）	`scene/chatroom`	`FcrChatroom`
计时器（适配 FcrUIScene）	`scene/countdown`	`FcrCountdownWidget`
投票器（适配 FcrUIScene）	`scene/polling`	`FcrPollingWidget`
答题器（适配 FcrUIScene）	`scene/quiz`	`FcrPopupQuizWidget`
视频同步播放器（适配 FcrUIScene）	`scene/stream-media`	`FcrStreamMediaPlayerWidget`
内嵌浏览器（适配 FcrUIScene）	`scene/webview`	`FcrWebviewWidget`
互动白板（适配 FcrUIScene）	`scene/whiteboard`	`FcrBoardWidget`

新增一个插件

如果你需要新增一个自定义的 Widget，可继承灵动课堂提供的 AgoraWidgetBase 类，并实现抽象方法。

如下是 AgoraWidgetBase 类的定义：

TypeScript
/**
 * AgoraWidgetBase 提供 Widget 相关操作 API
 */
export declare abstract class AgoraWidgetBase
  implements
    AgoraWidgetRenderable,
    AgoraMultiInstanceWidget,
    AgoraWidgetLifecycle
{
  constructor(
    _widgetController: AgoraWidgetController,
    _classroomStore: EduClassroomStore
  );

  onInstall(controller: AgoraWidgetController): void {}
  onCreate(properties: any, userProperties: any): void {}
  onPropertiesUpdate(properties: any): void {}
  onUserPropertiesUpdate(userProperties: any): void {}
  onDestroy(): void {}
  onUninstall(controller: AgoraWidgetController): void {}

展开全部 131 行

下面展示新增一个 ExampleWidget 来实现一个最基本的 Widget。

使用 AgoraWidgetBase

创建一个继承 AgoraWidgetBase 类的 ExampleWidget 类：

TypeScript
import { AgoraWidgetBase } from "agora-common-libs";

export class ExampleWidget extends AgoraWidgetBase {
  private _dom?: HTMLElement;
  /**
   * 全局唯一的 Widget 名称
   */
  get widgetName(): string {
    return "example";
  }

  /**
   * 挂载点
   * 重写 locate 方法返回一个节点，则此 Widget 将渲染在此节点内部
   *
   * 这里将 ExampleWidget 挂载至白板区域
   */
  locate(): HTMLElement | null | undefined {
    return document.querySelector(".widget-slot-board") as HTMLElement;
  }

展开全部 42 行

通过 launch 中的 widgets 参数传入自定义 Widget：

TypeScript
const widgets = {
  // 需要引入上面定义的 ExampleWidget 类
  'example': ExampleWidget
};
// 填入你使用的 SDK 名，如 AgoraEduSDK、AgoraProctorSDK
AgoraEduSDK.launch(dom, {
  // ...
  widgets: widgets
  // ...
});

因为这里的 ExampleWidget 为自定义的 Widget，因此需要手动调用 WidgetUIStore 中的 createWidget 方法来创建 Widget：

TypeScript
// 修改 WidgetUIStore 代码
// 文件路径 packages/agora-classroom-sdk/src/infra/stores/common/widget/index.ts 文件中加入代码

onInstall() {
  // ...
  // 在 onInstall 方法最后加入此代码，在房间加入成功后打开指定 Widget
  this._disposers.push(
    reaction(
      () => this.classroomStore.widgetStore.widgetController,
      () => {
        // 打开我们新增的 widget ，此处传入 widgetName
        this.createWidget('example');
      },
    ),
  );
}

插件效果展示

启动教室，插件挂载后的效果如图：

基于现有能力快速创建一个教具插件

灵动课堂为开发者提供了一个名为 AgoraEduToolWidget 抽象类，此类实现了教具类插件通用能力的封装。继承此类可以获得插件的轨迹同步、层级控制能力，以及对 UI 窗口的显示和显示的控制逻辑。

配合 ControlledModal 组件，你还可快速实现内置教具插件的外层窗口，减少大量的通用逻辑代码开发，具体实现请参考仓库 src/gallery 目录下 answer、vote、counter 文件夹，其中提供灵动课堂内置的教具类插件源代码。

如下是 AgoraEduToolWidget 类的定义：

TypeScript
/**
 * AgoraEduToolWidget 是教学道具 Widget 基类
 * 使用 AgoraEduToolWidget 抽象类作为基类，实现可拖拽且轨迹同步的 Widget
 */
export abstract class AgoraEduToolWidget
  extends AgoraWidgetBase
  implements AgoraWidgetLifecycle, AgoraTrackSyncedWidget
{
  private _controlStateCallbacks: CallableFunction[] = [];
  onUninstall(controller: AgoraWidgetController) {}
  onInstall(controller: AgoraWidgetController) {}
  onCreate(properties: any, userProperties: any): void {}
  onPropertiesUpdate(properties: any): void {}
  onUserPropertiesUpdate(userProperties: any): void {}
  onDestroy(): void {}
  get track(): Track {
    return this.trackController?.track!;
  }
  get zIndex(): number {
    return this.trackController?.zIndex || 0;

展开全部 113 行

下面展示如何基于灵动课堂现有 Widget 能力创建一个课前点名的教具插件。完整源代码见 rollbook-widget。

使用 AgoraEduToolWidget

创建一个继承 AgoraEduToolWidget 类的 RollbookWidget 类：

TypeScript
// src/gallery/rollbook/index.tsx
import { render, unmountComponentAtNode } from "react-dom";
import { App } from "./app";
import { AgoraEduToolWidget } from "../../common/edu-tool-widget";
import { observable, action, computed } from "mobx";
import type { AgoraWidgetController } from "agora-edu-core";
import { bound } from "agora-common-libs";
import { AgoraExtensionWidgetEvent } from "../../events";
import { SvgIconEnum } from "../../components/svg-img";

/**
 * 点名册：
 * 老师可通过此插件知晓教室内学生参与情况
 */
export class RollbookWidget extends AgoraEduToolWidget {
  private _dom?: HTMLElement;
  @observable
  started = false;
  @observable
  checkInList: string[] = [];

展开全部 154 行

增加渲染组件

增加一个 App 组件用于在插件窗口中渲染：

TypeScript
// src/gallery/rollbook/app.tsx
import React, { FC } from "react";
import { observer } from "mobx-react";
import { ControlledModal } from "../../common/edu-tool-modal";
import { EduRoleTypeEnum } from "agora-edu-core";
import { RollbookWidget } from ".";
import { Button } from "../../components/button";

/**
 * 点名册组件
 * @param param0
 * @returns
 */
export const App: FC<{ widget: RollbookWidget }> = ({ widget }) => {
  const view = () =>
    [EduRoleTypeEnum.teacher, EduRoleTypeEnum.assistant].includes(
      widget.classroomConfig.sessionInfo.role
    ) ? (
      <TeacherView widget={widget} />
    ) : (

展开全部 75 行

通过 launch 中的 widgets 参数传入自定义 Widget：

TypeScript
const widgets = {
  // 需要引入上面定义的 RollbookWidget 类
  'rollbook': RollbookWidget
};
// 填入你使用的 SDK 名，如 AgoraEduSDK、AgoraProctorSDK
AgoraEduSDK.launch(dom, {
...
widgets: widgets
...
});

插件效果展示

启动教室，可以在工具箱中找到此插件，如图：

老师点击并打开插件的界面效果：

老师点击 Start Check-In 后，学生端显示插件的效果：

学生点击 Check-In 后，老师端签到列表中显示此学生的效果：

自定义插件

技术原理

内置插件

新增一个插件

使用 AgoraWidgetBase

launch 中传入自定义的 Widget

创建自定义的 Widget

插件效果展示

基于现有能力快速创建一个教具插件

使用 AgoraEduToolWidget

增加渲染组件

launch 中传入自定义的 Widget

插件效果展示

技术原理​

内置插件​

新增一个插件​

使用 AgoraWidgetBase​

launch 中传入自定义的 Widget​

创建自定义的 Widget​

插件效果展示​

基于现有能力快速创建一个教具插件​

使用 AgoraEduToolWidget​

增加渲染组件​

launch 中传入自定义的 Widget​

插件效果展示​

技术原理

内置插件

新增一个插件

使用 AgoraWidgetBase

launch 中传入自定义的 Widget

创建自定义的 Widget

插件效果展示

基于现有能力快速创建一个教具插件

使用 AgoraEduToolWidget

增加渲染组件

launch 中传入自定义的 Widget

插件效果展示