trumbowyg编辑器文档笔记

最新推荐文章于 2025-11-17 11:01:12 发布
原创最新推荐文章于 2025-11-17 11:01:12 发布 · 3.6k 阅读
1 ·
CC 4.0 BY-SA版权
javascript 专栏收录该内容
33 篇文章
订阅专栏
本文详细介绍了Trumbowyg富文本编辑器的使用方法，包括基础配置、常见问题解决、插件使用等内容，并提供了丰富的示例代码。
1.官网地址：
	https://alex-d.github.io/Trumbowyg

2.github地址：
	https://github.com/Alex-D/Trumbowyg

3.引入文件：
	依赖jquery
	头部引入css文件
	<head>

		<!-- head头部引入css文件 -->
		<link rel="stylesheet" href="components/trumbowyg-editor/ui/trumbowyg.css">
	</head>
	<body>

		<!-- body底部引入js文件 -->
		<script src="library/jquery-1.11.2.min.js"></script>
		<script src="components/trumbowyg-editor/trumbowyg.js"></script>
		<!-- 如果使用插件，引入插件js文件 -->
		<script src="components/trumbowyg-editor/plugins/base64/trumbowyg.base64.min.js"></script>
	</body>

4.开始(get start)
	1>基础
		将<div>转换为编辑器，最简单的代码：
			$('#editor').trumbowyg();
		设置编辑器配置，传递一个对象：
			$('#editor').trumbowyg({
				btns: ['strong', 'em', '|', 'insertImage'],	
				autogrow: true,
			});

	2>常见问题
		SVG图标未加载
			1)检查是否是 'HTTP' 或 'HTTPS' 协议(看来本地可能不支持，只能搭建服务)
			2)查看是否出现跨域错误(使用了XHR请求)

	3>插件使用
		插件js，需要在 jquery 和 trumbowyg '之后' & 在实例化编辑器代码 '之前' 引入，顺序不可错乱！


5.一般的(general)
	1>前缀(通常，我们引入别人的代码，操作dom，都会有自己的一个类前缀，类似命名空间，以防类名冲突！)
		可以改变trumbowyg实例化的元素的所有类的前缀。默认是 'trumbowyg'
		$('#editor').trumbowyg({
			prefix: 'dongxuemin',	
		});

	2>本地化(语言包)
		1)支持20种语言，首先需要引入语言包 'langs/'，(引入位置同插件一致！)
			<script type="text/javascript" src="components/trumbowyg-editor/langs/fr.min.js"></script>
		2)修改默认配置
			$('#editor').trumbowyg({
				lang: 'zh_cn',			// 未找到语言包，默认使用 'en'
			});

	3>自定义皮肤
		1)我们在 <head> 中，引入的 ui/trumbowyg.css，就是默认皮肤。可新建自己的样式文件，然后引入！
		2)为不同的编辑器实例，实例化不同的皮肤。
			可借助 'prefix' 选项，例如：
				prefix: 'dongxuemin'
			实例化的编辑器，所有的类前缀就是 'dongxuemin'，然后，我们可自定义 'dongxuemin-' 为前缀的类名的样式
			/*
				不要采用官网的，修改默认的皮肤。
				我们要使用不同的皮肤，自定义不同的皮肤目录，以及前缀！
					ui/
						default/	// 默认皮肤
						skin1/		// 皮肤1
						skin2/		// 皮肤2
				然后，引入不同的css文件即可！
			 */

		/*
			感觉这里的机制还是不够好...
			我们是不是直接不需要引入 .css 文件，而应该通过传递一个 'skin' 配置，从而到 'ui/' 目录下，去查找对应的皮肤，没有则使用默认，然后，通过js追加css文件到 <head>，实现皮肤自动加载！
			ui/
				default/	// 默认皮肤
				skin1/		// 皮肤1
				skin2/		// 皮肤2
				...
		 */

	4>SVG图标
		默认情况下，SVG图标可用的、并且启用状态。文件是通过javascript的XHR请求加载的，因此，svg文件的路径可能和项目的 'assets' 目录不相匹配。我们可能改变SVG的路径，或者禁用此功能。
		1)全局范围内改变SVG路径
			// 在初始化 'Trumbowyg' 实例之前
			$.trumbowyg.svgPath = '/assets/my-custom-path/icons.svg';
		2)全局范围内禁用SVG
			$.trumbowyg.svgPath = false;
		3)在本地环境下，改变SVG路径或禁用SVG
			$('#editor').trumbowyg({
				svgPath: false,
				svgPath: '/assets/default/icons.svg',
			});
		4)不通过XHR使用SVG图标，或者通过其他协议，而非 HTTP或HTTPS
			可以将SVG写到<body>内
				<div id="trumbowyg-icons">
				    <svg xmlns="http://www.w3.org/2000/svg">
				        <symbol id="trumbowyg-blockquote" viewBox="0 0 72 72"><path d="..."></path></symbol>
				        <symbol id="trumbowyg-bold" viewBox="0 0 72 72"><path d="..."></path></symbol>
				        <symbol id="trumbowyg-close" viewBox="0 0 72 72"><path d="..."></path></symbol>
				        <!-- ... all other icons here -->
				    </svg>
				</div>	
			注意：
				1.如果想兼容 IE9，应该使用该选项
				2.必须使用 'ID=<prefix>-icons'(prefix，就是之前我们提前到 '前缀配置')
			SVG加载检测机制:
				1.检查是否有DOM的ID为 '<prefix>-icons'
				2.不存在，则通过XHR来获取SVG图标，并会生成一个ID为 '<prefix>-icons' 的<div>，追加到<body>

	5>Placeholder(占位符)
		类似<input>和<textarea>的placeholder属性，可以给编辑器添加placeholder。当编辑器内没有内容，则会显示。
		placeholder是根据 '默认皮肤'，通过JS和CSS一起来管理的。当我们创建了自己的皮肤，也同样需要将placeholder的css重新设置
			// 将 trumbowyg 替换为 <prefix>
			.trumbowyg-editor[contenteditable=true]:empty::before{
			    content: attr(placeholder);
			    color: #999;
			}

	6>禁用
		可通过2种方式，来禁用编辑器。
		1)属性
			<textarea id="editor" disabled></textarea>
		2)实例化时，设置配置
			$('#editor').trumbowyg({
				disabled: true,	
			});
		上面描述的都是 "初始化时" 设置！实例化后，还可以通过JS，来 '禁用' 和 '启用' 编辑器
			$('#editor').trumbowyg('enable');
			$('#editor').trumbowyg('disable');


6.基本选项(basic options)
	1>按钮面板
		很简单，几个注意点：
			1)传递一个数组
				btns: [],
			2)数组内，传递的是一个一个的数组，表示一组按钮
				btns: [['bold', 'italic'], ['link']],
		默认的按钮配置：
			$('.simple-editor').trumbowyg({
			    btns: [
			        ['viewHTML'],
			        ['undo', 'redo'], // Only supported in Blink browsers
			        ['formatting'],
			        ['strong', 'em', 'del'],
			        ['superscript', 'subscript'],
			        ['link'],
			        ['insertImage'],
			        ['justifyLeft', 'justifyCenter', 'justifyRight', 'justifyFull'],
			        ['unorderedList', 'orderedList'],
			        ['horizontalRule'],
			        ['removeformat'],
			        ['fullscreen']
			    ],
			});

	2>隐藏按钮文字
		当设置 svgPath 为false时，可以隐藏按钮的文本展示
		1)全局设置
			$.trumbowyg.hideButtonTexts = true;
		2)本地设置
			$('#editor').trumbowyg({
				hideButtonTexts: true,
			});
		注意：
			如果禁用了SVG图标和按钮文字展示，我们需要自己来设计展示

	3>语义化
		生成一个更好的、更面向语义化的HTML标签。(例如：<em>替代<i>, <strong>替代<b>等)。只需要设置为true即可：
			$('#editor').trumbowyg({
				semantic: false,	
			});
		注意：
			1.默认情况下，此选项关闭下划线按钮，因为他们没有任何真正的语义传达。如果你想重新激活下划线按钮，必须明确在按钮面板设置。
			2.默认值为true

	4>重置CSS
		如果你不希望页面样式，影响到编辑器的文本展示，可以设置该选项为true。
			$('#editor').trumbowyg({
				resetCss: true,	
			});
		默认值为false
		CSS重置只应用于编辑器，不会影响到生成的HTML代码

	5>去除黏贴过来的样式
		我们从word或其他网页，可能黏贴过来的内容，包含有其他样式。该选项可以去除标签上的样式。
			$('.trumbowyg').trumbowyg({
			    removeformatPasted: true,
			});
		默认值为false
		如果设置为true，我们需要已经自定义好样式。

	6>编辑内容区自增
		当写一个长内容时，编辑区域自动增长。
			$('.trumbowyg').trumbowyg({
				autogrow: true,
			});
		默认值为false

	7>编辑内容区自增(当获取焦点)
		获取焦点时，编辑区域自增，失去焦点，编辑区域自动减少。
			$('.trumbowyg').trumbowyg({
				autogrowOnEnter: true,
			});
		默认值为false

7.高级选项(advanced options)
	1>添加语言包
		很简单，就是一个javascript对象
			jQuery.trumbowyg.langs.zh_cn = {
				bold: '加粗',
			};

	2>自定义按钮
		trumbowyg默认按钮不足，我们可创建自己的按钮。下面给出了按钮的参数:
			$('.trumbowyg').trumbowyg({

				// 需要扩展的按钮
			    btnsDef: {

			    	// 按钮名
			        buttonName: {
			            fn: 'functionName',
			            tag: 'tagName',
			            title: 'Button tooltip',
			            text: 'Displayed button name',
			            isSupported: function () { return true; },
			            key: 'K',
			            param: '' ,
			            forceCSS: false,
			            class: '',
			            hasIcon: true
			        },

			        // 按钮2
			        ...
			    }
			});

		buttonName，表示按钮，可用在 'btns' 和 'dropdown' 的按钮

			fn - 点击按钮时调用的函数
			tag - 高亮展示的标签名
			title - 鼠标滑动上去显示的文字
			text - 当svgPath设置为false，按钮使用的文字。该文本可通过配置 'hideButtonTexts' 隐藏
			isSupported - 是否自定义的按钮被支持(浏览器兼容性检查、内容检查)
			key - 触发按钮的快捷键
			param - 使用浏览器内置的execCommand
			class - 追加给按钮的类。
					默认值：prefix+按钮名
			hasIcon - 允许强制显示特定按钮的文本
					默认值：false

		示例：
			$('#editor').trumbowyg({
				btnsDef: {
					alert: {
						fn: function(){
							alert('this is alert 弹框！');	
						},
						ico: 'blockquote',
					}	
				},
				btns: [
					[alert],
				],
			});

	3>自定义dropdown
		类似创建按钮，也可以自定义下拉按钮组。
		$('.trumbowyg').trumbowyg({
			btnsDef: {

				// 需要扩展的下拉按钮
				dropdownButtonName: {
					dropdown: ['按钮1', '按钮2', ...],		// 下拉按钮组，包含的按钮
					title: '',
					ico: '下拉按钮组图标',
					hasIcon: true,
				},
			},
		});
		参数：
			dropdown - 包含的按钮，是个数组
			title - 鼠标滑动上去显示的文字
			ico - 图标(默认值：icon-按钮蛇形名字)(蛇形即遇到大写，变小写，添加'-'前缀)
			hasIcon - 允许显示按钮的文本(默认值：true)

		示例：
			$('.trumbowyg').trumbowyg({
			    btnsDef: {

			    	// 文本对齐
			        align: {
			            dropdown: ['justifyLeft', 'justifyCenter', 'justifyRight', 'justifyFull'],
			            ico: 'justifyLeft',
			        }
			    },
			    btns: [
			        ['align']
			    ],
			});


8.API
	1>模态框
		1)打卡&关闭

			// 打卡模态框，并返回该模态框对象，用于之后的 '绑定事件'
			var modal = $('#editor').trumbowyg('openModal', {
				title: '模态框标题',
				content: '模态框内容',			// 支持HTML结构
			});

			// 关闭
			$('#editor').trumbowyg('closeModal');

			注意:
				1.打卡模态框，返回一个包含了模态框的 jquery 对象。接下来绑定事件，我们需要它！
				2.任何时刻，只能打卡一个模态框，如果有模态框被打卡，则再调用 'openModal'，返回 false。

		2)模态框上绑定事件
			modal.on('btwconfirm', function(e){		// 确定事件

				// 发起ajax或表单提交等
				$.ajax();

				// 成功后，关闭模态框
				$('#editor').trumbowyg('closeModal');
			});
			modal.on('btwcancel', function(e){		// 取消事件
				// 关闭模态框
				$('#editor').trumbowyg('closeModal');
			});

		3)仅在模态框中构建输入
			仅需要在模态框中添加输入，更加简单。不需要管理确认和关闭按钮，并且confirm时，获取所有输入值。
			var img = $('#img');
			var modal = $('#editor').trumbowyg('openModalInsert', {
				title: '',
				fields: {
					url: {
						value: img.attr('src'),
					},
					alt: {
						label: 'Alt',
						name: 'alt',
						value: img.attr('alt'),
					},
					example: {

					},
				},	
				callback: function(values){
					img.attr('src', values['url']);
					img.attr('alt', values['alt']);

					// 1.当模态框结束时，返回true
					// 2.如果不返回任何值，需要你手动来关闭模态框
					return true;
				}
			});

			// 当然，也可以自己重新定义 confirm/cancel 事件
			// 注意：openModalInsert的callback()，会被 'btwconfirm' 调用	
			modal.on('btwconfirm', function(e){		// 确定事件

				// 发起ajax或表单提交等
				$.ajax();

				// 成功后，关闭模态框
				$('#editor').trumbowyg('closeModal');
			});
			modal.on('btwcancel', function(e){		// 取消事件
				// 关闭模态框
				$('#editor').trumbowyg('closeModal');
			});

	2>选区
		trumbowyg有一个保存和恢复range选区的系统
		$('#editor').trumbowyg('saveRange');		// 保存当前选区
		$('#editor').trumbowyg('restoreRange');		// 恢复上一个选区
		$('#editor').trumbowyg('getRange');			// 获取最后保存的选区对象
		$('#editor').trumbowyg('getRangeText');		// 获取最后保存的选区文本

	3>管理内容	
		$('#editor').trumbowyg('html');		// 获取编辑器内容
		$('#editor').trumbowyg('html', '<p>您填写您的内容！</p>');		// 设置编辑器内容

	4>清空编辑器内容
		$('#editor').trumbowyg('empty');

	5>启用&禁用编辑器
		$('#editor').trumbowyg('disable');
		$('#editor').trumbowyg('enable');

	6>销毁编辑器
		$('#editor').trumbowyg('destroy');

	7>事件
		类型：
			tbwfocus - 编辑器获取焦点
			tbwblur - 编辑器失去焦点
			tbwinit - 编辑器初始化
			tbwchange - 编辑器内容发生改变
			tbwresize - 编辑区域自动增长，调整尺寸
			tbwpaste - 往编辑器复制内容
			tbwopenfullscreen - 全屏
			tbwclosefullscreen - 取消全屏
			tbwclose - 关闭编辑器

		绑定：
			$('#editor').trumbowyg().on('tbwfocus', function(){
				console.log('获得焦点');	
			});


9.插件
	查看之前讲过的 '插件js加载'，这里介绍下框架内置的几个插件
	1>Base64
		简介：将插入图片，转换为base64编码
		使用：1)引入js	
				<script src="components/trumbowyg-editor/plugins/base64/trumbowyg.base64.min.js"></script>
			 2)添加到按钮中
			 	$('#editor').trumbowyg({
			 		btns: [
			 			['base64'],
			 		],
			 	});

	2>clean paste
		简介：处理粘贴事件，在将粘贴内容插入到编辑器前，进行美化！
		使用：1)引入js	
				<script src="components/trumbowyg-editor/plugins/cleanpaste/trumbowyg.cleanpaste.min.js"></script>
		注意：
			新的trumbowyg实例，可能已经添加了这个功能

	3>colors
		简介：改变文本的前景色和背景色
		使用：1)<head>引入css
				<link rel="stylesheet" href="components/trumbowyg-editor/plugins/colors/ui/trumbowyg.colors.css">
			 2)<body>引入js
				<script src="components/trumbowyg-editor/plugins/colors/trumbowyg.colors.min.js"></script>
			 3)添加到按钮中
			 	$('#editor').trumbowyg({
			 		btns: [
			 			['foreColor', 'backColor'],
			 		],
			 	});

	4>emoji
		简介：支持emoji表情
		使用：1)引入js
				依赖 'emojify.js'，可通过 "npm install emojify.js" 来安装

				// 这里的路径，我们自己来定义(我们可以自己下载一个，放到emoji目录下)
				<script src="components/trumbowyg-editor/plugins/emoji/emojify.min.js"></script>
				<script src="components/trumbowyg-editor/plugins/emoji/trumbowyg.emoji.min.js"></script>
			 2)配置emojify.js
			 	emojify.setConfig({

			 		// emoji的图片所在(也可以下载下来，添加到我们的目录中，不过，可能不能及时获取到最新的图片)
			 		img_dir: '//cdnjs.cloudflare.com/ajax/libs/emojify.js/1.1.0/images/basic/',
			 	});
			 3)添加到按钮中
			 	$('#editor').trumbowyg({
			 		btns: [
			 			['emoji'],
			 		],
			 	});
			 4)运行emojify
			 	emojify.run();

			 	// 每个input输入，内容变化时，都会触发 'emojify.run'，将 ':emoji:' 转换为 emoji 图片
			 	$('#editor').on('input propertychange', function(){
			 		emojify.run();
			 	});

	5>insert audio - 插入音频
		简介：类似插件图片，支持插入音频
		使用：1)引入js	
				<script src="components/trumbowyg-editor/plugins/insertaudio/trumbowyg.insertaudio.min.js"></script>
			 2)添加到按钮中
			 	$('#editor').trumbowyg({
			 		btns: [
			 			['insertaudio'],
			 		],
			 	});

	6>noembed
		简介：允许使用 'noembed.com' 的API，通过一个链接，插入任何内容到编辑器
		使用：1)引入js	
				<script src="components/trumbowyg-editor/plugins/noembed/trumbowyg.noembed.min.js"></script>
			 2)添加到按钮中
			 	$('#editor').trumbowyg({
			 		btns: [
			 			['noembed'],
			 		],
			 	});
		/*
			这个还有点意思，可查看官网了解：
				https://noembed.com/
		 */

	7>paste image
		简介：处理粘贴事件，检查粘贴板中是否有图片，有的话，复制到编辑器内，并转换为base64格式。对文本或html复制，不起作用
		使用：1)引入js	
				<script src="components/trumbowyg-editor/plugins/pasteimage/trumbowyg.pasteimage.min.js"></script>
		注意：
			新的trumbowyg实例，可能已经添加了这个功能

	8>preformatted
		简介：封装代码到<pre>标签，原型输出
		使用：1)引入js	
				<script src="components/trumbowyg-editor/plugins/preformatted/trumbowyg.preformatted.min.js"></script>
			 2)添加到按钮中
			 	$('#editor').trumbowyg({
			 		btns: [
			 			['preformatted'],
			 		],
			 	});

	9>table
		缺少文档

	10>template
		简介：管理一组HTML模板，以快速插入
		使用：1)引入js	
				<script src="components/trumbowyg-editor/plugins/template/trumbowyg.template.min.js"></script>
			 2)添加到按钮中
			 	$('#editor').trumbowyg({
			 		btns: [
			 			['template'],
			 		],
			 	});

	11>upload
		简介：添加一个前端上传，允许用户选择一个图像，查看进度条，然后在编辑器中插入上传的图像	
		使用：1)引入js
				<script src="components/trumbowyg-editor/plugins/upload/trumbowyg.upload.min.js"></script>
			 2)添加到按钮中
			 	$('#editor').trumbowyg({
			 		btns: [
			 			['upload'],
			 		],
			 		plugins: {
			 			upload: {
			 				// 设置上传配置参数	
			 			}
			 		},
			 	});
		参数：
			serverPath - 上传地址
			fileFieldName - 上传文件字段
			data - ajax上传附加的字段
			headers - ajax头部字段
			xhrFields - ajax的xhr字段
			urlPropertyName - json响应中的，上传成功后，图片的字段名。默认值：file。我们可修改为 'url'。响应就需要返回：{success: true, url: '图片地址'}
			statusPropertyName - json响应中，上传状态的字段名。默认值：success。我们可修改为其他。
			success - 成功后回调
				function(data, trumbowyg, $modal, values){

				}
			error - 失败后回调

		服务端：
			1.服务端会接收一个POST请求，上传文件字段-fileFieldName 和 图片描述-alt
				alt: '图片描述',
				fileToUpload: 'input:file - 图片字段'
			2.服务器保存好图片后，必须返回下面响应，才表示成功
				{
					success: true,		// 如果上传失败，必须设置为false
					url: '图片链接',
				}

		/*
			上传就是简单封装了下 $.ajax
		 */

10.创建插件
	1>插件可以是一个按钮，一个粘贴处理或者其他你想要的。如果想添加一个插件，到trumobwyg官方列表，应该遵循下面的目录规则：
		plugins
			myplugin
				ui
					icons
						myplugin.svg
					sass
						trumbowyg.myplugin.scss 		// 会自动生成.css和.min.css
				trumbowyg.myplugin.js

	2>js文件的结构：
		(function ($) {
			'use strict';	
			var defaultOptions = {

			};

			// 如果是个按钮
			function buildButtonDef (trumbowyg) {
				return {
					fn: function() {
					
					}	
				};
			}

			$.extend(true, $.trumbowyg, {

				// 语言包
				langs: {
		            zh_cn: {
		            	myplugin: '我的插件',
		            }
				},

				// 将自定义的插件，注册到 plugins
		        plugins: {
					myplugin: {
						init: function (trumbowyg) {
							trumbowyg.o.plugins.myplugin = $.extend(true, {}, defaultOptions, trumbowyg.o.plugins.myplugin || {});

							// 如果是一个paste处理器，注册
							trumbowyg.pasteHandlers.push(function (pasteEvent) {

							});

							// 如果是一个按钮(注册上面的函数)
							trumbowyg.addBtnDef('myplugin', buildButtonDef(trumbowyg));
						},
						tagHandler: function (element, trumbowyg) {
							return [];
						},
						destroy: function () {

						}
		            }
	            }
			});
		})(jQuery);


这篇博客，总结的几个编辑器还是不错的：
	http://blog.youkuaiyun.com/lensgcx/article/details/54405533