@liuzengwei/vue-xn-editor

v0.1.5

Published

2 months ago

A Vue2 rich text editor component based on tiptap v1

0High
0Medium
0Low

liuzengwei

@liuzengwei/vue-xn-editor 使用文档

基于 Vue2 + Tiptap 的富文本编辑器组件，提供：

可配置分组工具栏
Bubble 菜单与 Slash 命令
表格编辑工具集
图片粘贴、复制、宽度/对齐快捷操作
可选 OSS 上传能力（工具栏图片按钮）

环境要求

Vue: 2.7.x
Node.js: 建议 16+

安装

npm i @liuzengwei/vue-xn-editor

快速开始

1. 全局注册

import Vue from 'vue';
import VueXnEditor from '@liuzengwei/vue-xn-editor';
import '@liuzengwei/vue-xn-editor/dist/style.css';

Vue.use(VueXnEditor);

2. 页面中使用

<template>
	<xn-editor
		ref="editor"
		v-model="content"
		placeholder="请输入内容"
		:readonly="false"
		:theme-color="'#ff745c'"
		:toolbar="toolbar"
		:image-upload="imageUpload"
		@change="handleChange"
		@image-upload-state-change="handleUploadState"
	/>
</template>

<script>
export default {
	data() {
		return {
			content: '<p>hello</p>',
			toolbar: [
				{
					group: 'text',
					label: '文本',
					items: ['bold', 'italic', 'underline', 'strike', 'textColor', 'bgColor', 'fontSize', 'headingSelect']
				},
				{
					group: 'paragraph',
					label: '段落',
					items: ['alignLeft', 'alignCenter', 'alignRight', 'alignJustify', 'bulletList', 'orderedList']
				},
				{
					group: 'insert',
					label: '插入',
					items: ['link', 'image', 'insertTable']
				},
				{
					group: 'history',
					label: '历史',
					items: ['undo', 'redo']
				}
			],
			imageUpload: {
				stsUrl: '',
				pathPrefix: 'accessory/editor'
			}
		};
	},
	methods: {
		handleChange(payload) {
			console.log('editor change:', payload);
		},
		handleUploadState(payload) {
			console.log('upload state:', payload);
		}
	}
};
</script>

Props

| 名称 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | value | String | '' | 编辑器 HTML 内容（v-model） | | placeholder | String | '请输入内容' | 占位文案 | | readonly | Boolean | false | 只读模式 | | themeColor | String | '#ff745c' | 主题色，影响工具栏高亮等样式 | | toolbar | Array | Array | 内置默认分组 | 工具栏配置，支持旧数组和分组数组 | | imageUpload | Object | {} | 工具栏图片上传配置 |

toolbar 配置格式

旧格式: Array
新格式: Array<{ group: string, label?: string, items: string[] }>

示例：

toolbar: [
	{
		group: 'text',
		label: '文本',
		items: ['bold', 'italic', 'underline']
	},
	{
		group: 'history',
		label: '历史',
		items: ['undo', 'redo']
	}
];

事件

| 事件名 | 参数 | 说明 | | --- | --- | --- | | input | html: String | v-model 标准事件 | | change | { html, text, count } | 内容变化回调 | | image-copy | { src, width } | 图片复制成功回调 | | image-upload-state-change | { uploadId, status, fileName, progress?, message?, url? } | 图片上传状态变化 | | focus | - | 获得焦点 | | blur | - | 失去焦点 |

实例方法

通过 ref 调用：

this.$refs.editor.getHTML();
this.$refs.editor.setHTML('<p>new content</p>');
this.$refs.editor.clear();
this.$refs.editor.focus();
this.$refs.editor.blur();

| 方法 | 参数 | 返回值 | 说明 | | --- | --- | --- | --- | | getHTML | - | String | 获取当前 HTML | | setHTML | html: String | void | 设置编辑器内容 | | clear | - | void | 清空内容 | | focus | - | void | 聚焦编辑器 | | blur | - | void | 让编辑器失焦 |

imageUpload 配置

imageUpload: {
	stsUrl: 'https://your-domain/api/sts',
	accept: 'image/*',
	allowedMimeTypes: ['image/png', 'image/jpeg'],
	allowedExtensions: ['.png', '.jpg', '.jpeg'],
	headers: {
		Authorization: 'Bearer xxx'
	},
	pathPrefix: 'accessory/editor',
	onUploadStateChange: (payload) => {
		console.log(payload);
	}
}

stsUrl: 配置后启用 OSS 上传
accept: 文件选择器 accept，默认 image/*
allowedMimeTypes: MIME 白名单
allowedExtensions: 后缀白名单
headers: 请求 stsUrl 的附加请求头
pathPrefix: OSS 路径前缀，默认 accessory/editor
onUploadStateChange: 上传状态回调

常用命令项

可在 toolbar 的 items 中使用：

文本: bold, italic, underline, strike, textColor, bgColor, fontSize, headingSelect
段落: alignLeft, alignCenter, alignRight, alignJustify, heading, bulletList, orderedList, taskList, blockquote, codeBlock
插入: link, image, insertTable
表格: addColumnBefore, addColumnAfter, deleteColumn, addRowBefore, addRowAfter, deleteRow, deleteTable, mergeCells, splitCell
表格选区: selectTableAll, selectTableHeader, selectTableBody
历史: undo, redo

Word 粘贴保真

当粘贴来源为 Word 富文本时，编辑器会自动进行清洗与结构映射，优先保留可编辑结构和常用样式。
重点保留：表格结构（含合并单元格）、基础文本样式、段落对齐/缩进/列表、单元格边框与背景等。
会移除 Office 私有污染样式和不安全属性，以减少脏 HTML 对后续编辑的影响。

交互说明

输入 / 可唤起 Slash 命令面板
工具栏图片支持本地选择并上传（启用 stsUrl 时）
选中图片后可在 Bubble 菜单做复制、宽度与对齐快捷操作

注意事项

组件输出为 HTML 字符串，请在服务端做 XSS 过滤
当前推荐组合为 Vue2 + tiptap v2 生态