weboffice-js-sdk 2.0.5-beta.2 → 2.0.5

package/README.md

@@ -6,22 +6,22 @@
 
 _注：此 SDK 无法用于石墨文档官网产品 (即 shimo.im) 。_
 
-## [文档详情](https://shimo-open.github.io/shimo-js-sdk/#/)
+## [文档详情](https://shimo-open.github.io/weboffice-js-sdk/#/)
 
 ### 安装
 
 ```shell
 # 通过 npm
-npm install --save shimo-js-sdk
+npm install --save weboffice-js-sdk
 
 # 通过 yarn
-yarn add shimo-js-sdk
+yarn add weboffice-js-sdk
 ```
 
 ### 初始化 iframe
 
 ```js
-const { connect } = require('shimo-js-sdk')
+const { connect } = require('weboffice-js-sdk')
 
 connect({
   fileId: '您系统中的 file id',
@@ -29,13 +29,13 @@ connect({
   signature: '用您的 app id 和 secret 签发的签名',
   token: '用于您系统识别用户请求的 token',
   container: document.querySelector('#shimo-file'), // iframe 挂载的目标容器元素
-  lang: 'en', // 未指定此参数时，使用浏览器默认语言
+  lang: 'en-US', // 可选；未指定时使用编辑器默认语言
   disableAiEntry: true, // 可选，隐藏 iframe 内 AI 入口
   theme: {
     name: 'light'
   }, // 可选，透传给 iframe 内编辑器主题配置
   userUuid：'您的uuid' // 仅在v2版本回调时需要传入(co-1.3+支持)
-}).then((shimoSDK) => {
+}).then((officeSDK) => {
   // ...
 })
 ```
@@ -44,31 +44,31 @@ connect({
 
 其中：
 
-- `disableAiEntry` 为可选布尔值，透传到 iframe 内 `ShimoSDK` 的 AI 入口开关能力。
+- `disableAiEntry` 为可选布尔值，透传到 iframe 内 `OfficeSDK` 的 AI 入口开关能力。
 - `theme` 为可选主题对象，宿主侧仅负责透传；未传时 iframe 内仍使用默认主题配置。
 
 返回值：
 
 ```
-Promise<ShimoSDK>
+Promise<OfficeSDK>
 ```
 
 **使用传统的 `<script>` 的方式加载：**
 
 1. 使用 [npm view](https://docs.npmjs.com/cli/v7/commands/npm-view) 和 [npm pack](https://docs.npmjs.com/cli/v7/commands/npm-pack) 下载代码包 (`.tgz` 格式)
 2. 将 `.tgz` 解压缩后的 `dist` 目录下的文件放置到您托管静态资源的空间，然后使用 `<script>` 引入 `index.js` 资源
-3. 通过 `window.ShimoJSSDK` 对象获取对应的方法
+3. 通过 `window.WebOfficeJSSDK` 对象获取对应的方法
 
 ```js
-const { connect, FileType } = window.ShimoJSSDK
+const { connect, FileType } = window.WebOfficeJSSDK
 // 等价于
-const { connect, FileType } = require('shimo-js-sdk')
+const { connect, FileType } = require('weboffice-js-sdk')
 ```
 
 #### 使用示例
 
 ```js
-const { connect } = require('shimo-js-sdk')
+const { connect } = require('weboffice-js-sdk')
 
 const fileId = '1234'
 const uuid = 'youruuid'
@@ -84,19 +84,19 @@ connect({
   container: document.querySelector('#shimo-file'), // iframe 挂载的目标容器元素
   userUuid: uuid
 }).then((sdk) => {
-  // sdk 即为 ShimoSDK 实例
+  // sdk 即为 OfficeSDK 实例
 })
 ```
 
 调用 `connect()` 时，会以传入参数为基础，初始化一个 `<iframe>` 并插入 `container` 对应的元素中。
 
-返回的 `sdk` 为 `ShimoSDK` 实例，用于和 SDK、编辑器交互。
+返回的 `sdk` 为 `OfficeSDK` 实例，用于和 SDK、编辑器交互。
 
 ### SDK 和编辑器实例
 
 石墨 JS SDK 共有两种实例用于和 JS SDK 交互：
 
-- `ShimoSDK` 由 `connect()` 返回，处理初始化编辑器和编辑器交互的工作
+- `OfficeSDK` 由 `connect()` 返回，处理初始化编辑器和编辑器交互的工作
 - `Editor` 文档编辑器，直接和文档内容交互。**`Editor` 所有接口均返回 Promise**
 
 两者之间各有独立的方法和事件，具体请查看 `docs` 目录的文档。
@@ -104,7 +104,7 @@ connect({
 获取编辑器实例和与其交互：
 
 ```js
-const { FileType } = require('shimo-js-sdk')
+const { FileType } = require('weboffice-js-sdk')
 
 // 获取编辑器实例
 const editor = sdk.getEditor()
@@ -123,7 +123,7 @@ if (sdk.fileType === FileType.Document) {
 若为 `TypeScript`，可使用 `Generic`：
 
 ```typescript
-const { Document } = require('shimo-js-sdk')
+const { Document } = require('weboffice-js-sdk')
 
 const editor = sdk.getEditor<Document.Editor>()
 editor.on('saveStatusChanged', (payload) => {
@@ -193,7 +193,7 @@ const sdk = await connect({
 
 ### 协作者模块使用说明
 
-当 iframe 套件开启协作者能力后（依赖 `ENABLE_SDK_COLLABORATORS_MODULE` 开关），shimo-js-sdk 使用方可按以下方式接入：
+当 iframe 套件开启协作者能力后（依赖 `ENABLE_SDK_COLLABORATORS_MODULE` 开关），weboffice-js-sdk 使用方可按以下方式接入：
 
 1. **监听 `collaboratorsChanged`**
 
@@ -237,56 +237,63 @@ editor.on('editForbiddenConfirmed', ({ reason }) => {
 })
 ```
 
-### `signature` 和 `token`
+### 凭证自动刷新（建议）
 
 - `signature` 为石墨区分请求来源，并实现数据隔离的基础
 - `token` 为您用于识别回调请求来源、是否合法的依据
 
 具体说明请查阅在线文档：[https://platform.shimo.im/v2/docs/concepts/](https://platform.shimo.im/v2/docs/concepts/)。
 
-由于 `signature` 和 `token` 有过期时间，一般也不建议设置过长的时间，但为了减少因过期导致的用户体验问题，`ShimoSDK` 提供 `setCredentials({ signature, token })` 方法用于动态更新。
+由于 `signature` 和 `token` 有过期时间，建议在 `ConnectOptions` 中配置自动刷新，避免用户长时间编辑时因凭证失效而中断。
 
-```js
-/**
- * 从您的后端服务获取用于石墨鉴权的签名和 token
- * @deprecated
-*/
-let { signature, token, expires } = await getCredentialsFromServer()
-
-const shimoSDK = await connect({ ... })
-
-setInterval(
-  () => {
-    // 建议过期时间为7天
-    // 当剩余时间不到3.5天就过期时进行更新
-    if (expires - Date.now() < 1000 * 3600 * 24 * 3.5) {
-      const resp = await getCredentialsFromServer()
-      await shimoSDK.setCredentials({
-        signature: resp.signature,
-        token: resp.token
-      })
-      expires = resp.expires
-    }
-  },
-  60 * 1000
-)
-// 以上为旧版本更新鉴权方式，新版本（v1.2.23+）请参照如下方式进行更新
-const shimoSDK = await connect({
-  signature: '[your signature]',
-  token: '[your token]',
-  // 更新鉴权的时间间隔，单位为毫秒
-  // 若过期时间为7天，则建议设置为1000 * 3600 * 24 * 3.5 （3.5天）
-  refreshCredentialsInterval: 1000 * 3600 * 24 * 3.5,
-  getCredentials: async () => {
-    const res = await getCredentialsFromServer()
-    return {
-      signature: res.signature,
-      token: res.token,
-    }
-  }
-})
+```typescript
+const { expireMs } = (await appService.getExpireConfig()).data
+
+const options: ConnectOptions = {
+  ...config,
+  // 在过期时长的 80% 处刷新，给网络重试等情况预留时间
+  refreshCredentialsInterval: Math.ceil(expireMs * 0.8),
+  getCredentials: async () => (await appService.getCredentials()).data
+}
+
+const officeSDK = await connect(options)
+```
+
+示例配套接口：
+
+- `GET /api/apps/expire-config`：返回凭证过期时长，例如 `{ expireMs: 900000 }`
+- `GET /api/credentials`：返回新凭证，例如 `{ signature, token }`
+
+`getCredentials` 应从接入方后端获取最新凭证，并返回同时包含 `signature` 和 `token` 的对象。接口路径可按接入方系统实际情况调整。
+
+### 国际化：编辑器多语言（可选，co-1.8+）
+
+接入方可在调用 `connect` 时通过 `lang` 指定编辑器界面语言，传入对应语言码即可；用户选择“系统默认”时省略 `lang`（或传 `undefined`；纯 JavaScript 也可传 `null`）。
+
+```typescript
+const options: ConnectOptions = {
+  ...config,
+  ...(editorLang ? { lang: editorLang } : {}) // “系统默认”时不传 lang
+}
+
+const officeSDK = await connect(options)
 ```
 
+1.8 版本编辑器支持以下 16 种语言：
+
+| 语言          | `lang` 语言码 | 语言             | `lang` 语言码 |
+| ------------- | ------------- | ---------------- | ------------- |
+| 简体中文      | `zh-CN`       | 繁體中文         | `zh-TW`       |
+| English       | `en-US`       | 日本語           | `ja-JP`       |
+| 한국어        | `ko-KR`       | Español          | `es-ES`       |
+| Português     | `pt-PT`       | Deutsch          | `de-DE`       |
+| Français      | `fr-FR`       | Italiano         | `it-IT`       |
+| Русский       | `ru-RU`       | Bahasa Indonesia | `id-ID`       |
+| Tiếng Việt    | `vi-VN`       | ไทย              | `th-TH`       |
+| Bahasa Melayu | `ms-MY`       | العربية          | `ar-SA`       |
+
+为兼容旧版写法，仍可传入 `en`、`ja`，SDK 会分别映射为 `en-US`、`ja-JP`。新接入建议使用表中的标准语言码。
+
 ### 如何处理 URL
 
 由于石墨 SDK 以 `iframe` 的形式挂载到当前页面，`iframe.src` 对应的 URL 并不适合用于分享，而且在一些功能上，比如 @ 文件，需要用到您系统中对应的 URL 格式，比如 `https://your-domain/files/:id`。
@@ -294,9 +301,9 @@ const shimoSDK = await connect({
 为了解决这个问题，石墨 SDK 引入 `generateUrl()` 和 `openLink()` 方法：
 
 ```js
-import { UrlSharingType } from 'shimo-js-sdk'
+import { UrlSharingType } from 'weboffice-js-sdk'
 
-const shimoSDK = await connect({
+const officeSDK = await connect({
   ...,
 
   generateUrl(fileId: string, info: GenerateUrlInfo): string {
@@ -497,9 +504,9 @@ connect({
 - `ui.toast.tips.edit.noPermission`
 
 ```typescript
-import { connect } from 'shimo-js-sdk'
+import { connect } from 'weboffice-js-sdk'
 
-const shimoSDK = await connect({
+const officeSDK = await connect({
   ui: {
     toast: {
       tips: {
@@ -521,9 +528,9 @@ const shimoSDK = await connect({
 此方法可显示接入方自定义 toast，具体用法如下
 
 ```typescript
-import { connect, ShowToastOptions } from 'shimo-js-sdk'
+import { connect, ShowToastOptions } from 'weboffice-js-sdk'
 
-const shimoSDK = await connect({
+const officeSDK = await connect({
   // 初始化sdk时传了该方法将会拦截编辑器内的toast
   showToast: (options: ShowToastOptions) => {
     // show your toast

package/dist/OfficeSDK.d.ts

@@ -465,7 +465,7 @@ export interface SDKToastOptions {
 }
 /**
  * 透传给 iframe 编辑器的主题配置。
- * 当前 shimo-js-sdk 仅负责跨 iframe 传输，不在宿主侧约束字段细节。
+ * 当前 weboffice-js-sdk 仅负责跨 iframe 传输，不在宿主侧约束字段细节。
  */
 export interface CommonThemeConfig {
     [key: string]: unknown;
@@ -596,7 +596,7 @@ export interface OfficeSDKOptions extends Omit<ContainerMethods, 'getContainerRe
     headerBarsVisible?: boolean;
     /**
      * 是否隐藏 iframe 内 AI 入口。
-     * 对应 iframe 内 ShimoSDK 的现有 AI 入口开关能力。
+     * 对应 iframe 内 OfficeSDK 的现有 AI 入口开关能力。
      */
     disableAiEntry?: boolean;
     /**