Wagtail 2.0 发布说明解读Draftail 富文本编辑器、模块重组与升级路径【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtailWagtail 2.02018-02-28 发布是 Wagtail 从 Django 1.x 生态迈向 Django 2.0 的里程碑版本。本文基于 Wagtail 2.0 release notes 完整解读该版本的三大核心变化——全新 Draftail 富文本编辑器、Wagtail 模块路径重组与updatemodulepaths迁移命令、以及定时发布行为的重构并结合当前仓库源码如 wagtail/test/utils/form_data.py、wagtail/images/utils.py验证文档中各项升级要点的落地情况帮助开发者理解该版本引入的破坏性变更、掌握完整的模块重命名对照表与测试辅助函数用法。1. 版本背景与支持环境1.1 移除 Python 2.7 与旧版 Django 支持Wagtail 2.0 不再支持 Python 2.7、Django 1.8 和 Django 1.10。发布说明明确建议在升级到 Wagtail 2.0 之前先将项目升级到 Python 3 和 Django 1.11。这是 Wagtail 彻底转向 Python 3 生态的节点版本。1.2 新增 Django 2.0 支持Wagtail 2.0 宣布兼容 Django 2.0兼容性修复由 Matt Westcott、Karl Hobley、LB (Ben Johnston) 和 Mads Jensen 贡献。发布说明同时提醒升级到 Django 2.0 前应仔细阅读 Django 2.0 官方发布说明中的向后不兼容变更与被移除的特性两节因为 Django 2.0 本身移除了一批在 1.11 中已弃用的 API例如字节串不再允许传入reverse这一点直接催生了下文的generate_signature返回值变更。2. 新富文本编辑器Draftail 全面替换 Hallo.js2.1 为什么替换编辑器Wagtail 2.0 将富文本编辑器整体替换为Draftail——一个基于 Draft.js 构建的新编辑器。该特性由 Thibaud Colas、Loïc Teixeira 和 Matt Westcott 开发。官方给出的替换理由包括修复了大量 Hallo.js 时代积累的 bug提供更佳的编辑体验与对现代浏览器的更好支持产生更一致的 HTML 输出。从当前仓库结构看这一替换是彻底的富文本编辑器的实现位于 wagtail/admin/rich_text/editors/draftail/2.0 之前的 Hallo 编辑器已从编辑器目录中移除仅保留可通过配置回退的过渡能力见 2.2。2.2 回退到 Hallo 编辑器的配置由于 Draftail 与 Hallo.js 的 API 存在本质差异——包括内部数据表示采用非 HTML 格式——通过 Hallo.js 插件添加的功能在新编辑器下将不可用。如果项目依赖 Hallo.js 的特定行为可在settings.py中显式指定旧编辑器以回退WAGTAILADMIN_RICH_TEXT_EDITORS { default: { WIDGET: wagtail.admin.rich_text.HalloRichTextArea } }该配置的解析逻辑至今仍保留在当前代码中wagtail/admin/rich_text/init.py 中通过editor_settings.update(getattr(settings, WAGTAILADMIN_RICH_TEXT_EDITORS, {}))读取该设置项说明这一回退机制是 Wagtail 为编辑器迁移设计的正式扩展点。2.3assertCanCreate测试的数据格式变更assertCanCreate测试方法参见 docs/advanced_topics/testing.md要求传入的数据与页面编辑表单实际提交格式一致。由于 Draftail 以非 HTML 格式提交富文本数据升级后所有涉及富文本字段的既有assertCanCreate测试都会失败。旧写法self.assertCanCreate(root_page, ContentPage, { title: About us, body: pLorem ipsum dolor sit amet/p, # will not work })Wagtail 2.0 为此引入了一组构造表单数据的辅助函数上述断言应改写为from wagtail.tests.utils.form_data import rich_text self.assertCanCreate(root_page, ContentPage, { title: About us, body: rich_text(pLorem ipsum dolor sit amet/p), })源码佐证这组辅助函数目前实现于 wagtail/test/utils/form_data.py除rich_text外还包括nested_form_data将嵌套 dict 扁平化为连字符分隔的表单键L32-L47、streamfield构造 StreamField 表单数据L50-L77与inline_formset构造内联表单集 POST 数据L80-L125。其中rich_text函数L128-L144的核心逻辑是def rich_text(value, editordefault, featuresNone): widget get_rich_text_editor_widget(editor, features) return widget.format_value(value)即通过get_rich_text_editor_widget获取当前生效的编辑器 Widget再调用其format_value将 HTML 转换为该编辑器实际提交的数据格式——这意味着测试数据始终与当前编辑器Draftail 或配置的 Hallo保持同步无需手工适配。该模块还提供了querydict_from_htmlL189-L203可直接从渲染出的表单 HTML 中提取完整 POST 数据进一步降低复杂页面类型下手工构造测试数据的成本。2.4 Hallo 编辑器扩展点的新写法为保证既有 Hallo 插件只作用于 Hallo 编辑器2.0 引入了新的扩展点原有的.richtextCSS 类不再应用于 Hallo 编辑器的 DOM 元素JavaScript 中应使用属性选择器[data-hallo-editor]定位编辑器CSS 中应使用.halloeditor类选择器。变更对比/* JS */ - var widget $(elem).parent(.richtext).data(IKS-hallo); var widget $(elem).parent([data-hallo-editor]).data(IKS-hallo); [...] /* Styles */ - .richtext { .halloeditor { font-family: monospace; }3. 模块重组消除wagtail.wagtailcore式的双重前缀3.1 重组动机与影响范围Wagtail 2.0 对包内模块进行了大规模重命名与重组目的是消除wagtail.wagtailcore.models这类命名重复历史上源于 Django 1.6 时代 app 命名的限制并提升整体一致性。该变更由 Karl Hobley 和 Matt Westcott 实施。代价是需要对既有站点做一次性的模块引用更新官方认为这是长期改善开发者体验的取舍代码可读性提升、拼写错误减少。从当前仓库结构可以印证重组的最终形态wagtail/下直接就是 wagtail/images、wagtail/search、wagtail/sites、wagtail/snippets、wagtail/users、wagtail/documents、wagtail/embeds 以及 wagtail/contrib含forms、redirects、frontend_cache、routable_page、search_promotions、sitemaps、styleguide等子包与下文重命名表中的新名称一一对应。3.2updatemodulepaths迁移命令为降低迁移成本2.0 新增了管理命令updatemodulepaths。在项目代码库根目录下执行$ wagtail updatemodulepaths --list # 仅列出将被修改的文件不实际更新 $ wagtail updatemodulepaths --diff # 显示将发生的变更不更新文件 $ wagtail updatemodulepaths # 实际更新文件也可从其他位置指定项目路径$ wagtail updatemodulepaths /path/to/project --list $ wagtail updatemodulepaths /path/to/project --diff $ wagtail updatemodulepaths /path/to/project完整命令行选项可通过wagtail help updatemodulepaths查看。使用注意事项执行前建议备份项目代码库命令对所有*.py文件执行搜索替换虽然能覆盖绝大多数模块引用但无法修复未直接使用点分路径的写法例如from wagtail import wagtailcore这类导入该命令属于 2.0 迁移期工具仅用于从旧模块结构迁移到 2.0 新结构当前仓库的 wagtail/management/commands/ 目录中已不再包含该命令它属于历史迁移工具。3.3 完整模块重命名对照表旧名称新名称备注wagtail.wagtailcorewagtail.corewagtail.wagtailadminwagtail.adminwagtail.wagtaildocswagtail.documentsdocuments 不再缩写wagtail.wagtailembedswagtail.embedswagtail.wagtailimageswagtail.imageswagtail.wagtailsearchwagtail.searchwagtail.wagtailsiteswagtail.siteswagtail.wagtailsnippetswagtail.snippetswagtail.wagtailuserswagtail.userswagtail.wagtailformswagtail.contrib.forms移入 contribwagtail.wagtailredirectswagtail.contrib.redirects移入 contribwagtail.contrib.wagtailapi移除API v1在本版本中删除wagtail.contrib.wagtailfrontendcachewagtail.contrib.frontend_cache加下划线wagtail.contrib.wagtailroutablepagewagtail.contrib.routable_page加下划线wagtail.contrib.wagtailsearchpromotionswagtail.contrib.search_promotions加下划线wagtail.contrib.wagtailsitemapswagtail.contrib.sitemapswagtail.contrib.wagtailstyleguidewagtail.contrib.styleguide需要更新的位置包括import语句settings 中指定的路径如INSTALLED_APPS、MIDDLEWARE、WAGTAILSEARCH_BACKENDS迁移文件migrations中引用的字段与块例如wagtail.wagtailcore.fields.StreamField、wagtail.wagtailcore.blocks.RichTextBlock。3.4 不应修改的位置易错点注意重命名只适用于以wagtail.开头的点分模块路径。以下位置不应修改——此场景下wagtail前缀仍然必要用于避免与项目中可能存在的名为admin、images等的其他 app 冲突以app_name.ModelName字符串指定模型的 ForeignKey例如models.ForeignKey(wagtailimages.Image, ...)数据库表名、content type 或权限中使用的 app label模板与静态文件的路径例如自定义品牌覆盖后台模板时引用的路径模板标签库名称例如{% load wagtailcore_tags %}。4. 定时发布行为重构2.0 修订了定时发布scheduled publishing的行为设置未来的 go-live 时间不再导致页面被取消发布。这一改动使得为已发布的页面安排未来的更新成为可能——在此之前一旦为页面设定未来的上线时间页面会立即从线上撤下直到该时刻才重新上线这在编辑既有内容时会造成不必要的访问中断。该功能由 Patrick Woods 开发。5. 其他功能特性2.0 还带来了一批功能增强按主题归纳如下保留发布说明完整清单API 与搜索Wagtail API v1 实现wagtail.contrib.api移出主线转为外部应用Karl Hobley页面选择器page chooser改为搜索页面所有字段而不仅是标题Bertrand Bordage;表单提交视图支持按日期排序LB (Ben Johnston)搜索结果超过 100 条时改用 Elasticsearch scroll APIKarl Hobley为配合assertCanCreate构造表单数据提供了辅助函数Tim Heap, Matt Westcott即上文 2.3 节的form_data工具。页面与内容模型为Page新增exclude_fields_in_copy属性定义复制页面时应排除的字段LB (Ben Johnston)优化预览数据的存储Bertrand BordageInlinePanel新增heading关键字参数标题可与按钮标签独立设置Adrian TurjakStructBlock的返回值类型现在可自定义StreamField 块现在支持自定义get_template方法可在实例层面覆盖模板Christopher Bledsoe简化 edit handler APIFlorent Osmont, Bertrand Bordage。图片与表单新增bgcolor图片操作Karl Hobley表单构建器form builder新增隐藏字段hidden fieldRoss Crawford-dHeureuse改进{% image %}标签语法错误时的报错信息LB (Ben Johnston)Choose another image 按钮更名为 Change image 以消除歧义Edd BaldryFormPage列表与表单提交列表在后台改为类视图CBV实现便于覆盖Johan Arensman表单提交 CSV 导出的文件名中现在包含导出日期且可定制Johan ArensmanFormBuilder 类改用绑定方法生成字段自定义字段更容易且已有文档LB (Ben Johnston)新增render_landing_page方法到AbstractForm便于覆盖并向落地页上下文传入form_submissionStein Strindhaug。用户、Snippets 与权限新增before_create_user、after_create_user、before_delete_user、after_delete_user、before_edit_user、after_edit_user六个 hookJon CarmackSnippets 现在支持自定义主键Sævar Öfjörð Magnússon在WAGTAIL_USAGE_COUNT_ENABLED开启时删除确认页显示使用计数Kees HinkSnippets 增加使用计数Kees Hink使用计数移到编辑页侧边栏Kees Hink添加/修改/删除 collection权限现在可从用户组编辑页面配置Matt Westcott新增WAGTAILADMIN_USER_LOGIN_FORM设置项用于覆盖后台登录表单Mike Dingjan新增WAGTAILADMIN_NOTIFICATION_INCLUDE_SUPERUSERS设置项控制超级用户是否收到审核邮件通知Bruno AllaExplorer 菜单现在会反映通过construct_explorer_page_querysethook 和ModelAdmin.exclude_from_explorer属性所做的页面列表定制Tim Heap。富文本与后台前端富文本字段现在会考虑 feature list 来白名单化 HTML 元素Matt Westcott移除 Hallo 编辑器的.richtextCSS 类改用更明确的扩展点Thibaud Colas将 React 相关依赖暴露为全局变量便于在后台界面中扩展Thibaud ColasjQuery 升级到 3.2.1Janneke Janssenautoprefixer 配置更新以更贴合浏览器支持目标Janneke JanssenReact 及相关依赖升级到最新Janneke Janssen, Hugo van den Berg项目模板新增基础 DockerfileTom Dyson项目模板默认启用密码校验器Matt Westcott文档样式更新LB (Ben Johnston)。6. 修复的 Bug2.0 修复了大量缺陷完整清单如下从非 ASCII 标题生成 slug 时不再移除停用词避免错误的词边界问题Sævar Öfjörð MagnússonPostgreSQL 搜索后端在order_by_relevanceFalse搜索时保持QuerySet的原始排序Bertrand Bordagemodeladmin_register作为装饰器使用时不再把被装饰类替换为NoneTim Heap修复站点内所有页面均为私密时 XML sitemap 生成器崩溃的问题Stein StrindhaugWAGTAIL_APPEND_SLASH为False时{% routablepageurl %}模板标签不再生成非法 URLVenelin Stoykov页面无可用路由 URL 时不再显示 View live 按钮Tim Heap未定义任何 site 记录时 API 列表视图不再报错Karl Hobley修复 Chrome 中下拉箭头按钮边框渲染问题Bertrand Bordage修复 userbar 的 z-index 错误导致其显示在页面内容之后Stein Strindhaug表单提交分页在翻页时不再丢失日期筛选条件Bertrand BordagePostgreSQL 搜索后端现在会移除数据库中的重复页面实例Bertrand BordageFormSubmissionsPanel现在能识别自定义的表单提交类LB (Ben Johnston)防止移动端上 footer 与 revisions 链接不必要的折叠Jack Paine修复翻页浏览图片和文档时意外触发空搜索的问题LB (Ben Johnston)页面/图片/文档总数超过 4 位时不再失去响应式表现Michael PalmerTableBlock上下文菜单中的对齐选项被正确移除LB (Ben Johnston)修复 Elasticsearch 客户端1.7.0项目的ATOMIC_REBUILD支持Mikalai Radchuk修复 Elasticsearch 后端将 QuerySet 传入__in过滤器时的报错Karl Hobley, Matt Westcott__isnull过滤器在 Elasticsearch 5 上不再失败Karl Hobley防止同一字段同时定义为SearchField与FilterField时 Postgres 搜索后端间歇性失败Matt Westcott富文本中图片的 alt 文本不再在双引号处被截断Matt Westcott富文本中 embed URL 里的不再被双重转义Matt WestcottPillow 4.2.0 下使用 RGBA 图片不再崩溃Karl Hobley启用 PostgreSQL 搜索时复制页面不再崩溃Bertrand Bordage修复页面解锁按钮样式破损Bertrand Bordage后台搜索不再大量刷占浏览器历史Bertrand Bordage版本对比现在能正确处理内联模型的自定义主键LB (Ben Johnston)修复 chooser 面板插入 FieldRowPanel 时的报错Florent Osmont, Bertrand Bordage恢复图片上传时缺失的错误上报Matt Westcott仅在真正使用 Hallo 时才加载 Hallo CSSThibaud Colas防止 Wagtail 面板图标样式泄漏到使用h2元素的控件中Thibaud Colas。7. 升级注意事项Upgrade considerations7.1 Elasticsearch 1.x 支持移除本版本不再支持 Elasticsearch 1.x。升级到 Wagtail 2.0 之前请先将 Elasticsearch 升级到 2.x 或 5.x。7.2 Wagtail API v1 移除Wagtail API 第 1 版wagtail.contrib.wagtailapi已从 Wagtail 中移除。若正在使用 v1需要迁移到 v2参见 API 文档v2 子目录位于 docs/advanced_topics/api/v2/。若因外部客户端如无法直接控制的移动 App暂时无法迁移可转向社区维护的wagtailapi_legacy外部仓库——该仓库由社区协作维护遗留 API 版本直至所有用户迁移到官方支持的版本。从当前仓库结构看wagtail/api/ 下仅存在v2与v3两个版本子目录印证 v1 的彻底移除。7.3construct_whitelister_element_ruleshook 弃用用于在富文本中放行额外 HTML 元素的construct_whitelister_element_ruleshook 被弃用推荐改用 rich text features 机制。旧写法from wagtail.core import hooks from wagtail.core.whitelist import allow_without_attributes hooks.register(construct_whitelister_element_rules) def whitelist_blockquote(): return { blockquote: allow_without_attributes, }应改写为from wagtail.admin.rich_text.converters.editor_html import WhitelistRule from wagtail.core import hooks from wagtail.core.whitelist import allow_without_attributes hooks.register(register_rich_text_features) def blockquote_feature(features): # register a feature blockquote which whitelists the blockquote element features.register_converter_rule(editorhtml, blockquote, [ WhitelistRule(blockquote, allow_without_attributes), ]) # add blockquote to the default feature set features.default_features.append(blockquote)需要注意新的 Draftail 编辑器采用不同的富文本处理机制不再应用白名单规则——白名单仅在 Hallo.js 编辑器下生效。这也解释了 2.0 中富文本字段现在会考虑 feature list 来白名单化 HTML 元素这一特性与 feature 机制的关系。7.4generate_signature返回值变为字符串wagtail.images.views.serve中的generate_signature函数用于为动态图片服务视图构建 URL参见 docs/advanced_topics/images/ 相关章节现在返回字符串而非字节串。这样做的目的Django 2.0 不再允许字节串传入reverse因此既有的用reverse拼出最终图片 URL的用户代码可继续工作。反过来任何期望字节串的代码例如对结果调用decode()需要更新需要兼容旧版本 Wagtail 的应用可改用django.utils.encoding.force_text。源码佐证该函数在后续版本中迁移至 wagtail/images/utils.py当前实现印证了返回字符串这一契约def generate_signature(image_id, filter_spec, keyNone): if key is None: key settings.SECRET_KEY # Key must be a bytes object if isinstance(key, str): key key.encode() # Based on libthumbor hmac generation url f{image_id}/{filter_spec}/ return force_str( base64.urlsafe_b64encode(hmac.new(key, url.encode(), hashlib.sha1).digest()) )可见函数基于 HMAC-SHA1 base64 urlsafe 编码生成签名借鉴 libthumbor 的做法并在返回前统一force_str转换为字符串。7.5 内置搜索视图弃用Wagtail 一直内置一个前台搜索视图但该视图不易定制按项目自定义视图通常是更好的做法。如果项目中使用了该内置视图检查urls.py中是否有从wagtail.wagtailsearch.urls的导入需要替换为自己的实现官方 Demo 项目中的搜索视图可作为参考实现。7.6 Hallo 编辑器扩展点如 2.4 节所述.richtext类移除JS 改用[data-hallo-editor]属性选择器CSS 改用.halloeditor类选择器确保既有 Hallo 插件只扩展 Hallo 编辑器。8. 小结Wagtail 2.0 的三条主线编辑器现代化Draftail 基于 Draft.js 重写富文本体验配套引入 rich text feature 体系与form_data测试辅助函数wagtail/test/utils/form_data.py并保留WAGTAILADMIN_RICH_TEXT_EDITORS设置作为回退到 Hallo 的过渡通道代码结构重组消除wagtail.wagtail*双重前缀模块命名与当前仓库目录结构wagtail.core时代终结、wagtail.contrib统一加下划线完全一致updatemodulepaths命令保证了迁移的机械化执行同时明确了只改点分模块路径、不动 app label / 模板标签 / 外键字符串的安全边界生态对齐 Django 2.0彻底放弃 Python 2.7并对齐 Django 2.0 的 API 变化如generate_signature的字符串返回值、移除 Elasticsearch 1.x 与 API v1 支持为后续版本的大步迭代清除了历史包袱。对于仍需从 Wagtail 1.x 升级的维护者本节的模块重命名对照表、不应修改项清单与WAGTAILADMIN_RICH_TEXT_EDITORS回退配置构成了可直接执行的升级检查清单。【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考