三米快写

# 指南

# 简介

三米快写WEB富文本编辑器，实际的应用包名是kxeditor。其由两部分组成：一部分是一个页面元素，元素标签是kx-editor，用来将编辑器引用到Web页面中，它可直接在HTML页面中使用，也可以在Vue或者React组件中使用；另一部分是编辑器的应用程序编程接口对象，通过该对象可访问编辑器开放的各种功能接口，详情参阅 API。

# 安装

# 使用 npm 安装

npm i kxeditor
1

推荐使用 npm 的方式安装，它能更好地和 webpack (opens new window) 打包工具配合使用。

# 导入

它是如何工作的？

事实上，kxeditor是一个单文件脚本库，文件名为editor.core.js；因此，不管什么类型的项目，您只要保证在其页面中引入了这个库文件即可。

# 在HTML页面中导入

在node_modules\kxeditor目录中找到editor.core.js文件，复制到您的项目中。然后在HTML页面加上：

<script defer="defer" src="editor.core.js"></script>
1

# 在Vue项目中导入

在您项目的入口文件中加入：

await import('kxeditor')
1

# 在React项目中导入

在您项目的入口文件中加入：

export * from 'kxeditor'
1

# 页面元素

编辑器的可视化交互部分由一个页面元素实现，用户的绝大部分操作都是在这个页面元素中进行，因此使用编辑器的第一步就是要把页面元素标签添加到页面或者组件的合适位置，如下：

<kx-editor></kx-editor>
1

元素属性

  • id：元素id，与普通元素id相同，用来识别和获取相应的编辑器实例
  • height：设置指定一个页面元素的高度，参考CSS中height (opens new window)的取值。
  • toolbar：是否显示菜单栏，取值：'false' 将隐藏菜单栏，如果您想开发自己的菜单栏可使用这个选项。

举个栗子

<kx-editor id="editor" height="98vh" toolbar="false"></kx-editor>
1

# 静态资源

# 数学公式依赖的静态资源

公式插件依赖的静态文件在node_modules\kxeditor\mathlive目录。基于Webpack的项目，可使用CopyWebpackPlugin插件复制这个目录到发布目标。

具体操作

在项目的webpack.config.js文件(无则新建)中加入：

const CopyWebpackPlugin = require('copy-webpack-plugin');

module.exports = {
    plugins: [
        new CopyWebpackPlugin([
            { 
                from: path.resolve(__dirname, 'node_modules/kxeditor/mathlive'), 
                to: 'mathlive' 
            }
        ])
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12

指定数学公式使用的字体目录路径：

customElements.whenDefined('math-field').then(() => {
    MathfieldElement.fontsDirectory = "/mathlive/fonts/";
})
1
2
3

# 事件监听

# 宏数据采集事件

  • # 定义

onMacroData(data)

系统会在需要的时候通过触发此事件来请求宏控件数据。

参数 data

  • fieldtype：字段类型（TEXT、IMAGE）

    TEXT：文本字符串内容； IMAGE：图片资源

    fieldtype = IMAGE 时，fieldvalue 的取值可参考CSS中HTMLImageElement: src property (opens new window)的取值。

  • fieldname：字段名称

  • fieldvalue：字段内容

  • # 使用

editor.addEvent('onMacroData', data => {
    const { fieldname } = data
    switch (fieldname) {
        case 'name':
            data.fieldvalue = '张三'
        break
        case 'gender':
            data.fieldvalue = '男'
        break
    }
})
1
2
3
4
5
6
7
8
9
10
11

# 文档保存事件

  • # 定义

onSave(data)

在调用editor.save()时，系统通过触发此事件将文档数据提交给用户。

参数 data

  • 这是一个文档对象。

  • # 使用

editor.addEvent('onSave', data => {
    //在这里保存文档数据
})
1
2
3

# 词条保存事件

  • # 定义

onEntrySave(data)

在调用editor.saveEntry()时，系统通过触发此事件将词条数据提交给用户。

参数 data

  • 这是一个词条对象。

  • # 使用

editor.addEvent('onEntrySave', data => {
    //在这里保存词条数据
})
1
2
3

# 元素保存事件

  • # 定义

onWidgetSave(data)

系统保存模板元素时，通过触发此事件将模板元素数据提交给用户。

参数 data

  • 这是一个模板元素对象。

  • # 使用

editor.addEvent('onWidgetSave', data => {
    //在这里保存模板元素数据
})
1
2
3
🎉🎉🎉就到这里！🎉🎉🎉