# shared

本目录提供 HTML / Vue / React 示例可复用的轻量 helper。

## 文件

| 文件 | 用途 |
| --- | --- |
| `officeWidget.js` | 封装文件类型校验、SDK 打开/新建/挂载/关闭、容器 resize 刷新和错误分类。 |
| `ui-defaults.js` | 提供语言列表、默认打开选项和 `buildOpenOptions(state, demoTag)`。 |

## 使用示例

```js
import OfficeUI from "../lib/UI.js";
import { createOfficeController, classifyError } from "./officeWidget.js";
import { buildOpenOptions, createDefaultState } from "./ui-defaults.js";

const controller = createOfficeController({ OfficeUI });
const state = createDefaultState();

try {
  await controller.open(
    container,
    { fileName: file.name, file },
    buildOpenOptions(state, "html-demo"),
  );
} catch (error) {
  const info = classifyError(error);
  console.warn(info.title, info.detail);
}

// 1 / 2 / 3 分别新建 DOCX、XLSX、PPTX。
await controller.create(
  container,
  1,
  buildOpenOptions(state, "html-demo"),
);
```

页面切换、重新打开文件或组件销毁前，建议调用：

```js
await controller.close();
```

`controller.close()` 会调用 widget 的 `close()`。

## 错误分类

`classifyError(error)` 会返回 `{ kind, title, detail }`，便于示例页面展示统一错误提示。它只属于本目录的示例 helper，不是 `UI.js` 公开 API，也不是 SDK 返回值合约。

| `kind` | 常见触发原因 | 排查建议 |
| --- | --- | --- |
| `no-file` | 未选择文件或未传入 `fileData.file`。 | 确认传入的是有效的 `File`、`Blob`、`ArrayBuffer`、`TypedArray` 或 URL 字符串。 |
| `missing-file-name` | 缺少带扩展名的 `fileName`。 | 传入真实文件名，SDK 会根据扩展名识别文档类型。 |
| `no-container` | viewer 容器尚未挂载或无效。 | 确认 DOM 容器已经渲染，并把有效 `HTMLElement` 传给示例 controller。 |
| `unsupported` | 文件类型不在 `doc`、`docx`、`xls`、`xlsx`、`pptx` 支持范围内。 | 在打开前限制文件选择范围，或提示用户更换文件。 |
| `license` | 未配置 `licenseSN` / `licenseKey`，或授权运行时返回 license 相关错误。 | 按外层 README 配置授权信息，并确认当前域名和文档模块在授权范围内。 |
| `invalid-create-type` | 新建文件时传入的文档类型不是 `1`、`2`、`3`。 | 只传入 DOCX / XLSX / PPTX 对应的示例类型。 |
| `create-unsupported` | 当前 SDK 未提供 `createfile` 接口。 | 确认使用的 SDK 版本包含 `createfile(...)`。 |
| `asset` | `lib/` 静态资源、worker、wasm、语言包或 vendor 资源加载失败。 | 完整部署 `lib/`，并确认服务器能访问 `worker/`、`worker/wasm/`、`locale-assets/`、`vendor/` 和 `.wasm` MIME。 |
| `open-failed` | SDK 未返回可挂载的 widget 实例。 | 记录原始错误和文件信息，检查文件是否损坏或运行时资源是否完整。 |
| `create-failed` | SDK 的 `createfile(...)` 调用失败。 | 记录原始错误，确认空白样例文件和 locale assets 已部署。 |
| `cancelled` | 新打开请求接管当前 viewer。 | 通常无需展示为失败，重新打开文件时可忽略。 |
| `unknown` | 未匹配到已知分类的错误。 | 展示通用失败提示，并上报原始错误便于定位。 |
