Wagtail 5.2 LTS 版本全解析图片性能优化、OpenSearch 支持、ModelViewSet 增强与升级指南【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtailWagtail 5.2 于 2023 年 11 月 1 日发布并被正式指定为Long Term SupportLTS长期支持版本——在下一个 LTS 版本到来之前通常为期 12 个月该系列会持续接收针对安全问题和数据丢失问题所需的维护更新。本篇文章以 Wagtail 5.2 官方发布说明 为主线结合当前仓库源码系统梳理 5.2 的核心新特性重设计的页面列表、OpenSearch 支持、picture/srcset_image响应式图片标签、Stimulus 客户端扩展、ModelViewSet能力迁移、逐条展开升级注意事项并给出可落地的迁移示例。读完本文你将掌握 5.2 的新能力用法、底层实现原理以及从旧版本平滑升级所需的全部改动清单。版本定位LTS 与维护周期Wagtail 5.2 被指定为 Long Term SupportLTS版本。根据发布说明LTS 版本会在下一个 LTS 版本发布之前通常是 12 个月持续收到针对安全问题和数据丢失问题的维护更新。对于追求稳定、不愿频繁大版本升级的生产项目5.2 系列是值得长期驻留的版本基线。它同时也是首个正式支持Python 3.12的版本由 Matt Westcott 贡献对升级 Python 运行环境的项目有直接意义。亮点一重设计的页面列表视图Page Explorer5.2 对后台的页面资源管理器page explorer列表视图做了重新设计以提供更流畅的导航与搜索体验。从官方截图可以看到新的列表在搜索时呈现精简slimmed-down的结果行行内直接展示标题、状态、操作等核心信息配合新的面包屑与下拉按钮交互整体信息密度和操作效率都有明显提升。该特性由 Ben Enright、Matt Westcott、Thibaud Colas 与 Sage Abdullah 共同开发。亮点二OpenSearch 正式支持5.2 起OpenSearch 被正式支持为 Elasticsearch 的替代方案由 Matt Westcott 开发。仓库中的对应后端实现位于 wagtail/search/backends/opensearch2.py 与 wagtail/search/backends/opensearch3.py分别对应 OpenSearch 2.x 与 3.x。完整的配置细节见 OpenSearch 配置文档核心要点如下通过WAGTAILSEARCH_BACKENDS设置选择后端可用的后端标识为wagtail.search.backends.opensearch2OpenSearch 2.x与wagtail.search.backends.opensearch3OpenSearch 3.x。前置依赖是 OpenSearch 服务本身以及 pip 安装的opensearch-py包且包的大版本必须与所连接的 OpenSearch 大版本一致pip install opensearch-py2,3 # 对应 OpenSearch 2.x pip install opensearch-py3,4 # 对应 OpenSearch 3.x一个典型的配置示例WAGTAILSEARCH_BACKENDS { default: { BACKEND: wagtail.search.backends.opensearch3, URLS: [http://localhost:9200], INDEX: wagtail, TIMEOUT: 5, AUTO_UPDATE: True, ATOMIC_REBUILD: True, } }若使用 OpenSearch 的 demo 配置其 TLS 证书位于 OpenSearch 配置目录通常为/usr/share/opensearch/config/或/etc/opensearch/客户端证书与密钥分别名为kirk.pem与kirk-key.pem可据此配置带认证的URLS。OpenSearch 后端兼容Amazon OpenSearch Service但需要通过requests-aws4auth包处理基于 IAM 的认证再在WAGTAILSEARCH_BACKENDS中配置相应的认证参数。亮点三picture / srcset_image 响应式多格式图片5.2 为图片模板标签引入两大新成员目标是显著降低全站图片体积、缩短加载时间并减小环境碳足迹该特性由 Paarth Agarwal 与 Thibaud Colas 在 Google Summer of Code 项目及 Green Web Foundation、Green Coding Berlin 合作中完成picture标签一次性按多种格式 × 多种尺寸批量生成图片输出 HTMLpicture标签srcset_image标签一次性生成多种尺寸输出带srcset属性的img标签。例如一次生成 6 个变体AVIF/WebP/JPEG 三种格式 × 400/800 两种宽度{% picture page.photo format-{avif,webp,jpeg} width-{400,800} sizes80vw %}输出picture source sizes80vw srcset/media/images/pied-wagtail.width-400.avif 400w, /media/images/pied-wagtail.width-800.avif 800w typeimage/avif source sizes80vw srcset/media/images/pied-wagtail.width-400.webp 400w, /media/images/pied-wagtail.width-800.webp 800w typeimage/webp img sizes80vw srcset/media/images/pied-wagtail.width-400.jpg 400w, /media/images/pied-wagtail.width-800.jpg 800w src/media/images/pied-wagtail.width-400.jpg altA pied Wagtail width400 height300 /picture源码级原理从源码看这套机制的核心是Filter类的花括号展开brace expansion与Picture/ResponsiveImage对象的 HTML 渲染wagtail/images/models.py 中的Filter.expand_spec()会把形如width-{100,200}的规格展开为[width-100, width-200]多个花括号段之间取笛卡尔积再以|组合成完整规格串对应地srcset_image/picture标签允许的规格字符集扩大到包含{}与,见 jinja2tags.py 中基于Filter.pipe_expanding_spec_pattern的语法校验。ResponsiveImagewagtail/images/models.py通过get_width_srcset()生成url 400w, url 800w形式的宽度描述符单张图片时不输出srcset并以第一张 rendition 作为兜底img。Picturewagtail/images/models.py按source_format_order [avif, webp, jpeg, png, gif]的优先级决定source的书写顺序与兜底格式fallback format浏览器会选取其支持的第一种格式若只生成了一种格式则退化为带srcset的普通img并包裹在picture中。格式与质量可通过设置项调节源码 wagtail/images/models.py 显示 JPEG 质量默认 76WAGTAILIMAGES_JPEG_QUALITY、WebP 默认 80WAGTAILIMAGES_WEBP_QUALITY、AVIF 默认 61WAGTAILIMAGES_AVIF_QUALITY并支持format-{...}系列操作符与preserve-svg跳过 SVG 转换等细节。更完整的用法多格式、响应式尺寸、AVIF 支持、AbstractImage.get_renditions()见 图片主题文档这两个新标签同样支持在 Jinja 模板中使用对应 API 见 Jinja2 参考WagtailImagesExtension在 wagtail/images/jinja2tags.py 中把image、image_url、srcset_image、picture注册为 Jinja 全局函数。亮点四官方支持 Stimulus 客户端扩展5.2 起Wagtail 正式支持使用Stimulus进行后台admin客户端定制并新增了专门的开发者文档页 扩展客户端侧由核心贡献者 LB (Ben) Johnston 编写。该文档覆盖客户端可扩展性的基础主题添加自定义 JavaScript基于 DOM 事件以及 Wagtail 自定义 DOM 事件进行扩展基于 Stimulus 扩展基于 React 扩展。与之配套5.2 同步将多个既有组件迁移到 Stimulus表单提交列表的复选框切换迁移到共享的w-bulk控制器、编辑器未保存消息弹窗由共享的w-message控制器驱动、tooltip/dropdown 全面改用data-*-value属性、w-action控制器新增reset方法、Stimulus dialog 新增notifytarget 等。这也解释了下方升级注意事项中大量旧 data 属性/旧事件名被替换的现象——后台前端正在稳步走向以 Stimulus 为统一框架的架构。亮点五ModelViewSet 能力大幅增强5.2 将SnippetViewSet的一批能力下沉到通用基类{class}~wagtail.admin.viewsets.model.ModelViewSet使得开发者**无需把模型注册为 snippet** 也能获得完整的后台管理视图。仓库中ModelViewSet的实现位于 [wagtail/admin/viewsets/model.py](https://link.gitcode.com/i/939380eea044e7e93a6af4c7fc04a7db)其类属性直接印证了 5.2 的新能力例如add_to_reference_index True默认注册引用索引、inspect_view_enabled False默认关闭 inspect 视图、list_per_page 20 等。本次从SnippetViewSet迁移到ModelViewSet的内容包括将SnippetViewSet的菜单注册机制迁移到基类ViewSet将模板覆盖机制、list_display迁移到ModelViewSet将list_filter、filterset_class、search_fields、search_backend_name、list_export、export_filename、list_per_page、ordering等属性迁移到ModelViewSet为通用IndexView/CreateView增加默认头部标题通用IndexView支持使用过滤器与导出列表为ModelViewSet新增通用UsageView、InspectView并从 snippets 中提取通用HistoryView从页面面包屑中提取通用面包屑功能并为自定义ModelViewSet视图提供面包屑支持允许ModelViewSet用于非整数主键模型为ModelViewSet注册的模型默认开启引用索引reference index追踪。同时以下新特性也加入了通用后台视图SnippetViewSet同样可用允许通过ModelViewSet覆盖IndexView.export_headings允许在通用IndexView上定义列表按钮listing buttons。完整用法参见 generic views 文档。亮点六管理界面打磨与搜索推广外链5.2 对后台用户界面做了一批细节打磨页面状态侧栏的相对日期上以 tooltip 显示完整的首次发布时间、无面板锚点时不再渲染 minimap、dashboard 面板的列表改用下拉按钮、面包屑设计细化、表单提交与简单翻译提交支持 Shift Click 批量行为、按用户权限优化审计日志过滤等。另一个实用新特性是推广搜索结果Promoted Search Results条目现在可以使用外部 URL 与自定义链接文本而不再只能指向 Wagtail 内的页面便于跨站点管理推广内容感谢 TopDevPros 与芝加哥大学图书馆的 Brad Busenius。其他功能亮点速览发布说明中的Other features包含一批值得关注的能力择要列出模板标签防缓存新增wagtailcache与wagtailpagecache模板标签确保预览 Page 或 Snippet 时不会被缓存视图限制随页面复制/别名迁移复制页面或创建别名时其视图限制view restrictions会一并复制到目标StreamField 值支持 pickleChooser 增强ChooserViewSet支持指定get_object_list方法chooser widgets 新增linked_fields机制可按调用页面的字段限制可选范围TableBlock 支持合并单元格通过mergedCells选项实现InlinePanel 焦点与 DOM 事件在InlinePanel内新增面板时焦点会移至新内容与StreamField一致并新增 ready/新增/移除等InlinePanelDOM 事件{% component %}标签支持传递额外上下文变量API v2 支持多字段排序PagesAPIViewSet子类可通过model属性覆盖默认 Page 模型Email 链接 chooser 支持主题与正文wagtail_update_image_renditions管理命令输出可视化进度条上传文件哈希生成增大读缓冲区并在 Python 3.11 使用hashlib.file_digest提升效率Block.get_template可接收value参数允许按块值选择模板purge_revisions管理命令现在会尊重带on_deletePROTECT外键关系的 revision不再删除它们。升级注意事项影响所有项目MariaDB 上的 UUID 字段与 Django 5.0Django 5.0 在 MariaDB 10.7 及以上引入了对 MariaDB 原生 UUID 类型的支持这会破坏旧版本 Django/MariaDB 创建的CHAR型 UUID 的向后兼容性。因此将站点升级到 Django 5.0 与 MariaDB 10.7 后创建或编辑页面时很可能出现类似Data too long for column translation_key at row 1或Data too long for column uuid at row 1的错误。修复方法是升级后运行该命令自Wagtail 5.2.5起提供convert_mariadb_uuids管理命令./manage.py convert_mariadb_uuids该命令会把 Wagtail 使用的所有既有 UUID 字段转换为新格式。在 Django 5.0 与 MariaDB 10.7 下新建的站点不受影响无需执行。升级注意事项旧功能弃用旧版 moderation 系统弃用在 Wagtail 2.10 被新工作流workflow系统取代的旧版 moderation 系统如今正式标记为弃用。自 2.10 起提交的页面审核已走新工作流但 2.10 之前提交、仍滞留在旧队列中的页面仍需通过旧系统批准/拒绝以超级用户登录后台可在仪表盘看到Pages awaiting moderation区块并操作也可以编程处理查询Revision.objects.filter(submitted_for_moderationTrue)对每个 revision 调用revision.approve_moderation()或revision.reject_moderation()。以下 API 与配置随之弃用并将在未来版本移除应替换为新工作流的对应能力wagtail.models.Revision.submitted_for_moderationwagtail.models.Revision.submitted_revisionswagtail.models.Revision.approve_moderationwagtail.models.Revision.reject_moderationRevisionMixin.save_revision的submitted_for_moderation参数WAGTAIL_MODERATION_ENABLEDwagtail.admin.userbar.ModeratePageItem、ApproveModerationEditPageItem、RejectModerationEditPageItemwagtail.admin.views.home.PagesForModerationPanelwagtail.admin.views.pages.moderationwagtail.permission_policies.pages.PagePermissionPolicy.revisions_for_moderation详情可回顾 Wagtail 2.10 发布说明。升级注意事项影响 Wagtail 定制代码classname命名约定Wagtail 从 4.2 开始推行统一的单数classname而非复数classnames约定5.2 将这一约定扩展到菜单与钩子体系。以下类采用新约定admin.menu.MenuItemadmin.ui.sidebar.ActionMenuItemadmin.ui.sidebar.LinkMenuItemadmin.ui.sidebar.PageExplorerMenuItemcontrib.settings.registry.SettingMenuItem以下钩子在使用classnames生成菜单项时可能受影响register_admin_menu_item、register_settings_menu_item钩子完整清单见 hooks 参考。旧的classnames关键字仍可用但会触发弃用警告未来版本将移除。示例注意第 8 行使用classnamefrom django.urls import reverse from wagtail import hooks from wagtail.admin.menu import MenuItem hooks.register(register_admin_menu_item) def register_frank_menu_item(): return MenuItem( Frank, reverse(frank), icon_namefolder-inverse, order10000, classnamehighlight-menu, # 不是 classnames... )ModelViewSet 的编辑/删除 URL 变更支持非整数主键为支持非整数主键模型ModelViewSet中编辑与删除视图的 URL 模式已变更。相对于视图集的url_prefix编辑 URL 由int:pk/改为edit/str:pk/删除 URL 由int:pk/delete/改为delete/str:pk/。若你通过django.urls.reverse配合get_url_name()生成 URL无需改动但若在代码中硬编码了这些 URL必须更新。旧 URL 的重定向仅为向后兼容保留未来版本会移除。SnippetViewSet中旧 URL 的重定向也已被标记为未来移除。ModelViewSet 自动注册引用索引通过ModelViewSet注册的模型默认启用引用索引追踪不再需要在 app 的ready()方法中手动调用ReferenceIndex.register_model()。若不希望如此可在ModelViewSet子类上设置add_to_reference_index False对应源码 wagtail/admin/viewsets/model.py。详见 引用索引管理文档。其他行为变更一览GroupViewSet的IndexView.results_template_name更名由wagtailusers/groups/results.html改为wagtailusers/groups/index_results.html自定义过该模板如 自定义组视图的项目需要同步重命名。construct_snippet_listing_buttons钩子不再接受context参数需要访问视图计算值的场景应改为覆盖SnippetViewSet.index_view_class自定义IndexView特别是get_list_buttons与get_list_more_buttons方法。旧签名会触发警告并收到空字典{}。页面列表/头部按钮钩子的page_perms参数被user取代register_page_header_buttons由func(page, page_perms, next_url)变为func(page, user, next_url, view_name)其中view_name为edit或indexregister_page_listing_buttons变为func(page, user, next_url)construct_page_listing_buttons变为fn(buttons, page, user, context)register_page_listing_more_buttons变为func(page, user, next_url)ButtonWithDropdownFromHook构造器同样改传user。旧代码如需获取权限测试对象可用page.permissions_for_user(user)替代。相关钩子说明见 hooks 参考。升级注意事项未文档化的内部变更面包屑类名由单数改为复数自定义面包屑样式时类名w-breadcrumb已改为w-breadcrumbs。Snippets 模板重构为复用slim_header.html以下 snippets 头部模板已被移除绝大多数场景可用wagtailadmin/shared/headers/slim_header.html替代wagtailsnippets/snippets/headers/_base_header.htmlcreate_header.html、edit_header.html、history_header.html、list_header.html、usage_header.html侧栏组合类移除BaseSidePanels、PageSidePanels、SnippetSidePanels类已移除每个侧栏现在直接在视图中实例化BasePreviewSidePanel/PagePreviewSidePanel/SnippetPreviewSidePanel合并为PreviewSidePanelBaseStatusSidePanel更名为StatusSidePanel。媒体对象可用wagtail.admin.ui.components.MediaContainer组合。旧写法from wagtail.admin.ui.side_panels import PageSidePanels def my_view(request): ... side_panels PageSidePanels( request, page.get_latest_revision_as_object(), show_schedule_publishing_toggleFalse, live_pagepage, scheduled_pagepage.get_scheduled_revision_as_object(), in_explorerFalse, preview_enabledTrue, comments_enabledFalse, ) return render( request, template_name, {page: page, side_panels: side_panels, media: side_panels.media}, )新写法from wagtail.admin.ui.components import MediaContainer from wagtail.admin.ui.side_panels import PageStatusSidePanel, PreviewSidePanel def my_view(request): ... side_panels [ PageStatusSidePanel( page, request, show_schedule_publishing_toggleFalse, live_objectpage, scheduled_objectpage.get_scheduled_revision_as_object(), localepage.locale, translationstranslations, ), PreviewSidePanel( page, request, preview_urlreverse(wagtailadmin_pages:preview_on_edit, args[page.id]), ), ] side_panels MediaContainer(side_panels) return render( request, template_name, {page: page, side_panels: side_panels, media: side_panels.media}, )面包屑迁移到 Stimulus事件与 data 属性变化头部面包屑组件已迁移到 Stimulus 控制器事件与 data 属性均发生变化自定义头部实现、以及未使用breadcrumbs却依赖展开/收起行为的自定义面包屑可能受影响旧事件新事件wagtail:breadcrumbs-expandw-breadcrumbs:openedwagtail:breadcrumbs-collapsew-breadcrumbs:closed旧 data 属性新 data 属性data-breadcrumb-nextdata-controllerw-breadcrumbsdata-toggle-breadcrumbsdata-w-breadcrumbs-targettoggle>window.updateFooterSaveWarning (formDirty, commentsDirty) { if (!formDirty !commentsDirty) { document.dispatchEvent(new CustomEvent(w-unsaved:clear)); } else { const [type] [ formDirty commentsDirty all, commentsDirty comments, formDirty edits, ].filter(Boolean); document.dispatchEvent(new CustomEvent(w-unsaved:add, { detail: { type } })); } };其他内部变更速查dropdown模板标签参数更名toggle_tippy_offset改为toggle_tooltip_offset例如{% dropdown toggle_tooltip_offset[0, -2] %}...{% enddropdown %}。escapescript模板标签与escape_script函数弃用它们是为已停止支持的 IE11 提供 HTML 模板内容转义且不符合 CSP请改用 HTMLtemplate元素避免内容被浏览器解析template idid_{{ formset.prefix }}-EMPTY_FORM_TEMPLATE divWidget template content/div script src/js/my-widget.js/script /template图片Format实例的classnames改为classname自定义格式代码中访问self.classnames仍可返回self.classname但会触发弃用警告应改为self.classname。search promotions 模块调整search_garbage_collect管理命令已彻底移除5.0 起迁移到searchpromotions_garbage_collect见 管理命令文档部分 URL 名称与模板从主 admin 搜索模块迁入 search promotions 模块例如 URL 名称wagtailsearch_admin:queries_chooser改为wagtailsearchpromotions:chooserchooser 相关模板路径相应迁移到 wagtail/contrib/search_promotions/ 模块内。Block.get_template新增value参数StreamField 块的get_template现在接收value与context旧签名def get_template(self, contextNone)应更新为def get_template(self, valueNone, contextNone)。结语Wagtail 5.2 作为一个 LTS 版本交出了相当扎实的成绩单picture/srcset_image为全站图片体积与碳足迹带来立竿见影的改善OpenSearch 补齐了搜索后端的可替代选择ModelViewSet的能力下沉让非 snippet 模型也能拥有完整后台成为现实Stimulus 的正式支持则标志着后台前端进入统一框架时代。与此同时5.2 也集中清理了一大批历史包袱旧版 moderation、classnames、page_perms钩子、旧侧栏组合类等升级时需要对照本文的变更清单逐一核对自定义代码。若你的项目正计划长期维护5.2 LTS 系列是当前值得认真评估的稳定基线。【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Wagtail 5.2 LTS 版本全解析：图片性能优化、OpenSearch 支持、ModelViewSet 增强与升级指南
Wagtail 5.2 LTS 版本全解析图片性能优化、OpenSearch 支持、ModelViewSet 增强与升级指南【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtailWagtail 5.2 于 2023 年 11 月 1 日发布并被正式指定为Long Term SupportLTS长期支持版本——在下一个 LTS 版本到来之前通常为期 12 个月该系列会持续接收针对安全问题和数据丢失问题所需的维护更新。本篇文章以 Wagtail 5.2 官方发布说明 为主线结合当前仓库源码系统梳理 5.2 的核心新特性重设计的页面列表、OpenSearch 支持、picture/srcset_image响应式图片标签、Stimulus 客户端扩展、ModelViewSet能力迁移、逐条展开升级注意事项并给出可落地的迁移示例。读完本文你将掌握 5.2 的新能力用法、底层实现原理以及从旧版本平滑升级所需的全部改动清单。版本定位LTS 与维护周期Wagtail 5.2 被指定为 Long Term SupportLTS版本。根据发布说明LTS 版本会在下一个 LTS 版本发布之前通常是 12 个月持续收到针对安全问题和数据丢失问题的维护更新。对于追求稳定、不愿频繁大版本升级的生产项目5.2 系列是值得长期驻留的版本基线。它同时也是首个正式支持Python 3.12的版本由 Matt Westcott 贡献对升级 Python 运行环境的项目有直接意义。亮点一重设计的页面列表视图Page Explorer5.2 对后台的页面资源管理器page explorer列表视图做了重新设计以提供更流畅的导航与搜索体验。从官方截图可以看到新的列表在搜索时呈现精简slimmed-down的结果行行内直接展示标题、状态、操作等核心信息配合新的面包屑与下拉按钮交互整体信息密度和操作效率都有明显提升。该特性由 Ben Enright、Matt Westcott、Thibaud Colas 与 Sage Abdullah 共同开发。亮点二OpenSearch 正式支持5.2 起OpenSearch 被正式支持为 Elasticsearch 的替代方案由 Matt Westcott 开发。仓库中的对应后端实现位于 wagtail/search/backends/opensearch2.py 与 wagtail/search/backends/opensearch3.py分别对应 OpenSearch 2.x 与 3.x。完整的配置细节见 OpenSearch 配置文档核心要点如下通过WAGTAILSEARCH_BACKENDS设置选择后端可用的后端标识为wagtail.search.backends.opensearch2OpenSearch 2.x与wagtail.search.backends.opensearch3OpenSearch 3.x。前置依赖是 OpenSearch 服务本身以及 pip 安装的opensearch-py包且包的大版本必须与所连接的 OpenSearch 大版本一致pip install opensearch-py2,3 # 对应 OpenSearch 2.x pip install opensearch-py3,4 # 对应 OpenSearch 3.x一个典型的配置示例WAGTAILSEARCH_BACKENDS { default: { BACKEND: wagtail.search.backends.opensearch3, URLS: [http://localhost:9200], INDEX: wagtail, TIMEOUT: 5, AUTO_UPDATE: True, ATOMIC_REBUILD: True, } }若使用 OpenSearch 的 demo 配置其 TLS 证书位于 OpenSearch 配置目录通常为/usr/share/opensearch/config/或/etc/opensearch/客户端证书与密钥分别名为kirk.pem与kirk-key.pem可据此配置带认证的URLS。OpenSearch 后端兼容Amazon OpenSearch Service但需要通过requests-aws4auth包处理基于 IAM 的认证再在WAGTAILSEARCH_BACKENDS中配置相应的认证参数。亮点三picture / srcset_image 响应式多格式图片5.2 为图片模板标签引入两大新成员目标是显著降低全站图片体积、缩短加载时间并减小环境碳足迹该特性由 Paarth Agarwal 与 Thibaud Colas 在 Google Summer of Code 项目及 Green Web Foundation、Green Coding Berlin 合作中完成picture标签一次性按多种格式 × 多种尺寸批量生成图片输出 HTMLpicture标签srcset_image标签一次性生成多种尺寸输出带srcset属性的img标签。例如一次生成 6 个变体AVIF/WebP/JPEG 三种格式 × 400/800 两种宽度{% picture page.photo format-{avif,webp,jpeg} width-{400,800} sizes80vw %}输出picture source sizes80vw srcset/media/images/pied-wagtail.width-400.avif 400w, /media/images/pied-wagtail.width-800.avif 800w typeimage/avif source sizes80vw srcset/media/images/pied-wagtail.width-400.webp 400w, /media/images/pied-wagtail.width-800.webp 800w typeimage/webp img sizes80vw srcset/media/images/pied-wagtail.width-400.jpg 400w, /media/images/pied-wagtail.width-800.jpg 800w src/media/images/pied-wagtail.width-400.jpg altA pied Wagtail width400 height300 /picture源码级原理从源码看这套机制的核心是Filter类的花括号展开brace expansion与Picture/ResponsiveImage对象的 HTML 渲染wagtail/images/models.py 中的Filter.expand_spec()会把形如width-{100,200}的规格展开为[width-100, width-200]多个花括号段之间取笛卡尔积再以|组合成完整规格串对应地srcset_image/picture标签允许的规格字符集扩大到包含{}与,见 jinja2tags.py 中基于Filter.pipe_expanding_spec_pattern的语法校验。ResponsiveImagewagtail/images/models.py通过get_width_srcset()生成url 400w, url 800w形式的宽度描述符单张图片时不输出srcset并以第一张 rendition 作为兜底img。Picturewagtail/images/models.py按source_format_order [avif, webp, jpeg, png, gif]的优先级决定source的书写顺序与兜底格式fallback format浏览器会选取其支持的第一种格式若只生成了一种格式则退化为带srcset的普通img并包裹在picture中。格式与质量可通过设置项调节源码 wagtail/images/models.py 显示 JPEG 质量默认 76WAGTAILIMAGES_JPEG_QUALITY、WebP 默认 80WAGTAILIMAGES_WEBP_QUALITY、AVIF 默认 61WAGTAILIMAGES_AVIF_QUALITY并支持format-{...}系列操作符与preserve-svg跳过 SVG 转换等细节。更完整的用法多格式、响应式尺寸、AVIF 支持、AbstractImage.get_renditions()见 图片主题文档这两个新标签同样支持在 Jinja 模板中使用对应 API 见 Jinja2 参考WagtailImagesExtension在 wagtail/images/jinja2tags.py 中把image、image_url、srcset_image、picture注册为 Jinja 全局函数。亮点四官方支持 Stimulus 客户端扩展5.2 起Wagtail 正式支持使用Stimulus进行后台admin客户端定制并新增了专门的开发者文档页 扩展客户端侧由核心贡献者 LB (Ben) Johnston 编写。该文档覆盖客户端可扩展性的基础主题添加自定义 JavaScript基于 DOM 事件以及 Wagtail 自定义 DOM 事件进行扩展基于 Stimulus 扩展基于 React 扩展。与之配套5.2 同步将多个既有组件迁移到 Stimulus表单提交列表的复选框切换迁移到共享的w-bulk控制器、编辑器未保存消息弹窗由共享的w-message控制器驱动、tooltip/dropdown 全面改用data-*-value属性、w-action控制器新增reset方法、Stimulus dialog 新增notifytarget 等。这也解释了下方升级注意事项中大量旧 data 属性/旧事件名被替换的现象——后台前端正在稳步走向以 Stimulus 为统一框架的架构。亮点五ModelViewSet 能力大幅增强5.2 将SnippetViewSet的一批能力下沉到通用基类{class}~wagtail.admin.viewsets.model.ModelViewSet使得开发者**无需把模型注册为 snippet** 也能获得完整的后台管理视图。仓库中ModelViewSet的实现位于 [wagtail/admin/viewsets/model.py](https://link.gitcode.com/i/939380eea044e7e93a6af4c7fc04a7db)其类属性直接印证了 5.2 的新能力例如add_to_reference_index True默认注册引用索引、inspect_view_enabled False默认关闭 inspect 视图、list_per_page 20 等。本次从SnippetViewSet迁移到ModelViewSet的内容包括将SnippetViewSet的菜单注册机制迁移到基类ViewSet将模板覆盖机制、list_display迁移到ModelViewSet将list_filter、filterset_class、search_fields、search_backend_name、list_export、export_filename、list_per_page、ordering等属性迁移到ModelViewSet为通用IndexView/CreateView增加默认头部标题通用IndexView支持使用过滤器与导出列表为ModelViewSet新增通用UsageView、InspectView并从 snippets 中提取通用HistoryView从页面面包屑中提取通用面包屑功能并为自定义ModelViewSet视图提供面包屑支持允许ModelViewSet用于非整数主键模型为ModelViewSet注册的模型默认开启引用索引reference index追踪。同时以下新特性也加入了通用后台视图SnippetViewSet同样可用允许通过ModelViewSet覆盖IndexView.export_headings允许在通用IndexView上定义列表按钮listing buttons。完整用法参见 generic views 文档。亮点六管理界面打磨与搜索推广外链5.2 对后台用户界面做了一批细节打磨页面状态侧栏的相对日期上以 tooltip 显示完整的首次发布时间、无面板锚点时不再渲染 minimap、dashboard 面板的列表改用下拉按钮、面包屑设计细化、表单提交与简单翻译提交支持 Shift Click 批量行为、按用户权限优化审计日志过滤等。另一个实用新特性是推广搜索结果Promoted Search Results条目现在可以使用外部 URL 与自定义链接文本而不再只能指向 Wagtail 内的页面便于跨站点管理推广内容感谢 TopDevPros 与芝加哥大学图书馆的 Brad Busenius。其他功能亮点速览发布说明中的Other features包含一批值得关注的能力择要列出模板标签防缓存新增wagtailcache与wagtailpagecache模板标签确保预览 Page 或 Snippet 时不会被缓存视图限制随页面复制/别名迁移复制页面或创建别名时其视图限制view restrictions会一并复制到目标StreamField 值支持 pickleChooser 增强ChooserViewSet支持指定get_object_list方法chooser widgets 新增linked_fields机制可按调用页面的字段限制可选范围TableBlock 支持合并单元格通过mergedCells选项实现InlinePanel 焦点与 DOM 事件在InlinePanel内新增面板时焦点会移至新内容与StreamField一致并新增 ready/新增/移除等InlinePanelDOM 事件{% component %}标签支持传递额外上下文变量API v2 支持多字段排序PagesAPIViewSet子类可通过model属性覆盖默认 Page 模型Email 链接 chooser 支持主题与正文wagtail_update_image_renditions管理命令输出可视化进度条上传文件哈希生成增大读缓冲区并在 Python 3.11 使用hashlib.file_digest提升效率Block.get_template可接收value参数允许按块值选择模板purge_revisions管理命令现在会尊重带on_deletePROTECT外键关系的 revision不再删除它们。升级注意事项影响所有项目MariaDB 上的 UUID 字段与 Django 5.0Django 5.0 在 MariaDB 10.7 及以上引入了对 MariaDB 原生 UUID 类型的支持这会破坏旧版本 Django/MariaDB 创建的CHAR型 UUID 的向后兼容性。因此将站点升级到 Django 5.0 与 MariaDB 10.7 后创建或编辑页面时很可能出现类似Data too long for column translation_key at row 1或Data too long for column uuid at row 1的错误。修复方法是升级后运行该命令自Wagtail 5.2.5起提供convert_mariadb_uuids管理命令./manage.py convert_mariadb_uuids该命令会把 Wagtail 使用的所有既有 UUID 字段转换为新格式。在 Django 5.0 与 MariaDB 10.7 下新建的站点不受影响无需执行。升级注意事项旧功能弃用旧版 moderation 系统弃用在 Wagtail 2.10 被新工作流workflow系统取代的旧版 moderation 系统如今正式标记为弃用。自 2.10 起提交的页面审核已走新工作流但 2.10 之前提交、仍滞留在旧队列中的页面仍需通过旧系统批准/拒绝以超级用户登录后台可在仪表盘看到Pages awaiting moderation区块并操作也可以编程处理查询Revision.objects.filter(submitted_for_moderationTrue)对每个 revision 调用revision.approve_moderation()或revision.reject_moderation()。以下 API 与配置随之弃用并将在未来版本移除应替换为新工作流的对应能力wagtail.models.Revision.submitted_for_moderationwagtail.models.Revision.submitted_revisionswagtail.models.Revision.approve_moderationwagtail.models.Revision.reject_moderationRevisionMixin.save_revision的submitted_for_moderation参数WAGTAIL_MODERATION_ENABLEDwagtail.admin.userbar.ModeratePageItem、ApproveModerationEditPageItem、RejectModerationEditPageItemwagtail.admin.views.home.PagesForModerationPanelwagtail.admin.views.pages.moderationwagtail.permission_policies.pages.PagePermissionPolicy.revisions_for_moderation详情可回顾 Wagtail 2.10 发布说明。升级注意事项影响 Wagtail 定制代码classname命名约定Wagtail 从 4.2 开始推行统一的单数classname而非复数classnames约定5.2 将这一约定扩展到菜单与钩子体系。以下类采用新约定admin.menu.MenuItemadmin.ui.sidebar.ActionMenuItemadmin.ui.sidebar.LinkMenuItemadmin.ui.sidebar.PageExplorerMenuItemcontrib.settings.registry.SettingMenuItem以下钩子在使用classnames生成菜单项时可能受影响register_admin_menu_item、register_settings_menu_item钩子完整清单见 hooks 参考。旧的classnames关键字仍可用但会触发弃用警告未来版本将移除。示例注意第 8 行使用classnamefrom django.urls import reverse from wagtail import hooks from wagtail.admin.menu import MenuItem hooks.register(register_admin_menu_item) def register_frank_menu_item(): return MenuItem( Frank, reverse(frank), icon_namefolder-inverse, order10000, classnamehighlight-menu, # 不是 classnames... )ModelViewSet 的编辑/删除 URL 变更支持非整数主键为支持非整数主键模型ModelViewSet中编辑与删除视图的 URL 模式已变更。相对于视图集的url_prefix编辑 URL 由int:pk/改为edit/str:pk/删除 URL 由int:pk/delete/改为delete/str:pk/。若你通过django.urls.reverse配合get_url_name()生成 URL无需改动但若在代码中硬编码了这些 URL必须更新。旧 URL 的重定向仅为向后兼容保留未来版本会移除。SnippetViewSet中旧 URL 的重定向也已被标记为未来移除。ModelViewSet 自动注册引用索引通过ModelViewSet注册的模型默认启用引用索引追踪不再需要在 app 的ready()方法中手动调用ReferenceIndex.register_model()。若不希望如此可在ModelViewSet子类上设置add_to_reference_index False对应源码 wagtail/admin/viewsets/model.py。详见 引用索引管理文档。其他行为变更一览GroupViewSet的IndexView.results_template_name更名由wagtailusers/groups/results.html改为wagtailusers/groups/index_results.html自定义过该模板如 自定义组视图的项目需要同步重命名。construct_snippet_listing_buttons钩子不再接受context参数需要访问视图计算值的场景应改为覆盖SnippetViewSet.index_view_class自定义IndexView特别是get_list_buttons与get_list_more_buttons方法。旧签名会触发警告并收到空字典{}。页面列表/头部按钮钩子的page_perms参数被user取代register_page_header_buttons由func(page, page_perms, next_url)变为func(page, user, next_url, view_name)其中view_name为edit或indexregister_page_listing_buttons变为func(page, user, next_url)construct_page_listing_buttons变为fn(buttons, page, user, context)register_page_listing_more_buttons变为func(page, user, next_url)ButtonWithDropdownFromHook构造器同样改传user。旧代码如需获取权限测试对象可用page.permissions_for_user(user)替代。相关钩子说明见 hooks 参考。升级注意事项未文档化的内部变更面包屑类名由单数改为复数自定义面包屑样式时类名w-breadcrumb已改为w-breadcrumbs。Snippets 模板重构为复用slim_header.html以下 snippets 头部模板已被移除绝大多数场景可用wagtailadmin/shared/headers/slim_header.html替代wagtailsnippets/snippets/headers/_base_header.htmlcreate_header.html、edit_header.html、history_header.html、list_header.html、usage_header.html侧栏组合类移除BaseSidePanels、PageSidePanels、SnippetSidePanels类已移除每个侧栏现在直接在视图中实例化BasePreviewSidePanel/PagePreviewSidePanel/SnippetPreviewSidePanel合并为PreviewSidePanelBaseStatusSidePanel更名为StatusSidePanel。媒体对象可用wagtail.admin.ui.components.MediaContainer组合。旧写法from wagtail.admin.ui.side_panels import PageSidePanels def my_view(request): ... side_panels PageSidePanels( request, page.get_latest_revision_as_object(), show_schedule_publishing_toggleFalse, live_pagepage, scheduled_pagepage.get_scheduled_revision_as_object(), in_explorerFalse, preview_enabledTrue, comments_enabledFalse, ) return render( request, template_name, {page: page, side_panels: side_panels, media: side_panels.media}, )新写法from wagtail.admin.ui.components import MediaContainer from wagtail.admin.ui.side_panels import PageStatusSidePanel, PreviewSidePanel def my_view(request): ... side_panels [ PageStatusSidePanel( page, request, show_schedule_publishing_toggleFalse, live_objectpage, scheduled_objectpage.get_scheduled_revision_as_object(), localepage.locale, translationstranslations, ), PreviewSidePanel( page, request, preview_urlreverse(wagtailadmin_pages:preview_on_edit, args[page.id]), ), ] side_panels MediaContainer(side_panels) return render( request, template_name, {page: page, side_panels: side_panels, media: side_panels.media}, )面包屑迁移到 Stimulus事件与 data 属性变化头部面包屑组件已迁移到 Stimulus 控制器事件与 data 属性均发生变化自定义头部实现、以及未使用breadcrumbs却依赖展开/收起行为的自定义面包屑可能受影响旧事件新事件wagtail:breadcrumbs-expandw-breadcrumbs:openedwagtail:breadcrumbs-collapsew-breadcrumbs:closed旧 data 属性新 data 属性data-breadcrumb-nextdata-controllerw-breadcrumbsdata-toggle-breadcrumbsdata-w-breadcrumbs-targettoggle>window.updateFooterSaveWarning (formDirty, commentsDirty) { if (!formDirty !commentsDirty) { document.dispatchEvent(new CustomEvent(w-unsaved:clear)); } else { const [type] [ formDirty commentsDirty all, commentsDirty comments, formDirty edits, ].filter(Boolean); document.dispatchEvent(new CustomEvent(w-unsaved:add, { detail: { type } })); } };其他内部变更速查dropdown模板标签参数更名toggle_tippy_offset改为toggle_tooltip_offset例如{% dropdown toggle_tooltip_offset[0, -2] %}...{% enddropdown %}。escapescript模板标签与escape_script函数弃用它们是为已停止支持的 IE11 提供 HTML 模板内容转义且不符合 CSP请改用 HTMLtemplate元素避免内容被浏览器解析template idid_{{ formset.prefix }}-EMPTY_FORM_TEMPLATE divWidget template content/div script src/js/my-widget.js/script /template图片Format实例的classnames改为classname自定义格式代码中访问self.classnames仍可返回self.classname但会触发弃用警告应改为self.classname。search promotions 模块调整search_garbage_collect管理命令已彻底移除5.0 起迁移到searchpromotions_garbage_collect见 管理命令文档部分 URL 名称与模板从主 admin 搜索模块迁入 search promotions 模块例如 URL 名称wagtailsearch_admin:queries_chooser改为wagtailsearchpromotions:chooserchooser 相关模板路径相应迁移到 wagtail/contrib/search_promotions/ 模块内。Block.get_template新增value参数StreamField 块的get_template现在接收value与context旧签名def get_template(self, contextNone)应更新为def get_template(self, valueNone, contextNone)。结语Wagtail 5.2 作为一个 LTS 版本交出了相当扎实的成绩单picture/srcset_image为全站图片体积与碳足迹带来立竿见影的改善OpenSearch 补齐了搜索后端的可替代选择ModelViewSet的能力下沉让非 snippet 模型也能拥有完整后台成为现实Stimulus 的正式支持则标志着后台前端进入统一框架时代。与此同时5.2 也集中清理了一大批历史包袱旧版 moderation、classnames、page_perms钩子、旧侧栏组合类等升级时需要对照本文的变更清单逐一核对自定义代码。若你的项目正计划长期维护5.2 LTS 系列是当前值得认真评估的稳定基线。【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考