Wagtail 1.5 发布说明解析：页面探索器动作重组、ModelAdmin 与 TableBlock，以及升级注意事项

Wagtail 1.5 发布说明解析页面探索器动作重组、ModelAdmin 与 TableBlock以及升级注意事项【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtailWagtail 1.52016 年 5 月 1 日发布是一次以管理后台体验为核心的重要版本它重组了页面探索器的操作按钮、将wagtailmodeladmin正式并入wagtail.contrib.modeladmin、新增了TableBlock流字段块并显著改进了富文本链接的编辑体验。阅读本文后你将掌握 1.5 版本的全部新特性与次要功能清单、修复的缺陷以及四项必须了解的升级注意事项按钮样式类、search_fields类型变更、Elasticsearch SSL 校验默认值、项目模板 settings 导入方式并能结合当前仓库源码验证这些特性的实现位置。版本定位1.5 的发布说明docs/releases/1.5.rst按“新特性 / 次要功能 / 缺陷修复 / 升级注意事项”四个部分组织。对于仍然基于 1.5 时代代码库做历史考证、或需要从该版本向前迁移的项目这份文档是核心依据对于理解当前代码库中诸多机制的由来如register_page_listing_buttons钩子、WAGTAIL_APPEND_SLASH设置项它同样是指明起点的入口。Whats new四大核心特性页面探索器操作按钮重组与 register_page_listing_buttons 钩子1.5 对页面探索器Page Explorer的操作按钮做了重新组织以减少界面杂乱低频使用的动作被收进一个 “More” 下拉菜单。同时新增了register_page_listing_buttons钩子允许第三方应用向页面列表添加自定义操作按钮。在当前仓库中可以追踪到该钩子的完整链路钩子的注册侧wagtail/admin/wagtail_hooks.py 中hooks.register(register_page_listing_buttons)装饰的page_listing_buttons函数通过yield ButtonWithDropdownFromHook(...)产出内置按钮其中 “More” 下拉本身又由register_page_listing_more_buttons钩子填充——这正是 1.5 引入的按钮重组在源码中的体现钩子的消费侧wagtail/admin/templatetags/wagtailadmin_tags.py 中通过hooks.get_hooks(register_page_listing_buttons)取出所有注册的按钮并在模板中渲染。需要说明的是1.5 发布说明中记录的钩子签名为(page, request)从当前仓库的调用链传入page, user, next_url可以看出其签名在此后版本中经历了演进若要将 1.5 时代的自定义按钮代码移植到新版本需要按新的签名调整。ModelAdmin 并入核心贡献包Wagtail 1.5 将此前以独立包wagtailmodeladmin形式分发的功能正式收编为wagtail.contrib.modeladmin应用。它允许把任意 Django 模型不限于Page、Snippet配置为在 Wagtail 后台中列表、新增和编辑使后台成为所有后台模型的统一入口。该特性由 Andy Babic 开发。1.5 时期文档中的使用方式为在项目settings.py的INSTALLED_APPS中加入wagtail.contrib.modeladmin然后定义继承自ModelAdmin的类并用register_app注册——这套模式是后来 Snippet 体系演进的基础理解它对追溯 Wagtail 后台模型管理的历史脉络很有帮助。TableBlock表格型内容的 StreamField 块TableBlock是一种新的 StreamField 块类型用于编辑表格型内容可通过wagtail.contrib.table_block模块使用。它由 Moritz Pfeiffer、David Seddon 和 Brad Busenius 共同开发。对应的使用文档见 table_block 参考仓库中还提供了类型化扩展版本 typed_table_block 参考可用于在表格单元中放置结构化的 StreamField 块内容。富文本链接处理的改进1.5 大幅改善了富文本区域内插入、编辑和删除链接的用户体验链接目标地址会以下悬提示tooltip形式显示已存在的链接既可以编辑也可以取消链接unlink。该特性由 Loic Teixeira 开发。这一交互是后来 Draftail 富文本编辑器中链接操作的基础体验。“Image serve view”动态图片服务视图增强Image serve view 用于从外部应用请求图片缩略图。1.5 对其做了五项改进新增 “redirect” 动作视图可以重定向到缩放后图片实际托管的位置而不是直接由应用输出图片。若图片托管在外部存储如 S3这对性能有利可选的路径组件URL 末尾可以附加一个文件名便于生成带语义的图片 URL密钥可配置视图的签名 key 可单独配置不再强制使用项目的SECRET_KEY重构为类视图CBV可以基于不同的图片模型和不同的 key 创建多个 serve view 实例支持 django-sendfile图片文件输出可走 sendfile由 Yannick Chabbert 实现。在当前仓库中图片服务视图位于 wagtail/images/views/serve.py其后继实现仍延续了“签名 key 可配置、多视图实例”的设计思路。次要功能清单1.5 还包含一批面向具体场景的改进按主题归类如下搜索相关可搜索模型如Page或自定义Image模型上的search_fields属性类型从元组tuple变为列表list——这同时是一项升级注意事项见下文update_index管理命令新增--schema-only选项可仅创建/更新索引 schema 而不重建全部索引。URL 与路由新增WAGTAIL_APPEND_SLASH设置项决定页面 URL 是否以斜杠结尾。在当前仓库中仍可看到它的定义wagtail/coreutils.py 中WAGTAIL_APPEND_SLASH getattr(settings, WAGTAIL_APPEND_SLASH, True)默认Truewagtail/urls.py 据此选择不同的 URL 匹配规则wagtail/models/pages.py 在页面路由时也引用该值无主视图的 Routable page 不再抛出TypeError该机制详见 Routable page 文档。模板与钩子settings模板标签支持 Jinja2新增insert_global_admin_js钩子用于在后台各页面注入自定义 JavaScript项目模板改为显式通过settings.dev导入开发设置升级注意事项之一内部预留了替换富文本编辑器的机制。模型与上传为AbstractRendition增加get_upload_to方法覆盖后可控制图片 rendition 的存储位置。当前仓库中该方法保留在 wagtail/images/models.pyAbstractRendition.get_upload_to与文档记载一致新增定制 add/edit 用户表单的机制以适配自定义用户模型发布说明中引用了custom_user_models文档为StreamBlock内的字段控件支持 media 资源为StreamField块提供有意义的默认图标。后台体验密码重置邮件会提示用户名修改密码改用PasswordChangeForm要求输入当前密码页面列表新增 “revisions” 动作站点创建/编辑的通知消息包含站点名日期选择器高亮当前日期并修复了只在正确月份高亮的缺陷站点设置的 Save 按钮放大并加了 spinner后台登出后有成功提示多图上传器现在会显示服务端错误详情页面探索器的操作按钮加上 title 文本识别带www前缀的 Instagram 嵌入 URL。性能Site.find_for_request优化为只执行一次数据库查询此前会按 Site 列表逐个查询。Bug fixes 摘要1.5 修复的缺陷可分为四类图片服务无源文件的图片经 “dynamic serve view” 缩放时崩溃的问题被修复搜索模型创建/更新/删除时搜索索引出错现在只记录日志而不再让整个操作失败对象删除后现在会正确地从索引中移除后台与表单所有可能包含文件上传的后台表单现在正确声明multipart/form-data注册过的 settings 后台菜单项正确显示激活状态Document模型的直接引用在wagtail.contrib.wagtailmedusa与wagtail.contrib.wagtailapi中替换为get_document_model函数decorate_urlpatterns改用functools.update_wrapper以保留视图名称和 docstring前端细节Wagtailuserbar 中 REM 单位导致的间距错误、Explorer 菜单随页面滚动、StreamField 菜单遮挡新插入块的控件、以及一个阻止字符串被收录翻译的无效__别名用法等均已修复。Upgrade considerations升级必读的四项变更1. 后台按钮现在必须显式添加classbuttonWagtail 后台 CSS 为可维护性做了重构按钮样式不再自动作用于所有type为submit、reset或button的input而是要求显式的button类。如果你的应用扩展了 Wagtail 后台新增视图/模板需要为所有按钮补上这个类否则升级后按钮会失去样式。2.search_fields应改为列表可搜索模型上的search_fields现在应使用 list 而非 tuple。例如旧的写法class MyPage(Page): ... search_fields Page.search_fields ( indexed.SearchField(body), )应改为class MyPage(Page): ... search_fields Page.search_fields [ indexed.SearchField(body), ]为减轻第三方模块的负担向Page.search_fields追加元组在过渡期仍然有效但官方声明这一向后兼容处理将在 Wagtail 1.7 移除——升级时应尽快统一为列表。3. Elasticsearch 后端默认校验 SSL 证书此前使用URLS属性配置 Elasticsearch 后端时WAGTAILSEARCH_BACKENDS { default: { BACKEND: wagtail.wagtailsearch.backends.elasticsearch, URLS: [https://example.com/], } }HTTPS 连接不会校验 SSL 证书。1.5 起改为默认校验。如需恢复旧行为应改用HOSTS选项显式关闭校验WAGTAILSEARCH_BACKENDS { default: { BACKEND: wagtail.wagtailsearch.backends.elasticsearch, HOSTS: [{ host: example.com use_ssl: True, verify_certs: False, }], } }更多配置项可参考 elasticsearch-py 官方文档中的 SSL 与认证章节。4. 项目模板显式导入settings.dev此前项目模板的settings/__init__.py会导入开发设置settings/dev.py使其在未显式指定 settings 模块时成为默认。但这在某些部署环境下导致生产模式误加载开发设置。因此 1.5 移除了该导入现在所有命令必须显式指定myproject.settings.dev或myproject.settings.production配套脚本如manage.py已相应更新。从源码结构看当前仓库中的项目模板模板文件 wagtail/project_template/manage.py-tpl 依然执行os.environ.setdefault(DJANGO_SETTINGS_MODULE, {{ project_name }}.settings.dev)印证了这一约定延续至今。既有项目不受影响但任何依赖“直接导入myproject.settings”的公共脚本或配置文件需要在 1.5 之后创建的项目上更新。延伸阅读发布说明原文docs/releases/1.5.rstTableBlock 参考docs/reference/contrib/table_block.md页面列表按钮钩子实现wagtail/admin/wagtail_hooks.py、wagtail/admin/templatetags/wagtailadmin_tags.pyWAGTAIL_APPEND_SLASH定义与消费wagtail/coreutils.py、wagtail/urls.pyrendition 存储位置定制wagtail/images/models.py需要强调的前提本文以 1.5 发布说明为准描述当时的行为仓库中大量机制钩子签名、Elasticsearch 后端、管理命令等在此后版本已演进。若你当前维护的是新版 Wagtail请以docs/releases/下对应版本的发布说明为准1.5 说明的价值在于理解这些机制的引入背景与历史约束。【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考