Skip to Content

Odoo 钩子（Hooks）实操指南：三大类型配置与使用方法

Odoo 钩子（Hooks）实操指南：三大类型配置与使用方法

在 Odoo 中，钩子（Hooks）是一种强大的机制，可在模块生命周期的特定阶段执行自定义操作。这些函数注册在 Odoo 模块的 __init__.py 和 __manifest__.py 文件中，允许开发者在模块安装前、安装过程中或卸载后修改或扩展功能。本文将详细介绍 Odoo 19 中三种主要的钩子类型：安装后钩子（Post-Init Hooks）、安装前钩子（Pre-Init Hooks）和卸载钩子（Uninstall Hooks），并附带实操示例说明其用法。

1. 安装后钩子（Post-Init Hooks）

安装后钩子在模块安装完成后立即执行，特别适用于初始化数据、配置系统设置，或运行依赖模块成功安装的数据库操作（例如创建初始记录、更新默认配置等）。

定义安装后钩子的步骤

  • 在 __manifest__.py 文件中，通过 post_init_hook 键声明钩子函数名；
  • 在模块的 __init__.py 文件中，实现该钩子函数。

示例：使用安装后钩子创建员工记录

1、__manifest__.py 中声明钩子

{
    # 其他模块配置...
    'post_init_hook': 'create_employees',  
    # 钩子函数名为 'create_employees'
}

2、__init__.py 中实现钩子函数

def create_employees(env):
    """安装后创建初始员工记录"""
    # env：Odoo 核心环境对象，用于操作模型数据
    env['company.employee'].create({
        'name': "John Doe",
        'phone': '+1234567890',
        'email': 'johndoe@example.com'
    })

安装后钩子的关键特性

  • 函数接收 Odoo 环境对象（env）作为参数，通过 env 可操作任意模型（如创建、查询记录）；
  • 仅在模块安装成功后执行，适合在数据库模式（表结构）更新完成后初始化数据；
  • 若模块升级（Upgrade），安装后钩子不会重复执行（仅首次安装时触发）。

2. 安装前钩子（Pre-Init Hooks）

安装前钩子在模块开始安装前执行，通常用于准备数据库环境或进行结构性修改（例如为现有模型添加字段、调整表结构，确保模块安装时数据库满足依赖条件）。

定义安装前钩子的步骤

  • 在 __manifest__.py 文件中，通过 pre_init_hook 键声明钩子函数名；
  • 在模块的 __init__.py 文件中，实现该钩子函数。

示例：使用安装前钩子修改员工表结构

1、__manifest__.py 中声明钩子

{
    # 其他模块配置...
    'pre_init_hook': '_prepare_employee_table', 
    # 钩子函数名为 "_prepare_employee_table"
}

2、__init__.py 中实现钩子函数

def _prepare_employee_table(env):
    """安装前为员工表添加字段，准备数据库环境"""
    # 通过 env.cr 执行原生 SQL 语句（cr 为数据库游标对象）
    env.cr.execute("""
        ALTER TABLE company_employee
        ADD COLUMN department VARCHAR,  # 添加“部门”字段（字符串类型）
        ADD COLUMN hire_date DATE;      # 添加“入职日期”字段（日期类型）
    """)

安装前钩子的关键特性

  • 核心用途是修改数据库模式（如增删字段、调整表关系），为模块安装铺路；
  • 执行时模块尚未完成安装，因此无法直接操作 Odoo 模型（如 env['model.name'].create()），需通过原生 SQL（env.cr.execute()）操作数据库；
  • 若模块安装失败，安装前钩子已执行的数据库修改不会自动回滚，需手动处理。

注意：company.employee 是当前模块自定义的模型，Odoo 会在 “安装前钩子执行后、模块核心安装阶段”才根据模型定义创建 company_employee 表，安装前钩子执行时表还未生成，安装模块时报错：company_employee 关系不存在

3. 卸载钩子（Uninstall Hooks）

卸载钩子在模块卸载完成后执行，主要用于清理模块相关数据（如删除依赖该模块的记录、恢复系统配置），确保模块卸载后系统状态保持一致，避免残留数据影响其他功能。

定义卸载钩子的步骤

  • 在 __manifest__.py 文件中，通过 uninstall_hook 键声明钩子函数名；
  • 在模块的 hooks.py 文件（或自定义命名的文件，需确保被 __init__.py 导入）中，实现该钩子函数。

示例：使用卸载钩子清理支付方式记录

1、__manifest__.py 中声明钩子

{
    # 其他模块配置...
    'uninstall_hook': 'clean_up_payment_methods', 
    # 钩子函数名为 "clean_up_payment_methods"
}

2、hooks.py 中实现钩子函数（需在 __init__.py 中导入，如：from . import hooks）

def clean_up_payment_methods(env):
    """卸载后清理与当前模块关联的收款方式"""
    # 步骤1：查询已安装的支付提供商（排除已卸载的模块关联的提供商）
    installed_providers = env['payment.provider'].search([
        ('module_id.state', '=', 'installed')  # module_id：支付提供商关联的模块
    ])
    # 步骤2：删除与已安装提供商关联的“收款”类型支付方式
    env['account.payment.method'].search([
        ('code', 'in', installed_providers.mapped('code')),  # 匹配支付提供商的编码
        ('payment_type', '=', 'inbound'),  # 仅删除“收款”类型（inbound）的支付方式
    ]).unlink()  # unlink()：Odoo 模型方法，用于删除记录

卸载钩子的关键特性

  • 执行时机是模块卸载后，因此仅能操作未被卸载的模型（若模型属于当前卸载模块，则无法访问）；
  • 核心作用是维护数据库完整性，避免残留数据（如无效的支付方式、冗余配置）；
  • 函数同样接收 env 作为参数，可通过 Odoo 模型方法（search()、unlink()）灵活清理数据。

总结

Odoo 钩子为开发者提供了在模块生命周期各阶段自定义行为的灵活性：

  • 安装后钩子：安装后初始化数据（如创建初始记录）；
  • 安装前钩子：安装前准备数据库（如修改表结构）；
  • 卸载钩子：卸载后清理数据（如删除关联记录）。

在 Odoo 19 中，这些钩子机制保持了稳定性与易用性，是优化模块功能、简化业务流程的核心工具。合理使用钩子可大幅提升模块的健壮性，减少人工干预成本。

Odoo 钩子（Hooks）实操指南：三大类型配置与使用方法
中国 Odoo, 苏州远鼎 January 12, 2026
Tags
Our blogs
Archive