shimo-sdk-cabinet

v4.5.0

Published

3 years ago

shimo sdk cabinet, which to simplify the development process

Downloads

0High
0Medium
0Low

tomwan

chrisyipw

luoyjx

石墨 SDK 简易开发模块

简介

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

接入示例：sdk-cabinet-example。

使用说明

安装

通过 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 | objectboolean | 可选 | 协作者插件，详见 d.ts 文件 | | plugins.Collaboration | objectboolean | 可选 | 协作插件，详见 d.ts 文件 | | plugins.Comment | objectboolean | 可选 | 划词评论插件，详见 d.ts 文件 | | plugins.DemoScreen | objectboolean | 可选 | 演示模式插件，详见 d.ts 文件 | | plugins.Gallery | objectboolean | 可选 | 相册插件，详见 d.ts 文件 | | plugins.History | objectboolean | 可选 | 历史插件，详见 d.ts 文件 | | plugins.Shortcut | objectboolean | 可选 | 快捷键插件，详见 d.ts 文件 | | plugins.TableOfContent | objectboolean | 可选 | 目录插件，详见 d.ts 文件 | | plugins.Toolbar | objectboolean | 可选 | 工具栏插件，详见 d.ts 文件 | | plugins.Uploader | objectboolean | 可选 | 文件上传器插件，详见 d.ts 文件 |

默认初始化的插件：

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

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

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

表格 (`sheet`) 配置

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

文件大小

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme