石墨 SDK 简易开发模块

简介

用于石墨 SDK 接入的 All-in-One 模块。

使用说明

安装

通过 npm 安装：

npm install shimo-sdk-cabinet

通过 yarn 安装：

yarn add shimo-sdk-cabinet

安装后，本模块提供以下可用资源：

.
├── dist
│   ├── cabinet.min.js
│   ├── cabinet.min.js.map
│   ├── document-pro.min.js
│   ├── document-pro.min.js.map
│   ├── document.min.js
│   ├── document.min.js.map
│   ├── sheet.min.js
│   ├── sheet.min.js.map
│   ├── slide.min.js
│   └── slide.min.js.map
└── vendor

dist：为已预先处理的 JS 文件，可以在项目中直接使用。

vendor：为已预先处理的石墨 JS SDK 文件，本模块初始化编辑器依赖于此目录下的 JS SDK 文件。

dist/cabinet.min.js：仅包含简易开发模块基础逻辑，需配合引入 vendor 目录下的 JS SDK 一起使用。适用于有定制需求，希望自定义使用部分插件功能的场景。

dist/document.min.js、dist/document-pro.min.js、dist/sheet.min.js 和 dist/slide.min.js 等等为包含对应套件的 JS SDK 文件的模块文件，不需要额外引入 JS SDK 文件。适用于无定制需求，希望全部使用石墨编辑器所有功能的场景。

document：新文档
document-pro：专业文档
sheet：表格
slide：幻灯片

本模块仅提供统一的代码包，不代表实际可用的套件。

用法 (以新文档为例)

开始之前

请参考鉴权认证文档了解如何申请 Access Token
请参考创建文档一节了解如何获取文档 GUID
Access Token (下称 <SHIMO_ACCESS_TOKEN>) 和 GUID (下称 <SHIMO_FILE_GUID>) 均需要由你获取后提供给前端页面

全局引入

<body>
  <div id="editor"></div>

  <script src="/path/to/shimo-sdk-cabinet/dist/document.min.js"></script>
  <script>
    const cabinet = new window.ShimoCabinet({
      fileGuid: '<SHIMO_FILE_GUID>',
      entrypoint: '<SHIMO_ENTRYPOINT_URL>',
      token: '<SHIMO_ACCESS_TOKEN>',

      container: document.getElementById('editor')
    })
    cabinet.render().then(() => {
      console.log('Editor is ready!')
    })
  </script>
</body>

React / Vue 等方式

以 React 为例：

shimo-sdk-cabinet/dist 下的文件为已经过打包处理、兼容 ES5 的代码，包含

cabinet.min.js 不包含任何套件的初始化工具，仅在需定制插件时使用
document.min.js 文档
document-pro.min.js 专业文档
sheet.min.js 表格
slide.min.js 幻灯片

import React from "react"
import ReactDOM from "react-dom"

// 仅加载文档套件
import ShimoCabinet from 'shimo-sdk-cabinet/dist/document.min.js'

class Editor extends React.Component {
  componentDidMount () {
    const elm = ReactDOM.findDOMNode(this)
    const cabinet = new ShimoCabinet({
      fileGuid: this.props.fileGuid,
      entrypoint: this.props.entrypointURL,
      token: this.props.accessToken,

      container: elm
    })
    cabinet.render().then(() => {
      console.log('Editor is ready!')
    })
  }

  render () {
    return (
      <div class="editor" fileGuid="..." entrypointURL="..." accessToken="...">
      </div>
    )
  }
}

ReactDOM.render(<Editor />, document.getElementById('app'))

如有定制需求，比如希望自定义使用部分插件 (一般建议采用上述方式自动处理配置) ：

import React from "react"
import ReactDOM from "react-dom"

// ES5 兼容的格式
import ShimoCabinet from 'shimo-sdk-cabinet/dist/cabinet.min.js'
// TypeScript 可用原始文件
// import ShimoCabinet from 'shimo-sdk-cabinet'

// 加载石墨 JS SDK 资源，需要用 script-loader 等方式加载，不能再次使用 webpack 或其他工具重新处理
require('shimo-sdk-cabinet/vendor/shimo-jssdk/shimo.sdk.common.min.js')
require('shimo-sdk-cabinet/vendor/shimo-jssdk/shimo.sdk.document.editor.min.js')
// 假设只启用上传插件
require('shimo-sdk-cabinet/vendor/shimo-jssdk/shimo.sdk.document.plugins.uploader.min.js')

class Editor extends React.Component {
  componentDidMount () {
    const elm = ReactDOM.findDOMNode(this)
    const cabinet = new ShimoCabinet({
      fileGuid: this.props.fileGuid,
      entrypoint: this.props.entrypointURL,
      token: this.props.accessToken,

      container: elm,

      editorOptions: {
        plugins: {
          // 以默认选项启用工具栏插件
          Uploader: {
            // 自定义选项
          },

          // 停用其他插件
          Collaborator: false,
          Collaboration: false,
          Comment: false,
          DemoScreen: false,
          Gallery: false,
          History: false,
          Shortcut: false,
          TableOfContent: false
        }
      }
    })
    cabinet.render().then(() => {
      console.log('Editor is ready!')

      // 访问插件，如启动文档演示模式
      cabinet.document.plugins.demoScreen.show()
    })
  }

  render () {
    return (
      <div class="editor" fileGuid="..." entrypointURL="..." accessToken="...">
      </div>
    )
  }
}

ReactDOM.render(<Editor />, document.getElementById('app'))

ShimoCabinet 參数

名称	类型	默认值	描述
container	HTMLElement	必选	石墨表格渲染所需的根 DOM
entrypoint	string	必选	石墨 SDK 后端入口地址
token	string	必选	石墨 SDK 后端鉴权 access token
fileGuid	string	必选	石墨文件的 GUID
editorOptions	object	可选	编辑器基本配置
externals	object	可选	石墨 JS SDK 文件的远程地址，用于优化加载性能
externalLoader	function	可选｜自定义 JS SDK 加载器

新文档 (`document`) 配置

名称	类型	默认值	描述
plugins	object	可选	插件配置，设为 `true` 时使用默认配置，设为 `false` 为关闭，空配置 `{}` 等同于 `true`
plugins.Collaborator	object boolean	可选	协作者插件，详见 `d.ts` 文件
plugins.Collaboration	object boolean	可选	协作插件，详见 `d.ts` 文件
plugins.Comment	object boolean	可选	划词评论插件，详见 `d.ts` 文件
plugins.DemoScreen	object boolean	可选	演示模式插件，详见 `d.ts` 文件
plugins.Gallery	object boolean	可选	相册插件，详见 `d.ts` 文件
plugins.History	object boolean	可选	历史插件，详见 `d.ts` 文件
plugins.Shortcut	object boolean	可选	快捷键插件，详见 `d.ts` 文件
plugins.TableOfContent	object boolean	可选	目录插件，详见 `d.ts` 文件
plugins.Toolbar	object boolean	可选	工具栏插件，详见 `d.ts` 文件
plugins.Uploader	object boolean	可选	文件上传器插件，详见 `d.ts` 文件

默认初始化的插件：

协作者
协作
划词评论
演示模式
相册
历史
快捷键
目录
工具栏
文件上传器

专业文档 (`document-pro`) 配置

专业文档暂没有定制化配置。

表格 (`sheet`) 配置

名称	类型	默认值	描述
plugins	object	可选	插件配置，设为 `true` 时使用默认配置，设为 `false` 为关闭，空配置 `{}` 等同于 `true`
plugins.Chart	object boolean	可选	图表插件，详见 `d.ts` 文件
plugins.Collaborator	object boolean	可选	协作者插件，详见 `d.ts` 文件
plugins.Collaboration	object boolean	可选	协作插件，详见 `d.ts` 文件
plugins.Comment	object boolean	可选	划词评论插件，详见 `d.ts` 文件
plugins.ContextMenu	object boolean	可选	上下文菜单插件，详见 `d.ts` 文件
plugins.Fill	object boolean	可选	下拉填充插件，详见 `d.ts` 文件
plugins.FilterViewport	object boolean	可选	筛选插件，详见 `d.ts` 文件
plugins.FormulaSidebar	object boolean	可选	公式插件，详见 `d.ts` 文件
plugins.HistorySidebarSkeleton	object boolean	可选	历史插件，详见 `d.ts` 文件
plugins.Lock	object boolean	可选	锁定插件，详见 `d.ts` 文件
plugins.Shortcut	object boolean	可选	快捷键插件，详见 `d.ts` 文件
plugins.Toolbar	object boolean	可选	工具栏插件，详见 `d.ts` 文件
plugins.Print	object boolean	可选	打印插件，详见 `d.ts` 文件

默认不初始化的插件：

锁定。需要额外的定制化配置。

移动端不可用的插件：

上下文
下拉填充
打印
公式
工具栏
历史
快捷键

幻灯片 (`slide`) 配置

幻灯片暂没有定制化配置。

externals 和 externalLoader

由于打包后的文件较大，如 dist/sheet.min.js，且文档数据接口请求也是在 JS 加载完后进行，会影响整体性能。

因此提供 externals 来缓解此问题。此模式仅支持文档 (document) 和表格 (sheet) 。

import ShimoCabinet from 'shimo-sdk-cabinet/dist/cabinet.min.js'

const cabinet = new ShimoCabinet({
  ...options,
  externals: {
    common: {
      common: 'https://cdn.com/static/sdk-cabinet/vendor/shimo-jssdk/shimo.sdk.common.min.js',
      collaboration: 'https://cdn.com/static/sdk-cabinet/vendor/shimo-jssdk/shimo.sdk.common.collaboration.min.js'
    },
    sheet: {
      editor: 'https://cdn.com/static/sdk-cabinet/vendor/shimo-jssdk/shimo.sdk.sheet.editor.min.js',
      basicPlugins: '/static/sdk-cabinet/vendor/shimo-jssdk/shimo.sdk.sheet.plugins.basicPlugins.min.js',
      chart: 'https://cdn.com/static/sdk-cabinet/vendor/shimo-jssdk/shimo.sdk.sheet.plugins.chart.min.js',
      ...
    }
  }
})
cabinet.render()

注意 import ShimoCabinet from 'shimo-sdk-cabinet/dist/cabinet.min.js' 引入的是 cabinet.min.js，此文件不包含 vendor/ 下的 JS SDK 文件，因此体积很小。

下面例子定义了 common 和 sheet JS SDK 的地址：

externals: {
  common: {
    common: 'https://cdn.com/static/sdk-cabinet/vendor/shimo-jssdk/shimo.sdk.common.min.js',
    collaboration: 'https://cdn.com/static/sdk-cabinet/vendor/shimo-jssdk/shimo.sdk.common.collaboration.min.js'
  },
  sheet: {
    editor: 'https://cdn.com/static/sdk-cabinet/vendor/shimo-jssdk/shimo.sdk.sheet.editor.min.js',
    basicPlugins: '/static/sdk-cabinet/vendor/shimo-jssdk/shimo.sdk.sheet.plugins.basicPlugins.min.js',
    chart: 'https://cdn.com/static/sdk-cabinet/vendor/shimo-jssdk/shimo.sdk.sheet.plugins.chart.min.js',
    ...
  }
}

common 属于必须加载的组件，其他组件则按需选择，key 为 shimo.sdk.<套件名>.<组件名>.min.js 或 shimo.sdk.<套件名>.plugins.<组件名>.min.js 中的组件名。

同时提供一个方法：cabinet.preload()，此方法在调用的时候，会同步执行：

通过 Ajax 请求指定 fileGuid 文档的数据和配置
通过 <script src="..."> 的方式加载 externals

render() 内部也会调用 preload()，preload() 会根据内部缓存结果是否再次进行请求。

这么做的好处：

cabinet.min.js 更新时，其他没有更新的 JS SDK 组件可有效利用 CDN 缓存，减少用户下载量
Ajax 请求和 script 请求和并行加载

事件

ShimoCabinet 借助 tiny-emitter 提供了事件订阅功能：

cabinet('error', errorHandler)

目前支持的事件：

error：任何在运行中，无法正常抛出的错误都会用此事件抛出
readyState：状态变更时会触发事件，可用事件列表在 ShimoCabinet.ReadyState 中可查
debug：输出用于调试用的信息

移动端适配

移动端目前尽量保证浏览效果，编辑功能和桌面端有差距
目前仅支持
- 文档
- 表格

const cabinet = new ShimoCabinet({
  editorOptions: {
    isMobile: true
  }
})
cabinet.render()

文档需要在 body 添加 in-mobile class。

补充说明

Webpack 配置

由于石墨 JS SDK 已经使用 Webpack 预处理过，因此需要在 Webpack 用 script-loader 处理石墨 JS SDK 文件：

{
  test: /shimo-sdk-cabinet\/vendor\/shimo-jssdk\/.+\.js/i,
  use: 'script-loader'
}

直接引入套件完整包 (如 shimo-sdk-cabinet/dist/document.min.js) 时不需要使用 script-loader 处理。

文件大小

由于套件完整包尺寸都较大，不建议在单个页面同时加载多个套件。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

石墨 SDK 简易开发模块

简介

使用说明

安装

用法 (以新文档为例)

开始之前

全局引入

React / Vue 等方式

ShimoCabinet 參数

新文档 (`document`) 配置

专业文档 (`document-pro`) 配置

表格 (`sheet`) 配置

幻灯片 (`slide`) 配置

externals 和 externalLoader

事件

移动端适配

补充说明

Webpack 配置

文件大小

Files

README.md

Latest commit

History

README.md

File metadata and controls

石墨 SDK 简易开发模块

简介

使用说明

安装

用法 (以新文档为例)

开始之前

全局引入

React / Vue 等方式

ShimoCabinet 參数

新文档 (document) 配置

专业文档 (document-pro) 配置

表格 (sheet) 配置

幻灯片 (slide) 配置

externals 和 externalLoader

事件

移动端适配

补充说明

Webpack 配置

文件大小

新文档 (`document`) 配置

专业文档 (`document-pro`) 配置

表格 (`sheet`) 配置

幻灯片 (`slide`) 配置