Plaso Client SDK

这是一个用于快速集成Plaso教育平台的SDK。通过简单的API调用，您可以轻松地在您的应用中嵌入Plaso的作业和课堂功能。该SDK内置了所有必要的依赖，无需额外安装React等库。

特点

• 完全独立: SDK包含所有所需依赖，不需要外部引入React
• 简单集成: 只需提供一个DOM容器元素即可渲染Plaso内容
• 多环境支持: 支持Web应用和Electron应用
• 多种功能: 支持作业、课堂等多种内容类型
• 事件系统: 提供完整的事件监听机制，支持应用重启、错误处理等事件
• 资源模块: 支持创建和管理各种资源模块

安装

npm install @plasosdk/client-sdk
npm install @plasosdk/plaso-electron-sdk
npm install [email protected]
npm install [email protected]

在Electron项目中使用

在Electron项目中，您需要进行以下配置：

1. 在main.js中启用webview,初始化@plasosdk/client-sdk：

const { app, BrowserWindow } = require('electron')
const remoteMain = require('@electron/remote/main');
const { init } = require('@plasosdk/client-sdk/electron');

remoteMain.initialize();
// 初始化Plaso Electron功能，并获取事件发射器
const plasoEvents = init(remoteMain);

// 监听应用是否token过期
plasoEvents.on('relaunch', (args) => {
  // 可以做一些事情
});

2. 在渲染进程中使用：

import { PlasoClient } from '@plasosdk/client-sdk';

const plasoClient = new PlasoClient({
  token: 'your-token-here',
  container: document.getElementById('plaso-container')
});

// 初始化作业模块
plasoClient.createAssignment();

// 初始化课堂模块
plasoClient.createClassroom();

// 初始化资源模块 - 会打开新的资源页面
plasoClient.createResource();

事件系统

SDK提供了完整的事件系统，支持监听各种应用事件：

事件发射器

通过init()函数返回的事件发射器，您可以监听以下事件：

const plasoEvents = init(remoteMain);

// 监听应用重启事件
plasoEvents.on('relaunch', (args) => {
  console.log('应用重启事件触发，参数:', args);
  // 执行重启逻辑
});

// 监听错误事件
plasoEvents.on('error', (error) => {
  console.error('SDK错误:', error);
  // 处理错误
});

// 监听资源模块创建事件
plasoEvents.on('module-created', (moduleInfo) => {
  console.log('资源模块已创建:', moduleInfo);
  // 处理模块创建后的逻辑
});

支持的事件类型

| 事件名 | 描述 | 参数 | |--------|------|------| | relaunch | 应用重启事件 | args: any[] - 重启参数 | | error | 错误事件 | error: Error - 错误对象 | | module-created | 资源模块创建事件 | moduleInfo: object - 模块信息 | | window-opened | 新窗口打开事件 | windowInfo: object - 窗口信息 |

资源模块

SDK支持创建和管理各种资源模块，每个模块都有独立的功能和生命周期：

创建资源模块

// 创建作业模块
await plasoClient.createModule(PlasoContentType.NHOMEWORK);

// 创建课堂模块
await plasoClient.createModule(PlasoContentType.LIVECLASS);

// 创建自定义模块
await plasoClient.createModule(PlasoContentType.MAIN);

// 创建资源模块 - 会打开一个新的页面
await plasoClient.createModule(PlasoContentType.RESOURCES);

模块生命周期管理

// 创建模块
const module = await plasoClient.createModule(PlasoContentType.NHOMEWORK);

// 监听模块事件
plasoEvents.on('module-created', (moduleInfo) => {
  console.log('模块已创建:', moduleInfo.type, moduleInfo.id);
});

// 销毁模块
plasoClient.destroy();

资源模块类型

SDK支持以下资源模块类型：

• NHOMEWORK: 作业模块 - 用于显示和管理作业内容
• LIVECLASS: 课堂模块 - 用于在线课堂功能
• MAIN: 主模块 - 主页面内容
• RESOURCES: 资源模块 - 打开新的资源页面，用于资源管理和展示

API 文档

PlasoClient

构造函数参数

| 参数名 | 类型 | 必填 | 描述 | |--------|------|------|------| | token | string | 是 | Plaso平台的认证令牌 | | container | HTMLElement | 是 | 用于渲染内容的DOM容器元素 | | sdkVersion | string | 是 | SDK的版本号，用于标识当前使用的SDK版本 | | platform | string | 否 | 平台标识，默认为'plaso'，用于区分不同的平台环境 | | env | Environment | 否 | 环境配置，可选值：PROD（生产环境）、TEST（测试环境）等 | | onError | (error: Error) => void | 否 | 错误处理回调函数 | | onLoading | (isLoading: boolean) => void | 否 | 加载状态回调函数 | | devTools | boolean | 否 | 是否打开开发者工具，默认为false |

方法

createModule(module: PlasoContentType): Promise

创建一个指定类型的模块。这是最通用的方法，可以用于创建任何支持的内容类型。

createAssignment(): Promise

创建一个作业页面。内部调用createModule(PlasoContentType.NHOMEWORK)。

createClassroom(): Promise

创建一个课堂页面。内部调用createModule(PlasoContentType.LIVECLASS)。

createResources(): Promise

创建一个资源页面。内部调用createModule(PlasoContentType.RESOURCES)。这个模块会打开一个新的页面用于资源管理和展示。

renderCustomContent(type: PlasoContentType): Promise

渲染自定义内容，可以用于渲染其他类型的内容。内部调用createModule(type)。

destroy(): void

销毁客户端实例，清理资源。

PlasoContentType

内容类型枚举，用于指定要渲染的内容类型。

export enum PlasoContentType {
  NHOMEWORK = 'nhomework',
  LIVECLASS = 'liveclass',
  MAIN = 'main',
  RESOURCES = 'resources'
  // 后期可以在这里添加更多类型
}

Electron API

SDK提供了专用的Electron模块，支持特定的Electron功能：

// 从electron入口导入
import { init } from '@plasosdk/client-sdk/electron';

// 或使用require
const { init } = require('@plasosdk/client-sdk/electron');

方法

init(remoteMain: any): EventEmitter

初始化Electron相关功能，设置IPC通信以支持以下功能：

• 音频格式转换 (WAV到MP3)
• 系统进程获取
• 应用重启
• Electron远程模块支持
• 新窗口管理

返回值: 返回一个EventEmitter实例，用于监听各种事件。

参数:

• remoteMain: Electron远程模块的主进程实例

使用示例:

const { app, BrowserWindow } = require('electron');
const remoteMain = require('@electron/remote/main');
const { init } = require('@plasosdk/client-sdk/electron');

remoteMain.initialize();

// 初始化并获取事件发射器
const plasoEvents = init(remoteMain);

// 监听应用重启事件
plasoEvents.on('relaunch', (args) => {
  console.log('应用重启事件触发，参数:', args);
  app.relaunch(args);
  app.exit();
});

// 监听错误事件
plasoEvents.on('error', (error) => {
  console.error('SDK错误:', error);
});

// 监听资源模块创建事件
plasoEvents.on('module-created', (moduleInfo) => {
  console.log('资源模块已创建:', moduleInfo);
});

// 监听新窗口打开事件
plasoEvents.on('window-opened', (windowInfo) => {
  console.log('新窗口已打开:', windowInfo);
});

事件类型

| 事件名 | 描述 | 参数 | 触发时机 | |--------|------|------|----------| | relaunch | 应用重启事件 | args: any[] - 重启参数 | 当应用需要重启时 | | error | 错误事件 | error: Error - 错误对象 | 当SDK发生错误时 | | module-created | 资源模块创建事件 | moduleInfo: object - 模块信息 | 当资源模块创建完成时 | | window-opened | 新窗口打开事件 | windowInfo: object - 窗口信息 | 当新窗口打开时 |

IPC通信接口

SDK还提供了以下IPC通信接口，可在渲染进程中使用：

// 音频格式转换
const { ipcRenderer } = require('electron');
const result = await ipcRenderer.invoke('convert-audio', {
  inputPath: '/path/to/input.wav',
  outputPath: '/path/to/output.mp3'
});

// 获取系统进程
const processes = await ipcRenderer.invoke('getSystemProcess', 'win'); // 或 'mac'

// 打开新窗口
const windowInfo = await ipcRenderer.invoke('open-new-window', {
  url: 'https://example.com',
  width: 800,
  height: 600,
  frameless: false,
  modal: false,
  parentWindowId: parentWindow.id
});

// 存储操作
const value = await ipcRenderer.invoke('getStoreValue', 'key');
await ipcRenderer.invoke('setStoreValue', 'key', 'value');

错误处理

SDK提供了完善的错误处理机制：

1. 错误回调：通过onError回调函数获取详细错误信息
2. 加载状态：通过onLoading回调函数监控加载状态
3. 错误展示：在UI中展示友好的错误提示

注意事项

1. 确保在使用前已经获取了有效的Plaso平台认证令牌
2. 容器元素必须具有明确的宽高设置
3. 所有异步操作都返回Promise，可以使用async/await处理
4. 在Electron环境中使用时，确保已正确配置webview支持

示例

// 在任何JS文件或框架中使用
const { PlasoClient, PlasoContentType } = require('@plasosdk/client-sdk');
// 或使用ES模块语法
// import { PlasoClient, PlasoContentType } from '@plasosdk/client-sdk';

// 创建容器元素
const container = document.getElementById('plaso-container');
if (!container) {
  console.error('容器元素不存在');
  return;
}

// 设置容器样式
container.style.width = '100%';
container.style.height = '600px';

// 初始化客户端
const client = new PlasoClient({
  token: 'your-token-here',
  container: container,
  sdkVersion: '1.53.409', // 指定SDK版本
  platform: 'plaso',   // 指定平台
  onError: (error) => {
    console.error('Plaso error:', error);
    // 显示错误信息
    container.innerHTML = `<div style="color: red;">错误: ${error.message}</div>`;
  },
  onLoading: (loading) => {
    console.log('加载状态:', loading);
    // 可以显示加载指示器
  }
});

// 使用通用方法创建作业
client.createModule(PlasoContentType.NHOMEWORK)
  .catch(error => {
    console.error('创建作业失败:', error);
  });

// 使用前记得在不需要时销毁实例
// client.destroy();

变更日志

3.0.16

• 新增事件系统，支持监听应用重启、错误处理、资源模块创建等事件
• 新增资源模块管理功能，支持创建和管理各种类型的资源模块
• 新增RESOURCES资源模块类型，会打开新的资源管理页面
• 优化init函数返回值，现在返回EventEmitter实例用于事件监听
• 新增IPC通信接口文档，包括音频转换、系统进程获取、窗口管理等
• 完善事件类型文档，提供详细的事件参数和触发时机说明

3.0.1

• 优化了SDK的独立性，确保用户不需要安装额外的React依赖
• 改进了文档，更清晰地说明SDK的使用方式

1.0.30

• 添加了专用的Electron模块，可通过@plasosdk/client-sdk/electron导入
• 实现了双入口打包，分离React客户端和Electron主进程功能
• 新增音频格式转换功能(WAV转MP3)
• 新增系统进程获取功能
• 优化了Electron远程模块的支持

1.0.12

• 修复了依赖安装问题

1.0.7

• 添加了统一的createModule方法，使用module作为入参
• 重构了现有方法，使它们调用新的createModule方法
• 更新了PlasoContentType枚举，使用更准确的类型名称
• 优化了API文档和示例代码

1.0.6

• 优化了webview支持检测，更准确地识别Electron环境
• 移除了加载中的提示UI，使界面更加简洁
• 保留了加载状态变量，以便在需要时仍然可以跟踪加载状态

1.0.5

• 添加了PlasoContentType枚举，支持更多内容类型
• 添加了renderCustomContent方法，支持渲染自定义内容
• 优化了错误提示，全部改为中文
• 使用React 18推荐的createRoot API
• 通过URL参数传递token，而不是使用localStorage

1.0.0

• 初始版本发布
• 支持作业和课堂功能
• 提供错误处理和加载状态回调

开发计划

• [ ] 支持自定义主题
• [ ] 添加更多交互事件回调
• [ ] 支持移动端适配
• [ ] 添加加载状态提示