quansitech / cmf-module-rich-content
CMF 富文本扩展:中文 TinyMCE 编辑器、粘贴清理、HTML 白名单清洗、公众号文章抓取、远程图片本地化到 cmf-media。
Package info
github.com/quansitech/cmf-module-rich-content
pkg:composer/quansitech/cmf-module-rich-content
Requires
- php: ^8.3
- ext-curl: *
- ext-dom: *
- ext-fileinfo: *
- amidesfahani/filament-tinyeditor: ^5.0
- filament/filament: ^5.0
- illuminate/database: ^11.0 || ^12.0 || ^13.0
- illuminate/http: ^11.0 || ^12.0 || ^13.0
- illuminate/support: ^11.0 || ^12.0 || ^13.0
- livewire/livewire: ^4.0
- quansitech/cmf-module-media: ^1.6
- tinymce/tinymce: ^8.0
Requires (Dev)
- phpunit/phpunit: ^12.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-18 07:50:59 UTC
README
QS CMF 的 TinyMCE 富文本模块,支持格式化粘贴、cmf-media 图片/视频上传、公众号可编辑正文导入、内联 SVG 动画与图片/卡片尺寸调整。
安装
在已初始化的 Filament 5 / QS CMF 项目中(PHP 8.3+、Livewire 4):
composer require quansitech/cmf-module-rich-content php artisan cmf:rich-content:install
Composer 自动发现 Provider;安装命令同时发布 TinyMCE、语言包、富文本资源和 Filament(含媒体指纹脚本)资源。升级部署时复跑同一条命令。不需要 npm 构建、发布配置、手工注册 Provider 或设置 dont-discover;从之前项目内版本升级时,请移除旧的 TinyEditor dont-discover 条目。
依赖的 cmf-media 需完成标准安装和迁移,编辑用户需有媒体创建权限。默认使用媒体模块配置的存储驱动;云存储直传需给存储桶配置后台来源的 CORS。CORS/网络阻断时会尝试同源中转,受 PHP 和反向代理上传上限约束。
在表单和模型中接入
use Quansitech\Cmf\RichContent\Support\RichText; RichText::editor('content')->label('正文')->columnSpanFull();
让正文宿主模型 implements Filament\Forms\Components\RichEditor\Models\Contracts\HasRichContent,并同时使用 Quansitech\Cmf\Media\Concerns\HasMedia 和 Quansitech\Cmf\RichContent\Concerns\HasLocalizedRichContent。默认处理 content 字段;配置模型的 $mediaRichContentAttributes 可指定其他字段。保存时清洗 HTML;仅当前操作者有媒体创建权限时尝试转存远程或内联图片,无权限时仍可正常保存清洗后的正文。保存后同步媒体引用,避免正文图片和视频被当作孤立媒体清理。
若旧正文仍用 data-id,且曾变更 CDN 域名或媒体路径前缀,可按当前驱动配置可信旧媒体根,例如 cmf-rich-content.legacy_media_roots = ['local' => ['/cmf-media', 'https://old-cdn.example.com/media']]。仅改标题或不改变该媒体的旧节点集合时,已有旧引用无需配置即可保留;如果同号节点混用、编辑时改变了这组节点,则通过旧根与完整对象路径确认保留哪个引用。请在此类编辑前配置旧根;根相对旧地址(如默认本地盘的 /cmf-media/...)和绝对旧地址须按正文里实际保存的形式分别配置。旧根不用于建立新引用。
若旧 COS CDN 剥掉了对象目录,请在对应旧根记录当时的 path_prefix,无需修改当前 CDN 配置:
'legacy_media_roots' => [ 'cos' => [ ['url' => 'https://old-cdn.example.com', 'path_prefix' => 't4tstudio'], ], ],
例如对象 key t4tstudio/image/ab/photo.png 只匹配该旧根下的 /image/ab/photo.png;未配置前缀的字符串旧根仍按完整对象 key 匹配。若旧地址使用腾讯云 CDN Type B/C 路径鉴权,请在该旧根额外指定 'auth_type' => 'type_b' 或 'auth_type' => 'type_c'。匹配仅识别相应的历史鉴权路径格式,不需要旧密钥,也不会建立新的引用。
前台可直接使用 Blade 组件,它会清洗正文、刷新媒体 URL 并加载画面限宽及 SVG 动画所需资源:
<x-cmf-rich-content::body :html="$article->content" />
已有自己的渲染层,也可以调用 MediaUrlResolver::resolve() 刷新受时效限制的媒体地址。
默认行为和按需定制
- 图片上传成功直接插入正文;视频对话框提供「上传 / 嵌入」,默认选择上传。已有图文格式与编辑器空行保留。
- 公众号导入只提取可编辑正文,不嵌入整篇网页;白名单图片转存 cmf-media。常见公众号 SVG 动画卡片支持导入、播放和缩放,不保证兼容所有第三方动画。
- 自动注册
cmf-rich-image(默认上限 10 MiB)和cmf-rich-video(默认上限 500 MiB)上传规则,不覆盖同名规则,不放宽媒体库全局 MIME 或体积限制。 - 登录、媒体创建权限、限流、远程图片域名与公网地址校验、HTML/iframe/SVG 白名单继续生效。配置
cmf-rich-content可按需收紧;仅定制时执行php artisan vendor:publish --tag=cmf-rich-content-config。
包内测试
cd rich-content
composer install
vendor/bin/phpunit