主题化

开发环境完全设置完毕后，您可以开始构建主题模块的骨架。在本章中，您将了解如何：

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

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

• 充分利用 Bootstrap 变量。

• 添加自定义样式和 JavaScript。

主题模块

Odoo 附带一个默认主题，提供最小的结构和布局。当您创建新主题时，您正在扩展默认主题。

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

技术命名

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

website_airproof

注解

以 website_ 为前缀，并仅使用小写 ASCII 字母数字字符和下划线。

在本文档中，我们将使用**Airproof**（一个虚构的项目）作为示例。

文件结构

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

website_airproof
├── data
├── i18n
├── static
│   ├── description
│   ├── fonts
│   ├── lib
│   ├── image_shapes // Shapes for images
│   ├── 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
│       └── website_builder // Options for the Website Builder
├── views
├── __init__.py
└── __manifest__.py

文件夹	描述
数据	预设、菜单、页面、图像、形状……(*.xml)
国际化	翻译（*.po、*.pot）
库	外部库 (*.js)
静止的	自定义资源（*.jpg、*.gif、*.png、*.svg、*.pdf、*.scss、*.js）
意见	自定义视图和模板 (*.xml)

初始化

Odoo 模块也是一个 Python 包，带有 __init__.py 文件，其中包含模块中各种 Python 文件的导入指令。该文件暂时可以保留为空。

宣言

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

/website_airproof/__manifest__.py

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

场地	描述
姓名	人类可读的模块名称（必需）
描述	模块的扩展描述，在 reStructuredText 中
类别	Odoo 内的分类类别
版本	该模块正在寻址的 Odoo 版本
作者	模块作者姓名
执照	默认情况下，我们使用 LGPL-3 许可证。更多信息请参见 module manifest 页面。
取决于	Odoo 模块必须在此模块之前加载，因为该模块使用他们创建的功能，或者因为它改变了他们定义的资源
数据	XML 文件列表
资产	SCSS 和 JS 文件列表

注解

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

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

• Odoo 版本和主版本号为必填项。但是，补丁号是可选的。如果您想指定运行模块所需的 Odoo 版本，您应该使用五个参数结构，使用前两个参数来指示您当前的 Odoo 版本 (* = 19.0)。

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

警告

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

默认选项

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

1. 你不会重新发明已经存在的东西。例如，由于 Odoo 提供了在页脚上添加边框的选项，因此您不应该自己重新编码。相反，首先启用默认选项，然后根据需要扩展它。

2. 用户仍然可以在您的主题中使用 Odoo 的所有功能。例如，如果您重新编码页脚上的边框，则可能会破坏默认选项或使其变得无用，从而给用户带来糟糕的体验。此外，您的重新编码可能无法像默认选项一样工作，因为其他 Odoo 功能可能依赖它。

小技巧

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

• 不要使用选项卡。

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

其他资料

Odoo coding guidelines

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',
   ],
},

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

<BuilderSelectItem
   id="'...'"
   title.translate="..."
   actionParam="[
      {
         action: 'websiteConfig',
         actionParam: {
             views: [...],
             vars: { 'header-template': 'sidebar' },
             checkVars: false,
         }
      }
   ]">
   <Img src="'/website_airproof/static/src/img/wbuilder/template-header-opt.svg'" class="'mw-100'" />
</BuilderSelectItem>

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

全球的

宣言

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

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

小技巧

该文件必须仅包含 SCSS 变量和 mixins 的定义和覆盖。

其他资料

Primary variables 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>',
   ),
);

谷歌字体

/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/fonts.scss',
   ],
},

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

/website_airproof/static/src/scss/fonts.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,
         ),
      ),
   ),
);

小技巧

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

颜色

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

颜色	描述
o-颜色-1	基本的
o-颜色-2	中学
o-颜色-3	额外（轻）
o-颜色-4	发白
o-颜色-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-cc 表示 color combination）通过 $o-color-palettes 进行覆盖。

/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-*',

      ),
   )
);

注解

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

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

其他资料

Color combinations 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],
   ),
);

引导变量

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

如果 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;

小技巧

该文件必须仅包含 SCSS 变量和 mixins 的定义和覆盖。

警告

不要覆盖依赖于 Odoo 变量的 Bootstrap 变量。否则，您可能会破坏用户使用网站生成器自定义它们的可能性。

当选项由 primary_variables.scss 中的变量和 Boostrap 变量定义时，您应该始终通过主变量进行覆盖。仅当主变量中不存在任何内容时才通过 bootstrap_overridden.scss 执行此操作。

其他资料

Bootstrap overridden SCSS

演示页面

http://localhost:8069/网站/演示/bootstrap

字体大小

Odoo 有 CSS 字体大小类来区分样式（字体大小）和语义（一般标签和样式）。两种逻辑可以结合起来更加灵活。

其他资料

Bootstrap documentation about display headings

文字样式

Odoo 的网站生成器允许为您的文本选择样式。有些只是与标签相关，例如 Header ，没有额外的 CSS 类。其他组合标签和样式直接应用于它们，例如 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>

显示标题

如果需要更大的标题，Odoo 使用 Bootstrap 的显示标题类，从 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>

注解

网站生成器仅允许用户配置从 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_airproof.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="shop_gap">16px</field>
      <field name="shop_opt_products_design_classes">
            o_wsale_products_opt_layout_catalog
            o_wsale_products_opt_design_cards
            o_wsale_products_opt_name_color_regular
            o_wsale_products_opt_thumb_cover
            o_wsale_products_opt_img_hover_zoom_out_light
            o_wsale_products_opt_has_cta
            o_wsale_products_opt_actions_onhover
            o_wsale_products_opt_wishlist_fixed
            o_wsale_products_opt_cc
            o_wsale_products_opt_cc1
            o_wsale_products_opt_rounded_2
            o_wsale_products_opt_actions_promote
            o_wsale_products_opt_actions_subtle
            o_wsale_products_opt_name_weight_bold
      </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>

其他资料

来自电子商务应用程序的 Website model：

• 以`shop_`为前缀的字段与`/shop`页面配置相关；

• 以`product_page_`为前缀的字段与产品页面配置相关；

• “Cards Design”类在 /shop 页面和动态产品代码段之间共享。

场地	描述
姓名	网站名称（在浏览器中显示）
标识	徽标的路径（之前创建到记录中）
图标	网站图标的路径（之前创建到记录中）
商店_ppg	电子商务中每页显示的产品数量
商店_ppr	电子商务中每行（页面）显示的产品数量
店铺间隙	用于分隔产品网格项目的装订线值
shop_opt_products_design_classes	与产品设计选项相关的 CSS 类列表。
cookies_bar	启用/禁用 cookie 栏
contact_us_button_url	Contact us 页面的 URL（例如，在标准标头模板中使用）。
社交脸书	Facebook 个人资料的 URL
社交Instagram	Instagram 个人资料的 URL
社交链接	LinkedIn 公司简介的 URL
社交YouTube	YouTube 频道的 URL

注解

当您仅使用一个网站时，website.default_website 是默认参考。如果您的数据库中有多个网站，则此记录将引用默认网站（第一个）。

意见

对于某些选项，除了 Website Builder 变量之外，您还必须激活特定视图。

通过阅读源码，很容易找到与选项相关的模板。

<BuilderContext action="'websiteConfig'">
   <BuilderRow label.translate="...">
      <BuilderCheckbox actionParam="{views: ['website.show_website_info']}" />
   </BuilderRow>
</BuilderContext>

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

其他资料

在这种情况下，在 XML 中定义记录时使用 <template id="..."> syntax should be preferred over the <record id="..." model="ir.ui.view"> 语法。

请参阅 template，尤其是关于“active”值。

预设

为了激活和停用预设视图，您应该将这些视图包含在 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 文件添加到该捆绑包中。网站建立器使用自己的捆绑包（例如：website.website_builder_assets 和 website.assets_wysiwyg）。

这是网站常用捆绑包的非详尽列表：

捆	描述
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.website_builder_assets	添加与网站生成器选项行为相关的 JS 文件（例如，自定义构建块的自定义方法）
web._assets_bootstrap_frontend	例如，如果您需要通过 Bootstrap Utilities API 扩展 Boostrap

风格

网站生成器与 Bootstrap 一起非常适合定义网站的基本样式。但要设计出独特的东西，你应该更进一步。为此，您可以轻松地将任何 SCSS 文件添加到您的主题中。

宣言

/website_airproof/__manifest__.py

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

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

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 文件：

• :ref:`plain JavaScript files <frontend/modules/plain_js>`（无模块系统），

• native JavaScript module，以及

• :ref:`Odoo modules <frontend/modules/odoo_module>`（使用自定义模块系统）。

大多数新的 Odoo JavaScript 代码应该使用本机 JavaScript 模块系统。它更简单，并且通过与 IDE 更好的集成带来更好的开发人员体验。

宣言

/website_airproof/__manifest__.py

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

注解

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

小技巧

• 使用 linter (ESLint, …)。

• 始终添加缩小的 JavaScript 库

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

• 变量和函数应该是 camelCased (myVariable) 而不是 snake_cased (my_variable)。

• JavaScript 类使用 PascalCase (MyClass)。

• 不要将变量命名为 event；使用 ev 代替。这是为了避免非 Chrome 浏览器上的错误，因为 Chrome 神奇地分配了一个全局 event 变量（因此，如果您使用 event 变量而不声明它，它将在 Chrome 上正常工作，但在所有其他浏览器上崩溃）。

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

• 所有字符串均使用双引号（例如 "Hello"、".x_nav_item"）。

• 如果您使用本机标准 JS 函数（start()、willStart()、cleanForSave() 等），请确保调用父实现（例如 super.start(...arguments)；检查标准代码中是否有必要）。

其他资料

• Odoo JavaScript coding guidelines

• Overview of the Odoo JavaScript framework

• Odoo Experience Talk: Best practices to use the Website Builder like a professional designer