Wagtail UI 编码指南从浏览器兼容到 Stimulus 交互的完整开发规范【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtailWagtail 管理后台的用户界面由 Django 模板HTML、Sass 与 TailwindCSS、TypeScriptJavaScript以及经 SVGO 压缩的内联 SVG 图标共同构成。本文以 docs/contributing/ui_guidelines.md 为骨架系统梳理 Wagtail 前端开发的浏览器支持矩阵、无障碍a11y目标、HTML/CSS/JavaScript 编码规范、Stimulus 交互框架的控制器构建流程、多语言与 RTL 支持、图标与图片的使用约束以及 Styleguide 与 Storybook 模式库的本地运行方式并结合仓库源码client/scss/core.scss、client/tailwind.config.js、client/src/controllers/、wagtail/admin/wagtail_hooks.py等进行纵深印证帮助你为 Wagtail 贡献 UI 代码时一步到位地符合官方标准。技术栈总览Wagtail 管理界面admin的 UI 构建技术栈如下HTML基于 Django 模板语言 编写模板文件主要存放于wagtail/admin/templates/。CSS使用 Sass主样式表为 client/scss/core.scss。JavaScript使用 TypeScript源码位于client/src/交互框架以 Stimulus 为主。SVG图标全部采用内联 SVG使用 SVGO 压缩优化存放于wagtail/admin/templates/wagtailadmin/icons/。浏览器与设备支持Wagtail 面向广泛的设备与浏览器官方支持矩阵如下浏览器设备/OS版本Mobile SafariiOS 手机最近 2 个版本17、18Mobile SafariiOS 平板最近 2 个版本17、18ChromeAndroid最近 2 个版本Chrome桌面最近 2 个版本MS EdgeWindows最近 2 个版本Firefox桌面最新版本Firefox ESR桌面最新140SafarimacOS最近 3 个版本16、17、18Wagtail 的目标是保证在这些环境中正常工作开发标准同时确保站点在其他浏览器以及未来的浏览器上可用。明确不支持的浏览器/设备包括浏览器设备/OS版本Stock browser安卓自带浏览器Android全部IE桌面全部SafariWindows全部无障碍Accessibility目标Wagtail 面向使用各种辅助技术的用户追求的无障碍标准是 WCAG 2.1AA 级别并针对以下辅助技术进行测试与支持Windows Firefox ESR 下的 NVDA屏幕阅读器macOS Safari 下的 VoiceOverWindows Magnifier 与 macOS Zoom屏幕放大Windows voice access 与 macOS Voice Control语音控制iOS 上的 VoiceOver 或 Android 上的 TalkBackWindows 对比度主题Contrast Themes / 高对比度模式在实际开发与代码评审中Wagtail 依赖以下工具来发现无障碍问题axe-core/playwright作为集成测试的一部分运行 Axe 自动检查。Axe Chrome 扩展对指定页面做更全面的自动化测试。Accessibility Insights for Web Chrome 扩展用于半自动化测试与人工审计。已知的无障碍问题Wagtail 管理后台目前尚未做到完全无障碍团队会在日常维护和大版本重构中持续修复。已知问题清单见 “WCAG2.1 AA for CMS admin” 问题看板以及 2021 年无障碍审计文档其中说明了哪些部分已测试/未测试、问题对 WCAG 2.1 合规性的影响及对用户的影响程度。HTML 编码规范HTML 的格式化使用 djhtmllint 使用 Curlylint。规范要点编写 有效的、语义化的 HTML。遵循 ARIA 编写实践尤其是其中的核心原则“没有 ARIA 比错误的 ARIA 更好”No ARIA is better than Bad ARIA。ID 只用于语义class 只用于样式data-属性只用于 JavaScript 行为。属性排序id最前然后是class再是data-及其他属性其中 Stimulus 的data-controller排在data-属性最前面。注释一律使用 Django 模板注释语法{# ... #}而不是 HTML 注释。CSS 编码规范CSS 使用 Prettier 格式化、Stylelint lint。核心要求遵循 BEM 与 ITCSS 架构并大量使用 Tailwind 生成的工具类。熟悉 stylelint-config-wagtail 配置它规定了首选代码风格。font-size一律使用rem对文字提供绝对控制line-height优先使用无单位数值它基于font-size的倍数继承而非继承父元素的百分比。设计令牌颜色、字号等始终使用变量禁止硬编码具体值。所有供 Wagtail 站点实现者复用的样式统一使用w-前缀。样式表组织ITCSS 与 core.scss大部分样式被合并进单一主样式表core.css。这也是所有新样式的推荐做法——减少潜在样式冲突促进工具类与组件样式在不同视图间复用。core.scss内部的use导入按照 ITCSS 分层组织见 client/scss/core.scss文件夹内容ITCSS 层级settings变量、映射、字体1 Settingstoolsmixins、函数2 Toolsgeneric重置样式3 Genericelements无 class 的元素样式4 Elementsobjects未使用5 ObjectscomponentsBEM 块 class6 Componentsoverrides覆盖、工具类7 TrumpsITCSS 结构有两大例外vendor/中的遗留第三方样式按引入主样式表之前的顺序导入以避免兼容性问题如果可能这些样式应被改写成组件并下沉到级联更靠后的位置。layouts/中的遗留布局专用样式被导入在文件最末尾以匹配过去多样式表加载方式如果可能应改写成组件或工具类并上移到级联更靠前的位置。创建新样式时始终优先使用组件在components文件夹新增一个样式文件并在core.scss中use导入它。从源码看React 组件的样式与其组件同目录存放client/src/components/下如Sidebar、Minimap、PageExplorer等组件直接 import 同名 scss这是比放进 scss 文件夹更推荐的模式纯 scss 组件则位于 client/scss/components/涵盖按钮、下拉、弹窗、标签、消息、页头、工作流时间线等数十个组件。Tailwind 工具类导入在overrides/utilities.tailwind位于文件底部以便其优先于其他 CSS 类生效。全局样式所有样式共用以下全局约定使用非常古老版本的normalize.css作为 CSS reset见 client/scss/core.scss 中的generic/normalize导入。box-sizing: border-box元素始终继承父元素的box-sizing。全局 CSS 变量定义颜色供站点实现者修改。全局 CSS 变量定义字体族供站点实现者修改。--w-direction-factorCSS 变量默认1RTL 语言下为-1用于反转物理值transform、background-position的计算以及箭头等方向性图标/视觉元素的镜像。--w-density-factorCSS 变量控制 UI 信息密度默认1降低或提高该值可减小或增大界面元素的间距与尺寸。这些变量的定义可以在 client/tailwind.config.js 中看到addBase插件在:root, :host上声明了--w-font-sans、--w-font-mono、--w-density-factor: 1以及由设计令牌生成的色彩变量.w-density-snug类则将密度因子设为0.5。颜色主题通过.w-theme-system跟随系统偏好、.w-theme-dark强制深色两个类切换并同步设置color-scheme。Tailwind 使用方式Tailwind 用于通过其 theme 管理设计令牌并生成 CSS 工具类配置在 client/tailwind.config.js且基础配置设计为可复用于其他项目配置导出时prefix: w-直接以wagtail风格对外提供。Wagtail 使用 Tailwind 大部分核心插件并通过vanillaRTL插件覆盖让工具类在保持默认名称与设计令牌名的同时生成 CSS 逻辑属性 样式即自动适配 LTR/RTL而不是物理方向属性。工具类的使用建议将工具类数量控制在合理上限如果多个工具类相互依赖或频繁组合复用应提取为组件样式。避免使用与字号、字重等排版相关的工具类应改用 client/src/tokens/typography.js 中定义的高层级类型刻度type scale。源码中typeScale插件基于 theme 值为每个刻度生成组件类如.w-h1、.w-body等并把w-前缀先移除再交由 Tailwind 加回从而保证命名一致。Sass 使用方式Wagtail 将 Sass 用法控制在最低限度倾向用直白 vanilla CSS 而非高级 Sass 语法。完全避免的 Sass 特性Placeholders /extend会导致样式意外级联。颜色运算所有颜色都在 JavaScript 侧通过 Tailwind 定义以一致地生成 CSS 变量定义与文档。谨慎使用的 Sass 特性嵌套不要依赖深层 Sass 嵌套与过于具体的选择器。大多数样式只需 12 层嵌套特定 UI 状态允许 3 层最复杂场景最多 4 层。父选择器插值仅在类名中少量使用插值便于全项目搜索样式。Sass 变量优先用 Tailwind theme 变量复用设计令牌或当某属性随状态变化时使用 CSS 变量Sass 变量只作为这些场景的短别名或局部组件变量。Mixins仅当样式无法写成可复用组件或工具类时才新建 mixin。Sass 数学运算设计令牌大多定义在 Tailwind经 PostCSS 加载数学运算使用 CSScalc()而非 Sass。强制颜色模式Windows 高对比度强制颜色模式Windows High Contrast Mode / 对比度主题允许用户用自己的样式覆盖网站样式以提高可读性Wagtail 计划在全部样式中完整支持它。实践建议在背景色承担了元素定位语义的地方尤其是页面区域与浮层组件额外添加边框。media (forced-colors: active)覆盖只在没有更简单替代方案时使用应从编写 CSS 之初就按 WHCM 支持来写而不是用大范围覆盖。绝不使用forced-color-adjust: none它会破坏与大量自定义主题的兼容仅在组件依赖特定色相才能工作属反模式时才可能用到。源码侧client/tailwind.config.js 用addVariant注册了forced-colors变体media (forced-colors: active)并在variants.extend中为backgroundColor、width、height开启该变体方便在工具类层面如forced-colors:bg-[Canvas]直接支持高对比度。JavaScript 编码规范JavaScript 使用 Prettier 格式化、ESLint lint。要求遵循放宽版的 Airbnb 风格指南。熟悉 eslint-config-wagtail。Stimulus管理后台的轻量交互框架Wagtail 使用 Stimulus目前已有ActionController、DialogController、DropdownController、TabsController、AutosaveController、PreviewController、UnsavedController等 30 余个控制器。为什么选择 StimulusStimulus 是轻量级框架能简单直接地创建交互式 UI 元素。它通过数据属性的变化实现小规模响应式更新无需像 jQuery 那样到处手动init同时取代了内联script与 window 全局变量的做法降低了代码库复杂度。何时使用 StimulusStimulus 是 Wagtail 处理简单客户端交互的首选库适用场景交互确实需要 JavaScript否则优先只用 HTML 与 CSS 实现。部分逻辑定义在 HTML 模板中而非纯 JavaScript。交互简单不需要 React 这类重量级库。管理后台目前仍有一些 jQuery 代码用于类似场景但这属于遗留代码最终会被移除。新功能开发时应认真权衡是复用现有 jQuery还是用 Stimulus 重建更合适。如何构建一个 Stimulus 控制器官方推荐的构建流程以 client/src/controllers/ 目录约定为例先想好控制器命名保持简洁理想情况是一到两个单词文件名为 TitleCase如CountController.ts。从 HTML 模板开始尽可能在纯 HTML 中构建 UI并确保其符合无障碍与 CSS 规范。创建控制器文件放在client/src/controllers文件夹同时配套测试与 Storybook stories。测试文件命名如CountController.test.jsStorybook 故事如CountController.stories.js注意 stories 目前必须写成 JavaScript因为 Storybook 的编译产物会与 Stimulus 仅在实例化时添加 getter 的机制冲突详见 client/src/controllers/README.md。选择初始化生命周期方法按需使用 controller 生命周期回调connect、initialize。处理元素移除如果相关考虑受控元素从 DOM 中被移除的情况使用disconnect生命周期方法。用 JSDoc 注释记录控制器类与方法。使用 values 提供配置项与响应式状态尽量避免实例属性默认值优先用 falsy 或空值并避免过度使用 Object 类型。围绕小而离散的方法构建行为并通过 HTML 中声明的 Stimulus actions 驱动调用时机。以 client/src/controllers/CountController.ts 为例可以看到上述规范的完整落地它通过static values声明container、find、labels、min、total五个可配置值对应data-w-count-*-value属性通过static targets声明label、total两个 target通过connect()在挂载时立即计数并在totalValueChanged中响应式更新 label 文本与activeClass切换。HTML 侧只需声明data-controllerw-count即可启用div>{% blocktranslate trimmed %} Your content has been published. {% endblocktranslate %}从右到左RTL语言支持Wagtail 支持从右到左语言尤其是水平镜像布局的管理后台界面。保证 RTL 支持的规范尽量使用 CSS 逻辑属性 编写样式如margin-inline-start、inset-inline-start而非margin-left、left。对于只能用物理属性书写的样式transform、background-position 等使用--w-direction-factor变量值为 1 或 -1根据元素或页面的dir属性自动反转数值。最后手段才是使用[dirrtl]选择器。同时JavaScript 中的位置计算也必须反转方向DOM API 不支持逻辑值x 轴偏移永远从左开始需要在 JS 中根据dir处理。在 Tailwind 侧client/tailwind.config.js 通过vanillaRTL插件禁用了相应的物理属性核心插件vanillaRTL.disabledCorePlugins并用w-前缀 逻辑属性生成工具类从工具类层面就保证了 RTL 的正确性。图标IconsWagtail 图标使用内联 SVG既出于性能考虑也便于用 CSS 直接控制图标样式颜色、尺寸。图标文件位于wagtail/admin/templates/wagtailadmin/icons/关于站点实现者如何使用图标的完整说明见 docs/advanced_topics/icons.md。新增/更新图标的步骤先用 SVGO 压缩使用合适的压缩设置。手动移除多余属性设置viewBox属性移除width与height属性。手动添加id属性前缀为icon-图标名与文件名一致尽量保留源图标的命名。添加或保留许可信息以!--!开头的 HTML 注释形式书写例如 Font Awesome 图标写为!--! triangle-exclamation (solid): Font Awesome Pro 6.4.0 --。将图标加入 Wagtail 自己的register_iconshook 实现中按字母顺序排列。该实现在 wagtail/admin/wagtail_hooks.py形如hooks.register(register_icons) def register_icons(icons): for icon in [ arrow-down.svg, arrow-right-full.svg, # ... 按字母顺序排列 ]: icons.append(icon)更新图标表格前往 Styleguide按模板中的说明复制 Wagtail 图标表粘贴到 docs/_static/wagtail_icons_table.txt。如果图标需要 RTL 镜像如箭头等方向性图标添加classicon--directional属性。图片Images管理后台中的图片通过统一模式与组件展示使用{% image %}模板标签 渲染并自动缩放。规范始终使用max-缩放规则保证尺寸一致。CMS 中只使用max-165x165与max-800x600两种规格以提升性能进一步缩放交给 CSS 完成。在合适的地方尤其是视图会显示多张图片时添加loadinglazy属性。避免手动设置alt属性让 image 标签默认使用图片描述或标题。使用show-transparencyCSS 类让用户能看到视觉元素的透明区域。UI Styleguide样式指南模块为 Wagtail UI 开发新组件时可以借助官方提供的 contrib 模块wagtailstyleguide测试效果。安装方式把它加入INSTALLED_APPSINSTALLED_APPS ( # ... wagtail.contrib.styleguide, # ... )这会在管理后台的Settings 菜单中新增一个 “Styleguide” 项其视图实现在 wagtail/contrib/styleguide/views.pyIndexView基于WagtailAdminTemplateMixinTemplateView。当前说明Styleguide 是静态的新 UI 组件必须手动加入目前没有供其他模块使用的专门 hook。它会包含insert_editor_jshook 的输出因此任何自定义编辑表单的 JavaScript 也会被展示。官方计划未来支持专门的 styleguide hooks。Styleguide 目前并未覆盖全部核心界面组件尤其缺少 Page、Document、Image、Snippet 选择器界面。使用模式库Pattern Library / StorybookWagtail 的 UI 组件库基于 Storybook 与 django-pattern-library 构建。本地运行方式export DJANGO_SETTINGS_MODULEwagtail.test.settings_ui # 假设当前环境已包含可用于本地开发的 Wagtail 安装 ./wagtail/test/manage.py migrate ./wagtail/test/manage.py createcachetable ./wagtail/test/manage.py runserver 0:8000 # 在另一个终端中 npm run storybook最后一条命令会在http://localhost:6006/启动 Storybook默认将特定请求代理到http://localhost:8000的 Django。如需给 Django 使用其他端口可通过TEST_ORIGIN环境变量指定TEST_ORIGINhttp://localhost:9000 npm run storybookStorybook 的相关配置位于 client/storybook/main.jsStimulus 的包装组件见 client/storybook/StimulusWrapper.tsx每个 Stimulus 控制器都配有对应的*.stories.js文件如ActionController.stories.js、FormsetController.stories.js用于在模式库中预览其交互行为。小结Wagtail 的 UI 开发规范可以概括为几条主线用 BEM ITCSS Tailwind 工具类组织样式并以w-前缀保证可复用性、用 Stimulus data-属性承载轻量交互、用逻辑属性与--w-direction-factor保障 RTL、用内联 SVG SVGO 管理图标、以 WCAG 2.1 AA 与官方浏览器矩阵作为质量底线。无论是为管理后台贡献新组件还是为站点实现自定义界面遵循本指南都能让代码与 Wagtail 的既有体系无缝衔接并借助 Styleguide 与 Storybook 快速完成可视化验证。【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Wagtail UI 编码指南：从浏览器兼容到 Stimulus 交互的完整开发规范
Wagtail UI 编码指南从浏览器兼容到 Stimulus 交互的完整开发规范【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtailWagtail 管理后台的用户界面由 Django 模板HTML、Sass 与 TailwindCSS、TypeScriptJavaScript以及经 SVGO 压缩的内联 SVG 图标共同构成。本文以 docs/contributing/ui_guidelines.md 为骨架系统梳理 Wagtail 前端开发的浏览器支持矩阵、无障碍a11y目标、HTML/CSS/JavaScript 编码规范、Stimulus 交互框架的控制器构建流程、多语言与 RTL 支持、图标与图片的使用约束以及 Styleguide 与 Storybook 模式库的本地运行方式并结合仓库源码client/scss/core.scss、client/tailwind.config.js、client/src/controllers/、wagtail/admin/wagtail_hooks.py等进行纵深印证帮助你为 Wagtail 贡献 UI 代码时一步到位地符合官方标准。技术栈总览Wagtail 管理界面admin的 UI 构建技术栈如下HTML基于 Django 模板语言 编写模板文件主要存放于wagtail/admin/templates/。CSS使用 Sass主样式表为 client/scss/core.scss。JavaScript使用 TypeScript源码位于client/src/交互框架以 Stimulus 为主。SVG图标全部采用内联 SVG使用 SVGO 压缩优化存放于wagtail/admin/templates/wagtailadmin/icons/。浏览器与设备支持Wagtail 面向广泛的设备与浏览器官方支持矩阵如下浏览器设备/OS版本Mobile SafariiOS 手机最近 2 个版本17、18Mobile SafariiOS 平板最近 2 个版本17、18ChromeAndroid最近 2 个版本Chrome桌面最近 2 个版本MS EdgeWindows最近 2 个版本Firefox桌面最新版本Firefox ESR桌面最新140SafarimacOS最近 3 个版本16、17、18Wagtail 的目标是保证在这些环境中正常工作开发标准同时确保站点在其他浏览器以及未来的浏览器上可用。明确不支持的浏览器/设备包括浏览器设备/OS版本Stock browser安卓自带浏览器Android全部IE桌面全部SafariWindows全部无障碍Accessibility目标Wagtail 面向使用各种辅助技术的用户追求的无障碍标准是 WCAG 2.1AA 级别并针对以下辅助技术进行测试与支持Windows Firefox ESR 下的 NVDA屏幕阅读器macOS Safari 下的 VoiceOverWindows Magnifier 与 macOS Zoom屏幕放大Windows voice access 与 macOS Voice Control语音控制iOS 上的 VoiceOver 或 Android 上的 TalkBackWindows 对比度主题Contrast Themes / 高对比度模式在实际开发与代码评审中Wagtail 依赖以下工具来发现无障碍问题axe-core/playwright作为集成测试的一部分运行 Axe 自动检查。Axe Chrome 扩展对指定页面做更全面的自动化测试。Accessibility Insights for Web Chrome 扩展用于半自动化测试与人工审计。已知的无障碍问题Wagtail 管理后台目前尚未做到完全无障碍团队会在日常维护和大版本重构中持续修复。已知问题清单见 “WCAG2.1 AA for CMS admin” 问题看板以及 2021 年无障碍审计文档其中说明了哪些部分已测试/未测试、问题对 WCAG 2.1 合规性的影响及对用户的影响程度。HTML 编码规范HTML 的格式化使用 djhtmllint 使用 Curlylint。规范要点编写 有效的、语义化的 HTML。遵循 ARIA 编写实践尤其是其中的核心原则“没有 ARIA 比错误的 ARIA 更好”No ARIA is better than Bad ARIA。ID 只用于语义class 只用于样式data-属性只用于 JavaScript 行为。属性排序id最前然后是class再是data-及其他属性其中 Stimulus 的data-controller排在data-属性最前面。注释一律使用 Django 模板注释语法{# ... #}而不是 HTML 注释。CSS 编码规范CSS 使用 Prettier 格式化、Stylelint lint。核心要求遵循 BEM 与 ITCSS 架构并大量使用 Tailwind 生成的工具类。熟悉 stylelint-config-wagtail 配置它规定了首选代码风格。font-size一律使用rem对文字提供绝对控制line-height优先使用无单位数值它基于font-size的倍数继承而非继承父元素的百分比。设计令牌颜色、字号等始终使用变量禁止硬编码具体值。所有供 Wagtail 站点实现者复用的样式统一使用w-前缀。样式表组织ITCSS 与 core.scss大部分样式被合并进单一主样式表core.css。这也是所有新样式的推荐做法——减少潜在样式冲突促进工具类与组件样式在不同视图间复用。core.scss内部的use导入按照 ITCSS 分层组织见 client/scss/core.scss文件夹内容ITCSS 层级settings变量、映射、字体1 Settingstoolsmixins、函数2 Toolsgeneric重置样式3 Genericelements无 class 的元素样式4 Elementsobjects未使用5 ObjectscomponentsBEM 块 class6 Componentsoverrides覆盖、工具类7 TrumpsITCSS 结构有两大例外vendor/中的遗留第三方样式按引入主样式表之前的顺序导入以避免兼容性问题如果可能这些样式应被改写成组件并下沉到级联更靠后的位置。layouts/中的遗留布局专用样式被导入在文件最末尾以匹配过去多样式表加载方式如果可能应改写成组件或工具类并上移到级联更靠前的位置。创建新样式时始终优先使用组件在components文件夹新增一个样式文件并在core.scss中use导入它。从源码看React 组件的样式与其组件同目录存放client/src/components/下如Sidebar、Minimap、PageExplorer等组件直接 import 同名 scss这是比放进 scss 文件夹更推荐的模式纯 scss 组件则位于 client/scss/components/涵盖按钮、下拉、弹窗、标签、消息、页头、工作流时间线等数十个组件。Tailwind 工具类导入在overrides/utilities.tailwind位于文件底部以便其优先于其他 CSS 类生效。全局样式所有样式共用以下全局约定使用非常古老版本的normalize.css作为 CSS reset见 client/scss/core.scss 中的generic/normalize导入。box-sizing: border-box元素始终继承父元素的box-sizing。全局 CSS 变量定义颜色供站点实现者修改。全局 CSS 变量定义字体族供站点实现者修改。--w-direction-factorCSS 变量默认1RTL 语言下为-1用于反转物理值transform、background-position的计算以及箭头等方向性图标/视觉元素的镜像。--w-density-factorCSS 变量控制 UI 信息密度默认1降低或提高该值可减小或增大界面元素的间距与尺寸。这些变量的定义可以在 client/tailwind.config.js 中看到addBase插件在:root, :host上声明了--w-font-sans、--w-font-mono、--w-density-factor: 1以及由设计令牌生成的色彩变量.w-density-snug类则将密度因子设为0.5。颜色主题通过.w-theme-system跟随系统偏好、.w-theme-dark强制深色两个类切换并同步设置color-scheme。Tailwind 使用方式Tailwind 用于通过其 theme 管理设计令牌并生成 CSS 工具类配置在 client/tailwind.config.js且基础配置设计为可复用于其他项目配置导出时prefix: w-直接以wagtail风格对外提供。Wagtail 使用 Tailwind 大部分核心插件并通过vanillaRTL插件覆盖让工具类在保持默认名称与设计令牌名的同时生成 CSS 逻辑属性 样式即自动适配 LTR/RTL而不是物理方向属性。工具类的使用建议将工具类数量控制在合理上限如果多个工具类相互依赖或频繁组合复用应提取为组件样式。避免使用与字号、字重等排版相关的工具类应改用 client/src/tokens/typography.js 中定义的高层级类型刻度type scale。源码中typeScale插件基于 theme 值为每个刻度生成组件类如.w-h1、.w-body等并把w-前缀先移除再交由 Tailwind 加回从而保证命名一致。Sass 使用方式Wagtail 将 Sass 用法控制在最低限度倾向用直白 vanilla CSS 而非高级 Sass 语法。完全避免的 Sass 特性Placeholders /extend会导致样式意外级联。颜色运算所有颜色都在 JavaScript 侧通过 Tailwind 定义以一致地生成 CSS 变量定义与文档。谨慎使用的 Sass 特性嵌套不要依赖深层 Sass 嵌套与过于具体的选择器。大多数样式只需 12 层嵌套特定 UI 状态允许 3 层最复杂场景最多 4 层。父选择器插值仅在类名中少量使用插值便于全项目搜索样式。Sass 变量优先用 Tailwind theme 变量复用设计令牌或当某属性随状态变化时使用 CSS 变量Sass 变量只作为这些场景的短别名或局部组件变量。Mixins仅当样式无法写成可复用组件或工具类时才新建 mixin。Sass 数学运算设计令牌大多定义在 Tailwind经 PostCSS 加载数学运算使用 CSScalc()而非 Sass。强制颜色模式Windows 高对比度强制颜色模式Windows High Contrast Mode / 对比度主题允许用户用自己的样式覆盖网站样式以提高可读性Wagtail 计划在全部样式中完整支持它。实践建议在背景色承担了元素定位语义的地方尤其是页面区域与浮层组件额外添加边框。media (forced-colors: active)覆盖只在没有更简单替代方案时使用应从编写 CSS 之初就按 WHCM 支持来写而不是用大范围覆盖。绝不使用forced-color-adjust: none它会破坏与大量自定义主题的兼容仅在组件依赖特定色相才能工作属反模式时才可能用到。源码侧client/tailwind.config.js 用addVariant注册了forced-colors变体media (forced-colors: active)并在variants.extend中为backgroundColor、width、height开启该变体方便在工具类层面如forced-colors:bg-[Canvas]直接支持高对比度。JavaScript 编码规范JavaScript 使用 Prettier 格式化、ESLint lint。要求遵循放宽版的 Airbnb 风格指南。熟悉 eslint-config-wagtail。Stimulus管理后台的轻量交互框架Wagtail 使用 Stimulus目前已有ActionController、DialogController、DropdownController、TabsController、AutosaveController、PreviewController、UnsavedController等 30 余个控制器。为什么选择 StimulusStimulus 是轻量级框架能简单直接地创建交互式 UI 元素。它通过数据属性的变化实现小规模响应式更新无需像 jQuery 那样到处手动init同时取代了内联script与 window 全局变量的做法降低了代码库复杂度。何时使用 StimulusStimulus 是 Wagtail 处理简单客户端交互的首选库适用场景交互确实需要 JavaScript否则优先只用 HTML 与 CSS 实现。部分逻辑定义在 HTML 模板中而非纯 JavaScript。交互简单不需要 React 这类重量级库。管理后台目前仍有一些 jQuery 代码用于类似场景但这属于遗留代码最终会被移除。新功能开发时应认真权衡是复用现有 jQuery还是用 Stimulus 重建更合适。如何构建一个 Stimulus 控制器官方推荐的构建流程以 client/src/controllers/ 目录约定为例先想好控制器命名保持简洁理想情况是一到两个单词文件名为 TitleCase如CountController.ts。从 HTML 模板开始尽可能在纯 HTML 中构建 UI并确保其符合无障碍与 CSS 规范。创建控制器文件放在client/src/controllers文件夹同时配套测试与 Storybook stories。测试文件命名如CountController.test.jsStorybook 故事如CountController.stories.js注意 stories 目前必须写成 JavaScript因为 Storybook 的编译产物会与 Stimulus 仅在实例化时添加 getter 的机制冲突详见 client/src/controllers/README.md。选择初始化生命周期方法按需使用 controller 生命周期回调connect、initialize。处理元素移除如果相关考虑受控元素从 DOM 中被移除的情况使用disconnect生命周期方法。用 JSDoc 注释记录控制器类与方法。使用 values 提供配置项与响应式状态尽量避免实例属性默认值优先用 falsy 或空值并避免过度使用 Object 类型。围绕小而离散的方法构建行为并通过 HTML 中声明的 Stimulus actions 驱动调用时机。以 client/src/controllers/CountController.ts 为例可以看到上述规范的完整落地它通过static values声明container、find、labels、min、total五个可配置值对应data-w-count-*-value属性通过static targets声明label、total两个 target通过connect()在挂载时立即计数并在totalValueChanged中响应式更新 label 文本与activeClass切换。HTML 侧只需声明data-controllerw-count即可启用div>{% blocktranslate trimmed %} Your content has been published. {% endblocktranslate %}从右到左RTL语言支持Wagtail 支持从右到左语言尤其是水平镜像布局的管理后台界面。保证 RTL 支持的规范尽量使用 CSS 逻辑属性 编写样式如margin-inline-start、inset-inline-start而非margin-left、left。对于只能用物理属性书写的样式transform、background-position 等使用--w-direction-factor变量值为 1 或 -1根据元素或页面的dir属性自动反转数值。最后手段才是使用[dirrtl]选择器。同时JavaScript 中的位置计算也必须反转方向DOM API 不支持逻辑值x 轴偏移永远从左开始需要在 JS 中根据dir处理。在 Tailwind 侧client/tailwind.config.js 通过vanillaRTL插件禁用了相应的物理属性核心插件vanillaRTL.disabledCorePlugins并用w-前缀 逻辑属性生成工具类从工具类层面就保证了 RTL 的正确性。图标IconsWagtail 图标使用内联 SVG既出于性能考虑也便于用 CSS 直接控制图标样式颜色、尺寸。图标文件位于wagtail/admin/templates/wagtailadmin/icons/关于站点实现者如何使用图标的完整说明见 docs/advanced_topics/icons.md。新增/更新图标的步骤先用 SVGO 压缩使用合适的压缩设置。手动移除多余属性设置viewBox属性移除width与height属性。手动添加id属性前缀为icon-图标名与文件名一致尽量保留源图标的命名。添加或保留许可信息以!--!开头的 HTML 注释形式书写例如 Font Awesome 图标写为!--! triangle-exclamation (solid): Font Awesome Pro 6.4.0 --。将图标加入 Wagtail 自己的register_iconshook 实现中按字母顺序排列。该实现在 wagtail/admin/wagtail_hooks.py形如hooks.register(register_icons) def register_icons(icons): for icon in [ arrow-down.svg, arrow-right-full.svg, # ... 按字母顺序排列 ]: icons.append(icon)更新图标表格前往 Styleguide按模板中的说明复制 Wagtail 图标表粘贴到 docs/_static/wagtail_icons_table.txt。如果图标需要 RTL 镜像如箭头等方向性图标添加classicon--directional属性。图片Images管理后台中的图片通过统一模式与组件展示使用{% image %}模板标签 渲染并自动缩放。规范始终使用max-缩放规则保证尺寸一致。CMS 中只使用max-165x165与max-800x600两种规格以提升性能进一步缩放交给 CSS 完成。在合适的地方尤其是视图会显示多张图片时添加loadinglazy属性。避免手动设置alt属性让 image 标签默认使用图片描述或标题。使用show-transparencyCSS 类让用户能看到视觉元素的透明区域。UI Styleguide样式指南模块为 Wagtail UI 开发新组件时可以借助官方提供的 contrib 模块wagtailstyleguide测试效果。安装方式把它加入INSTALLED_APPSINSTALLED_APPS ( # ... wagtail.contrib.styleguide, # ... )这会在管理后台的Settings 菜单中新增一个 “Styleguide” 项其视图实现在 wagtail/contrib/styleguide/views.pyIndexView基于WagtailAdminTemplateMixinTemplateView。当前说明Styleguide 是静态的新 UI 组件必须手动加入目前没有供其他模块使用的专门 hook。它会包含insert_editor_jshook 的输出因此任何自定义编辑表单的 JavaScript 也会被展示。官方计划未来支持专门的 styleguide hooks。Styleguide 目前并未覆盖全部核心界面组件尤其缺少 Page、Document、Image、Snippet 选择器界面。使用模式库Pattern Library / StorybookWagtail 的 UI 组件库基于 Storybook 与 django-pattern-library 构建。本地运行方式export DJANGO_SETTINGS_MODULEwagtail.test.settings_ui # 假设当前环境已包含可用于本地开发的 Wagtail 安装 ./wagtail/test/manage.py migrate ./wagtail/test/manage.py createcachetable ./wagtail/test/manage.py runserver 0:8000 # 在另一个终端中 npm run storybook最后一条命令会在http://localhost:6006/启动 Storybook默认将特定请求代理到http://localhost:8000的 Django。如需给 Django 使用其他端口可通过TEST_ORIGIN环境变量指定TEST_ORIGINhttp://localhost:9000 npm run storybookStorybook 的相关配置位于 client/storybook/main.jsStimulus 的包装组件见 client/storybook/StimulusWrapper.tsx每个 Stimulus 控制器都配有对应的*.stories.js文件如ActionController.stories.js、FormsetController.stories.js用于在模式库中预览其交互行为。小结Wagtail 的 UI 开发规范可以概括为几条主线用 BEM ITCSS Tailwind 工具类组织样式并以w-前缀保证可复用性、用 Stimulus data-属性承载轻量交互、用逻辑属性与--w-direction-factor保障 RTL、用内联 SVG SVGO 管理图标、以 WCAG 2.1 AA 与官方浏览器矩阵作为质量底线。无论是为管理后台贡献新组件还是为站点实现自定义界面遵循本指南都能让代码与 Wagtail 的既有体系无缝衔接并借助 Styleguide 与 Storybook 快速完成可视化验证。【免费下载链接】wagtailA Django content management system focused on flexibility and user experience项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考