主题制作

在开发环境完全搭建好之后，您就可以开始构建主题模块的骨架了。本章将介绍如何：

• 启用/禁用网站构建器的标准选项和模板。

• 定义用于设计的颜色和字体。

• 充分利用 Bootstrap 变量。

• 添加自定义样式和 JavaScript。

主题模块

Odoo 自带一个默认主题，它提供了最基本的结构和布局。当您创建新主题时，实际上是在扩展默认主题。

请记得在开发环境中运行 Odoo 时，将包含您模块的目录添加到 addons-path 命令行参数中。

技术命名

第一步是创建一个新目录。

website_airproof

Note

为其添加 website_ 前缀，并且只使用小写 ASCII 字母数字字符和下划线。

在本文档中，我们将以 Airproof （一个虚构的项目）为例。

文件结构

主题的打包方式与任何 Odoo 模块相同。即使您正在设计一个基础网站，也需要像打包模块一样打包它的主题。

website_airproof
├── data
├── i18n
├── static
│   ├── description
│   ├── fonts
│   ├── lib
│   ├── shapes // Shapes for background
│   └── src
│       ├── img
│       │   ├── content // For those used in the pages of your website
│       │   └── wbuilder // For those used in the builder
│       ├── js
│       ├── scss // Theme specific styles
│       └── snippets // custom snippets
├── views
├── __init__.py
└── __manifest__.py

文件夹	说明
data	预设、菜单、页面、图像、形状等（*.xml）
i18n	翻译文件（*.po、*.pot）
lib	外部库（*.js）
static	自定义资源（*.jpg、*.gif、*.png、*.svg、*.pdf、*.scss、*.js）
views	自定义视图和模板（*.xml）

初始化

Odoo 模块也是一个 Python 包，其中包含一个 __init__.py 文件，用于导入模块中的各个 Python 文件。目前该文件可以保持为空。

声明

Odoo 模块通过其清单文件进行声明。该文件将一个 Python 包声明为 Odoo 模块，并指定模块的元数据。它至少必须包含 name 字段，该字段始终是必需的。通常它还会包含更多信息。

/website_airproof/__manifest__.py

{
   'name': 'Airproof Theme',
   'description': '...',
   'category': 'Website/Theme',
   'version': '18.0.0',
   'author': '...',
   'license': '...',
   'depends': ['website'],
   'data': [
      # ...
   ],
   'assets': {
      # ...
   },
}

字段	说明
name	模块的易读名称（必填）
description	模块的扩展描述，使用 reStructuredText 编写
category	Odoo 内的分类类别
version	此模块所针对的 Odoo 版本
author	模块作者的名称
license	默认情况下，我们使用 LGPL-3 许可证。更多信息请参阅 模块清单 页面。
depends	这些 Odoo 模块必须先于本模块加载，原因可能在于本模块使用了它们创建的功能，或者会修改它们定义的资源
data	XML 文件列表
assets	SCSS 和 JS 文件列表

Note

• 上述文件结构仅是一个建议。我们可以根据项目需要添加任意数量的其他文件夹，例如使用 /controllers 包含控制器，或使用 /views/backend 存放后端视图等。

• 要创建网站主题，您只需安装网站应用。如果您需要其他应用（博客、活动、电子商务等），也可以添加它们。

• Odoo 版本号和主版本号是必填的。不过，补丁号是可选的。如果您想指定运行模块所需的 Odoo 版本，应使用五段式结构，其中前两段用于指明您当前的 Odoo 版本（* = 18.0）。

示例：18.0.1.0.0 odoo_major.odoo_minor.module_major.module_minor.module_patch

Warning

在 Odoo SaaS 数据库中，使用通配符表示法 (ex.: /myfolder/*.scss) 自动包含文件不可用。在这种情况下，请在清单中手动包含每个文件。

默认选项

首先，尝试使用 Odoo 的默认选项来构建您的主题。这可以确保两件事：

1. 您不必重新发明已经存在的东西。例如，既然 Odoo 提供了在页脚添加边框的选项，您就不应自己重新编写它。相反，先启用默认选项，然后再根据需要扩展它。

2. 用户仍然可以在您的主题中使用 Odoo 的所有功能。例如，如果您重新编写页脚边框，可能会破坏默认选项或使其失效，从而给用户带来糟糕的体验。此外，您重新编写的功能可能不如默认选项那样好用，因为其他 Odoo 功能可能依赖于它。

Tip

• 每个缩进级别使用四个空格。

• 不要使用制表符。

• 切勿混用空格和制表符。

更多内容

Odoo 编码指南

Odoo 变量

Odoo 声明了许多 CSS 规则，其中大多数都可以通过覆盖相关的 SCSS 变量来完全自定义。为此，请创建一个 primary_variables.scss 文件，并将其添加到 _assets_primary_variables 包中。

声明

/website_airproof/__manifest__.py

'assets': {
   'web._assets_primary_variables': [
      'website_airproof/static/src/scss/primary_variables.scss',
   ],
},

通过阅读源代码，可以很容易地注意到与选项相关的变量。

<we-button title="..."
   data-name="..."
   data-customize-website-views="..."
   data-customize-website-variable="'Sidebar'"
   data-img="..."/>

例如，这些变量可以通过 $o-website-value-palettes 映射来覆盖。

全局

声明

/website_airproof/static/src/scss/primary_variables.scss

$o-website-values-palettes: (
   (
      // Templates
      // Colors
      // Fonts
      // Buttons
      // ...
   ),
);

Tip

该文件只能包含 SCSS 变量和混入的定义与覆盖。

更多内容

主要变量 SCSS

字体

您可以在网站上嵌入任何字体。网站构建器会自动使这些字体在字体选择器中可用。

声明

/website_airproof/static/src/scss/primary_variables.scss

$o-theme-font-configs: (
   <font-name>: (
      'family': <css font family list>,
      'url' (optional): <related part of Google fonts URL>,
      'properties' (optional): (
         <font-alias>: (
            <website-value-key>: <value>,
            ...,
         ),
      ...,
   )
)

用法

/website_airproof/static/src/scss/primary_variables.scss

$o-website-values-palettes: (
   (
      'font':                             '<font-name>',
      'headings-font':                    '<font-name>',
      'navbar-font':                      '<font-name>',
      'buttons-font':                     '<font-name>',
   ),
);

Google 字体

/website_airproof/static/src/scss/primary_variables.scss

$o-theme-font-configs: (
   'Poppins': (
      'family':                         ('Poppins', sans-serif),
      'url':                            'Poppins:400,500',
      'properties' : (
         'base': (
            'font-size-base':           1rem,
         ),
      ),
   ),
);

自定义字体

首先，创建一个专用的 SCSS 文件来声明您的自定义字体。

/website_airproof/__manifest__.py

'assets': {
   'web.assets_frontend': [
      'website_airproof/static/src/scss/font.scss',
   ],
},

然后，使用 @font-face 规则使您的自定义字体能够加载到您的网站上。

/website_airproof/static/src/scss/font.scss

@font-face {
   font-family: "My Custom Font", Helvetica, Helvetica Neue, Arial, sans-serif;
   font-weight: 400;
   font-style: normal;
   src: url('/fonts/my-custom-font.woff') format('woff'),
        url('/fonts/my-custom-font.woff2') format('woff2');
}

/website_airproof/static/src/scss/primary_variables.scss

$o-theme-font-configs: (
   'Proxima Nova': (
      'family':                         ('Proxima Nova', sans-serif),
      'properties' : (
         'base': (
            'font-size-base':           1rem,
         ),
      ),
   ),
);

Tip

建议为您的字体使用 .woff 和/或 .woff2 格式。

颜色

网站构建器依赖于由五个命名颜色构成的调色板。在主题中定义这些颜色可确保其保持一致。

颜色	说明
o-color-1	主色
o-color-2	副色
o-color-3	附加（浅色）
o-color-4	近白色
o-color-5	近黑色

声明

/website_airproof/static/src/scss/primary_variables.scss

$o-color-palettes: map-merge($o-color-palettes,
   (
      'airproof': (
         'o-color-1':                    #bedb39,
         'o-color-2':                    #2c3e50,
         'o-color-3':                    #f2f2f2,
         'o-color-4':                    #ffffff,
         'o-color-5':                    #000000,
      ),
   )
);

将创建的调色板添加到网站构建器提供的调色板列表中。

$o-selected-color-palettes-names: append($o-selected-color-palettes-names, 'airproof');

用法

/website_airproof/static/src/scss/primary_variables.scss

$o-website-values-palettes: (
   (
      'color-palettes-name':              'airproof',
   ),
);

颜色组合

基于前面定义的五个调色板，网站构建器会自动生成五种颜色组合，每种组合分别为背景、文本、标题、链接、主要按钮和次要按钮定义一种颜色。用户之后可以自定义这些颜色。

颜色组合中使用的颜色是可访问的，并且可以通过 $o-color-palettes 使用特定前缀（o-cc 对应 color combination）进行覆盖。

/website_airproof/static/src/scss/primary_variables.scss

$o-color-palettes: map-merge($o-color-palettes,
   (
      'airproof': (

         'o-cc*-bg':                     'o-color-*',
         'o-cc*-text':                   'o-color-*',
         'o-cc*-headings':               'o-color-*',
         'o-cc*-h2':                     'o-color-*',
         'o-cc*-h3':                     'o-color-*',
         'o-cc*-h4':                     'o-color-*',
         'o-cc*-h5':                     'o-color-*',
         'o-cc*-h6':                     'o-color-*',
         'o-cc*-link':                   'o-color-*',
         'o-cc*-btn-primary':            'o-color-*',
         'o-cc*-btn-primary-border':     'o-color-*',
         'o-cc*-btn-secondary':          'o-color-*',
         'o-cc*-btn-secondary-border':   'o-color-*',

      ),
   )
);

Note

对于每个 o-cc*，请将 * 替换为与所需颜色组合对应的数字（1 - 5）。

默认文本颜色为 o-color-5。如果背景太暗，它将自动更改为 o-color-4 颜色。

更多内容

颜色组合 SCSS

演示页面

网站构建器会自动生成一个页面，用于查看主题调色板的颜色组合：http://localhost:8069/website/demo/color-combinations

渐变

您也可以直接在 primary_variables.scss 文件中为菜单、页眉、页脚和版权栏定义渐变。

声明

/website_airproof/static/src/scss/primary_variables.scss

$o-website-values-palettes: (
   (
      'menu-gradient': linear-gradient(135deg, rgb(203, 94, 238) 0%, rgb(75, 225, 236) 100%),
      'header-boxed-gradient': [your-gradient],
      'footer-gradient': [your-gradient],
      'copyright-gradient': [your-gradient],
   ),
);

Bootstrap 变量

Odoo 默认包含 Bootstrap。您可以使用该框架的所有变量和 mixin。

如果 Odoo 不提供您要找的变量，可能有某个 Bootstrap 变量可以实现这一点。实际上，所有 Odoo 布局都遵循 Bootstrap 结构，并使用 Bootstrap 组件或其扩展。如果您自定义某个 Bootstrap 变量，就会为整个用户网站添加一种通用样式。

请使用添加到 _assets_frontend_helpers 包中的专用文件来覆盖 Bootstrap 值，而 不要 使用 primary_variables.scss 文件。

声明

/website_airproof/__manifest__.py

'assets': {
   'web._assets_frontend_helpers': [
      ('prepend', 'website_airproof/static/src/scss/bootstrap_overridden.scss'),
   ],
},

用法

/website_airproof/static/src/scss/bootstrap_overridden.scss

// Typography
$h1-font-size:                 4rem !default;

// Navbar
$navbar-nav-link-padding-x:    1rem!default;

// Buttons + Forms
$input-placeholder-color:      o-color('o-color-1') !default;

// Cards
$card-border-width:            0 !default;

Tip

该文件只能包含 SCSS 变量和混入的定义与覆盖。

Warning

不要覆盖那些依赖于 Odoo 变量的 Bootstrap 变量。否则，可能会破坏用户使用网站构建器自定义这些变量的能力。

当某个选项既由 primary_variables.scss 中的变量定义，又由 Bootstrap 变量定义时，您应始终通过主变量进行覆盖。仅当主变量中不存在任何内容时，才通过 bootstrap_overridden.scss 进行覆盖。

更多内容

Bootstrap 覆盖 SCSS

演示页面

http://localhost:8069/website/demo/bootstrap

字号

Odoo 提供 CSS 字号类，用于将样式（字号）与语义（标签及一般样式）分离。这两种逻辑可以结合使用，从而更加灵活。

更多内容

关于 Display 标题的 Bootstrap 文档

文本样式

Odoo 的网站构建器允许为您的文本选择样式。有些样式仅与标签相关，例如不带额外 CSS 类的 Header。另一些则将标签与直接应用于其上的样式相结合，例如 Header 1 Display。

<!-- h1 with display heading sizes -->
<h1 class="display-1">Heading 1 with Display Heading 1 size</h1>
<h1 class="display-2">Heading 1 with Display Heading 2 size</h1>
<h1 class="display-3">Heading 1 with Display Heading 3 size</h1>
<h1 class="display-4">Heading 1 with Display Heading 4 size</h1>

<!-- Lead text - named "Light" in the dropdown -->
<p class="lead">A text typically used as an introduction.</p>

<!-- Small text -->
<p class="o_small">Body text with a smaller size.</p>

尺寸类

尺寸类会添加到目标元素内部新创建的 span 标签上（参见下面的示例）。

标题和正文文本

假设这些类可以应用于任何文本元素，下面以 h2 为例：

<!-- h2 sized like an h1 -->
<h2><span class="h1-fs">Heading</span></h2>

<!-- h2 sized with other heading sizes -->
<h2><span class="h2-fs">Heading</span></h2>
<h2><span class="h3-fs">Heading</span></h2>
<h2><span class="h4-fs">Heading</span></h2>
<h2><span class="h5-fs">Heading</span></h2>
<h2><span class="h6-fs">Heading</span></h2>

<!-- h2 sized like a normal paragraph (base size, 16px by default) -->
<h2><span class="base-fs">Heading</span></h2>

<!-- h2 sized like a small text (14px by default) -->
<h2><span class="o_small-fs">Heading</span></h2>

Display 标题

如果需要更大的标题，Odoo 会使用 Bootstrap 的 Display Headings 类，即从 display-1 到 6。

<h2><span class="display-1-fs">Heading</span></h2>
<h2><span class="display-2-fs">Heading</span></h2>
<h2><span class="display-3-fs">Heading</span></h2>
<h2><span class="display-4-fs">Heading</span></h2>

Note

网站构建器只允许用户配置从 Display 1 到 Display 4 的尺寸。您可以设置其他尺寸（5 和 6）以便在代码中使用，但用户无法直接在网站构建器界面中修改它们。

网站设置

与网站相关的全局选项可以通过网站记录按照以下结构进行设置。

声明

/website_airproof/data/website.xml

<?xml version="1.0" encoding="utf-8"?>
<odoo noupdate="1">
   <record id="website.default_website" model="website">
      <field name="name">Airproof</field>
      <field name="logo" type="base64" file="website_airproof/static/src/img/content/logo_pred.png"/>
      <field name="favicon" type="base64" file="website_airproof/static/description/favicon.png" />
      <field name="shop_ppg">18</field>
      <field name="shop_ppr">3</field>
      <field name="cookies_bar" eval="True" />
      <field name="contact_us_button_url">/contact-us</field>
      <field name="social_facebook">https://www.facebook.com/Airproof</field>
      <field name="social_instagram">https://www.instagram.com/airproof</field>
      <field name="social_linkedin">https://www.linkedin.com/company/airproof</field>
      <field name="social_youtube">https://www.youtube.com/c/airproof</field>
   </record>
</odoo>

字段	说明
name	网站名称（显示在浏览器中）
logo	徽标的路径（此前已在记录中创建）
favicon	网站图标的路径（此前已在记录中创建）
shop_ppg	电子商务中每页显示的产品数量
shop_ppr	电子商务中每行显示的产品数量（在页面内）
cookies_bar	启用/禁用 Cookie 栏
contact_us_button_url	联系我们 页面的 URL（例如，用于标准页眉模板中）。
social_facebook	Facebook 个人资料页的 URL
social_instagram	Instagram 个人资料页的 URL
social_linkedin	LinkedIn 公司主页的 URL
social_youtube	YouTube 频道的 URL

Note

website.default_website 是仅使用一个网站时的默认引用。如果您的数据库中有多个网站，该记录将指向默认站点（即第一个网站）。

视图

对于某些选项，除了网站构建器变量外，您还需要激活特定的视图。

通过阅读源代码，可以轻松找到与选项相关的模板。

<we-button title="..."
   data-name="..."
   data-customize-website-views="website.template_header_default"
   data-customize-website-variable="'...'"
   data-img="..."/>

<template id="..." inherit_id="..." name="..." active="True"/>
<template id="..." inherit_id="..." name="..." active="False"/>

预设

为了将视图作为预设进行激活和停用，您应将这些视图包含在 presets.xml 文件中。

用法

/website_airproof/data/presets.xml

<record id="module.view" model="ir.ui.view">
      <field name="active" eval="False"/>
</record>

Example

更改菜单项的水平对齐方式

/website_airproof/data/presets.xml

<record id="website.template_header_default_align_center" model="ir.ui.view">
   <field name="active" eval="True"/>
</record>

同样的逻辑也适用于其他 Odoo 应用。

电子商务 - 显示产品类别

/website_airproof/data/presets.xml

 <record id="website_sale.products_categories" model="ir.ui.view">
    <field name="active" eval="False"/>
 </record>

门户 - 禁用语言选择器

/website_airproof/data/presets.xml

<record id="portal.footer_language_selector" model="ir.ui.view">
   <field name="active" eval="False"/>
</record>

资源

在本部分中，我们将引用位于 web 模块中的 assets_frontend 包。该包指定了网站构建器加载的资源列表，目标是将您的 SCSS 和 JS 文件添加到此包中。

以下是网站中常用包的列表，并非详尽无遗：

包	说明
web._assets_primary_variables	主要用于 primary_variables.scss 文件
web._assets_secondary_variables	主要用于 secondary_variables.scss 文件
web._assets_frontend_helpers	主要用于 bootstrap_overridden.scss 文件
web.assets_frontend	您可以添加所有自定义的 SCSS、JS 或 QWeb JS 文件
website.assets_wysiwyg	添加与网站构建器选项行为相关的 JS 文件（例如，为您自定义的构建块添加一个自定义方法）
website.assets_wysiwyg	例如，如果您需要通过 Bootstrap Utilities API 扩展 Bootstrap

样式

网站构建器与 Bootstrap 相结合，非常适合定义网站的基本样式。但要设计出独特的效果，您还应更进一步。为此，您可以轻松地将任何 SCSS 文件添加到主题中。

声明

/website_airproof/__manifest__.py

'assets': {
   'web.assets_frontend': [
      'website_airproof/static/src/scss/theme.scss',
   ],
},

您可以随意在 theme.scss 文件中重用来自 Bootstrap 文件的变量以及 Odoo 使用的变量。

Example

/website_airproof/static/src/scss/theme.scss

 blockquote {
   border-radius: $rounded-pill;
   color: o-color('o-color-3');
   font-family: o-website-value('headings-font');
 }

交互性

Odoo 支持三种不同的 JavaScript 文件：

• 纯 JavaScript 文件 （无模块系统），

• 原生 JavaScript 模块，以及

• Odoo 模块 （使用自定义模块系统）。

大多数新的 Odoo JavaScript 代码都应使用原生 JavaScript 模块系统。它更简单，并且能带来更好的开发者体验，与 IDE 的集成也更好。

声明

/website_airproof/__manifest__.py

'assets': {
   'web.assets_frontend': [
      'website_airproof/static/src/js/theme.js',
   ],
},

Note

如果您想包含来自外部库的文件，可以将它们添加到模块的 /lib 文件夹中。

Tip

• 使用代码检查工具（JSHint 等）。

• 切勿添加压缩过的 JavaScript 库。

• 在每个旧式模块的顶部添加 'use strict';；新式模块会自动完成此操作。

• 在您用 JavaScript 定位的元素上使用带 js_ 前缀的 CSS 类。

• 变量和函数应使用 camelCased （myVariable），而不是 snake_cased （my_variable）。

• 不要将变量命名为 event，而应使用 ev。这样做是为了避免在非 Chrome 浏览器上出现错误，因为 Chrome 会神奇地分配一个全局 event 变量（因此，如果您使用 event 变量而不声明它，在 Chrome 上会正常运行，但在其他所有浏览器上都会崩溃）。

• 使用严格比较（=== 而不是 ==）。

• 对所有文本字符串（例如 "Hello"）使用双引号，对所有其他字符串（例如 CSS 选择器 .x_nav_item）使用单引号。

• 如果您使用标准的原生 JS 函数（start()、willStart()、cleanForSave() 等），请确保调用 this._super.apply(this, arguments)；（请检查标准代码中是否必要）。

更多内容

• Odoo JavaScript 编码规范

• Odoo JavaScript 框架概览

• Odoo Experience 演讲：让您的网站设计更上一层楼的 10 个技巧！