# 常见问题

# 前端 SDK 常见问题

## 如何传递自定义参数给接入方？\{#customArgs}

可通过 WebOffice SDK [初始化](/app-integration-dev/docs-center/online-preview-edit/web/quick-start#步骤-3-初始化)时的`customArgs`字段设置，例如 customArgs 的值为`{"firstname":"jack","lastname":"green"}`，那么该请求头的内容为`\_w_appid=xxx&\_w_tokentype=xxx&file_id=xxx&firstname=jack&lastname=green`

:::danger 注意
customArgs中自定义参数不能使用内部保留字段如：type、version、mode、history\_id、share\_id等，强烈建议开发者采用`业务前缀_参数`来命名，例如业务前缀abc，则可以这样定义`abc_参数`，否则有可能影响文档的正常预览。
:::

## 关于 GetHtmlData() 函数调用时报权限错误\{#gethtmldata}

出现该错误的原因是 GetHtmlData 接口依赖剪切板能力，需要文档开启复制权限。您需要在回调服务的[文档用户权限](/app-integration-dev/docs-center/online-preview-edit/callback/preview#文档用户权限) 的返回值中将 `copy` 置为 1。

## 如何知晓文档加载失败和成功？\{#fileopen}

通过监听通用事件 [fileOpen](/app-integration-dev/docs-center/online-preview-edit/web/events#fileopen) 即可。

## 文档类型正确但打开文档失败\{#openfail}

![](https://open-docs.wpscdn.cn/public/dms/prod-env/resource/1/07/e7/07e7f691b1c0199bd5795a9850ece5e139c75988d8a1a1085854462cc7f4c60f.png)

![](https://open-docs.wpscdn.cn/public/dms/prod-env/resource/1/92/d7/92d790af0e43bd91c317ea473d5c96fc49fd598ce263a44255efa4064b9f39ed.png)

在文件本身没有问题的情况下，用户无法打开 PPT 和 Excel 文件，在控制台可以看到 JS 报错，过一段时间后，又可以正常打开了。

出现这个问题的原因可能是用户先使用了错误的文件类型去打开文件，比如用 w 类型去打开 PPT 格式的文档，当再次使用正确的类型打开时就会出现打开异常，原因是 WebOffice 已经对该文件创建了文字编辑会话，使用正确的文档类型打开也会因为内核指令不对应导致报错。

我们 WebOffice 编辑会话默认五分钟无连接就会关闭，所以当您关闭会话再等待一段时间后，该文件又可以正常打开了。

解决方案：关闭所有预览编辑页面，等待一段时间后，使用正确的文件类型打开文件。

## 如何实现文字大纲的显示与隐藏？\{#documentmap}

文字组件内，通过 SDK 提供的 API 动态控制大纲的显示与隐藏，示例代码如下：

```js
async function showDocumentMap() {
  await instance.ready()

  const app = instance.Application

  // 控制目录显示与否
  app.ActiveDocument.ActiveWindow.DocumentMap = true
}
async function hideDocumentMap() {
  await instance.ready()

  const app = instance.Application

  // 控制目录显示与否
  app.ActiveDocument.ActiveWindow.DocumentMap = false
}
```

## 如何插入表格至指定的内容控件？\{#inserttable}

如下图所示，需要向指定内容控件中插入表格

![](https://open-docs.wpscdn.cn/public/dms/prod-env/resource/1/a9/0a/a90adbe39c5fee05c57359a0d95ce26c742e352ad6ff0334f92cb1c3a852faad.png)

```js
async function insertTable(i) {
  // 内容控件对象
  const contentControls = await app.ActiveDocument.ContentControls

  // 获取指定内容控件
  const contentControl = await contentControls.Item(i)

  // 获取内容控件的范围
  const range = await contentControl.Range

  // 获取起始位置
  const start = await range.Start

  await app.ActiveDocument.Range.SetRange(start, start)

  // 获取所有表格
  const tables = await app.ActiveDocument.Tables

  // 插入表格
  await tables.Add(
    app.ActiveDocument.ActiveWindow.Selection.Range, // 位置信息
    3, // 新增表格的行数
    3, // 新增表格的列数
    1, // 启用自动调整功能
    1 // 根据表格中包含的内容自动调整表格的大小
  )
}
```

## 关于调用带有url传参时报跨域错误\{#addmediaobject}

以调用 [AddMediaObject()](/app-integration-dev/docs-center/online-preview-edit/client/PPT/Shapes#addmediaobject)为例，当函数调用跨域视频地址后，其控制台常见报错，如下图所示：

![](https://open-docs.wpscdn.cn/public/dms/prod-env/resource/1/3a/7d/3a7dffc26cce7322a4d44da1d6be3696fc0743e2e39d12a30e8c984e16ab4509.png)

出现该错误的原因是调用 AddMediaObject 的视频url传参存在跨域，建议业务方增加跨域白名单处理。另外一些视频url访问报 403 Forbidden 可能是url服务作出的访问限制，需确保url有权限访问。

## 如何进入历史版本预览页面？

方式一：通过文档内菜单-历史版本进入

![](https://open-docs.wpscdn.cn/public/dms/prod-env/resource/1/54/d3/54d3648dc1832a5c660e8b6dd795ffc1f2e6c17468da3bfb33f4485908664459.png)


方式二：使用url在地址栏拼接version参数

拼接url：`https://o.wpsgo.com/office/:officeType/:fileId?_w_appid=应用appId&version=预览版本号`

拼接前提是：

1. 若业务方初始化SDK时处理过token，则拼接version前需确保浏览器cookie里有token，一般情况下文件预览正常加载后，token会自动写入cookie
2. 拼接参数version的预览版本号需与业务方版本对应，否则文件将无权限访问

历史版本预览页也可内嵌到业务方页面中，通过方式一[拦截超链接跳转](/app-integration-dev/docs-center/online-preview-edit/demo/public/intercept-link#%E8%B6%85%E9%93%BE%E6%8E%A5%E8%B7%B3%E8%BD%AC%E6%8B%A6%E6%88%AA)并利用iframe内嵌即可，也可通过方式二自行拼接处理

## 关于微信小程序业务域名配置问题

利用webview组件微信小程序也可承载在线预览编辑服务，值得注意的是，webview组件使用前需在小程序管理后台配置业务域名，可以通过[开放平台社区](https://solution-community.wps.cn/)向我们提供配置校验文件信息，社区管理员后台提供配置服务，后台配置所需信息可参考[微信小程序业务域名配置问题](https://solution-community.wps.cn/questions/10010000000004129)。（2025.8.26起新用户域名配置mp1.wpsgo.com）