主题制作¶
在开发环境完全搭建好之后,您就可以开始构建主题模块的骨架了。本章将介绍如何:
启用/禁用网站构建器的标准选项和模板。
定义用于设计的颜色和字体。
充分利用 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 |
预设、菜单、页面、图像、形状等( |
i18n |
翻译文件( |
lib |
外部库( |
static |
自定义资源( |
views |
自定义视图和模板( |
初始化¶
Odoo 模块也是一个 Python 包,其中包含一个 __init__.py 文件,用于导入模块中的各个 Python 文件。目前该文件可以保持为空。
声明¶
Odoo 模块通过其清单文件进行声明。该文件将一个 Python 包声明为 Odoo 模块,并指定模块的元数据。它至少必须包含 name 字段,该字段始终是必需的。通常它还会包含更多信息。
/website_airproof/__manifest__.py¶{
'name': 'Airproof Theme',
'description': '...',
'category': 'Website/Theme',
'version': '16.0.0',
'author': '...',
'license': '...',
'depends': ['website'],
'data': [
# ...
],
'assets': {
# ...
},
}
字段 |
说明 |
|---|---|
name |
模块的易读名称(必填) |
description |
模块的扩展描述,使用 reStructuredText 编写 |
category |
Odoo 内的分类类别 |
version |
此模块所针对的 Odoo 版本 |
author |
模块作者的名称 |
license |
默认情况下,我们使用 |
depends |
这些 Odoo 模块必须先于本模块加载,原因可能在于本模块使用了它们创建的功能,或者会修改它们定义的资源 |
data |
XML 文件列表 |
assets |
SCSS 和 JS 文件列表 |
Note
上述文件结构仅是一个建议。我们可以根据项目需要添加任意数量的其他文件夹,例如使用
/controllers包含控制器,或使用/views/backend存放后端视图等。要创建网站主题,您只需安装网站应用。如果您需要其他应用(博客、活动、电子商务等),也可以添加它们。
Odoo 版本号与主版本号是必填项,但补丁版本号是可选的。如果您想指定运行模块所需的 Odoo 版本,应使用五段式结构,用前两段指明 Odoo 版本。
Warning
在 Odoo SaaS 数据库中,使用通配符表示法 (ex.: /myfolder/*.scss) 自动包含文件不可用。在这种情况下,请在清单中手动包含每个文件。
默认选项¶
首先,尝试使用 Odoo 的默认选项来构建您的主题。这可以确保两件事:
您不必重新发明已经存在的东西。例如,既然 Odoo 提供了在页脚添加边框的选项,您就不应自己重新编写它。相反,先启用默认选项,然后再根据需要扩展它。
用户仍然可以在您的主题中使用 Odoo 的所有功能。例如,如果您重新编写页脚边框,可能会破坏默认选项或使其失效,从而给用户带来糟糕的体验。此外,您重新编写的功能可能不如默认选项那样好用,因为其他 Odoo 功能可能依赖于它。
Tip
每个缩进级别使用四个空格。
不要使用制表符。
切勿混用空格和制表符。
更多内容
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 变量和混入的定义与覆盖。
更多内容
字体¶
您可以在网站上嵌入任何字体。网站构建器会自动使这些字体在字体选择器中可用。
声明
/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 颜色。
更多内容
演示页面
网站构建器会自动生成一个页面,用于查看主题调色板的颜色组合: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 进行覆盖。
视图¶
对于某些选项,除了网站构建器变量外,您还需要激活特定的视图。
通过阅读源代码,可以轻松找到与选项相关的模板。
<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 文件添加到此包中。
以下是网站中常用包的列表,并非详尽无遗:
包 |
说明 |
|---|---|
|
主要用于 |
|
主要用于 |
|
主要用于 |
|
您可以添加所有自定义的 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 文件 (无模块系统),
Odoo 模块 (使用自定义模块系统)。
大多数新的 Odoo JavaScript 代码都应使用原生 JavaScript 模块系统。它更简单,并且能带来更好的开发者体验,与 IDE 的集成也更好。
Important
Odoo 需要知道哪些文件应被转换为 Odoo 模块,哪些文件不应。这是一个 opt-in 机制:Odoo 会查看 JavaScript 文件的第一行,检查其中是否包含 @odoo-module 字符串。如果包含,该文件会自动转换为 Odoo 模块。
/** @odoo-module **/
声明
/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);(请检查标准代码中是否必要)。