Alan Hou的个人博客

本文为最好用的免费ERP系统Odoo 12开发手册系列文章第七篇。

在上一篇文章中，我们概览了模型创建以及如何从模型中载入和导出数据。现在我们已有数据模型和相关数据，是时候学习如何编程与其进行交互 了。模型的 ORM（Object-Relational Mapping）提供了一些交互数据的方法，称为 API（Application Programming Interface）。这包括基本的增删改查(CRUD)操作，也包括一些其它操作，如数据导入导出，以及改善用户界面和体验的工具方法。它还包含一些我们在前面文章中所看到的装饰器。这些都让我们可以通过添加新的方法来调用 ORM 进行相关操作。

本文主要内容有：

• 使用 shell 命令交互式地学习 ORM API
• 理解执行环境和上下文
• 使用记录集和作用域(domain)查询数据
• 在记录集中访问数据
• 在记录中写入
• 编写记录集
• 使用底层 SQL 和数据库事务

开发准备

本文代码使用交互式 shell 命令行执行，无需使用前面章节的代码。

使用 shell 命令行

Python带有命令行界面，是研究其语法一个很好的方式。Odoo 也有类似的功能，可以交互式的测试命令的执行效果，这就是 shell 命令行。在命令行中执行以下命令并指定数据库即可使用：

1

~/odoo-dev/odoo/odoo-bin shell -d dev12

此时在终端上可以看到正常的服务启动信息，等到出现>>>Python提示符时即为完成，可以输入命令了。

ℹ️Odoo 9中的修改
shell 功能在9.0中才添加。Odoo 8.0可使用社区模块来添加这一功能。只需下载并放入 addons 路径即可使用，下载请见应用市场。

此处 self 表示管理员用户的记录，可通过如下命令进行确认：

1
2
3
4
5
6

>>> self
res.users(1,)
>>> self._name
'res.users'
>>> self.login
'__system__'

在以上 shell 会话中，我们检查了自己的环境：

• self命令表示res.users记录集，仅包含一条 id 为1的记录
• 查看self._name获得记录集模型名，你可能猜到了，是’res.users’
• 记录的 name 值为OdooBot
• 记录的 login 字段值为__system__

ℹ️Odoo 12中的修改
id 号为1的超级用户由原来的 admin 变成无法直接登录的内部系统用户。现在 admin 的 id 号为 2并且不是超级用户，但默认各应用会将其加入所有安全组。主要原因是避免用户使用超级用户账号来执行日常操作。这样的风险是该用户会跳过权限规则并导致数据的不一致，比如跨公司(cross-company)关联。现在超级用户仅用于检测问题或具体的跨公司操作。

和 Python 一样，可通过 Ctrl + D退出该命令行。此时会结束服务并返回到系统shell 命令行。

执行环境

Odoo shell 中包含一个 self 引用，类似于在res.users模型的方法中看到的那样。如我们所见，self 是一个记录集。记录集自带环境信息，包括浏览信息的用户以及其它上下文信息，如语言和时区。下面我们会学习执行环境中可用的属性、环境上下文的用处以及如何修改该上下文。

环境属性

我们可通过如下代码查看当前环境：

1
2

>>> self.env
<odoo.api.Environment object at 0x7f78a26026a0>

self.env 中的执行环境中有以下属性：

• env.cr是正在使用的数据库游标(cursor)
• env.user是当前用户的记录
• env.uid是会话用户 id，与env.user.id相同
• env.context是会话上下文的不可变字典

环境还提供对带有所有已安装模型注册表的访问，如self.env[‘res.partner’]返回一条对 partner 模型的引用。然后我们还可以对其使用search()或browse()方法来获取记录集：

1
2

>>> self.env['res.partner'].search([('name', 'like', 'Ad')])
res.partner(10, 35, 3)

上例中返回的res.partner模型记录集包含三条记录，id 分别为10, 35和3。记录集并没有按 id 排序，因为使用了相应模型的默认排序。就 partner 模型而言，默认的_order为display_name。

环境上下文

环境上下文是一个带有会话数据的字典，可用于客户端用户界面以及服务端 ORM 和业务逻辑中。在客户端中，它可以把信息从一个视图带到另一个视图中，比如前一个视图中活跃的记录 id，通过点击链接或按钮，可将默认值带入到下一个视图中。在服务端中，一些记录集的值会依赖于上下文提供的本地化设置。具体的例子有lang键影响可翻译字段的值。上下文还可为服务端代码提供信号。比如active_test键在设为 False 时，会改变ORM中search()方法的行为，它会忽略记录中的active标记，inactive(假删除)的记录也会被返回。

客户端的初始上下文长这样：

1

{'lang': 'en_US', 'tz': 'Europe/Brussels', 'uid': 2}

补充：服务端查看上下文命令为self.context_get()或self.env.context

其中 lang 键为用户语言，tz 为时区信息，uid 为当前用户 id。记录中的内容随当前依赖的上下文可能会不同：

• translated字段根据活跃的 lang 语言不同值也会不同
• datetimep字段根据活跃的的 tz 时区不同时间会不同

在上一个视图中点击链接或按钮打开表单时，一个active_id键会被加入上下文，它带有原表单我们所在位置记录的 id。以列表视图为例，active_ids上下文键中包含上一个列表中所选择的记录 id 列表。

在客户端中，上下文可用于使用default_或default_search_前缀在目录视图上设置默认值或启动默认过滤器。举例如下：

• 设置当前用户为user_id字段默认值，使用{‘default_user_id’: uid}
• 在目标视图上默认启动filter_my_books过滤器，使用{‘default_search_filter_my_tasks’: 1}

修改记录集执行环境

记录集执行环境是不可变的，因此不能被修改，但我们可以创建一个变更环境并使用它来执行操作。我们通过如下方法来实现：

• env.sudo(user)中传入一条用户记录并返回该用户的环境。如未传入用户，则使用__system__超级用户root，这时可绕过安全规则执行指定操作。
• env.with_context() 替换原上下文为新的上下文
• env.with_context(key=value,…)修改当前上下文，为一些键设置值

此外还有一个env.ref()函数，传入一个外部标识符字符串并返回它的记录，请参见：

1
2

>>> self.env.ref('base.user_root')
res.users(1,)

使用记录集和作用域(domain)查询数据

在方法或 shell 会话中，self表示当前模型，并且我们仅能访问该模型的记录。要访问其它模型就需要使用self.env。例如self.env[‘res.partner’]返回一条对 Partner 模型的引用(也是一个空记录集)。我们可以使用search()或browse()来获取记录集，其中search()方法使用域表达式来定义记录选择范围。

创建记录集

search()方法接收一个域表达式并返回符合条件记录的记录集。空域[] 将返回所有记录。

ℹ️如果模型有特殊字段 active，默认只有active=True的记录才在选择范围内

还可以使用以下关键字参数：

• order是一个数据库查询语句中ORDER BY使用的字符串，通常是一个逗号分隔的字段名列表。每个字段都可接DESC关键字，用于表示倒序排列。
• limit设置获取记录的最大条数
• offset忽略前 n 前记录，可配合limit使用来一次查询指定范围记录

有时我们只要知道满足某一条件的记录条数，这时可使用search_count()来返回记录条数而非记录集。这节约了先获取记录列表再记数的开销，在还没有获取记录集且仅想知道记录条数时这样会更高效。

browse()方法接收一个 ID 列表或单个ID并返回这些记录的记录集。在我们知道 ID 并想要获取记录时这就非常方便了。

一些使用示例如下：

1
2
3
4

>>> self.env['res.partner'].search([('name', 'like', 'Pac')])
res.partner(42, 62)
>>> self.env['res.partner'].browse([42, 62])
res.partner(42, 62)

域表达式

域(domain)用于过滤数据记录。它使用一个特殊语法来供 Odoo ORM解析，生成数据库查询中的 WHERE 表达式。域表达式是一组条件组成的列表，每个条件都是一个 (‘字段名’, ‘运算符’, ‘值’) 组成的元组，例如，[(‘is_done’,’=’,False)]是仅带有一个条件的有效域表达式。以下是对各个元素的说明：

• 字段名：是一个待过滤字段，可使用点号标记来表示关联模型中的字段

• 值：在 Python 表达式中运行。可使用字面值，如数字、布尔值、字符串和列表，也可使用运行上下文中的字段和标识符。针对域其实有两种运行上下文：

  • 在窗口操作或字段属性等客户端中使用时，可使用原生字段值来渲染当前可用视图，但不能对其使用点标记符
  • 在服务端使用时，如安全记录规则或服务端 Python 代码中，可以对字段使用点标记符，因为当前记录是一个对象

• 运算符：可以是以下中的一个

  • 常用比较运算符有<, >, <= , >=, =和!=。
  • ‘=like’和’=ilike’匹配某一模式，这里下划线_匹配单个字符，百分号%匹配任意一组字符。
  • ‘like’匹配’%value%’模式，’ilike’与其相似但忽略大小写。还可以使用’not like’和’not ilike’运算符。
  • ‘child of’在配置支持层级关联的模型中查找层级关系中的子级值。
  • ‘in’ 和’not in’用于查看给定列表的包含，所以其值为一个列表。用于to-many关联字段时，in运算符和contains运算符一样。
  • ‘not in’是in的反向运算，用于查看不在列表中的值。

域表达式是一个列表并且包含多个条件元组。默认这些条件使用AND逻辑运算符连接，也就是说它仅返回满足所有条件的记录。也可以使用显式逻辑运算符 - ‘&’符号表示 AND 运算符（默认值），管道运算符’|’表示OR运算符。这两个运算符会作用于接下来的两项，递归执行。后面我们会一起来详细了解。

ℹ️域表达式使用了更为正式的定义方式：前缀标记法，也称波兰表达式(Polish notation)：运算符放在运算项之前。AND和OR是二元运算符，而NOT是一元运算符。

感叹号’!’表示NOT运算符，可用于下一项的运算，因此要放执行的否定项之前。例如[‘!’, (‘is_done’,’=’,True)]将过滤出所有未完成(not-don e)的记录。

下一项本身也可以是一个作用其后续项的运算符，形成一个嵌套条件。下例可以有助于我们进行理解。在服务端记录规则中，可以找到类似下面这样的域表达式：

1
2
3
4
5
6

['|',
    ('message_follower_ids', 'in', [user.partner_id.id]),
    '|',
        ('user_id', '=', user.id),
        ('user_id', '=', False)
]

这个域过滤出当前用户在follower列表中并且是负责人用户，或者没有负责人用户的用户集。第一个’|’或运算符作用于 follower 条件以及下一个条件的结果。下一个条件是后面两个条件的并集：用户ID是当前会话用户或未进行设置。下图是上例域表达式的抽象语法树表示：

在记录集中访问数据

一旦获取了数据集，就可以查看其中包含的数据了。下面的几个部分中我们就来看看如何访问记录集中的数据。我们可以获取单条记录的字段值，称为单例(singleton)。关联字段带有特殊属性，我们可通过点号标记来查看关联记录。最后我们一起思考处理日期和时间记录并进行格式转换。

访问记录中数据

记录集的一个特例是仅有一条记录，称为单例。单例仍是记录集，在需要记录集的地方均可使用。与多元素记录集不同，单例可使用点号标记访问它的字段，如：

1
2

>>> print(self.name)
OdooBot

下个例子中我们看看同一个 self 单例和记录集相同的行为，我们可对其进行遍历。它只有一条记录，所以只会打印出一个名称：

1
2
3
4

>>> for rec in self:
...     print(rec.name)
...
OdooBot

尝试访问有多条记录的记录集字段值会产生错误，所以在不确定操作的是否为单例数据集时就会产生问题。对于设计仅操作单例的方法，可在开头处使用self.ensure_one()，如果 self 不是单例时将抛出错误。

ℹ️空记录也是单例。这样很方便，因为访问字段会返回 None 而非抛出错误。对于关联字段同样如此，使用点号标记访问关联记录也不会抛出错误。

访问关联字段

如前面所见，模型可包含关联字段：many-to-one, one-to-many和many-to-many。这些字段类型的值为记录集。

对于many-to-one，其值可以是单例或空记录集。两种情况下都可以直接访问字段值。如下例中的命令是正确并安全的：

1
2
3
4
5
6
7
8

>>> self.company_id
res.company(1,)
>>> self.company_id.name
'YourCompany'
>>> self.company_id.currency_id
res.currency(1,)
>>> self.company_id.currency_id.name
'EUR'

为避免麻烦，空记录可像单例一样操作，访问其字段值不会返回错误而是返回 False。所以我们可以使用点号标记来遍历字段，而无需担心因其值为空而报错，如：

1
2
3
4

>>> self.company_id.parent_id
res.company()
>>> self.company_id.parent_id.name
False

访问时间和日期值

在记录集中，日期和日期时间值以原生 Python 对象展示，例如，在查询上次 admin 用户登录日期时：

1
2

>>> self.browse(2).login_date
datetime.datetime(2019, 1, 8, 9, 2, 54, 45546)

因为日期和日期时间是 Python 对象，它们可使用这些对象的所有功能。

ℹ️Odoo 12中的修改
date和datetime字段值以 Python 对象表示，而此前 Odoo 版本中它们以文本字符串表示。这些字段类型值仍可像此前 Odoo 版本中那样使用文本表示。

日期和时间在数据库中以原生的世界标准时间(UTC) 格式存储，不受时区影响。 在记录集中看到的datetime值也是 UTC格式，在客户端中向用户展示时，datetime值会根据当前会话的时间设置来转换成用户的时区。这一设置存储在上下文的tz键中，如{‘tz’: ‘Europe/Brussels’}。这一转换由客户端负责，而不是由服务端完成。

例如在布鲁塞尔(UTC+1)的用户输入12:00 AM数据库中会存储为10:00 AM UTC，而在纽约(UTC-4) 的用户查看时则为06:00 AM。

补充：请不要怀疑作者的数学是不是体育老师教的😂，布鲁塞尔为东一区，纽约为西五区，但冬令时和夏令时让这个问题变复杂了。将12:00修改为11:00应该就正确了。

ℹ️Odoo 服务日志消息时间戳使用UTC时间而非本地服务器时间

相反的转换，由会话时区转换为UTC，也需由客户端在将用户输入的datetime传回服务器时完成。日期对象可进行比较和相减来获取两个日期的时间差，时间差是一个timedelta对象。timedelta可通过date运算对date和datetime对象进行加减。这些对象由 Python 标准库datetime模块提供，以下是使用它进行的基本运算示例：

1
2
3
4
5
6
7
8

>>> from datetime import date
>>> date.today()
datetime.date(2019, 1, 12)
>>> from datetime import timedelta
>>> timedelta(days=7)
datetime.timedelta(7)
>>> date.today() + timedelta(days=7)
datetime.date(2019, 1, 19)

对于date, datetime和timedelta数据类型的完整参考请见Python 官方文档。Odoo 还在odoo.tools.date_utils模块中提供了一些额外的便利函数，这些函数有：

• start_of(value, granularity)是某个特定刻度时间区间的开始时间，这些刻度有year, quarter, month, week, day或hour
• end_of(value, granularity)是某个特定刻度时间区间的结束时间
• add(value, kwargs)为指定值加上一个时间间隔。kwargs参数由一个relativedelta对象来定义时间间隔。这些参数可以是years, months, weeks, days, hours, minutes等等
• subtract(value, **kwargs)为指定值减去一个时间间隔

relativedelta对象来自dateutil库，可使用months或years执行date运算（Python的timedelta标准库仅支持days）。更多内容请见相关文档。以下为上述函数的一些使用示例：

1
2
3
4
5
6
7
8
9
10
11

>>> from odoo.tools import date_utils
>>> from datetime import datetime
>>> date_utils.start_of(datetime.now(), 'week')
datetime.datetime(2019, 1, 7, 0, 0)
>>> date_utils.end_of(datetime.now(), 'week')
datetime.datetime(2019, 1, 13, 23, 59, 59, 999999)
>>> from datetime import date
>>> date_utils.add(date.today(), months=2)
datetime.date(2019, 3, 12)
>>> date_utils.subtract(date.today(), months=2)
datetime.date(2018, 11, 12)

这些工具方法在odoo.fields.Date和the odoo.fields.Datetime对象中也可使用，如：

• fields.Date.today()返回服务器所需格式的当前日期，它使用UTC作为一个引用。这足以计算默认值，这种情况下只需使用函数名无需添加括号。
•  fields.Datetime.now() 返回服务器所需格式的当前datetime，它使用UTC作为一个引用。这足以计算默认值，
• fields.Date.context_today(record, timestamp=None)在会话上下文中返回带有当前日期的字符串。时间从记录上下文中获取。可选项timestamp参数是一个datetime对象，如果传入将不使用当前时间，而使用传入值。
• fields.Datetime.context_timestamp(record, timestamp)将原生的datetime值(无时区)转换为具体时区的datetime。时区从记录上下文中提取，因此使了前述函数名。

转换文本形式的日期和时间

在Odoo 12以前，在进行运算前我们需要对文本形式的date和datetime进行转换。有些工作可帮助我们完成文本和原生数据类型的相互转换。这在此前的 Odoo 版本中都非常有用并且在 Odoo 12中也仍然相关：我们要将给到的日期格式化为文本。为便于格式之间的转换，fields.Date和fields.Datetime都提供了如下函数：

• to_date将字符串转换为date对象
• to_datetime(value)将字符串转换为datetime对象
• to_string(value)将date或datetime对象转换为 Odoo 11及之前版本Odoo服务所需的字符串格式

函数所需的文本格式由 Odoo 通过如下方式默认预置：

• odoo.tools.DEFAULT_SERVER_DATE_FORMAT
• odoo.tools.DEFAULT_SERVER_DATETIME_FORMAT

它们分别与%Y-%m-%d和%Y-%m-%d %H:%M:%S相对应。from_string用法示例如下：

1
2
3

>>> from odoo import fields
>>> fields.Datetime.to_datetime('2019-01-12 13:48:50')
datetime.datetime(2019, 1, 12, 13, 48, 50)

对于其它的日期和时间格式，可使用datetime对象中的strptime方法：

1
2
3

>>> from datetime import datetime
>>> datetime.strptime('1/1/2019', '%d/%m/%Y')
datetime.datetime(2019, 1, 1, 0, 0)

在记录中写入

有两种写入记录的方式：使用对象形式直接分配和使用write() 方法。第一种很简单但一次只能操作一条记录，效率较低。因为每次分配都执行一次写操作，会产生冗余的重复计算。第二种要求写入关联字段时使用特殊语法，但每条命令可写入多个字段和记录，记录计算更为高效。

使用对象形式分配值写入

记录集实施活跃记录模式。也就是说我们可以为其分配值，并且会将这些修改在数据库中持久化存储。这是一种操作数据的易于理解和便捷的方式，但一次只能操作一个字段和一条记录。如：

1
2
3
4
5
6

>>> root = self.env['res.users'].browse(1)
>>> print(root.name)
OdooBot
>>> root.name = 'Superuser'
>>> print(root.name)
Superuser

虽然使用的是活跃记录模式，也可以通过分配记录值来设置关联字段。对于many-to-one字段，分配的值必须是单条记录（单例）。对于to-many字段，也可以通过一条记录集分配，来替换关联记录列表为新列表（如果有的话），这里允许任何大小的记录集。

通过 write()方法写入

我们还可以使用write()方法来同时更新多条记录中的多个字段，仅需一条数据库命令。所以在重视效果时就应优先考虑这一方式。write() 接收一个字典来进行字段和值的映射。这会更新记录集中的所有记录并且没有返回值，如：

1
2
3
4

>>> Partner = self.env['res.partner']
>>> recs = Partner.search( [('name', 'ilike', 'Azure')] )
>>> recs.write({'comment': 'Hello!'})
True

与对象形式的分配不同，使用write() 方法时我们不能直接为关联字段分配记录集对象。取而代之的是，我们需要使用所需的记录ID来从记录集中进行提取。在写入many-to-one字段时，写入的值必须是关联记录的ID。例如，我们不用self.write({‘user_id’: self.env.user})，而应使用self.write({‘user_id’: self.env.user.id})。

在写入to-many字段时，写入的值必须使用和 XML 数据文件相同的特殊语法，这在第五章 Odoo 12开发之导入、导出以及模块数据中有介绍。比如，我们设置图书作者列表为author1和author2，这是两条 Partner 记录。| 管道运算符可拼接记录来创建一个记录集，因此使用对象形式的分配可以这么写：

1

publisher.child_ids = author1 | author2

使用write()方法，同样的操作如下：

1

book.write( { 'child_ids': [(6, 0, [author1.id, author2.id])] } )

回顾第五章 Odoo 12开发之导入、导出以及模块数据的写入语法，最常用的命令如下：

• (4, id, _)添加一条记录
• (6, _, [ids])替换关联记录列表为所传入的列表

写入日期和时间值

从 Odoo 12开始，不论是直接分配还是使用 write()方法，日期和时间字段都可以 Python 原生数据类型写入。我们仍可以使用文本形式值写入日期和时间：

1
2
3
4
5
6

>>> demo = self.search([('login', '=', 'demo')])
>>> demo.login_date
False
>>> demo.login_date = '2019-01-01 09:00:00'
>>> demo.login_date
datetime.datetime(2019, 1, 1, 9, 0)

创建和删除记录

write()方法用于向已有记录写入日期，但我们还需要创建和删除记录。这通过create()和unlink()模型方法实现。create()接收所需创建记录字段和值组成的字典，语法与 write()一致。没错，默认值会被自动应用，如下所示：

1
2
3
4
5
6

>>> Partner = self.env['res.partner']
>>> new = Partner.create({'name': 'ACME', 'is_company': True})
>>> print(new)
res.partner(64,)
>>> print(new.customer) # customer标记默认为 True
True

unlink()方法会删除记录集中的记录，如下所示：

1
2
3
4
5
6
7

>>> rec = Partner.search([('name', '=', 'ACME')])
>>> rec.unlink()
2019-01-12 06:32:48,601 2612 INFO dev12 odoo.models.unlink: User #1 deleted mail.message records with IDs: [28]
2019-01-12 06:32:48,651 2612 INFO dev12 odoo.models.unlink: User #1 deleted ir.attachment records with IDs: [416, 415, 414]
2019-01-12 06:32:48,655 2612 INFO dev12 odoo.models.unlink: User #1 deleted res.partner records with IDs: [64]
2019-01-12 06:32:48,666 2612 INFO dev12 odoo.models.unlink: User #1 deleted mail.followers records with IDs: [7]
True

以上我们看到日志中几条其它记录被删除的消息，这些是所删除 partner 关联字段的串联删除。

还有copy()模型方法可用于复制已有记录，它接收一个可选参数来在新记录中修改值，如复制demo 用户创建一个新用户：

1
2

>>> demo = self.env.ref('base.user_demo')
>>> new = demo.copy({'name': 'Daniel', 'login': 'daniel', 'email': ''})

带有copy=False属性的字段不会被自动拷贝。to-many关联字段带有该标记时默认被禁用，因此也不可拷贝。

重构记录集

记录集还支持一些其它运算。我们可查看一条记录是否在记录集中。如果x是一个单例，并且my_recordset是一个包含多条记录的记录集，可使用如下代码：

• x in my_recordset
• x not in my_recordset

还能使用如下运算：

• recordset.ids 返回记录集元素的ID列表
• recordset.ensure_one()检查是否为单条记录（单例）；若不是，则抛出ValueError异常
• recordset.filtered(func)返回一个过滤了的记录集，func可以是一个函数或一个点号分隔的表达式来表示字段路径，可参见下面的示例。
• recordset.mapped(func)返回一个映射值列表。除函数外，还可使用文本字符串作为映射的字段名。
• recordset.sorted(func)返回一个排好序的记录值。除函数外，文本字符串可用作排序的字段名。reverse=True是其可选参数。

以下是这些函数的使用示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

>>> rs0 = self.env['res.partner'].search([])
>>> len(rs0)
48
>>> starts_A = lambda r: r.name.startswith('A')
>>> rs1 = rs0.filtered(starts_A)
>>> print(rs1)
res.partner(63, 59, 14, 35)
>>> rs1.sorted(key=lambda r: r.id, reverse=True)
res.partner(63, 59, 35, 14)
>>> rs2 = rs1.filtered('is_company')
>>> print(rs2)
res.partner(14,)
>>> rs2.mapped('name')
['Azure Interior']
>>> rs2.mapped(lambda r: (r.id, r.name))
[(14, 'Azure Interior')]

我们势必会对这些关联字段中的元素进行添加、删除或替换的操作，那么就带来了一个问题：如何操作这些记录集呢？

记录集是不可变的，也就是说不能直接修改其值。那么修改记录集就意味着在原有的基础上创建一个新的记录集。一种方式是使用所支持的集合运算：

• rs1 | rs2是一个集合的并运算，会生成一个包含两个记录集所有元素的记录集
• rs1 + rs2是集合加法运算，会将两个记录集拼接为一个记录集，这可能会带来集合中有重复记录
• rs1 & rs2是集合的交集运算，会生成一个仅在两个记录集中同时出现元素组成的数据集
• rs1 - rs2是集合的差集运算，会生成在rs1中有但rs2中没有的元素组成的数据集

还可以使用分片标记，例如：

• rs[0]和rs[-1]分别返回第一个和最后一个元素
• rs[1:]返回除第一元素外的记录集拷贝。其结果和rs - rs[0]相同，但保留了排序

ℹ️Odoo 10中的修改
从Odoo 10开始，记录集操作保留了排序。此前的 Odoo 版本中，记录集操作不一定会保留排序，虽然加运算和切片已知是保留排序的。

我们可以用如下运算通过删除或添加元素来修改记录集：

• self.author_ids |= author1：如果不存在author1，它会将author1加入记录集
• self.author_ids -= author1：如果author1存在于记录集中，会进行删除
• self.author_ids = self.author_ids[:-1]删除最后一条记录

关联字段包含记录集值。many-to-one 可包含单例记录集，to-many字段包含任意数量记录的记录集。

使用底层 SQL 和数据库事务

数据库引入运算在一个数据库事务上下文中执行。通常我们无需担心这点，因为服务器在运行模型方法时会进行处理。但有些情况下，可能需要对事务进行更精细控制。这可通过数据库游标self.env.cr来实现，如下所示：

• self.env.cr.commit()执行事务缓冲的写运算
• self.env.cr.rollback()取消上次 commit之后的写运算，如果尚未 commit，则回滚所有操作

小贴士： 在shell会话中，直到执行self.env.cr.commit()时数据操作才会在数据库中生效

通过游标execute() 方法，我们可以直接在数据库中运行 SQL 语句。它接收一个要运行的SQL 语句，以及第二个可选参数：一个用作 SQL 参数值的元组或列表。这些值会用在%s占位符之处。

• ℹ️注意：
  在cr.execute() 中我们不应直接编写拼接参数的SQL查询。众所周知这样做会带来SQL注入攻击的安全风险。保持使用%s占位符并通过第二个参数来传值。

如果使用SELECT查询，会获取到记录。fetchall() 函数以元组列表的形式获取所有行，dictfetchall()则以字典列表的形式获取，示例如下：

1
2
3
4
5
6

>>> self.env.cr.execute("SELECT id, login FROM res_users WHERE login=%s OR id=%s", ('demo',1))
>>> self.env.cr.fetchall()
[(1, '__system__'), (6, 'demo')]
>>> self.env.cr.execute("SELECT id, login FROM res_users WHERE login=%s OR id=%s", ('demo',1))
>>> self.env.cr.dictfetchall()
[{'id': 1, 'login': '__system__'}, {'id': 6, 'login': 'demo'}]

还可以使用数据操纵语言(DML) 来运行指令，如UPDATE和INSERT。因为服务器保留数据缓存，这可能导致与数据库中实际数据的不一致。出于这个原因，在使用原生DML后，应使用self.env.cache.invalidate()清除缓存。

ℹ️注意：
直接在数据库中执行SQL语句可能会导致数据不一致，请仅在确定时进行该操作。

总结

在本文中，我们学习了如何操作模型数据以及执行 CRUD 运算：创建、读取、更新和删除数据。这是实现我们的业务逻辑和自动化的基石。

对于ORM API的测试，我们使用了Odoo交互式 shell 命令行。我们通过self.env环境运行了命令，该环境可访问模型注册表并提供命令运行相关信息的上下文，如当前语言 lang 和时区 tz。

记录集使用search()或browse([])ORM 方法创建。之后可对其进行遍历访问每个单例(一条独立的记录)。我们还可以使用对象样式的点号标记在单例中获取和设置记录值。

除直接为单例分配值外，我们还可以使用write()来通过单条命令更新记录集中的所有元素。create(), copy()和unlink()命令用于创建、拷贝和删除记录。

记录集可被检查和操作，检查运算符包含in和not in。重构运算符包含并集的|，交集的&以及切片:。可用的转换包含提取 ID 列表的.ids、.mapped()、.filtered() 或.sorted()。

最后，通过self.env.cr中暴露的游标对象可控制底层 SQL 运行和事务控制。

在下一篇文章中，我们将为模型添加业务逻辑层，实现通过ORM API来自动化操作的模型方法。

☞☞☞第八章 Odoo 12开发之业务逻辑 - 业务流程的支持

本文首发地址：Alan Hou 的个人博客

本文为最好用的免费ERP系统Odoo 12开发手册系列文章第六篇。

在本系列文章第三篇Odoo 12 开发之创建第一个 Odoo 应用中，我们概览了创建 Odoo 应用所需的所有组件。本文及接下来的一篇我们将深入到组成应用的每一层：模型层、视图层和业务逻辑层。

本文中我们将深入学习模型层，以及学习如何使用模型来设计应用所需的数据结构。我们会探索模型和字段的各项作用，包括定义模型关系、添加计算字段、创建数据约束。

本文的主要内容有：

• 学习项目 - 优化图书馆应用
• 创建模型
• 创建字段
• 模型间的关系
• 计算字段
• 模型约束
• 了解 Odoo的 base 模型

开发准备

本文代码基于第三章 Odoo 12 开发之创建第一个 Odoo 应用中所创建的代码。相关代码参见 GitHub 仓库，本文学习完成项目请参见GitHub 仓库。相关代码需放在一个 addons 路径中，然后在 Odoo中安装了 library_app 模型，本文中例子将会对该模块修改和新增代码。

学习项目 - 优化图书应用

在第三章 Odoo 12 开发之创建第一个 Odoo 应用中，我们创建了一个library_app插件模块，实现了一个简单的library.book模型用于展示图书目录。本文中，我们将回到该模块来丰富图书数据。我们将添加一个分类层级，添加如下用作图书分类：

• Name：分类标题
• Parent：所属父级分类
• Subcategories：将此作为父级分类的子分类
• Featured book或author: 此分类中所选图书或作者

图书模型中已有一些基本信息字段，我们会添加一些字段来展示 Odoo中的数据类型。我们还会为图书模型添加一些约束：

• 标题和出版日期应唯一
• 输入的ISBN应为有效

创建模型

模型是 Odoo 框架的核心，它们描述应用的数据结构，是应用服务和数据库存储之间的桥梁。可围绕模型实现业务逻辑来为应用添加功能，用户界面也建立在模型之上。下面我们将学习模型的通用属性，用于影响行为，以及几种模型类型：普通(regular)、临时(transient)和抽象(abstract)类型。

模型属性

模型类可以使用控制其部分行为的额外属性，以下是最常用的属性：

• _name 是我们创建的 Odoo 模型的内部标识符，在创建新模型时为必填。
• _description是对用户友好的模块记录标题，在用户界面中查看模型时显示。可选但推荐添加。
• _order设置浏览模型记录时或列表视图的默认排序。其值为 SQL 语句中 order by 使用的字符串，所以可以传入符合 SQL 语法的任意值，它有智能模式并支持可翻译及many-to-one字段名。

我们的图书模型中已使用了_name 和_description属性，可以添加一个_order属性来默认以图书名排序，然后按出版日期倒序排（新出版在前）。

1
2
3
4

class Book(models.Model):
    _name = 'library.book'
    _description = 'Book'
    _order = 'name, date_published desc'

在高级用例中还会用到如下属性：

• _rec_name在从关联字段（如many-to-one关联）中引用时作为记录描述。默认使用模型中常用的 name字段，但可以指定任意其它字段。
• _table是模型对应的数据表名。默认表名由 ORM 通过替换模块名中的点为下划线来自动定义，但是可通过该属性指定表名。
• _log_access=False用于设置不自动创建审计追踪字段：create_uid, create_date, write_uid和write_date。
• _auto=False 用于设置不自动创建模型对应的数据表。如有需要，可通过重载init()方法来创建数据库对象：数据表或视图。

还有用于继承模块的_inherit和_inherits属性，在本文后续会深入学习。

模型和 Python 类

Odoo 模型以 Python 类的形式展现，在前面的代码中，有一个继承了 models.Model类的 Python 类：Book，创建了新 Odoo 模型：library.book。Odoo的模型保存在中央注册表(central registry)中，可通过 env 环境对象(老 API 中称为 pool)获取。 它是一个数据库保存所有可用模型类引用的字典，其中的词条可通过模型名引用 。具体来说，模型方法中的代码可使用self.env[‘library.book’]来获取表示 library.book模型的模型类。

可以看出模型名非常重要，因为它是访问该注册表的关键。模型名的规则是以点号连接的小写单词，如library.book或library.book.category。内核模块中的其它示例有project.project, project.task和project.task.type。模型名应使用单数，如library.book而非library.books。

ℹ️由于历史原因，有些内核模型没有遵循这一规则，如res.users。

模型名必须全局唯一，因此第一个单词应使用模块关联的主应用对应，以图书应用而言，模型名前缀使用 library。其它示例如内核模块的project, crm和sale。另一方面 Python 类仅为所声明文件本地内容，名称仅需在代码文件中唯一即可。因为类名不会与其它模块中的类产生冲突，也就不需为其添加主应用相关的前缀。

类的命名规范是使用驼峰命名法（CamelCase），这与 Python 标准的 PEP8编码规范一致。

临时(Transient)模型和抽象模型

在前述代码中以及在大多数据 Odoo 模型中的类会继承models.Model类。这类模型在数据库中持久化存储：会为模型创建数据表并存储记录直至删除。但 Odoo 中还有另外两种模型类型：临时模型和抽象模型。

临时模型继承models.TransientModel类，用于向导式的用户交互。这类数据会存储在数据库中，但仅是临时性的。会定时运行清空 job 来清除这些表中的老数据。比如Settings > Translations菜单下的Load a Language对话窗口，就使用了临时模型来存储用户选择并实现向导逻辑。在第八章 Odoo 12开发之业务逻辑 - 业务流程的支持中会有讨论临时模型的示例。

抽象模型继承models.AbstractModel类，它不带有数据存储。抽象模型用作可复用的功能集，与使用 Odoo 继承功能的其它模型配合使用。例如mail.thread是 Discuss 应用中的一个抽象模型，用于为其它模型添加消息和follower 功能。

检查已有模型

通过 Python 类创建的模型和字段在用户界面中有自己的元标签。启动开发者模式，访问菜单Settings > Technical > Database Structure > Models，这里有数据库中的所有模型。点击列表中的模型会打开详情表单：

这是一个检查模型结构很好的工具，因为在这里可以看到不同模块所有自定义结果。上图中在右上角 In Apps字段中可以看到library.book模型的定义来自library_app和library_member两个模块。下方区域中还有几个包含附加信息的标签：

• Fields可快速查看模型字段
• Access Rights是授予不同权限组的访问控制规则
• Views显示模型所带的视图列表

我们可以通过开发者菜单下的View Metadata选项查看模型的外部标识符。模型的外部标识符或XML ID由 ORM 自动生成，但根据规则可预知，如library.book模型的外部标识符为model_library_book。在定义安全访问控制列表经常在 CSV 文件中使用到这些XML ID。

小贴士： 如第一章 使用开发者模式快速入门 Odoo 12中所见，模型表单是可编辑的。通过这里是可以创建并修改模型、字段和视图的。可在此处创建原型然后在插件模块中实现。

创建字段

创建新模型后的第一步是添加字段。Odoo 支持我们能想到的所有基本数据类型，如文本字符串、整型、浮点型、布尔型、日期、日期时间以及图片或二进制数据。下面就来看看 Odoo 中一些可用的字段类型吧。

基本字段类型

我们将为图书模型添加几种可用的字段类型，编辑library_app/models/library_book.py文件后 Book 类会长这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

class Book(models.Model):
...
    # String fields
    name = fields.Char('Title', required=True)
    isbn = fields.Char('ISBN')
    book_type = fields.Selection(
        [('paper', 'Paperback'),
        ('hard', 'Hardcover'),
        ('electronic', 'Electronic'),
        ('other', 'Other')],
        'Type')
    notes = fields.Text('Internal Notes')
    descr = fields.Html('Description')

    # Numeric fields:
    copies = fields.Integer(default=1)
    avg_rating = fields.Float('Average Rating', (3,2))
    price = fields.Monetary('Price', 'currency_id')
    currency_id = fields.Many2one('res.currency') # price helper

    # Date and time fields
    date_published = fields.Date()
    last_borrow_date = fields.Datetime(
        'Last Borrowed On',
        default=lambda self: fields.Datetime.now())

    # Other fields
    active = fields.Boolean('Active?', default=True)
    image = fields.Binary('Cover')

    # Relational Fields
...

此处是 Odoo 中所带的非关联字段示例，每个字段都带有所需的位置参数。

ℹ️Python 中有两类参数：位置参数和关键字参数。位置参数需按指定顺序使用。例如，f(x, y)应以f(1, 2)方式调用。关键字参数通过参数名传递。如同一个例子，可使用f(x=1, y=2)甚至是f(1, y=2)两种传参方式混用。更多有关关键字参数知识参见 Python 官方文档。

对于大多数非关联字段，第一个参数是字段标题，与字符串字段参数相对应。它用作用户界面标签的默认文本。这个参数是可选的，如未传入，会根据字段名将下划线替换为空格并将单词首字母大写来自动生成。以下为可用的非关联字段类型以及其对应的位置参数：

• Char(string)是一个单行文本，唯一位置参数是string字段标签。
• Text(string)是一个多行文本，唯一位置参数是string字段标签。
• Selection(selection, string)是一个下拉选择列表。选项位置参数是一个[(‘value’, ‘Title’),]元组列表。元组第一个元素是存储在数据库中的值，第二个元素是展示在用户界面中的描述。该列表可由其它模块使用selection_add关键字参数扩展。
• Html(string)存储为文本字段，但有针对用户界面 HTML 内容展示的特殊处理。出于安全考虑，该字段会被清洗，但清洗行为可被重载。
• Integer(string)仅需字段标题字符串参数。
• Float(string, digits)带有第二个可选参数digits，该字段是一个指定字段精度的(x,y)元组，x 是数字总长，y 是小数位。
• Monetary(string, currency_field)与浮点字段类似，但带有货币的特殊处理。第二个参数currency_field用于存储所使用货币，默认应传入currency_id字段。
• Date(string)和Datetime(string)字段只需一个字符串文本位置参数。
• Boolean(string)的值为True 或False，可传入一个字符串文本位置参数。
• Binary(string)存储文件类二进制文件，只需一个字符串文本位置参数。它可由Python使用 base64编码字符串进行处理。

ℹ️Odoo 12中的修改
Date和Datetime 字段现在 ORM 中作为日期对象处理。此前的版本中作为文本字符串处理，进行操作时需与 Python 日期对象间进行转换。

文本字符串：Char, Text和Html有一些特有属性：

• size (Char)设置最大允许尺寸。无特殊原因建议不要使用，例如可用于带有最大允许长度的社保账号。
• translate使用得字段内容可翻译，带有针对不同语言的不同值。
• trim默认值为 True，启动在网络客户端中自动去除周围的空格。可通过设置trim=false来取消。

ℹ️Odoo 12中的修改
trim字段属性在 Odoo 12中引入，此前版本中文本字段保存前后的空格。

除这些以外，还有在后面会介绍到的关联字段。不过， 我们还要先了解下有关字段属性的其它知识。

常用字段属性

字段还有一些其它属性供我们定义其行为。以下是常用的属性，通常都作为关键字参数：

• string是字段的默认标签，在用户界面中使用。除Selection和关联字段外，它都是第一个位置参数，所以大多数情况下它用作关键字参数。如未传入，将由字段名自动生成。
• default设置字段默认值。可以是具体值（如 active字段中的default=True），或是可调用引用，有名函数或匿名函数均可。
• help提供 UI 中鼠标悬停字段向用户显示的提示文本。
• readonly=True会使用户界面中的字段默认不可编辑。在 API 层面并没有强制，模型方法中的代码仍然可以向其写入。仅针对用户界面设置。
• required=True使得用户界面中字段默认必填。这通过在数据库层面为列添加NOT NULL 约束来实现。
• index=True为字段添加数据库索引，让搜索更快速，但同时也会部分降低写操作速度。
• copy=False让字段在使用 ORM copy()方法复制字段时忽略该字段。除 to-many 关联字段外，其它字段值默认会被复制。
• groups可限制字段仅对一些组可访问并可见。值为逗号分隔的安全组XML ID列表，如groups=’base.group_user,base.group_system’。
• states传入依赖 state字段值的 UI 属性的字典映射值。可用属性有readonly, required和invisible，例如states={‘done’:[(‘readonly’,True)]}。

ℹ️注意states 字段等价于视图中的 attrs 属性。同时注意视图也支持 states 属性，但用途不同，传入逗号分隔的状态列表来控制元素什么时候可见。

以下为字段属性关键字参数的使用示例：

1
2
3
4
5
6
7
8
9

name = fields.Char(
    'Title',
    default=None,
    index=True,
    help='Book cover title',
    readonly=False,
    required=True,
    translate=False,
)

如前所述，default 属性可带有固定值，或引用函数来自动计算默认值。对于简单运算，可使用 lambda 函数来避免过重的有名函数或方法的创建。以下是一个计算当前日期和时间默认值的常用示例：

1
2
3
4

last_borrow_date = fields.Datetime(
    'Last Borrowed On',
    default=lambda self: fields.Datetime.now(),
)

默认值也可以是一个函数引用，或待定义函数名字符串：

1
2
3
4
5
6
7

last_borrow_date = fields.Datetime(
    'Last Borrowed On',
    default='_default_last_borrow_date',
)

def _default_last_borrow_date(self):
    return fields.Datetime.now()

当模块数据结构在不同版本中变更时以下两个属性非常有用：

• deprecated=True在字段被使用时记录一条 warning 日志
• oldname=’field’是在新版本中重命名字段时使用，可在升级模块时将老字段中的数据自动拷贝到新字段中

特殊字段名

一些字段名很特别，可能是因为它们出于特殊目的作为 ORM 保留字，或者是由于内置功能使用了一些默认字段名。id 字段保留以用作标识每条记录的自增数字以及数据库主键，每个模型都会自动添加。

以下字段只要模型中没设置_log_access=False都会在新模型中自动创建：

• create_uid为创建记录的用户
• create_date是记录创建的日期和时间
• write_uid是最后写入记录的用户
• write_date是最后修改记录的日期和时间

每条记录的这些字段信息都可通过开发者菜单下的View Metadata进行查看。一些内置 API 功能默认需要一些指定字段名。避免在不必要的场合使用这些字段名会让开发更轻松。其中有些字段名被保留并且不能在其它地方使用：

• name (通常为 Char)默认作为记录的显示名称。通过是一个 Char，但也可以是 Text 或Many2one字段类型。用作显示名的字段可修改为_rec_name模型属性。
• active (Boolean型)允许我们关闭记录。带有active=False的记录会自动从查询中排除掉。可在当前上下文中添加{‘active_test’: False} 来关闭这一自动过滤。可用作记录存档或假删除（soft delete）。
• state (Selection类型) 表示记录生命周期的基本状态。它允许使用states字段属性来根据记录状态以具备不同的 UI 行为。动态修改视图：字段可在特定记录状态下变为readonly, required或invisible。
• parent_id和parent_path Integer和Char型)对于父子层级关系具有特殊意义。本文后续会进行讨论。

ℹ️Odoo 12中的修改
层级关联现在使用parent_path字段，它替代了老版本中已淘汰的parent_left和 parent_right字段(整型)。

到目前为止我们讨论的都是非关联字段。但应用数据结构中很大一部分是描述实体间关联的。下面就一起来学习。

模型间的关系

中、大型业务应用有一个结构数据模型，需要关联所涉及到的不同实体间的数据。要实现这点，需要使用关联字段。再来看看我们的图书应用，图书模型中有如下关系：

• 每本书有一个出版商。这是一个many-to-one 关联，在数据库引擎中通过外键实现。反过来则是one-to-many关联，表示一个出版商可出版多本书。
• 每本书可以有多名作者。这是一个many-to-many关联，反过来还是many-to-many关联，因为一个作者也可以有多本书。

下面我们就会分别讨论这些关联。具体的用例就是层级关联，即一个模型中的记录与同模型中的其它记录关联。我们将引入一个图书分类模型解释这一情况。最后，Odoo 框架还支持弹性关系，即一个字段可指向其它表中的字段，这称为引用字段。

Many-to-one关联

many-to-one关联是对其它模型中记录的引用，例如在图书模型中，publisher_id表示图书出版商，是对partner记录的一个引用：

1
2

publisher_id = fields.Many2one(
    'res.partner', string='Publisher')

与所有关联字段一样，Many2one字段的第一个位置参数是关联模型(comodel关键字参数)。第二位置参数是字段标签(string关键字参数)，但这和其它关联字段不同，所以推荐使用像以上代码一样一直使用string关键字参数。

many-to-one模型字段在数据表中创建一个字段，并带有指向关联表的外键，其中为关联记录的数据库 ID。以下是many-to-one字段可用的关键字参数：

• ondelete定义关联记录删除时执行的操作：

  • set null (默认值): 关联字段删除时会置为空值
  • restricted：抛出错误阻止删除
  • cascade：在关联记录删除时同时删除当前记录

• context是一个数据字典，可在浏览关联时为网页客户端传递信息，比如设置默认值。第八章 Odoo 12开发之业务逻辑 - 业务流程的支持中会做深入说明。

• domain是一个域表达式：使用一个元组列表过滤记录来作为关联记录选项，第八章 Odoo 12开发之业务逻辑 - 业务流程的支持中会详细说明。

• auto_join=True允许ORM在使用关联进行搜索时使用SQL连接。使用时会跳过访问安全规则，用户可以访问安全规则不允许其访问的关联记录，但这样 SQL 的查询会更有效率且更快。

• delegate=True 创建一个关联记录的代理继承。使用时必须设置required=True和ondelete=’cascade’。代理继承更多知识参见第四章 Odoo 12 开发之模块继承。

One-to-many反向关联

one-to-many关联是many-to-one的反向关联。它列出引用该记录的关联模型记录。比如在图书模型中，publisher_id与 parnter 模型是一个many-to-one关联。这说明partner与图书模型可以有一个one-to-many的反向关联，列出每个出版商出版的图书。

要让关联可用，我们可在 partner 模型中添加它，在library_app/models/res_partner.py文件中添加如下代码：

1
2
3
4
5
6
7
8

from odoo import fields, models

class Partner(models.Model):
    _inherit = 'res.partner'
    published_book_ids = fields.One2many(
        'library.book', # related model
        'publisher_id', # fields for "this" on related model
        string='Published Books')

我们向模块添加了新文件，所以不要忘记在library_app/models/init.py中导入该文件：

1
2

from . import library_book
from . import res_partner

One2many字段接收三个位置参数：

• 关联模型 (comodel_name关键字参数)
• 引用该记录的模型字段 (inverse_name关键字参数)
• 字段标签 (string关键字参数)

其它可用的关键字参数与many-to-one字段相同：context, domain和ondelete（此处作用于关联中的 many 这一方）。

Many-to-many关联

在两端都存在to-many关联时使用many-to-many关联。还是以我们的图书应用为例，书和作者之间是many-to-many关联：一本书可以有多个作者，一个作者可以有多本书。图书端有一个library.book模型：

1
2
3
4
5

class Book(models.Model):
    _name = 'library.book'
...
    author_ids = fields.Many2many(
        'res.partner', string='Authors')

在作者端，我们也可以为res.partner添加一个反向关联：

1
2
3
4

class Partner(models.Model):
    _inherit = 'res.partner'
    book_ids = fields.Many2many(
        'library.book', string='Authored Books')

Many2many最少要包含一个关联模型位置参数（comodel_name关键字参数），推荐为字段标签提供一个string参数。

在数据库层面上，many-to-many关联不会在已有表中添加任何列。而是自动创建一个关联表来存储记录间的关联，该表仅有两个 ID 字段，为两张关联表的外键。默认关联表名由两个表名中间加下划线并在最后加上_rel 来组成。我们图书和作者关联，表名应为library_book_res_partner_rel。

有时我们可能需要重写这种自动生成的默认值。一种情况是关联模型名称过长，导致关联表名的长度超出PostgreSQL数据库63个字符的上限。这时就需要手动选择一个关联表名来符合字符数据要求。另一种情况是我们需要在相同模型间建立第二张many-to-many关联表。这时也需要手动提供一个关联表名来避免与已存在的第一张表名冲突。

有两种方案来重写关联表名：位置参数或关键字参数。通过字段位置参数定义示例如下：

1
2
3
4
5
6
7

# Book <-> Authors关联(使用位置参数)
author_ids = fields.Many2many(
    'res.partner', # 关联模型（尾款）
    'library_book_res_partner_rel', # 要使用的关联表名
    'a_id', # 本记录关联表字段
    'p_id', # 关联记录关联表字段
    'Authors') # string标签文本

要使可读性更强，也可使用关键字参数：

1
2
3
4
5
6
7

# Book <-> Authors关联(使用关键字参数)
author_ids = fields.Many2many(
    comodel_name='res.partner', # 关联模型(必填)
    relation='library_book_res_partner_rel', # 关联表名
    column1='a_id', # 本记录关联表字段
    column2='p_id', # 关联记录关联表字段
    string='Authors') # string标签文本

与one-to-many relational字段相似，many-to-many 字段还可以使用context, domain和auto_join这些关键字参数。

ℹ️在创建抽象模型时，many-to-many中不要使用column1和column2属性。在 ORM 设计中对抽象模型有一个限制，如果指定关联表列名，就无法再被正常继承。

层级关联

父子树状关联使用同一模型中many-to-one关联表示，来将每条记录引用其父级。反向的one-to-many关联对应记录的子级。Odoo 通过域表达式附加的child_of和parent_of操作符改良了对这些层级数据结构的支持。只要这些模型有parent_id字段（或_parent_name有效模型定义）就可以使用这些操作符。

通过设置_parent_store=True和添加parent_path帮助字段可加快层级树的查询速度。该字段存储用于加速查询速度的层级树结构信息。

ℹ️Odoo 12中的修改
parent_path帮助字段在 Odoo 12中引入。此前版本中使用parent_left和parent_right整型字段来实现相同功能，但在 Odoo 12中淘汰了这些字段。

注意这些附加操作会带来存储和执行速度的开销，所以最好是用到读的频率大于写的情况下，比如本例中的分类树。仅在优化多节点深度层级时才需要使用，对于小层级或浅层级的可能会被误用。

为演示层级结构，我们将为图书应用添加一个分类树，用于为图书分类。在library_app/models/library_book_category.py文件中添加如下代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

from odoo import api, fields, models

class BookCategory(models.Model):
    _name = 'library.book.category'
    _description = 'Book Category'
    _parent_store = True

    name = fields.Char(translate=True, required=True)
    # Hierarchy fields
    parent_id = fields.Many2one(
        'library.book.category',
        'Parent Category',
        ondelete='restrict')
    parent_path = fields.Char(index=True)

    # Optional but good to have:
    child_ids = fields.One2many(
        'library.book.category',
        'parent_id',
        'Subcategories')

这里定义了一个基本模型，包含引用父级记录的parent_id字段。为启用层级索引来加快树级搜索，添加了一个_parent_store=True 模型属性。使用该属性必须要添加且必须要索引parent_path字段。引用父级的字段名应为parent_id，但如果声明了可选的_parent_name模型属性，则可以使用任意其它字段名。

添加字段列出直接的子级非常方便，即为上述代码中的one-to-many反向关联。还有不要忘记在library_app/models/init.py文件中添加对以上代码的引用：

1
2
3

from . import library_book
from . import res_partner
from . import library_book_category

使用引用字段的弹性关联

普通关联字段指定固定的引用co-model模型，但Reference字段类型不受这一限制，它支持弹性关联，因此相同字段不用限制只指向相同的目标模型。作为示例，我们使用图书分类模型来添加引用重点图书或作者。因此该字段可引用图书或 partner：

1
2
3
4
5
6

class BookCategory(models.Model):
...   
    highlighted_id = fields.Reference(
        [('library.book', 'Book'), ('res.partner', 'Author')],
        'Category Highlight'
    )

该字段定义与 selection 字段相似，但这里选择项为该字段中可以使用的模型。在用户界面中，用户会先选择列表中的模型，然后选择模型中的指定记录。

ℹ️Odoo 12中的修改
删除了可引用模型配置表。在此前版本中，可用于配置在 Reference 字段中可用的模型。通过菜单Settings > Technical > Database Structure可进行查看。这些配置可在 Reference 字段中使用odoo.addons.res.res_request.referenceable_models函数来替代模型选择列表。

以下为有关引用字段的一些其它有用技术细节：

• 引用字段在数据库中以model,id字符串形式存储
• read()方法供外部应用使用，以格式化的(‘model_name’, id)元组返回，而不是常用的many-to-one字段的(id, ‘display_name’)形式

计算字段

字段值除普通的读取数据库中存储值外，还可自动由函数计算。计算字段的声明和普通字段相似，但有一个额外的compute参数来定义用于计算的函数。大多数情况下，计算字段包含书写业务逻辑。因此要完全使用这一功能，还要学习第八章 Odoo 12开发之业务逻辑 - 业务流程的支持。此处我们将解释计算字段用法，但会使用简单的业务逻辑。

图书有出版商，我们的例子是在图书表单中添加出版商的国别。实现该功能，我们会使用基于publisher_id的计算字段，将会从出版商的country_id字段中获取值。

编辑library_app/models/library_book.py文件中的图书模型，代码如下：

1
2
3
4
5
6
7
8
9
10
11

class Book(models.Model):
...
    publisher_country_id = fields.Many2one(
        'res.country', string='Publisher Country',
        compute='_compute_publisher_country'
    )

    @api.depends('publisher_id.country_id')
    def _compute_publisher_country(self):
        for book in self:
            book.publisher_country_id = book.publisher_id.country_id

以上代码添加了一个publisher_country_id字段，和一个计算其值的_compute_publisher_country方法。方法名作为字符串参数传入字段中，但也可以传递一个可调用引用(方法标识符，不带引号)。但这时需确定Python 文件中方法在字段之前定义。

计算如果依赖其它字段的话就需要使用@api.depends装饰器，通常都会依赖其它字段。它告诉服务器何时重新计算或缓存值。参数可接受一个或多个字段名，点号标记可用于了解字段关联。本例中，只要图书publisher_id的country_id变更了就会重新进行计算。

和平常一样，self 参数是要操作的字符集对象。我们需要对其遍历来作用于每条记录。计算值通过常用(写)操作来设置，本例中计算相当简单，我们为其分配当前图书的publisher_id.country_id值。

同样的计算方法可用于一个以上字段。这时同一方法在多个compute 字段参数中使用，计算方法将为所有计算字段分配值。

小贴士： 计算函数必须为一个或多个字段分配值用于计算。如果计算方法有 if 条件分支，确保每个分支中为计算字段分配了值。否则在未分配置值的分支中将会报错。

现在我们还不会修改该模块的视图，但可通过在图书表单视图中点击开发者菜单中的Edit View选项，直接在表单 XML 中添加该字段查看效果。不必担心出问题，在下次模块升级时会进行覆盖。

搜索和写入计算字段

我们刚刚创建的计算字段可读取但不可搜索或写入。默认情况下计算字段是实时计算，而不存储在数据库中。这也是无法像普通字段那样进行搜索的原因。

我们可通过实现特殊方法来开启搜索和写入操作。计算字段可与 compute 方法一起设置实现搜索逻辑的 search 方法，以及实现写入逻辑的 inverse 方法。使用这些方法，计算字段可修改如下：

1
2
3
4
5
6
7
8
9

class Book(models.Model):
...
    publisher_country_id = fields.Many2one(
        'res.country', string='Publisher Country',
        compute='_compute_publisher_country'，
        # store = False, # 默认不在数据库中存储
        inverse='_inverse_publisher_country',
        search='_search_publisher_country',
    )

计算字段中的写入是计算的反向(inverse)逻辑。因此处理写入操作的方法称为 inverse，本例中 inverse 方法很简单。计算将book.publisher_id.country_id 的值复制给book.publisher_country_id，反向操作是将写入book.publisher_country_id的值拷贝给book.publisher_id.country_id field字段：

1
2
3

def _inverse_publisher_country(self):
    for book in self:
        book.publisher_id.country_id = book.publisher_country_id

注意这会修改出版商partner记录数据，因此也会修改相同出版商图书的相关字段。常规权限控制对这类写操作有效，因此仅有对 partner 模型有写权限的当前用户才能成功执行操作。

要为计算字段开启搜索操作，需要实现search 方法。为此我们需要能够将计算字段的搜索转换为使用常规存储字段的搜索域。本例中，实际的搜索可通过关联的publisher_id Partner 记录的country_id来实现：

1
2

def _search_publisher_country(self, opearator, value):
    return [('publisher_id.country_id', operator, value)]

在模型上执行搜索时，域表达式用作实施过滤的参数。域表达式在第八章 Odoo 12开发之业务逻辑 - 业务流程的支持会做详细讲解，现在我们应了解它是一系列(field, operator, value)条件。

当域表达式的条件中出现该计算字段时就会调用这个搜索方法。它接收搜索的操作符和值，并将原搜索元素转换为一个域搜索表达式。country_id字段存储在关联的partner模型中，因此我们的搜索实现仅需修改原搜索表达式来使用publisher_id.country_id字段。

存储计算字段

通过在定义时设置store = True还可以将计算字段值保存到数据库中。在任意依赖变更时值就会重新计算。因为值已被存储，所以可以像普通字段一样被搜索，也就不需要使用 search 方法了。

关联字段

前面我们实现的计算字段仅仅是从关联记录中将值拷贝到模型自己的字段中。这种常用情况可以由 Odoo 使用关联字段功能自动处理。关联字段通过关联模型的字段可在模型中直接可用，并且可通过点号标记法直接访问。这样在点号标记法不可用时(如 UI 表单视图)也可以使用该字段。

要创建关联字段，我们像普通计算字段那样声明一个所需类型的字段，但使用的不是 compute 属性，而是 related属性，设置用点号标记链来使用所需字段。我们可以使用引用字段来获取与上例publisher_country_id计算字段相同的效果：

1
2
3
4

publisher_country_id = fields.Many2one(
    'res.country', string='Publisher Country',
    related='publisher_id.country_id',
)

本质上关联字段仅仅是快捷实现 search 和 inverse 方法的计算字段。也就是说可以直接对其进行搜索和写入，而无需书写额外的代码。默认关联字段是只读的，因inverse写操作不可用，可通过readonly=False字段属性来开启写操作。

ℹ️Odoo 12中的修改
现在关联字段默认为只读：readonly=True。此前版本中它默认可写，但事实证明这是一个默认值，因为它可能会允许修改配置或主数据这些不应被修改的数据。

还应指出这些关联字段和计算字段一样可使用store=True来在数据库中存储。

模型约束

通常应用需保证数据完整性，并执行一些验证来保证数据是完整和正确的。PostgreSQL数据库管理器支持很多可用验证：如避免重复，或检查值以符合某些简单条件。模型为此可声明并使用 PostgreSQL约束。一些检查要求更复杂的逻辑，最好是使用 Python 代码来实现。对这些情况，我们可使用特定的模型方法来实现 Python 约束逻辑。

SQL模型约束

SQL约束加在数据表定义中，并由PostgreSQL直接执行。它由_sql_constraints类属性来定义。这是一个元组组成的列表，并且每个元组的格式为(name, code, error)：

• name是约束标识名
• code是约束的PostgreSQL语法
• error是在约束验证未通过时向用户显示的错误消息

我们将向图书模型添加两个SQL约束。一条是唯一性约束，用于通过标题和出版日期是否相同来确保没有重复的图书；另一条是检查出版日期是否为未出版：

1
2
3
4
5
6
7
8
9
10

class Book(models.Model):
...
    _sql_constraints = [
        ('library_book_name_date_uq', # 约束唯一标识符
        'UNIQUE (name, date_published)', # 约束 SQL 语法
        'Book title and publication date must be unique'), # 消息
        ('library_book_check_date',
        'CHECK (date_published <= current_date)',
        'Publication date must not be in the future.'),
    ]

更多有关PostgreSQL约束语法，请参见官方文档。

Python模型约束

Python 约束可使用自定义代码来检查条件。检查方法应添加@api.constrains装饰器，并且包含要检查的字段列表，其中任意字段被修改就会触发验证，并且在未满足条件时抛出异常。就图书应用来说，一个明显的示例就是防止插入不正确的 ISBN 号。我们已经在_check_isbn()方法中书写了 ISBN 的校验逻辑。可以在模型约束中使用它来防止保存错误数据：

1
2
3
4
5
6
7
8
9

from odoo.exceptions import ValidationError

class Book(models.Model):
...
    @api.constrains('isbn')
    def _constrain_isbn_valid(self):
        for book in self:
            if book.isbn and not book._check_isbn():
                raise ValidationError('%s is an invalid ISBN' % book.isbn)

了解 Odoo的 base 模型

在前面文章中，我们一起创建了新模型，如图书模型，但也使用了已有的模型，如  Odoo 自带的Partner 模型。下面就来介绍下这些内置模型。Odoo 内核中有一个base插件模块。它提供了 Odoo 应用所需的基本功能。然后有一组内置插件模块来提供标准产品中的官方应用和功能。base模块中包含两类模型：

• 信息仓库(Information Repository)， ir.*模型
• 资源(Resources)， res.*模型

信息仓库用于存储 Odoo 所需数据，以知道如何作为应用来运作，如菜单、视图、模型、Action 等等。Technical菜单下的数据通常都存储在信息仓库中。相关的例子有：

• ir.actions.act_window用于窗口操作
• ir.ui.menu用于菜单项
• ir.ui.view用于视图
• ir.model用于模型
• ir.model.fields用于模型字段
• ir.model.data用于XML ID

资源包含基本数据，基本上用于应用。以下是一些重要的资源模型：

• res.partner用于业务伙伴，如客户、供应商和地址等等
• res.company用于公司数据
• res.currency用于货币
• res.country用于国家
• res.users用于应用用户
• res.groups用于应用安全组

这些应该有助于你在未来遇到这些模型时理解它们来自何处。

总结

学习完本文，我们熟悉了模型带给我们构造数据模型的可能性。我们看到模型通常继承models.Model类，但还可使用models.Abstract来创建可复用的 mixin 模型、使用models.Transient来创建向导或高级用户对话。我们还学习了常见的模型属性，如_order 用于排序，_rec_name用于记录展示的默认值。

模型中的字段定义了所有它存储的数据。我们了解了可用的非关联字段类型以及它们支持的属性。我们还学习了关联字段的几种类型：many-to-one, one-to-many和many-to-many，以及它们如何定义模型间的关系，包括层级父子关系。

大多数字段在数据库中存储用户的输入，但字段也可以通过 Python 代码自动计算值。我们看到了如何实现计算字段，以及一些高级用法，如使计算字段可写及可搜索。

还有模型定义的一部分是约束，保持数据一致性和执行验证，可以通过PostgreSQL或Python代码实现。

一旦我们创建了数据模型，就应该为它提供一些默认和演示数据。在下一篇文章中我们将学习如何使用数据文件在系统中导入、导出和加载数据。

☞☞☞第七章 Odoo 12开发之记录集 - 使用模型数据

本文首发地址：Alan Hou 的个人博客

本文为最好用的免费ERP系统Odoo 12开发手册系列文章第五篇。

大多数Odoo 模块的定义，如用户界面和安全规则，实际是存储在对应数据表中的数据记录。模块中的 XML 和 CSV 文件不是 Odoo 应用运行时使用，而是载入数据表的手段。正是因为这个原因，Odoo 模块的一个重要部分是在文件中放入数据以在插件安装时将其载入数据库。

模块可以包含初始数据和演示数据，可通过数据文件将它们加入模块。此外，了解 Odoo 数据的格式对于在项目实施上下文中导入导出业务数据也非常重要。

本文的主要内容有：

• 理解外部标识符的概念
• 导入导出数据文件
• 使用 CSV 文件
• 添加模块数据
• 使用 XML 数据文件

开发准备

本文要求读者可以运行Odoo 服务并已安装前面我们此前开发的图书应用。相关代码请见GitHub 仓库。你可能也同时安装了第四章 Odoo 12 开发之模块继承中创建的library_member模块，但本文并不要求使用该模型。

本文的更新后的代码请见GitHub 仓库。

理解外部标识符的概念

外部标识符，也称为XML ID，是用于唯一标识 Odoo 中特定记录的有可读性的字符串标识符。在Odoo 中加载数据时它们就很重要了，这样可以对已有数据记录进行修改或在其它数据记录中引用它。

首先我们将讨论外部标识符的工作原理以及如何对其进行检查。然后我们会学习如何使用网页客户端来查找指定数据记录的外部标识符，在创建插件模块或继承已有模块时需要经常用到。

外部标识符的工作原理

记录在数据库中的真实标识符是自动分配的序列号，在安装模块时没法预先知道将要分配的具体ID的。外部标识符让我们无需知道真实的数据库 ID便可以引用一条相关记录。XML ID 为数据库 ID 提供了一个方便的别名，藉于此我们可以在任何时刻引用某一指定记录。

Odoo 模块数据文件中使用XML ID来定义记录。其中一个原因是避免在升级模块时创建重复的记录，在升级时会再次将数据文件加载到数据库中。我们要检测已有记录来进行更新，而不是重复创建记录。另一个原因是使用XML ID来支持交叉数据：即需引用其它数据记录的数据记录。因为我们无法知道真实数据库 ID，使用XML ID来由 Odoo 框架来进行相应的转换。

Odoo 处理由外部标识符向所分配的真实数据库 ID 的转换。背后的机制相当简单：Odoo 维护一张外部标识符和对应数据库 ID 的映射表：ir.model.data model。

我们需启用开发者模式才能访问下文中的菜单。可通过在右上角头像左侧查看是否有调试图标，如果没有需在 Settings菜单页启用，具体方法可参照第一章 使用开发者模式快速入门 Odoo 12中的内容。

通过菜单访问Settings > Technical > Sequences & Identifiers > External Identifiers可查看已有映射。例如访问外部标识符列表并过滤出library_app模块，将可以看到该模块生成的外部标识符：

可以看到外部标识符有Complete ID标签。注意其组成部分为：模块名+.+标识符名，如library_app.action_library_book。

外部标识符仅需在 Odoo 模块内唯一，两个模块中使用相同标识符不会产生冲突。全局唯一标识符是由模块名和外部标识符共同组成的，在上图Complete ID项中可以看到。

在数据文件中使用外部标识符，我们可以选择完整的标识符或仅外部标识符部分。通常仅使用外部标识符会更简单，但使用完整标识符时我们可以引用其它模块中的数据记录。做引用时不要忘记在模块依赖中加入这些模块以确保在我们的记录之前加载这些记录。

小贴士： 有时即便引用相同模块中的XML ID也需使用完整标识符

在上图列表最上方可以看到library_app.action_library_book完整标识符。这是我们在模块中创建的菜单操作，在相应的菜单项中引用。点击进入表单视图查看详情。图中可以看出library_app模块中的action_library_book外部标识符映射到ir.actions.act_window模型中的记录 ID，此处为85：

除了作为其它应用引用记录的一种方式外，外部标识符还可以避免重复导入带来的重复数据。一旦外部标识符已存在，则会在原有记录上更新，避免了重复数据的新建。

查找外部标识符

在为我们的模块写入数据记录时，经常需要查找已有外部标识符来作引用。一种方式是访问菜单Settings > Technical > Sequences & Identifiers > External Identifiers，前面已经演示过。另一种方法是使用开发者菜单。在第一章 使用开发者模式快速入门 Odoo 12中介绍了如何激开发者模式。

要查找一个数据记录的外部标识符，我们应打开对应的表单视图，在开发者菜单中选择View Metadata选项。此时会显示一个带有记录数据库 ID 和外部标识符（也称作XML ID）的对话框。比如要查看 demo 用户 ID，需通过 Settings > Users & Companies > Users 进入用户表单视图，然后点击开发者工具菜单中的View Metadata选项。此时可以看到XML ID是base.user_demo，数据库 ID 是6：

查看表单、列表、搜索或 action 视图中的外部标识符，都可以使用开发者菜单。下面我们通过Edit View选项来打开相应视图的详情表单。此时可以查看到External ID字段，其值即为外部标识符。例如在下图中，可以看到图书表单视图的External ID为library_app.view_form_book：

导入导出 CSV 数据文件

导出数据文件并查看文件结构的简易方式是使用内置的导出功能。通过生成 CSV 文件，我们可以了解手动导入系统所需的格式，或编辑该文件批量导入，甚至是使用它生成我们插件模块的演示数据。

下面我们一起来学习从 Odoo 用户界面导入和导出的基础知识。

导出数据

数据导出是表单视图中的标准功能。要使用该功能， 需要勾选左侧的复选框来选择需导出的行，然后在上方的 Action 菜单中点击 Export 选项。首先我们要在图书应用中添加一些带有出版商和作者的图书。下例中我使用此前添加的书籍。

我们还需要安装 Contacts 应用，这样可以看到 Partner 的列表视图，可从该处导出记录。注意其默认视图为带有名片的看板视图，需要先切换为列表视图：

可通过勾选列头的筛选框来选择所有匹配当前搜索条件的记录。

ℹ️Odoo 9中的修改
在 Odoo 更早的版本中，只有屏幕上显示（当页）的记录能被导出。Odoo 9做出了修改，勾选列头的复选框可导出当前过滤的所有匹配记录，而不仅仅是当前显示。这对导出屏幕上无法展示全的大量记录非常有用。

点击 Export 选项进入Export Data 对话表单，可选择导出方式。我们比较关注的是导出方式可以让我们通过手动或插件模块来导入该文件：

在对话表单最上方，有两个选项：

• What do you want do do?（老版本中为Export type），选择Import-Compatible Export选项，这样导出数据在以后导入时格式更友好。
• Export formats：可选择CSV或Excel，我们将选择 CSV 格式来更好理解原始导出格式，在很多表单应用中都能被读取。

下一步选取要导出的列，本例中简化操作，仅选择External ID和Name。如果我们点击Export To File按钮，就会下载带有导出数据的文件。最终的 CSV 内容类似：

1
2
3
4
5

"id","name"
"__export__.res_partner_45_5b73e404","Kaiwan N Billimoria"
"__export__.res_partner_42_49816b0d","Packt"
"__export__.res_partner_44_9e374a59","Russ McKendrick"
"__export__.res_partner_43_e38db1b7","Scott Gallagher"

补充： 伸手党请注意这里及后续的 ID 字段都与导出的系统有关，不应直接使用

第一行中包含列名，导入时会使用它们自动匹配目录列。导出内容有两列：

• id：为每条记录分配的外部 ID，如果不存在，会在模块名处使用__export__ 作为前缀自动生成一条新ID。
• name： 联系人/Partner 名称

带有外部 ID 使我们可以编辑导出数据并重新导入来把修改更新到记录中。

小贴士： 由于会自动生成记录 id，导出或导入功能可用于批量编辑 Odoo 数据：将数据导出至 CSV，使用表单软件批量编辑数据，再导入 Odoo。

导入数据

首先应确认开启了导入功能，默认是开启的。如果没有，进入Settings > General Settings，在 Users 版块下勾选Import & Export选项即可。启用该选项后，列表视图上方 Create 按钮旁就会显示一个 Import按钮。

注意： Import & Export 设置安装base_import模块，该模块用于提供这一功能。

下面我们尝试批量编辑Contact或Partner数据。使用电子表单或文本编辑器打开CSV并修改几个值。将 id 栏留空即可新增行。前文已经提到第一列 id 作为每行的唯一标识符，这让已有记录可以被更新，而不会因重新导入数据重复创建。我们在导出表中编辑任意字段在导入时对应记录就会被更新。

对于要加入 CSV 文件的新行，我们可以自己添加外部标识符或将 id 列留空。两种方式都会创建新的记录。作为示例，我们添加一行id 留空、name 为Phillip K. Dick，来在数据库中新建这一记录。在 CSV文件中进行保存，点击 Import(Create 按钮旁)，然后点击 Load File 按钮选择磁盘中 CSV 的路径就出会出现如下导入助手：

点击右上角的Test Import按钮，检查数据正确性。由于导入的文件是在 Odoo 中导出文件基础上修改的，正常会有效并且各列会自动与数据库中对应字段匹配。因编辑所使用的软件各异，有可能需对分隔符和编码进行处理。现在可以点击 Import 按钮，修改和新建记录就会被载入到 Odoo 中。

CSV 数据文件中的关联记录

前面的示例非常简单，一旦我们开使用关联多张表的关联字段时，数据文件就会变得更为复杂。我们处理过图书中的 Partner 记录，下面就看一下如何在图书 CSV 文件中表示对这些 Partner 的引用。具体来说，有一个出版商(publisher_id字段)的many-to-one(或外键)关联，以及一个作者(author_ids字段)的many-to-many关联。

CSV 文件的表头行中关联列应在名称后添加一个/id。它将使用外部标识符来引用关联记录。本例中，我们将在publisher_id/id字段中加载图书出版商，使用关联 Partner 的外部 ID 作为其值。

注意： 可使用/.id来进行替代来使用数据库中的真实 ID（自动分配的数字 id），但极少使用到。除非有特别原因，否则请使用外部 ID 而非数据库ID。同时要记住数据库 ID 针对具体的数据库，所以如果导入到非原始数据库中这种操作大多数情况下都会失败。

CSV 数据文件中也可导入many-to-many字段，这和添加带双引号并由逗号分隔的外部 ID 列表一样简单。例如，要载入图书作者，将需要一个author_ids/id列，并使用一个关联 Partner外部 ID 的逗号分隔列表作为其值：

1
2

id, name, author_ids/id
book_docker, "Mastering Docker - Third Edition","__export__.res_partner_44_767f4606,__export__.res_partner_43_b97c9264"

One-to-many 字段通常是表头和行或父子关系，对于这类关系有特别的支持方式：对于同一条父记录可以有多个关联行。此处我们在 Partner 模型中有一个 one-to-many字段的例子：公司可带有多个联系人。如果从 Partner 模型中导出数据并包含Contacts/Name 字段，就可以看到要导入此类型数据的格式(Contacts 中选择Azure Interior：默认应为第一条，并执行前述的导出步骤)：

id和 name 列为父记录的，child_ids两列为子记录的。注意第一行记录以下父记录部分留空。上表中CSV 文件形式显示为：

1
2
3
4

"id","name","child_ids/id","child_ids/name"
"base.res_partner_12","Azure Interior","base.res_partner_address_15","Brandon Freeman"
"","","base.res_partner_address_28","Colleen Diaz"
"","","base.res_partner_address_16","Nicole Ford"

可以看到id和name这两列第一行有值，后两行都为空。其中的父记录为联系人的公司信息。另两行的前缀都是child_ids/并且在三行中都有数据。这些是父公司的联系人信息。第一行包含公司和第一个联系人，其余行仅包含联系人这一子信息。

添加模块数据

模块使用数据文件来加载默认数据、演示数据、用户界面定义和其它需存入数据库的配置。可以选择使用 CSV 或 XML 文件。

ℹ️Odoo 12中的修改
Odoo 11及之前版本支持YAML格式文件，但在 Odoo 12移除了相关支持。相关使用示例可参考 Odoo 11官方模块l10n_be，更多YAML格式相关信息，可访问http://yaml.org/。

模块所使用的 CSV 和我们前述使用导入功能时用的文件是一样的。在模块中使用这些文件时，文件名须与要导入数据的模型名一致。例如，导入library.book模型的 CSV 数据文件名应为library.book.csv。CSV 数据文件经常用作导入ir.model.access模型来获取权限定义，通常放在security/子目录下并命名为ir.model.access.csv。

演示数据

Odoo插件模块可安装演示数据，推荐支持该安装。为模块提示使用示例和测试用的数据集会非常有用。模块的演示数据通过__manifest__.py文件中的 demo 属性来声明。和 data 属性一样，后接一个包含模块相对路径的文件名列表。我们应为library.book模块添加一些演示数据，一个简易方式是从安装了模块的开发数据库中导出数据。

按惯例数据文件放在data/子目录下，应以data/library.book.csv保存在library_app模块下。因这个数据为模块所有，应在导出的数据中将标识符的前缀__export__去除。

例如res.partner.csv文件可能长这样：

1
2
3
4
5

id,name
res_partner_alexandre,"Alexandre Fayolle"
res_partner_daniel,"Daniel Reis"
res_partner_holger,"Holger Brunn"
res_partner_packt,"Packt Publishing"

那么图书演示数据文件library.book.csv就应该是这样的：

1
2
3
4

"id","name","date_published","publisher_id/id","author_ids/id"
library_book_ode11,"Odoo Development Essentials 11","2018-03-01",res_partner_packt,res_partner_daniel
library_book_odc11,"Odoo 11 Development Cookbook","2018-01-01",res_partner_packt,"res_partner_alexandre,res_partner
_holger"

注意文件中同一条数据因显示原因可能在不同行中，但实际是不能换行的。还应记得在__manifest__.py的 demo 属性中声明数据文件：

1
2
3
4

'demo': [
 'data/res.partner.csv',
 'data/library.book.csv',
],

文件会以声明的顺序来加载，这个很重要，因为文件可能会因为未被安装而无法引用其记录。只要启用了安装演示数据，下次更新时，这些内容就会被导入。

ℹ️数据文件会在模块升级时重新导入，但演示文件则并非如此，它们仅在安装时导入。

当然 XML 文件也可用于加载或初始化数据，还可使用普通 CSV 文件所不具备的功能。

使用 XML 数据文件

CSV 文件是一种展示数据方便简洁的格式，但 XML 文件更为强大，可在加载过程中提供更多的控制。比如，其文件名无需与所导入到的模型名称一致。因为XML格式通过文件内的XML元素可以提供更丰富的信息、更多的内容。

在前面的文章中我们已经使用过XML数据文件。视图和菜单项这类用户界面组件实际上都是存储在系统模型中的记录。模块中的XML文件是将这些记录加载到实例数据库的方式。我们将在library_app模块中添加一个数据文件data/book_demo.xml来作为展示，文件内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13

<?xml version="1.0"?>
<odoo noupdate="1">
    <!-- Data to load -->
    <record model="res.partner" id="res_partner_huxley">
        <field name="name">Aldous Huxley</field>
    </record>
    <record model="library.book" id="library_book_bnw">
        <field name="name">Brave New World</field>
        <field name="author_ids"
                eval="[(4, ref('res_partner_huxley'))]" />
        <field name="date_published">1932-01-01</field>
    </record>
</odoo>

老规矩，新的数据文件应在__manifest__.py中声明：

1
2
3
4

    'demo': [
...
        'data/book_demo.xml',
    ],

类似 CSV 文件，该文件也会将数据加载到图书模型中。

XML文件包含一个外层<odoo>元素，内部可包含多个<record>元素与对应 CSV 数据行。

ℹ️数据文件中的外层元素在9.0中才引入用于替换此前的标签。现在仍支持外层元素内的标签，为可选项。事实上现在和是等价的，我们可以在数据文件中使用任意一个作为外层元素。

元素有两个强制属性： model 和作为记录外部标识符的 id，每个字段使用一个标签来进行写入。注意此处字段名内不可使用斜杠标记，如不可使用。应使用 ref 属性来引用外部标识符，一会儿就会讨论到关联 to-many 字段。

你可能注意到在外层元素中使用了noupdate=”1”属性。这防止了在模块升级时数据记录的载入，不至于在后续编辑中丢失数据。

noupdate 数据属性

升级模块时，会重新加载数据并重写模块记录。要谨记这可能意味着在升级模块时会重写任何对模块数据的手动更改。

小贴士： 值得注意的是，手动对视图所做的自定义修改会在下一次模块升级时丢失。避免这一问题正确的方法是创建继承视图来引入要做的修改。

这种重写行为是默认的，但可以修改有些数据仅在安装时导入，后续模块更新时则予以忽略，这正是通过<odoo>或<data>元素中的noupdate=”1”来实现的。

这对于需初始化配置且预期需自定义的数据来说非常有用，因为这些手动修改在模块更新时是安全的。例如在记录访问规则中经常使用，可以适应具体的实施需求。

在同一 XML 文件中可以有多个<data>版块。可通过这个来分隔仅需导入一次的数据（noupdate=”1”）和需在每次更新时重新导入的数据（noupdate=”0”）。noupdate=”0”是默认值，所以可以省略不写。注意还必须要有一个外层 XML 元素，就这个例子而言，使用两个<data>标签，并在外层包裹一个<odoo>或<data>元素。

小贴士： noupdate属性在开发模块时可能会引起不适，因为会忽略后续修改。一个解决方案是，使用-i 参数重新安装模块而不是使用-u 参数进行更新。命令行中使用-i 参数重新安装会忽略数据记录中的noupdate标记。

noupdate标记存储在每条记录的外部标识符信息中。可通过 Technical 菜单中的External Identifiers表单手动编辑，勾选Non Updatable 复选框即可。

ℹ️Odoo 12中的修改
点击开发者菜单中的View Metadata时，现在在弹出的对话框中 XML ID 下面还会显示No Update的值。并且在该处可通过点击来修改该标记的值。

在 XML 中定义记录

在 XML 文件中，每个<record>元素有两个基本属性：id 和 model，并包含为对应列设置的值。 id 属性对应记录外部标识符，model 对应目标模型。元素有几种分配值的方法，下面一起来看看。

直接为字段设置值

元素的 name 属性标识要写入的字段。写入的值是元素内容：字段开、闭标签之间的文本。对于 date 和datetime，带有返回 date 或 datetime 对象表达式的 eval 属性可进行设置。返回的”YYYY-mm-dd”和”YYYY-mm-dd HH:MM:SS”字符串会进行转化。对于布尔字段，”0” and “False”都会转换成 False，而任意非空值都会转换成 True。

小贴士：Odoo 10中的修改
Odoo 10中改进了从数据文件中读取布尔值 False的方式。在老版本中，包含”0” and “False”在内的非空值都会转换成 True，直至 Odoo 9，布尔值仍需使用 eval 属性进行设置，如 eval=”False”。

通过表达式设置值

设置字段值更复杂的方式是通过 eval 属性，它会运行 Python 表达式并将结果分配给字段。表达式通过 Python 内置的以及一些其它可创建表达式标识符的上下文求值。

可使用如下 Python 模块来处理日期：time, datetime, timedelta和relativedelta。通过它们可以计算日期值，在演示和测试数据经常会用到，以让日期和模块安装日期较近。关于 Python 模块更多这类知识，请参考官方文档。

比如，把值设为前一天，可使用如下代码：

1
2

<field name="date_published"
    eval="(datetime.now() + timedelta(-1))" />

求值上下文还可使用ref()函数，用于将外部标识符转换为对应的数据库 ID。这可用于为关联字段设置值。比如，可以使用它为publisher_id设置值：

1

<field name="publisher_id" eval="ref('res_partner_packt')" />

在 many-to-one 关联字段上设置值

对于many-to-one关联字段，要写入的是关联记录的数据库 ID。在 XML 文件中，我们一般会知道记录的XML ID，然后就需要把它转换成实际的数据库 ID。

一种方式是像前文那样使用带有 ref()函数的 eval 属性。更简单的替代方式是使用在元素中可用的ref 属性，使用它设置publisher_id many-to-one字段的值，我们可以这么写：

1

<field name="publisher_id" ref="res_partner_packt" />

在 to-many 关联字段上设置值

对于one-to-many和many-to-many字段，设置的不是单个 ID，而是一组关联 ID。并且还进行几种操作-我们可能需要将当前的关联记录列表替换成另外一个，或为其添加几次记录，甚至是删除其中的一些记录。

要让to-many字段支持写操作，我们要在 eval 属性中使用一种特殊的语法。我们使用一个元组组成的列表来写入to-many字段。每个元组有三个元素，构成一个写入命令，根据第一个元素中的代码进行对应操作。要重写图书作者列表，要使用如下代码：

1
2
3
4
5
6
7

<field
    name = "author_ids"
    eval = "[(6, 0,
        [ref('res_partner_alexandre'),
        ref('res_partner_holger')]
    )]"
/>

要往当前图书作者列表添加关联记录，需要添加如下代码：

1
2
3

<field name="author_ids"
    eval="[(4, ref('res_partner_daniel'))]"
/>

上述的例子非常常见。这里仅使用了一个命令，但在外层列中可以串联多条命令。添加(4)和 替换(6)是最常用的命令。在进行添加(4)时，不需要使用最后一个元素，因此在以上代码中省略了。

完整的可用命令如下：

• (0, _ , {‘field’: value})新建一条记录并将其与之关联
• (1, id, {‘field’: value})更新已关联记录的值
• (2, id, _)移除关联并删除 id 关联的记录
• (3, id, _)移除关联但不删除 id 关联的记录。通常使用它来删除many-to-many字段的关联记录
• (4, id, _)关联已存在记录，仅适用于many-to-many字段
• (5, _, _)删除所有关联，但不删除关联记录
• (6, _, [ids])替换已关联记录列表为此处的列表

上述下划线_字符代表非关联值，通常填入 o 或 False。

小贴士： 后面的非关联值可以放心地省略掉，如(4, id, _) 可使用(4, id)

常用模型的简写

如果回到第三章 Odoo 12 开发之创建第一个 Odoo 应用，我们在 XML 中还发现<record>之外的元素，如<act_window>和<menuitem>。这些是常用模型的简写方式，是比常用的<record>更为简练的符号。它们用于向 base 模型加载数据、组成用户界面，在第十章 Odoo 12开发之后台视图 - 设计用户界面会作更详细的探讨。

为便于查看，以下是可用的简写元素以及加载数据的对应模型：

• <act_window>是窗口操作模型ir.actions.act_window
• <menuitem>是菜单项模型ir.ui.menu
• <report>是报表操作模型ir.actions.report.xml
• <template>是存储在ir.ui.view模型中的 QWeb 模板

ℹ️Odoo 11中的修改
<url>标签已被淘汰并删除。此前的版本中它用作为 URL 操作模型ir.actions.act_url加载记录。

应当注意在用于修改已有记录时，简写元素会覆盖所有字段。这与仅写入所提供字段的<record>基础元素不同。因此在需修改用户界面元素指定字段时，应使用<record>元素。

XML 文件中的其它操作

截至目前我们了解了如何使用 XML 文件添加和更新数据。但也可以通过 XML 文件删除数据以及执行指定模型方法。对更复杂的数据场景会非常有用。

删除记录

我们可以使用<delete>元素删除数据记录，使用 ID 或搜索域来定位要删除的记录。例如，使用搜索域查找记录并删除：

1
2
3
4

<delete
    model="res.partner"
    search="[('id','=',ref('library_app.res_partner_daniel'))]"
/>

如果知道要删除记录的具体 ID，可使用 id 属性。上例还可以写成这样：

1

<delete model="res.partner" id="library_app.res_partner_daniel" />

调用模型方法

XML 文件还可以通过<function>元素在加载过程中执行任意方法，可用于设定演示和测试数据。比如 Odoo 捆绑的 Notes 应用，使用它来设定演示数据：

1
2
3
4
5
6

<data noupdate="1">
<function
    model="res.users"
    name="_init_data_user_note_stages"
    eval="[]" />
</data>

这会调用res.users模型中的_init_data_user_note_stages方法，不传任何参数。由参数列表eval传递，此处为空列表。

总结

本文中我们学习了如何在文件文中展示数据。可用作手动向 Odoo 导入数据，或放在插件模块中作为默认或演示数据。通过学习我们可以通过网页界面导出并导入 CSV 数据文件了，以及通过外部 ID 来检测并更新数据库中已有的记录。也可用作批量编辑数据，只需编辑导出的 CSV 文件再重新导入即可。

我们还详细学习了 XML 数据文件的结构以及所提供功能。不仅可以为字段设置值，还可以执行删除记录和调用方法一类的操作。

下一篇文章中，我们将集中学习如何使用记录来与模型中所含数据协作。这些工具可供我们实现应用的业务逻辑和规则。

☞☞☞第六章 Odoo 12开发之模型 - 结构化应用数据

学霸专区

1. XML ID 与外部 ID 的区别是什么？

2. 插件模块中可使用什么类型的数据文件？

3. 以下 XML 片段有什么问题？

   1	<field name="user_id">[(4, 0, [ref(base.user_demo)])]</field>?

4. 一个插件模块中的数据文件是否可以覆盖另一个模块中创建的记录？

5. 插件模块升级时，是否所有数据记录都会被重写为模块默认值？