导言
如果你在 Odoo 打开一张销售订单，看到客户信息下方那一行行的商品明细——那正是 One2many 字段在界面上的常见呈现。它把“一个父记录对应多个子记录”的关系可视化，是 Odoo 数据模型中最常见、最直观的构建单元之一。
本文将以实战视角讲清楚 One2many 是什么、在 Odoo ORM 中如何运作、什么时候该用它，以及如何通过 Odoo Studio 或直接在 Python 模块里创建与配置这类字段。
无论你是业务人员想看懂系统里的数据结构，还是开发者需要可操作的字段实现参考，这篇指南都包含了实用要点。
什么是 Odoo 中的 One2many 字段
在 Odoo 中，One2many 属于关系型字段的一种，用来在父模型中表示指向另一个模型的多条子记录。它是建立“1 对 多”联系的典型方式。
举个常见的设计思路：一个客户对应多张发票；一张销售订单包含多条订单明细；一个项目下有多个任务。父记录通过 One2many 在视图层把这些相关子记录聚合展示出来。
在 Odoo 界面里，One2many 通常以内嵌列表的形式出现在表单视图中，用户可以直接在父表单里增、删、改子记录，无需跳转到别的页面。这种内嵌表格是 Odoo 界面设计里最常见的交互模式之一。
与其他关系字段的区别
Odoo ORM 里常用的关系型字段主要有三类：
- Many2one：单条记录指向另一个模型的一条记录（例如，销售订单指向一个客户）。
- One2many：单条记录关联到另一个模型的多条记录（例如，销售订单对应多条订单明细）。
- Many2many：双方多对多的关联（例如，产品可以有多个标签，每个标签也能关联多个产品）。
当子记录只能属于单一父记录时，使用 One2many；如果子记录需要同时属于多个父记录，应采用 Many2many。选择关系类型决定了数据是否会被共享或必须复制。
在众多字段类型中，One2many 的特殊之处在于它本身不在父表中保存数据。它是一个“虚拟”视图，依赖子模型上的 Many2one 字段来反查相关记录。
字段的工作原理
从数据库角度看，One2many 并不在父模型的表里添加列；所有实际的外键都保存在子模型的表中，对应子记录有一个指向父记录 ID 的字段。
这是 Odoo ORM 的核心设计：每一个 One2many 都对应子模型上的一个 Many2one。One2many 只是把“找出子记录中那些外键等于当前父记录 ID 的行”这个反向查询封装成字段，供界面和代码使用。
One2many 与 Many2one 的定义关系
在 Python 里定义 One2many 字段时，需要明确两个关键参数：
- comodel_name：子记录所在的模型名称。
- inverse_name：子模型上指向父模型的 Many2one 字段名。
下面是一个简化的自定义模块示例，说明如何用 One2many 把“服务合同”与多条“交付项”关联起来：
deliverable_ids = fields.One2many(
comodel_name='service.deliverable',
inverse_name='contract_id',
string='Deliverables'
)在这个例子里，contract_id 是定义在 service.deliverable 子模型上的 Many2one 字段。没有先定义对应的 Many2one，One2many 无法成立。
数据库中实际发生的事情
在 Odoo 的数据库层面，父表不会得到 One2many 的列；所有相关数据保存在子模型的表里，每条子记录有一个外键列指向父记录的 ID。
当加载父记录并渲染其 One2many 字段时，ORM 会自动执行等价于“在子表中查找外键等于当前父 ID 的所有行”的查询。这是关系型数据库的标准行为，由 Odoo 自动管理。
因此 One2many 本质上是对相关记录的一个计算型视图，而不是在父表上额外存储数据的字段。
典型的业务场景
One2many 在业务场景中的常见应用
1. 销售订单与订单明细
销售模块中，sale.order 的 order_line_ids 就是 One2many，关联 sale.order.line。每条明细记录包含商品、数量、单价与折扣等信息，用户可以在销售订单表单里直接维护这些明细。
2. 发票与发票行
会计模块用 One2many 在发票（account.move）与发票行（account.move.line）之间建立关系，父发票会汇总各行的金额用于展示和过账。
3. 项目与任务
项目模块在 project.project 上显示所有属于该项目的任务，这个 One2many 可在表单里以列表、看板或甘特图形式呈现，背后都是同一层关系。
4. 公司与联系人子条目
res.partner 的 child_ids 字段列出与公司相关联的多个联系人，每个联系人在子模型上通过 parent_id 回指公司。
5. 定制业务模型（服务、制造等）
在定制模块时，只要存在“一条记录拥有多条子记录”的场景，One2many 就是自然的选择：例如一笔维修申请关联多项备件消耗、一门课程关联多期次、一份服务合同包含若干交付物等。
正是这种建模的灵活性，使得 One2many 在 Odoo 定制与行业解决方案中占据核心地位。
如何创建或定制 One2many 字段
添加 One2many 的两条主要路径：无代码的 Odoo Studio 或者在自定义模块中写 Python。
使用 Odoo Studio 时的要点
在 Studio 里，你不能直接在父模型的字段选择器中创建 One2many，因为它依赖于子模型上已经存在的 Many2one。
推荐的操作顺序是：
- 先在 Studio 里打开子模型，新增一个指向父模型的 Many2one 字段。
- 保存该字段后，回到父模型的 Studio 界面。
- 新增字段时选择 One2many，Studio 会提示你选择相关模型与 inverse（反向）字段。
- 添加完成后，One2many 会以内嵌列表的形式出现在表单视图中。
对许多业务人员而言，这是一种无需编程就能建立父子关系的便捷方法；Studio 创建的字段行为与 Python 中定义的字段一致。
在自定义模块中用 Python 创建 One2many
对于开发者，直接在 Python 中定义字段可以完全控制字段属性、名称和过滤条件。下面是一个完整示例：
from odoo import fields, models
class ServiceContract(models.Model):
_name = 'service.contract'
_description = 'Service Contract'
name = fields.Char(string='Contract Name', required=True)
deliverable_ids = fields.One2many(
comodel_name='service.deliverable',
inverse_name='contract_id',
string='Deliverables'
)
class ServiceDeliverable(models.Model):
_name = 'service.deliverable'
_description = 'Service Deliverable'
contract_id = fields.Many2one(
comodel_name='service.contract',
string='Contract',
ondelete='cascade'
)
name = fields.Char(string='Description', required=True)注意：子模型上的 Many2one（此例中的 contract_id）必须先定义好，One2many 的 inverse_name 要与其名称完全一致。
通过 XML-RPC API 创建字段
如果你通过脚本或自动化工具管理 Odoo 数据库字段，也可以使用 XML-RPC 调用 ir.model.fields 来创建字段。流程与手工操作相同：先建 Many2one，再用 relation_field 指定该 Many2one 的名字来创建 One2many。
当需要跨多个环境统一字段定义或自动化定制时，这种程序化创建字段的方法特别有用。
最佳实践要点
结合在多个行业实施 Odoo 的经验，这里列出在使用 One2many 时真正能提升可维护性与稳定性的实践要点。
- 始终先创建子模型的 Many2one。无论用 Studio、Python 还是 API，One2many 都依赖于子模型上的反向字段，先建反向字段可以避免很多错误。
- 字段命名遵循约定，使用 _ids 后缀。像
line_ids、task_ids、deliverable_ids这样的命名习惯能让代码阅读者立刻识别该字段返回的是一个记录集。 - 根据业务需求设置 ondelete='cascade'。如果父记录删除时子记录也应该被删除，务必在子模型的 Many2one 上设置该选项，避免遗留孤立数据。
- 在内嵌列表中只显示必要字段。过多列会影响加载速度和可读性。把次要信息设为可选列（optional），让用户按需展开。
- 通过 domain 过滤子记录。若同一子模型被多个父模型共享，给 One2many 添加 domain 可以只展示与当前父记录相关的子集，提升界面聚焦度。
- 面对海量子记录要谨慎加载。如果某父记录可能关联数千条子记录，不要在表单视图一次性全部渲染。可考虑跳转到独立列表视图、增加分页或设置查询限制。
常见陷阱与错误
总结常见错误以便规避
遗漏 Many2one 反向字段
最常见的问题就是在父模型上创建 One2many 时忘记先在子模型上创建对应的 Many2one。ORM 会报错，因为找不到 inverse 字段。创建前请核实 inverse_name 确实存在于子模型。
写入时使用错误的语法
通过 Python 或 API 修改 One2many 时，必须使用 Odoo 特有的命令元组语法，不能直接把普通的 Python 列表赋值给 One2many。正确的写入命令包括：
(0, 0, values_dict)—— 创建一个新的子记录。(1, child_id, values_dict)—— 更新已存在的子记录。(2, child_id, 0)—— 删除并移除已存在的子记录（从数据库中删除）。(4, child_id, 0)—— 将已有子记录添加到关系中（不创建新记录）。(5, 0, 0)—— 取消所有子记录的关联（不删除子记录，只解除关系）。
像 record.line_ids = [1, 2, 3] 这样的直接赋值在 ORM 中不起作用，会导致意外结果。
混淆 One2many 与 Many2many
如果子记录需要同时属于多个父记录，则应使用 Many2many。错误地用 One2many 会迫使你复制子记录，造成数据冗余与一致性问题。
大列表带来的性能问题
当 One2many 在表单中呈现上百甚至上千条明细时，页面会明显变慢。这在发票行或库存移动明细中常见。可在视图上设置 limit，或引导用户到专门的列表页面处理大量数据。
删除父记录后出现孤儿记录
如果删除父记录时没有在子模型的 Many2one 上指定合适的 ondelete 策略，子记录可能残留为空的外键或错误引用，久而久之会污染数据库并导致报表或视图异常。设计数据模型时要明确删除策略。
总结
One2many 是 Odoo ORM 与数据建模的基石之一。它驱动着平台中许多关键功能——从销售明细到发票行再到项目任务。理解它与子模型上 Many2one 的关联关系，会让你更容易读懂并扩展 Odoo 系统。
无论你是在为企业配置 Odoo、用 Studio 做定制，还是从零开发模块，One2many 都是会频繁使用的工具。掌握何时使用、如何正确定义以及如何避免常见错误，能节省大量时间并降低数据问题风险。
如果你想进一步学习 Odoo 字段与 API 的实务操作，请查看我们关于 Odoo 数据与 API 系列的更多教程文章。
需要 Odoo 实施支持吗？
Dasolo 专注于帮助企业实施、定制与优化 Odoo，使其契合具体业务流程。无论是数据模型设计、定制模块开发、字段创建，还是提升现有系统的使用价值，我们的团队都可以提供支持。
如果你对自己的 Odoo 项目有疑问，或想讨论如何更合理地组织数据结构， 请与我们联系，我们很乐意为你提供帮助。