| 项 | 说明 |
|---|---|
| SDK 版本 | @plasosdk/plaso-electron-sdk ≥ 1.3.18(预解析回调与 FILE_TYPE.ISPRINGPPT 自 1.3.8 起) |
| 接入性质 | 可选能力 |
| 适用文件 | PPT、PDF、Word、Excel 等需要分页/渲染的文件 |
| 客户端入口 | onGetPreParseFileNameFn |
info 中的稳定标识。| 字段 | 用途 |
|---|---|
fileId | 业务文件 ID;资料中心返回并写入 Electron info。 |
sourcePath | 原始文件在对象存储中的路径;创建解析任务时使用。 |
taskId | 伯索解析任务 ID;用于关联异步回调。 |
status | 至少区分 PENDING、COMPLETED、FAILED。 |
targetPath | 解析产物目录;只保存在服务端,不能下发给客户端。 |
totalPages | PDF、Word、Excel 等解析页数;资料中心返回后写入 Electron 的 totalPages。 |
fileType | 原始文件和解析资源类型;用于映射 FILE_TYPE。 |
PENDING。POST https://www.plaso.cn/dataentry/document/parserappId、sourcePath、taskType、callbackUrl、validBegin、validTime 和 signature。taskType 分别为:PPT 4、Word/Excel 5、PDF 8。taskId 并写入解析记录。callbackUrl。业务服务端应按 taskId 幂等处理回调:| 回调字段 | 处理要求 |
|---|---|
taskStatus=100 | 将记录更新为 COMPLETED,保存 targetPath 和 convertPages。 |
taskStatus=101 | 将记录更新为 FAILED,保存可定位的失败原因。 |
| 重复回调 | 不重复创建文件记录、资源目录或后续任务。 |
| 回调失败重试 | 接收端应能接受重复投递;解析服务的重试规则见服务端协议。 |
COMPLETED 的预解析文件。解析中或失败的文件应显示处理状态,不能作为可插入的预解析资源返回。fileId + suffix 并返回短时 URL。接口名称由业务方定义,处理逻辑必须满足:fileId 查询解析记录,并验证当前用户对该文件有访问权限。COMPLETED,且存在 targetPath。suffix 做规范化和白名单校验;拒绝 ..、反斜杠、绝对路径、完整 URL 及不属于该解析任务的资源。suffix 与 targetPath 组合,生成短时签名 URL。onGetPreParseFileNameFn 的 Promise。suffix 可能是 /index.html、/info.json、/1.jpg,也可能包含允许的图片处理查询参数(如 /1.jpg?x-oss-process=...)。不得将 targetPath、OSS 长期凭证或对象存储拼接规则下发给客户端。COMPLETED 的解析文件及其 fileId、类型、标题、 页数。onClassWindowReadyFn 之后,宿主将 fileId 写入 FileDataObj.info,将 PDF、Word、Excel 的页数写入 totalPages,然后调用 insertObject。onGetPreParseFileNameFn(info, { suffix })。info 提取 fileId,将 fileId + suffix 请求业务服务端。insertObject 适用于实时课堂、微课窗口,须在窗口就绪后调用。含预解析资源的历史课堂,回放页也必须实现播放器的 getPreParseFileName(课堂窗口中的 onGetPreParseFileNameFn 不会自动带到回放页),见 历史课堂回放/Electron。info,不能把产物目录或 OSS 根路径暴露给客户端。Demo 使用以 下结构:["parsed", { "id": "parsed-file-001" }]type | 必填字段 | SDK 可能请求的 suffix |
|---|---|---|
FILE_TYPE.ISPRINGPPT | info、title | 如 /index.html(1.3.8+) |
FILE_TYPE.PDF | info、title、totalPages | /1.jpg、/info.json |
FILE_TYPE.DOC、FILE_TYPE.XLS | info、title、totalPages | 由解析产物决定 |
const { FILE_TYPE } = window.require('@plasosdk/plaso-electron-sdk');
PlasoElectronSdk.insertObject({
type: FILE_TYPE.PDF,
title: '课件.pdf',
info: ['parsed', { id: 'parsed-file-001' }],
totalPages: 12,
});totalPages 是 Electron FileDataObj 的字段名;如果业务服务端使用相同字段名,赋值时写入 totalPages。须在 onClassWindowReadyFn 之后调用 insertObject。FILE_TYPE.ISPRINGPPT。不需要设置 totalPages;SDK 会按需请求 PPT 的 HTML 入口等页面。PlasoElectronSdk.insertObject({
type: FILE_TYPE.ISPRINGPPT,
title: '课件.pptx',
info: ['parsed', { id: 'ppt-001' }],
});suffix 对应的短时 URL;每个 suffix 调用一次,同一文件会多次调用:FILE_TYPE.PDF、FILE_TYPE.DOC、FILE_TYPE.XLS。必须将解析服务返回的页数写入 totalPages,否则 SDK 无法正确构建分页资源。PlasoElectronSdk.insertObject({
type: FILE_TYPE.PDF,
title: '讲义.pdf',
info: ['parsed', { id: 'pdf-001' }],
totalPages: 12,
});onGetPreParseFileNameFn,常见请求包括:suffix | 用途 |
|---|---|
/1.jpg、/2.jpg | PDF/文档解析页图片。 |
/info.json | 解析文件元数据。 |
/1.jpg?x-oss-process=... | 带图片处理参数的解析页;查询参数也属于 suffix 的一部分。 |
targetPath 定位解析产物;兼容原始文件路径推导的实现通常等价于从原文件 Object Key 构造 <ossKey>_i/<suffix>。无论采用哪种内部存储方式,Electron 只能传递 fileId + suffix,不能传递或拼接对象存储路径。onGetPreParseFileNameFn 的触发时机与参数insertObject 插入课堂或微课窗口,SDK 需要加载某一页、HTML 页面或元数据时,会调用:onGetPreParseFileNameFn: async (info: any, option: { suffix: string }) =>
api.fetchParsedFileUrl(info, option.suffix),| 参数 | 来源与处理方式 |
|---|---|
info | insertObject 时传入的原始文件标识。推荐使用 ["parsed", { "id": "解析文件 ID" }],从第二项的 id 取得业务解析文件 ID。 |
option.suffix | SDK 请求的解析产物相对路径,例如 /index.html、/info.json、/1.jpg;可能包含图片处理查询参数。必须原样提交给服务端。每个 suffix 调用一次,同一文件会多次调用。 |
| 返回值 | 成功时返回完整、可访问的短时 URL;所有失败场景均 reject。 |
info + suffix 转给业务服务端;服务端根据解析文件 ID 校验权限、校验 suffix、定位产物并签发 URL。suffix 做 URL 编码;特别是 /、? 以及图片处理查询参数必须完整保留。服务端解码、校验后再生成短时 URL;如果使用阿里云 OSS,签发方式应与当前存储配置匹配,兼容实现通常使用 OSS V1 签名。GET /api/files/{fileId}/parsed-url?suffix=<url-encoded-suffix>fileId + suffix 对应的短时 URL。服务端参考实现可见 DocParseDemo;生产环境应按自身鉴权、存储和审计要求实现,不能直接信任客户端提交的路径。onGetPreParseFileNameFn: async (info: any, option: { suffix: string }) => {
const fileId = info?.[1]?.id;
const suffix = option?.suffix;
if (!fileId || !suffix) {
return Promise.reject(new Error('invalid info or suffix'));
}
try {
return await api.fetchParsedFileUrl(info, suffix);
} catch (err) {
// 记录业务文件 ID、suffix、课堂 ID 后 reject,不要只打日志后让 Promise 挂起
throw err;
}
},api.* 均为业务后端接口,非 SDK API。如果业务服务端返回空 URL、无权限、解析未完成、产物不存在或网络请求超时,也必须 reject,不能只记录日志后直接返回,否则 SDK 会持续等待资源。info 就是 insertObject 时传入的原始对象;服务端仅使用其中的业务文件 ID 鉴权;suffix 是解析产物的相对路径或页面后缀。原样传给服务端,不要在客户端拼接 OSS URL;OPEN_FILE_MODE_WINDOW / OPEN_FILE_MODE_IMAGE 对应的打开模式配置。SDK 会按需请求解析页或页面资源,例如 /index.html、/1.jpg 和 /info.json。suffix 可能包含查询参数,例如 /1.jpg?x-oss-process=...。服务端应按协议解析和校验完整 suffix,不能简单把任意字符串拼到对象存储根路径。taskId 已与业务 fileId 关联。taskId 幂等处理,且只将 COMPLETED 文件展示到资料中心。onClassWindowReadyFn 之后插入;插入对象包含正确的 info。suffix 能完整到达服务端并完成白名单校验。totalPages 正确。getPreParseFileName。