Summernote编辑器默认配置详解：定制初始化参数

原创 于 2025-09-19 07:37:11 发布 · 728 阅读 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。

Summernote编辑器默认配置详解：定制初始化参数

【免费下载链接】summernote Super simple WYSIWYG editor 【免费下载链接】summernote 项目地址: https://gitcode.com/gh_mirrors/su/summernote

引言：为什么需要理解默认配置？

你是否曾在集成Summernote编辑器时遇到工具栏按钮缺失、编辑器高度异常或语言显示错误等问题？这些常见痛点往往源于对初始化参数的理解不足。本文将系统剖析Summernote的默认配置体系，通过20+核心参数解析和15个实用示例，帮助开发者精准定制编辑器行为，实现从"能用"到"好用"的跨越。

读完本文后，你将能够：

  • 掌握90%以上常用配置参数的含义与用法
  • 通过配置组合实现自定义工具栏布局
  • 解决图片上传、链接处理等常见功能需求
  • 优化编辑器性能与用户体验

配置体系概览：参数结构与优先级

Summernote采用层级化配置结构，主要包含核心设置、模块配置和回调函数三大类。配置优先级遵循：用户自定义参数 > 插件默认配置 > 全局默认值。

mermaid

配置加载流程

mermaid

核心配置参数详解

基础显示设置

参数名类型默认值说明
widthnumber/stringnull编辑器宽度，支持像素值(如500)或百分比(如'100%')
heightnumber/stringnull编辑器高度，仅支持像素值
focusbooleanfalse初始化后是否自动获取焦点
placeholderstringnull编辑器为空时显示的提示文本
airModebooleanfalse是否启用空气模式(内联编辑)
followingToolbarbooleanfalse滚动时工具栏是否跟随

示例：基础尺寸与焦点配置

$('.summernote').summernote({
  width: 800,        // 固定宽度800px
  height: 400,       // 固定高度400px
  focus: true,       // 初始化后自动聚焦
  placeholder: '请输入内容...',  // 空状态提示文本
  toolbarPosition: 'top'  // 工具栏位置(top/bottom)
});

交互行为设置

参数名类型默认值说明
tabSizenumber4Tab键缩进字符数
tabDisablebooleanfalse是否禁用Tab键
shortcutsbooleantrue是否启用键盘快捷键
spellCheckbooleantrue是否启用拼写检查
maxTextLengthnumber0最大文本长度限制(0为无限制)
historyLimitnumber200历史记录最大条数

示例：交互体验优化配置

$('.summernote').summernote({
  tabSize: 2,            // Tab缩进为2个空格
  shortcuts: false,      // 禁用所有快捷键
  maxTextLength: 5000,   // 限制最大输入5000字符
  historyLimit: 100,     // 历史记录保留100步
  recordEveryKeystroke: true  // 记录每一次按键
});

工具栏与按钮配置

默认工具栏结构：

toolbar: [
  ['style', ['style']],
  ['font', ['bold', 'underline', 'clear']],
  ['fontname', ['fontname']],
  ['color', ['color']],
  ['para', ['ul', 'ol', 'paragraph']],
  ['table', ['table']],
  ['insert', ['link', 'picture', 'video']],
  ['view', ['fullscreen', 'codeview', 'help']],
]

自定义工具栏示例：精简版配置

$('.summernote').summernote({
  toolbar: [
    // 仅保留格式化和基本编辑工具
    ['font', ['bold', 'italic', 'underline']],
    ['para', ['ul', 'ol']],
    ['insert', ['link', 'picture']],
    ['view', ['codeview']]
  ]
});

按钮组自定义：

$('.summernote').summernote({
  buttons: {
    // 重定义图片按钮
    picture: function(context) {
      var ui = $.summernote.ui;
      var button = ui.button({
        contents: '<i class="note-icon-picture"/>',
        tooltip: '插入图片',
        click: function() {
          // 自定义图片上传逻辑
          $('#myImageModal').modal('show');
        }
      });
      return button.render();
    }
  }
});

语言与本地化

参数名类型默认值说明
langstring'en-US'界面语言，需引入对应语言包
localeobjectnull自定义本地化文本

示例：配置中文界面

<!-- 引入中文语言包 -->
<script src="https://cdn.bootcdn.net/ajax/libs/summernote/0.8.18/lang/summernote-zh-CN.min.js"></script>

<script>
$('.summernote').summernote({
  lang: 'zh-CN'  // 使用中文界面
});
</script>

高级功能配置

图片与链接处理

参数名类型默认值说明
linkTargetBlankbooleantrue链接是否在新窗口打开
maximumImageFileSizenumbernull图片最大尺寸限制(字节)
allowClipboardImagePastingbooleantrue是否允许剪贴板粘贴图片
linkAddNoReferrerbooleanfalse链接是否添加rel="noreferrer"

示例：图片上传与链接安全配置

$('.summernote').summernote({
  linkTargetBlank: true,  // 链接在新窗口打开
  linkAddNoReferrer: true, // 添加noreferrer属性
  maximumImageFileSize: 5242880, // 限制图片最大5MB
  callbacks: {
    onImageUpload: function(files) {
      // 自定义图片上传逻辑
      var formData = new FormData();
      formData.append('file', files[0]);
      
      $.ajax({
        url: '/upload',
        method: 'POST',
        data: formData,
        processData: false,
        contentType: false,
        success: function(url) {
          $(this).summernote('insertImage', url);
        }
      });
    }
  }
});

代码视图与格式化

参数名类型默认值说明
styleWithCSSbooleanfalse是否使用CSS而非HTML标签格式化
codeviewFilterbooleantrue代码视图是否过滤危险标签
codemirrorobject见下文代码视图配置

默认代码视图配置：

codemirror: {
  mode: 'text/html',
  htmlMode: true,
  lineNumbers: true
}

示例：增强代码编辑体验

$('.summernote').summernote({
  codeviewFilter: false,  // 关闭HTML过滤
  styleWithCSS: true,     // 使用CSS样式
  codemirror: {
    lineNumbers: true,    // 显示行号
    theme: 'monokai',     // 使用Monokai主题
    indentUnit: 2,        // 缩进单位2空格
    tabSize: 2            // Tab键对应2空格
  }
});

弹出菜单(Popover)配置

Summernote使用弹出菜单处理图片、链接和表格等元素的操作。默认包含三类弹出菜单：

图片弹出菜单

popover: {
  image: [
    ['resize', ['resizeFull', 'resizeHalf', 'resizeQuarter', 'resizeNone']],
    ['float', ['floatLeft', 'floatRight', 'floatNone']],
    ['remove', ['removeMedia']],
  ]
}

表格弹出菜单

popover: {
  table: [
    ['add', ['addRowDown', 'addRowUp', 'addColLeft', 'addColRight']],
    ['delete', ['deleteRow', 'deleteCol', 'deleteTable']],
  ]
}

自定义表格弹出菜单示例：

$('.summernote').summernote({
  popover: {
    table: [
      ['add', ['addRowDown', 'addRowUp']],  // 仅保留添加行功能
      ['delete', ['deleteRow']],           // 仅保留删除行功能
      ['custom', ['myCustomTableFunction']] // 自定义功能
    ]
  }
});

回调函数应用

常用事件回调

函数名参数说明
onInitsummernote编辑器初始化完成时触发
onChangecontents内容变化时触发
onFocuse获取焦点时触发
onBlure失去焦点时触发
onImageUploadfiles图片上传时触发
onEntere按下Enter键时触发

示例：内容自动保存

$('.summernote').summernote({
  callbacks: {
    onInit: function() {
      console.log('Summernote初始化完成');
    },
    onChange: function(contents) {
      // 内容变化时保存到localStorage
      localStorage.setItem('editorContent', contents);
    },
    onImageUpload: function(files) {
      // 图片上传处理
      uploadImage(files[0]);
    }
  }
});

// 页面加载时恢复内容
$(document).ready(function() {
  var savedContent = localStorage.getItem('editorContent');
  if (savedContent) {
    $('.summernote').summernote('code', savedContent);
  }
});

实用配置组合示例

1. 极简编辑器配置

$('.summernote').summernote({
  toolbar: [
    ['style', ['bold', 'italic', 'underline']],
    ['para', ['ul', 'ol']]
  ],
  height: 200,
  placeholder: '输入简单文本...',
  shortcuts: false,
  disableDragAndDrop: true
});

2. 富媒体编辑器配置

$('.summernote').summernote({
  height: 500,
  focus: true,
  toolbar: [
    ['style', ['style', 'fontname', 'fontsize']],
    ['font', ['bold', 'italic', 'underline', 'strikethrough']],
    ['color', ['forecolor', 'backcolor']],
    ['para', ['ul', 'ol', 'paragraph', 'height']],
    ['insert', ['link', 'picture', 'video', 'table']],
    ['view', ['fullscreen', 'codeview']]
  ],
  popover: {
    image: [
      ['resize', ['resizeFull', 'resizeHalf', 'resizeQuarter']],
      ['float', ['floatLeft', 'floatRight', 'floatNone']]
    ]
  },
  maximumImageFileSize: 5242880, // 5MB
  callbacks: {
    onImageUpload: handleImageUpload
  }
});

3. 空气模式(内联编辑)配置

$('.summernote').summernote({
  airMode: true,
  placeholder: '点击此处编辑...',
  popover: {
    air: [
      ['font', ['bold', 'italic', 'underline']],
      ['para', ['ul', 'ol', 'paragraph']],
      ['insert', ['link', 'picture']]
    ]
  }
});

常见问题解决方案

1. 工具栏按钮不显示

可能原因：

  • 工具栏配置有误
  • 语言包未正确加载
  • 容器尺寸过小导致按钮被隐藏

解决方案：

// 简化工具栏配置
$('.summernote').summernote({
  toolbar: [
    ['basic', ['bold', 'italic', 'underline']] // 仅保留基础按钮
  ]
});

2. 图片上传失败

可能原因：

  • 未配置正确的上传回调
  • 服务器端限制了文件大小
  • 跨域问题导致请求失败

解决方案：

$('.summernote').summernote({
  callbacks: {
    onImageUpload: function(files) {
      var formData = new FormData();
      formData.append('file', files[0]);
      
      $.ajax({
        url: '/upload',
        type: 'POST',
        data: formData,
        processData: false,
        contentType: false,
        success: function(response) {
          $(this).summernote('insertImage', response.url);
        },
        error: function() {
          alert('图片上传失败，请重试');
        }
      });
    }
  }
});

3. 编辑器高度自适应

Summernote本身不支持高度自适应，但可通过回调实现：

$('.summernote').summernote({
  callbacks: {
    onChange: function() {
      // 内容变化时调整高度
      var height = $(this).summernote('code').length * 10;
      $(this).summernote('height', Math.max(200, height));
    }
  }
});

配置优化最佳实践

性能优化配置

$('.summernote').summernote({
  shortcuts: false,        // 禁用快捷键
  spellCheck: false,       // 禁用拼写检查
  historyLimit: 50,        // 减少历史记录数量
  textareaAutoSync: false  // 禁用与textarea的自动同步
});

移动端适配配置

$('.summernote').summernote({
  height: 300,             // 减小高度
  toolbar: [
    ['mobile', ['bold', 'italic', 'link', 'picture']] // 精简工具栏
  ],
  popover: {
    image: [['resize', ['resizeHalf']]] // 简化图片操作
  }
});

总结与扩展

Summernote的配置系统提供了丰富的定制选项，通过合理组合这些参数，可以打造出既美观又实用的富文本编辑体验。本文介绍的20+核心参数覆盖了90%的使用场景，掌握这些配置将帮助你应对大多数开发需求。

进阶学习路径：

  1. 深入研究各模块的具体实现
  2. 开发自定义插件扩展功能
  3. 优化编辑器性能与加载速度

记住，最佳配置不是一成不变的，需要根据具体项目需求进行调整。建议从基础配置开始，逐步添加高级功能，避免过度配置导致的性能问题。

【免费下载链接】summernote Super simple WYSIWYG editor 【免费下载链接】summernote 项目地址: https://gitcode.com/gh_mirrors/su/summernote

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值