4.4.2 • Published 3 years ago

tom-shimo-sdk-cabinet v4.4.2

Weekly downloads
-
License
ISC
Repository
-
Last release
3 years ago

石墨 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：幻灯片

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

用法 (以新文档为例)

开始之前

全局引入

<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 參数

名称类型默认值描述
containerHTMLElement必选石墨表格渲染所需的根 DOM
entrypointstring必选石墨 SDK 后端入口地址
tokenstring必选石墨 SDK 后端鉴权 access token
fileGuidstring必选石墨文件的 GUID
editorOptionsobject可选编辑器基本配置
externalsobject可选石墨 JS SDK 文件的远程地址，用于优化加载性能
externalLoaderfunction可选 ｜ 自定义 JS SDK 加载器
新文档 (document) 配置
名称类型默认值描述
pluginsobject可选插件配置，设为 true 时使用默认配置，设为 false 为关闭，空配置 {} 等同于 true
plugins.Collaboratorobjectboolean可选协作者插件，详见 d.ts 文件
plugins.Collaborationobjectboolean可选协作插件，详见 d.ts 文件
plugins.Commentobjectboolean可选划词评论插件，详见 d.ts 文件
plugins.DemoScreenobjectboolean可选演示模式插件，详见 d.ts 文件
plugins.Galleryobjectboolean可选相册插件，详见 d.ts 文件
plugins.Historyobjectboolean可选历史插件，详见 d.ts 文件
plugins.Shortcutobjectboolean可选快捷键插件，详见 d.ts 文件
plugins.TableOfContentobjectboolean可选目录插件，详见 d.ts 文件
plugins.Toolbarobjectboolean可选工具栏插件，详见 d.ts 文件
plugins.Uploaderobjectboolean可选文件上传器插件，详见 d.ts 文件

默认初始化的插件：

  • 协作者
  • 协作
  • 划词评论
  • 演示模式
  • 相册
  • 历史
  • 快捷键
  • 目录
  • 工具栏
  • 文件上传器
专业文档 (document-pro) 配置

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

表格 (sheet) 配置
名称类型默认值描述
pluginsobject可选插件配置，设为 true 时使用默认配置，设为 false 为关闭，空配置 {} 等同于 true
plugins.Chartobjectboolean可选图表插件，详见 d.ts 文件
plugins.Collaboratorobjectboolean可选协作者插件，详见 d.ts 文件
plugins.Collaborationobjectboolean可选协作插件，详见 d.ts 文件
plugins.Commentobjectboolean可选划词评论插件，详见 d.ts 文件
plugins.ContextMenuobjectboolean可选上下文菜单插件，详见 d.ts 文件
plugins.Fillobjectboolean可选下拉填充插件，详见 d.ts 文件
plugins.FilterViewportobjectboolean可选筛选插件，详见 d.ts 文件
plugins.FormulaSidebarobjectboolean可选公式插件，详见 d.ts 文件
plugins.HistorySidebarSkeletonobjectboolean可选历史插件，详见 d.ts 文件
plugins.Lockobjectboolean可选锁定插件，详见 d.ts 文件
plugins.Shortcutobjectboolean可选快捷键插件，详见 d.ts 文件
plugins.Toolbarobjectboolean可选工具栏插件，详见 d.ts 文件
plugins.Printobjectboolean可选打印插件，详见 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 处理。

文件大小

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

axioslodash.forinlodash.getlodash.isobjectobject-assignpromise-polyfilltiny-emitter
@infinitebrahmanuniverse/nolb-tom@everything-registry/sub-chunk-2957
4.4.2

3 years ago