如何在 Odoo 19 中为自定义模块添加设置菜单

Odoo 是一款高度可适配的开源平台，可作为管理业务流程的综合解决方案。其模块化设计允许开发者构建自定义应用，以应对独特的运营挑战。自定义 Odoo 的一个重要方面是添加配置界面 —— 用户可在此界面个性化设置、微调功能，使其与自身工作流程保持一致。这种灵活性确保企业能在不违背特定需求的前提下优化性能、简化运营。

本指南将详细介绍如何在 Odoo 19 的自定义模块中集成设置菜单，方便用户配置和自定义模块偏好。

整个流程从创建自定义模块开始。该设置的核心是定义配置模型—— 用于存储和管理模块设置的模型。此模型基于 Odoo 内置的 res.config.settings 类构建，提供结构化、高效的配置处理方式。

一、定义配置模型

首先，打开自定义模块的主 Python 文件，添加以下代码片段：

from odoo import fields, models, api

class ResConfigSettings(models.TransientModel):
    _inherit = 'res.config.settings'  # 继承odoo内置的配置模型

    contract_type = fields.Selection([('monthly', '月度'), ('half_yearly', '半年'), ('yearly', '年度')],
                                     string='合同类型',
                                     config_parameter='example_setting.contract_type', # 配置参数(模块名.字段名)
                                     help="从下拉选项中选择合同类型")

代码说明：

该代码可在 res.config.settings 模型中添加一个字段，用于让用户选择员工合同类型。

通过 config_parameter 属性，该字段被纳入 Odoo 的全局配置系统，确保配置数据在整个 Odoo 环境中存储一致、可随时调用。

用户保存设置后，字段值会存储到数据库中，便于跟踪变更。此处 config_parameter 定义为 example_setting.contract_type：example_setting 是自定义模块名，contract_type 是具体设置项。这种方式能简洁高效地存储自定义配置，确保需要时可快速调用。

二、创建配置视图

继承了 ‘res.config.settings’ 模型后，下一步是为自定义模块创建视图—— 定义设置界面在用户端的显示样式。需在模块中添加以下 XML 代码，确保新配置字段能在 Odoo 界面中正确显示，方便用户操作。

以下是创建视图的 XML 代码：

<?xml version="1.0" encoding = "utf-8"?>
<odoo>
  <record id="res_config_settings_view_form" model="ir.ui.view">
            <field name="name">res.config.settings.view.form.inherit.employee.contract</field>
            <field name="model">res.config.settings</field>  <!-- 关联的模型 -->
            <field name="priority" eval="15"/>  <!-- 视图优先级（值越高越优先显示） -->
            <field name="inherit_id" ref="base.res_config_settings_view_form"/>  <!-- 继承的父视图（Odoo 基础配置视图） -->
            <field name="arch" type="xml">
                <!-- 在父视图的 form 标签内插入自定义内容 -->
                <xpath expr="//form" position="inside">
                    <!-- 定义应用分组（用于在设置界面中归类） -->
                    <app data-string="员工管理" string="员工管理" name="employee_contract">
                        <!-- 定义设置区块（带标题） -->
                        <block title="员工管理设置" name="employee_management">
                            <!-- 具体设置项 -->
                            <setting string="合同类型" help="选择合同类型" id="contract_type_setting">
                                <field name="contract_type"/>  <!-- 关联 Python 中定义的 contract_type 字段 -->
                                <!-- 条件显示的提示信息（仅当选择合同类型后显示） -->
                                <div class="content-group" invisible="not contract_type" id="group_contract_type_setting">
                                    <div class="text-warning mt16">
                                        请<strong>保存</strong>此页面，然后返回此处完成功能设置。
                                    </div>
                                </div>
                            </setting>
                        </block>
                    </app>
                </xpath>
           </field>
    </record>
</odoo>

XML 代码说明：

该代码基于 Odoo 默认的配置表单视图（base.res_config_settings_view_form）进行扩展，新增一个名为 “员工管理” 的配置分组。

在 “员工管理” 分组下，添加 “合同类型” 设置项，包含一个下拉字段，供用户选择所需合同类型。

代码中包含条件提示信息：仅当用户选择了合同类型后，才显示 “保存页面并返回完成设置” 的提示，引导用户完成后续操作，避免遗漏关键步骤。

三、配置菜单与窗口动作

为确保新创建的设置视图能在 Odoo 界面中访问，需集成 ir.actions.act_window 模型（定义窗口动作，将视图与菜单关联）。这样用户可从 Odoo 主仪表盘或对应应用中直接进入设置菜单。

以下是如何在模块中包含 ‘ir.actions.act_window’ 模型，它将为新创建的菜单项定义动作行为：

<?xml version="1.0" encoding = "utf-8"?>
<odoo><!-- 定义窗口动作（关联配置视图） -->
        <record id="res_config_settings_actions" model="ir.actions.act_window">
            <field name="name">配置</field>  <!-- 动作名称 -->
            <field name="type">ir.actions.act_window</field>  <!-- 动作类型（窗口动作） -->
            <field name="res_model">res.config.settings</field>  <!-- 关联的模型 -->
            <field name="view_mode">form</field>  <!-- 视图模式（表单视图） -->
            <field name="target">new</field>  <!-- 打开方式（新窗口打开） -->
            <field name="context">{'model': 'employee_contract'}</field>  <!-- 上下文（指定关联模块） -->
        </record>

        <!-- 定义菜单层级结构 -->
        <!-- 1. 根菜单：员工管理 -->
        <menuitem id="employee_management_menu_root" name="员工管理" sequence="1"/>

        <!-- 2. 子菜单：配置（父菜单为“员工管理”） -->
        <!-- parent:父菜单ID（模块名.根菜单ID） -->
        <menuitem id="employee_management_menu_action" name="配置"
                  parent="example_setting.employee_management_menu_root"
                  sequence="6"/>

        <!-- 3. 子菜单：设置（关联窗口动作，父菜单为“配置”） -->
        <!-- parent:父菜单ID（模块名.配置菜单ID） -->
        <!-- action:关联的窗口动作ID -->
        <menuitem id="example_setting_settings_menu_action" name="设置"
                  parent="example_setting.employee_management_menu_action"
                  action="res_config_settings_actions" sequence="7"/>
</odoo>

此 XML 代码中的菜单项定义了 Odoo 应用程序内的一个层次结构，使用户能够轻松浏览设置。菜单代码定义了三级菜单结构，确保用户导航清晰：

• 根菜单：“员工管理”（作为自定义模块的主入口）；
• 二级菜单：“配置”（嵌套在 “员工管理” 下，用于归类配置相关功能）；
• 三级菜单：“设置”（关联 res_config_settings_action 窗口动作，点击后打开合同类型配置表单）。

执行代码后，用户界面会显示 “合同类型” 下拉选择框，包含预设的 “月度”“半年”“年度” 选项，可直接在 Odoo 系统中配置员工合同设置。

四、总结

在 Odoo 模块中配置上述代码的过程简单高效，只需定义必要的 XML 和 Python 代码，即可实现流畅的用户体验。遵循上述步骤，可增强 Odoo 自定义模块的功能 —— 通过专用设置菜单，让用户轻松配置模块特定选项。这种自定义不仅为用户提供了根据自身需求调整设置的灵活性，还能打造更直观、易用的界面。

在 Odoo 模块中集成设置菜单，不仅简化了配置流程，还能让用户个性化使用体验，使模块更适配其业务需求。借助 Odoo 灵活的架构，可扩展模块功能，打造更高效、更贴合特定运营目标的定制化解决方案。这种方式能提升整体用户体验，让 Odoo 成为企业更有价值的工具。