【前端】JS-API

安装

基本用法

npm 包

使用`<script>`

使用 npm view 和 npm pack 下载代码包 (.tgz 格式)

将 .tgz 解压缩后的 dist 目录下的文件放置到您托管静态资源的空间，然后使用 <script> 引入 index.js 资源

通过 window.ShimoJSSDK 对象获取对应的方法

使用示例

调用 connect() 时，会以传入参数为基础，初始化一个 <iframe> 并插入 container 对应的元素中。

返回的 sdk 为 ShimoSDK 实例，用于和 SDK、编辑器交互。

如何处理 URL

由于石墨 SDK 以 iframe 的形式挂载到当前页面，iframe.src 对应的 URL 并不适合用于分享，而且在一些功能上，比如 @ 文件，需要用到您系统中对应的 URL 格式，比如 https://your-domain/files/:id。

为了解决这个问题，石墨 SDK 引入 generateUrl() 和 openLink() 方法：

URL 的上下文信息

为了在 URL 上传递上下文信息，比如 URL 指向的段落、单元格，在调用 generateUrl() 生成 URL 后，会在 URL 后附加一个 smParams=PARAMS 的参数：

https://your-domain/files/:id?smParams=PARAMS

如无特殊需要，请保留该参数。

默认情况下，调用 connect() 会从当前 location.search 中提取 smParams，如果遇到需要自定义参数的场合，可以通过 connect({ smParams: PARAMS }) 参数修改。

smParams 为经过 base62 序列化后的 Record<string, unknown> 对象。

在传入 smParams 参数时，将不会从 location.search 中获取数据，如果想保留原有信息，可以这样传递：

URL Info

generateUrl(fileId, info) 中的 info 是用于对 URL 进行一些特殊处理的。

sharingText：石墨默认提供的分享文本：比如

https://your-domain/files/1 xxx 邀请您参与《标题》协作，请复制粘贴后在浏览器打开

https://your-domain/files/1/fill-form xxx 邀请您填写《标题》表单，……

sharingType：表示此次 generateUrl() 对应的行为类型，比如：

UrlSharingType.Form 代表一般的打开编辑表单的行为

UrlSharingType.FormPreview 代表打开预览表单页面的行为

UrlSharingType.FormFill 代表打开填写表单页面的行为

您需要根据具体类型，生成不同的 URL，比如：

UrlSharingType.Form、UrlSharingType.FormPreview 等一般需要进行鉴权，因此可以用 /files/${fileId}

UrlSharingType.FormFill 填写表单一般不需要登录鉴权，因此可以用另一个独立的路由，比如 /files/${fileId}/fill-form

在实际操作中，您可以根据 sharingType 按需为 URL 添加分享文本。若添加了分享文本，则需要您在 parseUrl() 中对 URL 进行处理，比如：

打开表格指定工作表 (Sheet)

使用本章节用法时，请先了解 URL 的上下文信息章节。

此用法适用于表格中存在多个工作表 (Sheet) ，希望在打开编辑器时，直接展示某个工作表格而非默认的第一个工作表。如用于希望直接分享表格的某个工作表链接给其他协作者，他人在打开后可直接查看指定的工作表。

首先通过表格的编辑器接口 getActiveSheetId 方法获取当前处于激活状态的工作表 ID ，此 ID 可用于追加在接入方自身的 URL 上作为参数。

如通过 URL QueryString 方式传递：https://your-domain.com/files/abcdefg?sheetId=XXXXX&smParams=XXXXXXXXXXXXXXXXXXXXXX

sheetId 仅为参数名举例，接入方可结合自身业务命名。

定位文中位置

说明：打开编辑器时，定位至在正文中 at 某用户或评论的位置

支持类型：

轻文档 - document

表格 - spreadsheet

传统文档 - documentPro

使用本章节用法时，请先了解 URL 的上下文信息章节。

此用法适用于:

定位@用户：在接入方系统的文件中 at 了指定用户，在回调接口中收到 石墨 SDK 事件 中的 mention_at 类型事件，并获取 mentionAt.guid 字段作为参数拼接至接入方的访问链接上，在接入方系统通知对应用户时，推送的链接可直接打开对应文件并定位至当前用户被 at 的正文位置，以便于查看对应位置相关内容。

新增评论：在接入方系统的文件中新增了评论，在回调接口中收到 石墨 SDK 事件 中的 comment 类型事件，并获取 comment.selectionGuid 字段作为参数拼接至接入方的访问链接上，在接入方系统通知对应用户时，推送的链接可直接打开对应文件并定位至当前新增的评论位置，以便于查看对应位置相关内容。

如通过 URL QueryString 方式传递：https://your-domain.com/files/abcdefg?mentionId=XXXXX&smParams=XXXXXXXXXXXXXXXXXXXXXX

mentionId 仅为参数名举例，接入方可结合自身业务命名。

支持的文档类型

类型	说明	编辑器 API
Document	轻文档	轻文档
DocumentPro	传统文档	传统文档
Spreadsheet	表格	表格
Presentation	幻灯片	幻灯片
Table	应用表格	应用表格
Form	表单	表单
Flowchart	流程图	流程图

安装#

基本用法#

npm 包#

使用<script>#

使用示例#

如何处理 URL#

URL 的上下文信息#

URL Info#

打开表格指定工作表 (Sheet)#

定位文中位置#

支持的文档类型#

安装