Open edX Platform 中的 TinyMCE 富文本编辑器:从内置集成到自定义插件扩展

原创2026-09-15 12:25:331,813 阅读
文章标签:教育后端前端CMS认证鉴权企业应用

Open edX Platform 中的 TinyMCE 富文本编辑器:从内置集成到自定义插件扩展

TinyMCE 是 Open edX 平台内置的所见即所得(WYSIWYG)富文本编辑器,承担着 Studio 课程创作中 HTML 组件、文本内容编辑等核心场景的编辑能力。本文以平台实际打包的 TinyMCE 发行版与其构建、配置、集成源码为依据,系统梳理 TinyMCE 在 edx-platform 中的定位、功能特性、定制化构建流程、iframe 集成细节,以及通过配置变量扩展自定义插件的完整实操路径。

TinyMCE 是什么:平台的 WYSIWYG 内容编辑内核

TinyMCE 是当前最流行的开源 Web 所见即所得(WYSIWYG)编辑器,被广泛集成进内容管理系统(CMS)、学习管理系统(LMS)、客户关系管理(CRM)与营销自动化系统、邮件营销系统以及各类 SaaS 应用的内容创作流程中。在 Open edX 生态里,它是平台默认使用的可视化文本/HTML 编辑器:课程作者在 Studio 中编辑 HTML 组件、富文本内容时,看到的即是一个 TinyMCE 实例,输入的内容最终以 HTML 形式存入课程结构。

在 edx-platform 仓库中,TinyMCE 以第三方 vendor 形式完整内置在 common/static/js/vendor/tinymce/js/tinymce 目录下,包含:

  • tinymce.min.js:核心编辑器主体;
  • tinymce.full.min.js:打包了全部本地插件的完整发行包;
  • jquery.tinymce.min.js:jQuery 集成封装;
  • langs/:多语言包;
  • skins/ui/studio-tmce5/:专门为 Studio 定制的皮肤(skin)与内容样式;
  • plugins/:40+ 内置插件(advlist、anchor、autolink、autoresize、autosave、code、codesample、fullscreen、image、imagetools、link、lists、media、paste、table、template 等)。

平台对 TinyMCE 的功能诉求,可以用其官方 README 的一句话概括:内容具有强大的力量——更多在线应用正在为人们提供受益于内容变革力量的平台,而 TinyMCE 让应用可以轻松集成编辑器,为用户提供最佳的内容创作体验。这一理念在 Open edX 中具体化为"让课程作者以所见即所得的方式创作教学内容"。

三种编辑模式:理解 TinyMCE 的能力模型

TinyMCE 提供三种编辑模式,这也是集成方需要首先做出的技术选型:

  • Classic(经典)模式:编辑器以 iframe 承载,工具栏与编辑区分离,内容最终写回隐藏的 <textarea>。Open edX Studio 采用的就是这种模式——HTML 组件的文本编辑在 iframe 内进行,因此平台在 iframe 处理上做了专门的兼容处理(下文详述)。
  • Inline(行内)模式:直接在页面元素上就地编辑,无 iframe,适合富文本字段就地输入场景。
  • Distraction-free(沉浸无干扰)模式:inline 模式的增强版,输入时隐藏工具栏等干扰元素,聚焦于内容本身。

对 edx-platform 而言,classic 模式的 iframe 载体直接影响了平台的集成代码。在 cms/static/js/utils/handle_iframe_binding.js 的注释中明确写道:"TinyMCE editor is hosted in an iframe, and before the iframe is removed we execute this code",平台因此实现了专门的 iframe/embed 标签处理逻辑:

// TinyMCE 的 iframe src 会被设置为 'javascript:""',
// 在移除 iframe 前必须跳过这种特殊值,避免抛错
else if (ifr_source.lastIndexOf('javascript:', 0) !== 0) {
    $(this).attr('src', ifr_source + '?' + wmode);
}

该工具还提供 iframeBindingHtml 方法,用于在 HTML 字符串渲染前,为其中所有 <iframe> 追加 wmode=transparent 查询参数、为 <embed> 追加 wmode="transparent" 属性,从而解决 Flash/视频弹层遮挡编辑器弹出层(z-index)的问题——这正是平台将编辑器与外部媒体内容共存的工程细节。

平台内的定制化构建:从上游发行版到 Studio 专用 bundle

TinyMCE 并非以开箱即用的官方包直接被使用。仓库中 common/static/js/vendor/tinymce/BUILD_README.md 记录了 Open edX 维护者如何将上游 TinyMCE 定制为平台内置发行版,这套流程也是任何想要升级或深度定制编辑器版本的技术团队应遵循的步骤。

版本升级流程

  1. 从 TinyMCE 官方 tags 下载目标版本;
  2. 若为主版本升级(major update),遵循官方迁移文档并同步更新 edx-platform 的调用代码;
  3. 按下文说明配置 codemirror 插件;
  4. 在 vendor/js/tinymce 目录下搜索字符串 "EDX",找出当前版本中所有 Open edX 特定修改;
  5. 将 EDX 特定修改合并到新下载的版本中;
  6. 重新生成 js/tinymce.full.min.js。

codemirror 插件集成

TinyMCE 内置的 code 插件负责 HTML 源码视图,而 Open edX 在此基础上进一步集成了 tinymce-codemirror 插件(仓库内位于 common/static/js/vendor/tinymce/js/tinymce/plugins/codemirror,含 plugin.js、plugin.min.js、source.html 及 10 种语言文件),让 HTML 源码编辑体验由 CodeMirror 提供。其安装步骤为:

# 1. 在插件目录安装依赖并生成压缩文件
npm install
npm run prepublish   # 生成 plugin.min.js

# 2. 删除插件自带的 codemirror-4.8 目录
# 3. 将 tinymce-codemirror/plugins 目录移动到
#    common/static/js/vendor/tinymce/js/plugins/ 下
# 4. 将 EDX 特定修改应用到 plugin.js 与 source.html
# 5. 使用 uglify-js 重新生成压缩版
cd common/static/js/vendor/tinymce/js/plugins/codemirror/
uglify plugin.js -m -o plugin.min.js

重要提示(BUILD_README 原文强调):每次重新生成 codemirror 的 plugin.min.js 后,都必须重新生成 tinymce.full.min.js 整体 bundle,以确保最新改动被打入发行包。

生成 tinymce.full.min.js

以 TinyMCE 5.5.1 为例,完整构建命令如下:

unzip tinymce-5.5.1.zip
cd tinymce-5.5.1
yarn && yarn build            # 在 dist 目录生成多个 zip
unzip dist/tinymce_5.5.1_dev.zip -d /path/to/edx-platform/common/static/js/vendor/
# 删除 vendor/tinymce 中 package.json、yarn.lock 等不必要文件
cd common/static/js/vendor/tinymce/js/tinymce
LC_ALL=C cat tinymce.min.js */*/*.min.js plugins/emoticons/js/emojis.min.js > tinymce.full.min.js

该命令将核心包、各插件目录下的 *.min.js 以及表情插件的数据文件按序拼接,生成包含全部插件的单文件 bundle。平台正是通过这种方式把"50+ 强大插件、一行代码即可引入"的 TinyMCE 插件哲学固化为自身发行策略。

Studio 中的静态资源管线:皮肤与内容样式

TinyMCE 的界面外观由 skin 决定,编辑区内容渲染由 content CSS 决定。Open edX 在 cms/envs/common.py 中通过 pipeline 配置,为 Studio 定义了三条 TinyMCE 相关资源管线:

'style-vendor-tinymce-content': {
    'source_filenames': [
        'css/tinymce-studio-content-fonts.css',
        'js/vendor/tinymce/js/tinymce/skins/ui/studio-tmce5/content.min.css',
        'css/tinymce-studio-content.css'
    ],
    'output_filename': 'css/cms-style-vendor-tinymce-content.css',
},
'style-vendor-tinymce-skin': {
    'source_filenames': [
        'js/vendor/tinymce/js/tinymce/skins/ui/studio-tmce5/skin.min.css'
    ],
    'output_filename': 'css/cms-style-vendor-tinymce-skin.css',
}

从配置可以看出平台的三层样式策略:

  1. 字体基础:tinymce-studio-content-fonts.css 先声明编辑区字体体系;
  2. Studio 专用皮肤:skins/ui/studio-tmce5/ 是平台为 Studio 定制的 TinyMCE 5 皮肤(skin.min.css 与 content.min.css 分离),保证编辑器 UI 与 Studio 视觉风格一致;
  3. 内容样式覆盖:tinymce-studio-content.css 进一步定制编辑区内 HTML 内容的渲染效果,使"所见"尽量贴近课程发布后的"所得"。

皮肤与内容样式的分离是 TinyMCE 的经典设计——skin 管编辑器外壳(工具栏、菜单、弹窗),content CSS 管编辑区内正文排版,Open edX 正是利用这一机制实现了深度品牌化。

在 Studio 代码中的实际调用

TinyMCE 作为 AMD 模块深度嵌入 Studio 的前端构建体系:

  • cms/djangoapps/pipeline_js/js/xmodule.js 在模块依赖声明中引入 'tinymce' 与 'jquery.tinymce',并通过 $script 动态加载,再以 tinymce 参数注入业务模块,说明平台通过 jQuery 封装(jquery.tinymce.min.js)与编辑器交互;
  • cms/static/cms/js/require-config.js 等 RequireJS 配置将 tinymce 路径映射到 vendor 目录;
  • cms/templates/widgets/source-edit.html 展示了平台与编辑器实例的直接交互:当 latex2edx 服务把 LaTeX 源码编译为 edX XML 后,如果当前没有父级 CodeMirror 编辑器,则回退到写入活动 TinyMCE 实例:
else if (window.tinyMCE !== undefined && window.tinyMCE.activeEditor !== undefined) {
    window.tinyMCE.activeEditor.setContent(xml);
}

这印证了 README 中"通过暴露的 API 编写符合框架的自定义功能"的可行性:tinyMCE.activeEditor.setContent() 正是 TinyMCE 公共 API 的典型用法。此外,openedx/core/djangoapps/xblock/rest_api/views.py 中还能看到 oa_editor_tinymce_js(openassessment 的 TinyMCE 编辑器资源)经由 REST API 清单分发,说明 TinyMCE 资源在开放评估(ORA)等组件中同样被复用。

扩展 TinyMCE:在 Open edX 中启用自定义插件

TinyMCE 官方 README 强调其可扩展性:通过暴露的 API,开发者可以在现有 UI 组件框架内编写自定义功能;50+ 插件让"增加功能只需一行代码"。Open edX 将这一能力落地为两条明确步骤,完整记录于 docs/extensions/tinymce_plugins.rst。

第一步:安装插件(打包进静态资源)

指定需要安装的插件,使其被捆绑进静态资源,通常通过 edX 部署配置中的 TINYMCE_ADDITIONAL_PLUGINS_LIST 配置变量完成(该角色说明位于 openedx/configuration 仓库的 playbooks/roles/tinymce_plugins/README.rst)。插件文件最终会被纳入 common/static/js/vendor/tinymce/js/plugins/ 目录参与 bundle 生成。

第二步:启用插件(通过 JS 环境配置)

启用插件需要设置一个 Studio 环境变量 JS_ENV_EXTRA_CONFIG——它是一个字典,承载各类额外的 JavaScript 配置。其中负责启用 TinyMCE 插件的键是 TINYMCE_ADDITIONAL_PLUGINS,值为插件对象列表。

每个插件对象包含三个属性:

属性 类型 说明
name string TinyMCE 插件名,将加入编辑器插件列表
toolbar boolean 是否将该插件显示在工具栏
extra_settings object 追加到 TinyMCE 编辑器配置中的额外插件设置

完整的配置示例(YAML):

EDXAPP_CMS_ENV_EXTRA:
  JS_ENV_EXTRA_CONFIG:
    TINYMCE_ADDITIONAL_PLUGINS:
    - name: adsklink
      toolbar: true
      extra_settings:
        linktypes:
        - Download
        - Offer
        filetypes:
        - PDF
        - ZIP
        - Video
        - Design
        orientations:
        - Vertical
        - Horizontal
        styles:
        - Primary
        - Normal
        - Secondary

该示例展示了一个名为 adsklink 的自定义链接类插件:它不仅被加入编辑器插件列表并出现在工具栏,还通过 extra_settings 注入业务定制的链接类型、文件类型、方向与样式选项。这正是"一行代码引入插件 + 几行配置释放完整能力"的实践范本。

与官方能力模型对照:可扩展、可定制、可集成

结合官方 README 的三大特性维度,可以对照出 Open edX 的具体落地:

  • Integration(集成):官方提供 tinymce-react、tinymce-vue、tinymce-angular 等框架组件;edx-platform 侧则以 jQuery 封装(jquery.tinymce.min.js)+ RequireJS 模块化方式集成,属于传统 AMD 前端架构下的对应方案。
  • Customization(定制):官方强调可配置 UI 以匹配站点设计、按需增减功能;平台通过 studio-tmce5 定制皮肤、内容 CSS 管线与 TINYMCE_ADDITIONAL_PLUGINS 机制实现了同样目标。
  • Extensibility(可扩展):官方开放源码与 API 支持自定义功能;平台通过 BUILD_README 的"搜索 EDX 标记 + 合并补丁"流程维护本地定制,并通过插件属性模型(name/toolbar/extra_settings)向下游集成方开放扩展入口。

对于希望深入源码的开发者,建议从三处入手:构建与升级流程见 common/static/js/vendor/tinymce/BUILD_README.md,插件扩展配置见 docs/extensions/tinymce_plugins.rst,编辑器 iframe 集成细节见 cms/static/js/utils/handle_iframe_binding.js。

登录后查看全文
openedx-platform