README

Yii2 widget for Summernote - A Super Simple WYSIWYG Editor on Bootstrap.

安装

通过 Composer 安装：

composer require jzkf/yii2-summernote

功能特性

✅ 支持 Bootstrap 5
✅ 中文语言包（默认）
✅ 图片上传功能（支持多图上传）
✅ 表单验证前自动保存内容
✅ 完全可配置的工具栏和选项
✅ 支持 ActiveForm 集成

使用方法

在 ActiveForm 中使用

use jzkf\summernote\widgets\Summernote;

<?= $form->field($model, 'content')->widget(Summernote::class, [
    'clientOptions' => [
        'height' => 300,
        'toolbar' => [
            ['style', ['style']],
            ['font', ['bold', 'italic', 'underline', 'clear']],
            ['fontname', ['fontname']],
            ['fontsize', ['fontsize']],
            ['color', ['color']],
            ['para', ['ul', 'ol', 'paragraph']],
            ['table', ['table']],
            ['insert', ['link', 'picture', 'video']],
            ['view', ['fullscreen', 'codeview', 'help']],
        ],
    ],
]) ?>

独立使用

use jzkf\summernote\widgets\Summernote;

<?= Summernote::widget([
    'name' => 'content',
    'value' => $content,
    'options' => ['id' => 'content-editor'],
    'clientOptions' => [
        'height' => 400,
    ],
]) ?>

配置图片上传

<?= Summernote::widget([
    'model' => $model,
    'attribute' => 'content',
    'uploadUrl' => '/filemanager/editor/summernote-upload',  // 图片上传地址
    'clientOptions' => [
        'height' => 300,
    ],
]) ?>

设置语言

<?= Summernote::widget([
    'model' => $model,
    'attribute' => 'content',
    'language' => 'zh-CN',  // 默认中文，支持所有 Summernote 支持的语言
    'clientOptions' => [
        'height' => 300,
    ],
]) ?>

配置选项

Widget 选项

选项	类型	默认值	说明
`model`	\yii\base\Model	null	模型对象（用于 ActiveForm）
`attribute`	string	null	属性名称（用于 ActiveForm）
`name`	string	null	输入框 name 属性
`value`	string	null	输入框当前值
`options`	array	[]	HTML 输入框选项
`clientOptions`	array	[]	Summernote 客户端配置选项
`uploadUrl`	string	'/filemanager/editor/summernote-upload'	图片上传地址
`language`	string	'zh-CN'	语言代码
`triggerSaveOnBeforeValidateForm`	bool	true	是否在表单验证前自动保存内容

Summernote 客户端选项

常用的 clientOptions 配置：

'clientOptions' => [
    'height' => 300,                    // 编辑器高度
    'lang' => 'zh-CN',                  // 语言
    'toolbar' => [                      // 工具栏配置
        ['style', ['style']],
        ['font', ['bold', 'italic', 'underline', 'clear']],
        ['fontname', ['fontname']],
        ['fontsize', ['fontsize']],
        ['color', ['color']],
        ['para', ['ul', 'ol', 'paragraph']],
        ['table', ['table']],
        ['insert', ['link', 'picture', 'video']],
        ['view', ['fullscreen', 'codeview', 'help']],
    ],
    'placeholder' => '请输入内容...',    // 占位符
    'focus' => true,                     // 自动聚焦
    'dialogsInBody' => true,            // 对话框在 body 中
    'disableDragAndDrop' => false,      // 禁用拖拽
]

更多选项请参考 Summernote 官方文档。

图片上传

Widget 默认支持图片上传功能，支持以下特性：

✅ 多图批量上传
✅ 拖拽上传
✅ 上传进度显示
✅ 错误提示

上传接口要求

上传接口需要返回以下格式之一：

成功时返回图片 URL（字符串）：

"https://example.com/uploads/image.jpg"

成功时返回 JSON 对象：

{
    "url": "https://example.com/uploads/image.jpg"
}

失败时返回错误对象：

{
    "error": "上传失败：文件过大"
}

自定义上传回调

如果需要自定义上传逻辑，可以在 clientOptions 中设置 callbacks.onImageUpload：

'clientOptions' => [
    'callbacks' => [
        'onImageUpload' => new \yii\web\JsExpression("function(files) {
            // 自定义上传逻辑
        }"),
    ],
],

支持的语言

Widget 包含所有 Summernote 支持的语言包，包括：

中文（zh-CN, zh-TW）
英文（en-US）
日文（ja-JP）
韩文（ko-KR）
法文（fr-FR）
德文（de-DE）
西班牙文（es-ES）
俄文（ru-RU）
等等...

默认使用中文（zh-CN），可以通过 language 选项切换。

系统要求

PHP >= 8.1.0
Yii2 >= 2.0.45
Bootstrap 5
jQuery

许可证

BSD-3-Clause

更新日志

v1.0.0 (2025-01-XX)

✅ 初始版本发布
✅ 支持 Bootstrap 5
✅ 支持图片上传（多图）
✅ 中文语言包（默认）
✅ 表单验证前自动保存

jzkf / yii2-summernote

Maintainers

Details