第三十四章 CSS/SCSS 与样式

篇别：第八篇 前端开发

与第三十二章的关系：资产 bundle 声明、__manifest__.py 中 assets 键、!default 变量覆盖、SCSS 编译顺序、主题模块最小结构 已并入 第三十二章 32.7。本章从 日常改样式、组件级 SCSS、图标与暗色策略 角度做 补充与练习，避免与 32.7 重复长文。

本章学习目标

  • 能在 组件旁 编写 scoped 或 BEM 风格 的 SCSS，并正确挂入 assets。
  • 理解 !default 与 变量覆盖顺序；知道 何时应回到 32.7 改 全局主题。
  • 熟悉 Font Awesome / Odoo UI Icons 在视图与 OWL 模板中的 典型写法（以当前版本文档为准）。
  • 能制定 暗色模式与可访问性 相关的 团队约定。

导读：先分清「主题」与「局部」

改品牌色、字体、导航高度 → 全局 SCSS 变量 + 32.7 资产顺序。某一列表上加徽章样式 → 组件 SCSS + 限定选择器，避免 !important 轰炸。混淆两者会导致 升级困难 与 选择器战争。

34.1 SCSS 开发

34.1.1 知识要点

  • 变量与嵌套：$local-padding 等 组件私有变量 放在 组件 scss 文件 顶部；嵌套 不宜过深（≤3 层 为宜）。
  • 选择器：优先 o_my_module_ 一类 前缀，降低与 标准 web 模块 冲突概率。
  • 加载顺序：在 __manifest__.py 的 web.assets_backend（或前端 bundle）末尾 追加 自定义文件，以便 覆盖（仍应 少用高特异性）。
  • 避免：直接改 addons/web/static 源码；一律 自定义模块扩展。

34.1.2 案例

static/src/components/book_badge/book_badge.scss

.o_library_book_badge {
    display: inline-flex;
    align-items: center;
    padding: 0.15rem 0.4rem;
    border-radius: 0.25rem;
    font-size: 0.75rem;
    background-color: $o-gray-200;
    &--available {
        background-color: $o-success;
        color: $o-white;
    }
}

34.1.3 截图占位

图 34-1 开发者工具查看编译后 CSS 与来源

34.1.4 本节练习

  1. 实操：在 测试模块 中覆盖 某一表单主按钮 的 hover 色（仅限测试库）。
  2. 简答：为何 长选择器链 不利于维护？

参考答案提示：2. 特异性过高、难以被主题覆盖、与 Odoo 升级 DOM 结构 脆弱绑定。

34.2 SCSS 继承体系（新增）

34.2.1 知识要点

  • !default：变量 首次定义可带默认值；在导入链前部 赋值可 覆盖 后续 !default（详见 32.7 表格）。
  • Odoo 变量：$o-brand-primary 等定义在 web 主题 SCSS；自定义主题模块用 before 插入点 抢先赋值。
  • 何时局部覆盖：仅 某一应用 需要 反差色 时，可在 该应用 assets 中加 scoped 根类 包裹变量（进阶）。

34.2.2 案例

$o-brand-primary: #123456 !default;

在 主题包 中 去掉 !default 并 置于 primary_variables 之前 的自定义文件里 强制覆盖（与 32.7 一致）。

34.2.3 截图占位

图 34-2 DevTools 中 CSS 变量与 SCSS 源映射

34.2.4 本节练习

  1. 简答：!default 的含义？
  2. 判断：在 任意 .scss 文件末尾修改 $o-brand-primary 总能生效。（ ）

参考答案提示：2. 错；取决于 导入顺序。

34.3 UI 图标（新增）

34.3.1 知识要点

  • Font Awesome：历史视图常用 <i class="fa fa-book"/>；具体版本与类名 以 bundled FA 为准。
  • Odoo UI Icons：新版本推 统一图标字体 / SVG（见官方 UI icons 文档）；OWL 模板 中优先 与官方组件一致 的写法。
  • 可访问性：装饰性图标 aria-hidden="true"；有意义按钮 配 aria-label 或 可见文本。

34.3.2 案例

<!-- 表单按钮图标（示意，类名以版本为准） -->
<button type="object" name="action_open_loans" class="btn btn-secondary" title="借阅记录">
    <i class="fa fa-list" title="借阅记录"/>
</button>

34.3.3 截图占位

图 34-3 图标文档或后台界面中的图标集

34.3.4 本节练习

  1. 实操：给 smart button 换 三种 fa-* 图标 对比 可读性。
  2. 简答：Spreadsheet 相关图标与 后台菜单图标 是否一定 同一套？

参考答案提示：2. 不一定；以 资产 bundle 与文档为准。

34.4 暗色模式与主题策略（补充）

34.4.1 知识要点

  • 若启用 暗色 / 对比度 主题：硬编码 #fff 背景 易 失效；优先 Odoo 语义变量（$o-view-background 等，以源码为准）。
  • 媒体查询：prefers-color-scheme 可与 用户设置 冲突；以 产品策略 为准。

34.4.2 本节练习

  1. 简答：暗色模式下 避免魔法数颜色 的两条规则。
  2. 拓展：阅读 32.7 中 主题模块目录，标出 你项目可复用的文件名。

本章综合练习

  1. 暗色模式（若启用）：变量组织 建议（全局 vs 组件 各一条）。
  2. 可维护性：团队约定 禁止魔法数颜色 的 落地方式（如 只允许 SCSS 变量）。
  3. 综合：升级 Odoo 小版本 后某视图 样式错乱，列出 三条 排查顺序（DOM 结构、选择器、资产顺序）。
  4. 实操：用 DevTools Coverage 粗测 自定义 SCSS 是否 重复打入多个 bundle（概念题可口述）。

本章对应白皮书目录：第三十四章 CSS/SCSS 与样式。