npm package: @qingbing/ts-v3-xz-editor
Description: 以 @wangeditor/editor 为基础， 使用 vue3 二次封装的在线富文本编辑器
Author: qingbing
Latest version: 1.0.3

# XzEditor 插件介绍

- [XzEditor 插件介绍](#xzeditor-插件介绍)
  - [1. 概要说明](#1-概要说明)
    - [1.1 地址](#11-地址)
    - [1.2 插件描述](#12-插件描述)
    - [1.3 重要依赖](#13-重要依赖)
    - [1.4 插件安装](#14-插件安装)
  - [2. 包说明](#2-包说明)
    - [2.1 属性说明](#21-属性说明)
      - [2.1.1 toolbarConf 重要属性说明](#211-toolbarconf-重要属性说明)
      - [2.1.2 editorConf 重要属性说明](#212-editorconf-重要属性说明)
      - [2.1.3 editorEvents 重要属性说明](#213-editorevents-重要属性说明)
    - [2.2 事件说明](#22-事件说明)
    - [2.3 实例暴露说明](#23-实例暴露说明)
  - [3. 示例](#3-示例)
    - [3.1 全局注册使用](#31-全局注册使用)
    - [3.2 模板组件使用](#32-模板组件使用)

## 1. 概要说明
### 1.1 地址

- [https://gitee.com/duqingbing/ts-v3-package/tree/ts-v3-xz-editor](https://gitee.com/duqingbing/ts-v3-package/tree/ts-v3-xz-editor)
- [@wangeditor/editor 官网](https://www.wangeditor.com/)

### 1.2 插件描述

vite + ts + vue3 技术，以 @wangeditor/editor 为基础， 二次封装的在线富文本编辑器

### 1.3 重要依赖

- @qingbing/ts-v3-utils: ^1.0.1
- @qingbing/ts-v3-element-plus: ^2.1.4
- @wangeditor/editor: ^5.1.23
- @wangeditor/editor-for-vue: ^5.1.12
- element-plus: ^2.6.2
- vue: ^3.4.21

### 1.4 插件安装

```bash
# yarn 安装
yarn add @qingbing/ts-v3-xz-editor

# npm 安装
npm i @qingbing/ts-v3-xz-editor
```

## 2. 包说明

### 2.1 属性说明

| 属性名               | 类型    | 是否必需 | 默认值                           | 意义                                                                |
| :------------------- | :------ | :------- | :------------------------------- | :------------------------------------------------------------------ |
| modelValue           | String  | 是       | -                                | 编辑器的初始值                                                      |
| showHtml             | Boolean | 否       | false                            | 是否显示组件自定义的html源代码功能                                  |
| mode                 | String  | 否       | 'simple'                         | 控制编辑器工具栏按钮的模式: mini, simple, default, all              |
| height               | String  | 否       | '300px'                          | 编辑区域的高度                                                      |
| toolbarConf          | Object  | 否       | {}                               | 工具栏配置, 参考 @wangeditor/editor 的配置                          |
| editorConf           | Object  | 否       | { placeholder: "请输入内容..." } | 编辑器配置, 参考 @wangeditor/editor 的配置                          |
| editorEvents         | Object  | 否       | {}                               | 编辑器触发事件, 参考 @wangeditor/editor 的配置                      |
| uploadImageServer    | String  | 否       | ""                               | 图片上传服务地址,控制上传图片工具是否有效                           |
| uploadImageUseInsert | Boolean | 否       | true                             | 是否使用当前插件的上传格式,否则使用  @wangeditor/editor 的返回格式  |
| uploadImage          | Object  | 否       | {}                               | 图片上传配置, 会和 uploadImageServer, uploadImageUseInsert 进行整合 |
| uploadVideoServer    | String  | 否       | ""                               | 视频上传服务地址,控制上传视频工具是否有效                           |
| uploadVideoUseInsert | Boolean | 否       | true                             | 是否使用当前插件的上传格式,否则使用  @wangeditor/editor 的返回格式  |
| uploadVideo          | Object  | 否       | {}                               | 视频上传配置, 会和 uploadVideoServer, uploadVideoUseInsert 进行整合 |


#### 2.1.1 toolbarConf 重要属性说明

| 属性              | 类型    | 默认值                       | 说明                                                             |
| :---------------- | :------ | :--------------------------- | :--------------------------------------------------------------- |
| toolbarKeys       | Array   | 参考 @wangeditor/editor 官网 | 重新配置工具栏                                                   |
| insertKeys        | Object  | {}                           | 在当前 toolbarKeys 的基础上继续插入新菜单，如自定义扩展的菜单    |
| excludeKeys       | Array   | []                           | 在当前 toolbarKeys 的基础上排除某些菜单                          |
| modalAppendToBody | Boolean | 参考 @wangeditor/editor 官网 | 菜单弹出的 modal 添加到 body 下，并自定义 modal 的定位和其他样式 |

#### 2.1.2 editorConf 重要属性说明

| 属性        | 类型                       | 默认值         | 说明                                                                    |
| :---------- | :------------------------- | :------------- | :---------------------------------------------------------------------- |
| placeholder | string                     | 'Type here...' | 编辑器 placeholder 提示                                                 |
| readOnly    | boolean                    | false          | 配置编辑器是否只读, 可通过 editor.enable() 和 editor.disable() 进行切换 |
| autoFocus   | boolean                    | true           | 编辑器默认是否 focus                                                    |
| scroll      | boolean                    | true           | 编辑器是否支持滚动                                                      |
| maxLength   | number                     | 0              | 配置编辑器的 maxlength， 无特殊需求，慎用，耗资源，易卡顿               |
| onMaxLength | (editor: IDomEditor)=>void | xxx            | 配置编辑器的 maxlength， 无特殊需求，慎用，耗资源，易卡顿               |

#### 2.1.3 editorEvents 重要属性说明

| 属性        | 类型                         | 说明                                                         |
| :---------- | :--------------------------- | :----------------------------------------------------------- |
| onCreated   | (editor: IDomEditor) => void | 编辑器创建完毕时的回调函数                                   |
| onChange    | (editor: IDomEditor) => void | 编辑器内容、选区变化时的回调函数                             |
| onDestroyed | (editor: IDomEditor) => void | 编辑器销毁时的回调函数。调用 editor.destroy() 即可销毁编辑器 |
| onFocus     | (editor: IDomEditor) => void | 编辑器 focus 时的回调函数                                    |
| onBlur      | (editor: IDomEditor) => void | 编辑器 blur 时的回调函数                                     |
| customPaste | (editor: IDomEditor) => void | 自定义粘贴。可阻止编辑器的默认粘贴，实现自己的粘贴逻辑       |
| customAlert | (editor: IDomEditor) => void | 自定义编辑器 alert                                           |

### 2.2 事件说明

支持 @wangeditor/editor 的事件, 配置上属性 editorEvents 中, 参考 [2.1.3 editorEvents 重要属性说明](#213-editorevents-重要属性说明)

### 2.3 实例暴露说明

| 属性名       | 类型       | 说明                   |
| :----------- | :--------- | :--------------------- |
| editor       | IDomEditor | 当前编辑器             |
| getToolbar() | Toolbar    | 获取当前编辑器的工具栏 |

## 3. 示例
### 3.1 全局注册使用

- 一旦注册， `Editor` 作为组件全局通用 
- 使用方法参考 [3.2 模板组件使用](#32-模板组件使用), 去掉组件导入的语句即可

```ts
// main.ts
import "@qingbing/ts-v3-xz-editor/dist/css/preview.css" // xz-editor 组件定义的一套编辑器基础样式

import '@wangeditor/editor/dist/css/style.css' // wangeditor 样式表
import "@qingbing/ts-v3-xz-editor/dist/style.css" // xz-editor 组件定义样式
import { XzEditorPlugin } from '@qingbing/ts-v3-xz-editor'
app.use(XzEditorPlugin, {
  name: 'Editor',
  options: {}
})
```

### 3.2 模板组件使用

```vue
<template>
    <h2>mini</h2>
    <XzEditor ref="editor-mini" v-model="miniContent" mode="mini" :showHtml="true" />
    <h2>normal</h2>
    <XzEditor ref="editor-normal" v-model="normalContent" mode="normal" :showHtml="true" />
    <h2>full</h2>
    <XzEditor ref="editor-full" v-model="fullContent" mode="full" :showHtml="true" />
    <h2>default</h2>
    <XzEditor ref="editor-default" v-model="defaultContent" mode="default" :showHtml="true" />
    <h2>simple</h2>
    <XzEditor ref="editor-simple" v-model="simpleContent" mode="simple" :showHtml="true" />
    <hr>
    <button @click="onClick">获取 editor</button>
    <XzEditor ref="editorRef" v-model="content" :showHtml="true" :editorEvents="events"
        :uploadImageServer="uploadImageServer" :uploadImage="uploadImage" mode="default" />
    <p>{{ content }}</p>
</template>

<script setup lang="ts">
import '@wangeditor/editor/dist/css/style.css' // wangeditor 样式表
import "@qingbing/ts-v3-xz-editor/dist/style.css" // xz-editor 组件定义样式
import type { IDomEditor } from "@wangeditor/editor";
import type { TXzEditorEvents } from '@qingbing/ts-v3-xz-editor' // 如果注册成了全局组件，这句将不再需要
import { XzEditor } from '@qingbing/ts-v3-xz-editor' // 如果注册成了全局组件，这句将不再需要
import { Toolbar } from "@wangeditor/editor";
import { ref } from "vue";

const content = ref("what")
const uploadImageServer = 'http://mock.qiyezhu.net/mock/64e35b8e4a2b7b001dd2e4ec/example/upload-image-server'
const uploadImage = {
    headers: {
        'Access-Control-Allow-Origin': '*',
        'Access-Control-Allow-Headers': "Content-Type"
    }
}
const events: TXzEditorEvents = {
    onBlur(editor) {
        console.log("blur", editor);
    },
    onChange: (editor) => {
        console.log("change", editor);
    }
}
const editorRef = ref({
    editor: "",
    getToolbar: ((): Toolbar | void => { return })
})
const onClick = () => {
    const editor: IDomEditor = editorRef.value.editor as unknown as IDomEditor
    const toolbar: Toolbar = editorRef.value.getToolbar() as Toolbar

    const menuKeys = editor.getAllMenuKeys()
    const toolbarConf = toolbar.getConfig()
    const toolbarMenus = toolbar.getMenus()

    console.log(menuKeys);
    console.log(toolbarConf);
    console.log(toolbarConf.toolbarKeys);
    console.log(toolbarMenus);
}

const miniContent = ref("mini")
const normalContent = ref("normal")
const fullContent = ref("full")
const defaultContent = ref("default")
const simpleContent = ref("simple")
</script>
```