summernote富文字編輯器的基本使用
基礎API
初始化 summernote
$('#summernote').summernote();
初始化並配置summernote
高度和焦點設定
如果對summernote設定了focus項,在編輯器初始化之後會自動獲取焦點。
$('#summernote').summernote({ height: 300, // set editor height minHeight:null, // set minimum heightof editor maxHeight:null, // set maximum heightof editor focus: true // set focus to editable areaafter initializing summernote });
對高度進行設定後,如果內容超過編輯器高度會出現滾動條。否則,編輯器高度會隨內容高度變化而變化。
編輯器的銷燬(destroy)
銷燬summernote
$('#summernote').summernote('destroy');
獲取&設定HTML內容(get&set)
獲取編輯器內的HTML內容
var markupStr = $('#summernote').summernote('code');
如果初始化了多個編輯器,可以通過jquery的eq方法獲取某個編輯器的HTML內容。eg,獲取第二個編輯器的。
var markupStr = $('.summernote').eq(1).summernote('code');
給指定的編輯器設定HTML內容
var markupStr = 'hello world';
$('#summernote').summernote('code', markupStr);
國際化支援
語言
引入需要支援的語言庫。eg. summernote-ko-KR.js
<linkhref="http://netdna.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.css"rel="stylesheet"> <scriptsrc="http://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.4/jquery.js"></script> <scriptsrc="http://netdna.bootstrapcdn.com/bootstrap/3.3.5/js/bootstrap.js"></script> <link href="summernote.css"rel="stylesheet"> <script src="summernote.min.js"></script> <!-- include summernote-ko-KR --> <scriptsrc="lang/summernote-ko-KR.js"></script> 通過本地配置執行引入的指令碼 $(document).ready(function() { $('#summernote').summernote({ lang: 'ko-KR' // default: 'en-US' }); });
初始化配置
通過配置option和元件來自定義編輯器
自定義工具欄,彈出框
summernote允許自定義工具欄`
$('#summernote').summernote({
toolbar: [
// [groupName, [list of button]]
['style', ['bold', 'italic', 'underline', 'clear']],
['font', ['strikethrough', 'superscript', 'subscript']],
['fontsize', ['fontsize']],
['color', ['color']],
['para', ['ul', 'ol', 'paragraph']],
['height', ['height']]
]
});
你也可以使用外掛中已經預先定義好的工具欄。
你可以使用popover.air項來自定義極簡模式的彈出框而不是工具欄。
$('#summernote').summernote({
popover: {
air: [
['color', ['color']],
['font', ['bold', 'underline', 'clear']]
]
}
});
同樣也可以配置其他彈出框的按鈕。
自定義placeholder
$('#summernote').summernote({
placeholder: 'write here...'
});
自定義字型
$('#summernote').summernote({
fontNames: ['Arial', 'Arial Black', 'Comic Sans MS', 'Courier New']
});
summernote在把配置項中的字型新增到字型下拉框之前會先進行字型檢測,因此當我們使用網路字型時會遇到問題。可以在fontNamesIgnoreCheck配置項中定義網路字型的列表來使編輯器忽略對網路字型的檢測。
Dialogs
對話方塊不止可以放置在編輯器內,也可以被置於body中。
$('#summernote').summernote({
dialogsInBody: true
});
Dialogs預設是沒有淡入淡出效果的,可以使用dialogsFade配置
$('#summernote').summernote({
dialogsFade: true // Add fade effect on dialogs
});
禁止拖放
可以使用disableDragAndDrop禁止拖放
$('#summernote').summernote({
disableDragAndDrop: true
});
禁止使用快捷鍵
$('#summernote').summernote({
shortcuts: false
});
基礎API(editor模組)
使用summernote初始化編輯器
$('#summernote').summernote();
然後可以使用summernote呼叫編輯器提供的API。下面是一個插入文字的示例程式碼。
$('#summernote').summernote('editor.insertText', 'hello world'));
它呼叫了editor模組的‘insertText’函式,第一個引數是代表模組及其方法的字串,其餘的是需要傳入方法的引數。
第一個引數沒有模組名的情況下,會預設為editor。
$('#summernote').summernote('insertText', 'hello world');
editor模組中支援以下方法
createRange
為使用者當前選中的內容建立一個範圍物件。
var range = $('#summernote').summernote('createRange');
saveRange, restoreRange
儲存當前使用者選中的內容
$('#summernote').summernote('saveRange');
重新儲存選中的區域
$('#summernote').summernote('saveRange');
// move cursor and select another
$('#summernote').summernote('restoreRange');
undo, redo
撤銷和恢復最後一個命令
$('#summernote').summernote('undo');
$('#summernote').summernote('redo');
focus
為編輯器設定焦點
$('#summernote').summernote('focus');
isEmpty
返回編輯器中內容是否為空
編輯區域獲取焦點時會自動生成
,即使並沒有實際內容。所以summernote提供了這個方法來判斷內容是否真的為空。
if ($('#summernote').summernote('isEmpty')) {
alert('contents is empty');
}
reset(重置)
清除內容和儲存記錄
$('#summernote').summernote('reset');
disable, enable
disable使編輯器處於不可用狀態。
$('#summernote').summernote('disable');
呼叫enable可以使編輯器從不可以轉換到可用狀態。
$('#summernote').summernote('enable');
字型樣式API
bold, italic, underline, strikethrough
設定編輯器所有內容的字型樣式。
$('#summernote').summernote('bold');//加粗
$('#summernote').summernote('italic');//斜體
$('#summernote').summernote('underline');//下劃線
$('#summernote').summernote('strikethrough');//刪除線
superscript, subscript(上角標,下角標)
$('#summernote').summernote('superscript');
$('#summernote').summernote('subscript');
removeFormat(清除樣式)
$('#summernote').summernote('removeFormat');
backColor, foreColor(背景色,前景色)
// @param {String} color
$('#summernote').summernote('backColor', 'red');
// @param {String} color
$('#summernote').summernote('foreColor', 'blue');
fontName(字型)
// @param {String} fontName
$('#summernote').summernote('fontName', 'Arial');
fontSize(字型大小)
// @param {Number} font size - unit is px
$('#summernote').summernote('fontSize', 20);
Paragraph API
justify left, right and more
設定段落居中樣式
$('#summernote').summernote('justifyLeft');
$('#summernote').summernote('justifyRight');
$('#summernote').summernote('justifyCenter');
$('#summernote').summernote('justifyFull');
insertParagraph(插入段落)
$('#summernote').summernote('insertParagraph');
insertOrderedList(插入列表)
$('#summernote').summernote('insertOrderedList');
$('#summernote').summernote('insertUnorderedList');
indent and outdent(縮排和凸排)
$('#summernote').summernote('indent');
$('#summernote').summernote('outdent');
formatPara
將編輯器內容格式化為段落
$('#summernote').summernote('formatPara');
formatH1-H6
$('#summernote').summernote('formatH2');
$('#summernote').summernote('formatH6');
lineHeight(設定行高)
// @param {Number} line height - unit is px
$('#summernote').summernote('lineHeight', 20);
Insertion API
insertImage(插入圖片)
// @param {String} url
// @param {String|Function} filename - optional
$('#summernote').summernote('insertImage', url, filename);
你也可以把第二個引數設定為回撥函式來對上傳的圖片進行修改
$('#summernote').summernote('insertImage', url, function ($image){
$image.css('width', $image.width() / 3);
$image.attr('data-filename', 'retriever');
});
insertNode
插入元素和文字節點
var node =document.createElement('div');
// @param {Node} node
$('#summernote').summernote('insertNode', node);
insertText(插入文字)
// @param {String} text
$('#summernote').summernote('insertText', 'Hello, world');
createLink, unlink(建立、取消連結)
// @param {String} text - link text
// @param {String} url - link url
// @param {Boolean} newWindow - whether link's target isnew window or not
$('#summernote').summernote('createLink', {
text: 'This is the Summernote's Official Site',
url: 'http://summernote.org',
newWindow: true
});
$('#summernote').summernote('unlink');
Callbacks
summernote支援初始化回撥函式和jquery自定義事件的回撥函式 在V0.7.0之後的版本中callback選項配置的位置變化了。
在V0.7.0之後的版本中callback應該被callbacks物件包裹。
在V0.6.5之後的版本中事件的回撥函式鍵值必須使用駝峰命名法。
在V0.6.5之前的版本中基本的事件命名(比如:oninit,onenter,onfocus,onblur,onkeyup,onkeydown,onpaste)都是使用小寫字串,但是在Callbacks中的對高階特性的事件回撥函式命名使用駝峰命名法,這樣就造成了命名不一致,更加混亂。所以我們把所有的小寫的callback改成了駝峰命名法。
onInit
// onInit callback
$('#summernote').summernote({
callbacks: {
onInit: function() {
console.log('Summernote is launched');
}
}
});
// summernote.init
$('#summernote').on('summernote.init', function() {
console.log('Summernote is launched');
});
onEnter
// onEnter callback
$('#summernote').summernote({
callbacks: {
onEnter: function() {
console.log('Enter/Return key pressed');
}
}
});
// summernote.enter
$('#summernote').on('summernote.enter', function() {
console.log('Enter/Return key pressed');
});
onFocus, onBlur
// onFocus callback
$('#summernote').summernote({
callbacks: {
onFocus: function() {
console.log('Editable area is focused');
}
}
});
// summernote.focus
$('#summernote').on('summernote.focus', function() {
console.log('Editable area is focused');
});
onKeyup, onKeydown
// onKeyup callback
$('#summernote').summernote({
callbacks: {
onKeyup: function(e) {
console.log('Key is released:', e.keyCode);
}
}
});
// summernote.keyup
$('#summernote').on('summernote.keyup', function(we, e) {
console.log('Key is released:', e.keyCode);
});
// onKeydown callback
$('#summernote').summernote({
callbacks: {
onKeydown: function(e) {
console.log('Key is downed:', e.keyCode);
}
}
});
// summernote.keydown
$('#summernote').on('summernote.keydown', function(we, e) {
console.log('Key is downed:', e.keyCode);
});
onPaste
// onPaste callback
$('#summernote').summernote({
callbacks: {
onPaste: function(e) {
console.log('Called event paste');
}
}
});
// summernote.paste
$('#summernote').on('summernote.paste', function(e) {
console.log('Called event paste');
});
onImageUpload
重寫圖片上傳方法
// onImageUpload callback
$('#summernote').summernote({
callbacks: {
onImageUpload: function(files) {
// uploadimage to server and create imgNode...
$summernote.summernote('insertNode', imgNode);
}
}
});
// summernote.image.upload
$('#summernote').on('summernote.image.upload', function(we,files) {
// upload image to server andcreate imgNode...
$summernote.summernote('insertNode', imgNode);
});
onChange
// onChange callback
$('#summernote').summernote({
callbacks: {
onChange: function(contents, $editable) {
console.log('onChange:', contents,$editable);
}
}
});
// summernote.change
$('#summernote').on('summernote.change', function(we,contents, $editable) {
console.log('summernote\'s content ischanged.');
});
Custom button(自定義按鈕)
summernote也支援自定義按鈕。如果你想要建立你自己的按鈕,可以定義新按鈕並在options中配置它。
定義按鈕
使用$.summernote.ui建立button物件,按鈕具有以下屬性:
- contents:在按鈕中顯示的內容
- tooltip:滑鼠懸浮時的提示文字
- click:按鈕被點選時的回撥函式
下面是一個插入“hello”按鈕的示例程式碼
var HelloButton = function (context) {
var ui = $.summernote.ui;
// create button
var button = ui.button({
contents: '<i class="fa fa-child"/> Hello',
tooltip: 'hello',
click: function () {
// invokeinsertText method with 'hello' on editor module.
context.invoke('editor.insertText', 'hello');
}
});
return button.render(); // return button as jquery object
}
將按鈕作為jquery物件返回renderr()
Using button with options(在配置項中使用按鈕)
在工具欄中使用button。首先,定義一個鍵為buttons的button物件,然後在工具欄中定義定製的按鈕
$('.summernote').summernote({
toolbar: [
['mybutton', ['hello']]
],
buttons: {
hello: HelloButton
}
});
同樣也可以在POPover中使用自定義按鈕
模組化
summernote通過模組化支援功能的擴充套件。這種模組體系的建立受益於spring框架的啟發。
關鍵術語
- Module:模組
- Context:Context包含modules和editor’s 宣告的容器
- Renderer:Renderer是用來建立元素的方法
- UI:UI是用來新建ui元素的渲染函式
Module
Module是用來擴充套件功能的元件,具有生命週期,也有輔助函式和依賴於生命週期的函式
initialize
通過$(‘..’).summernote()進行初始化的時候會呼叫這個函式,可以用來在editor中繫結事件和建立元素
this.initialize = function () {
// create button
var button = ui.button({
className: 'note-btn-bold',
contents: '<i class="fa fa-bold">'
click: function (e) {
context.invoke('editor.bold'); // 呼叫editor中的bold方法
}
});
// button.render()返回button生成的jquery物件
this.$button = button.render();
$toolbar.append(this.$button);
}
destroy
當$(‘..’).summernote(‘destroy’)的時候呼叫這個方法,移除initlize即初始化時建立的元素,並解綁事件
this.destroy = function () {
this.$button.remove();
this.$button = null;
}
shouldInitialize
這個方法來決定模組是否會被初始化/
/ AirPopover's shouldInitialize
this.shouldInitialize = function () {
return options.airMode && !list.isEmpty(options.popover.air);
};
下面是AutoLink 模組的完整程式碼
// Module Name is AutoLink
// @param {Object} context - states of editor
var AutoLink = function (context) {
// you can get current editor's elements from layoutInfo
var layoutInfo = context.layoutInfo;
var $editor = layoutInfo.editor;
var $editable = layoutInfo.editable;
var $toolbar = layoutInfo.toolbar;
// ui is a set of renderers to build ui elements.
var ui = $.summernote.ui;
// this method will be called when editor is initialized by $('..').summernote();
// You can attach events and created elements on editor elements(eg, editable, ...).
this.initialize = function () {
// create button
var button = ui.button({
className: 'note-btn-bold',
contents: '<i class="fa fa-bold">'
click: function (e) {
// invoke bold method of a module named editor
context.invoke('editor.bold');
}
});
// generate jQuery element from button instance.
this.$button = button.render();
$toolbar.append(this.$button);
}
// this method will be called when editor is destroyed by $('..').summernote('destroy');
// You should detach events and remove elements on `initialize`.
this.destroy = function () {
this.$button.remove();
this.$button = null;
}
};
配置模組
可以通過option自定義模組
$(".summernote").summernote({
modules: {
myModule: MyModule
}
});
可以通過暴露的API來呼叫自定義模組中的方法
$(".summernote").summernote("myModule.method", 'hello');
Plugin
可以以外掛形式來自定義模組
// src/mymodule.js
$.extend($.summernote.plugins, {
myModule: function (context) {
// define module
...
}
});