Skip to Content

详解 Odoo 19 齿轮菜单（CogMenu）：新增自定义菜单项的完整步骤

详解 Odoo 19 齿轮菜单（CogMenu）：新增自定义菜单项的完整步骤

在 Odoo 中，齿轮菜单（CogMenu） 扮演着关键角色，它提供了对各类模型（Model）和功能相关的配置选项与设置的访问入口。该菜单以齿轮（或 cogwheel）图标为标识，通常位于用户界面的左上角。

本文将演示如何在 Odoo 19 中为齿轮菜单添加新选项 —— 通过在static/src目录下创建 XML 文件和 JavaScript（JS）文件，即可实现自定义菜单项的添加。

步骤 1：在 static/src 目录下创建 JS 文件

该 JS 文件用于定义齿轮菜单新项的组件（Component）及其功能逻辑，文件命名建议为cog_menu.js，代码如下：

/** @odoo-module **/
// 导入翻译函数_t（用于多语言文本支持）
import { _t } from "@web/core/l10n/translation";
// 导入下拉菜单项组件（齿轮菜单基于下拉组件实现）
import { DropdownItem } from "@web/core/dropdown/dropdown_item";
// 导入Odoo注册表（用于注册自定义齿轮菜单项）
import { registry } from "@web/core/registry";
// 导入Owl组件基类（Odoo前端框架核心组件类）
import { Component } from "@odoo/owl";

// 获取齿轮菜单的注册表（从全局注册表中分类获取"cogMenu"）
const cogMenuRegistry = registry.category("cogMenu");

// 定义自定义齿轮菜单组件类
export class NewCogMenu extends Component {
    // 绑定组件对应的XML模板（需与后续创建的XML模板名称一致）
    static template = "cog_menu.NewCogMenu";
    // 声明组件依赖的子组件（此处依赖DropdownItem实现菜单项样式）
    static components = { DropdownItem };
    // 声明组件接收的属性（此处无额外属性，留空）
    static props = {};

    // 定义菜单项点击事件的处理方法（需在此处实现自定义功能）
    async onClickCogMenu() {
        // 在这里添加菜单项点击后的操作...
        console.log("New Cog Menu Item Clicked!");
        // 例如，您可以在此处调用模型方法、触发动作等。
    }
}

// 定义自定义齿轮菜单项的配置对象
export const NewCogMenuItem = {
    // 关联的组件（即上面定义的NewCogMenu）
    Component: NewCogMenu,
    // 分组序号（用于菜单项排序，数值越小，在菜单中位置越靠上）
    groupNumber: 20,
    // 控制菜单项显示/隐藏的条件函数（接收config配置参数）
    isDisplayed: ({ config }) => {
        // 从config中解构出动作类型、动作ID、视图类型
        const { actionType, actionId, viewType } = config;
        // 显示条件：
        // 1. actionType: 动作类型为"ir.actions.act_window"（Odoo中标准的"窗口动作"，用于打开列表/看板等视图）
        // 2. actionId: 存在有效的动作ID（actionId非空、非undefined）
        // 3. viewType: 视图类型不是"form"（即不在表单视图中显示，仅在列表、看板等视图中显示）
        return actionType === "ir.actions.act_window" && actionId && viewType !== "form";
    }
}

// 将自定义菜单项注册到齿轮菜单注册表中
// "new-cog-menu"为注册标识（需唯一），sequence为同组内的排序（数值越小越靠前）
cogMenuRegistry.add("new-cog-menu", NewCogMenuItem, { sequence: 10 });

步骤 2：在 static/src 目录下创建 XML 文件

该 XML 文件用于定义自定义菜单项的结构（如显示文本、样式），文件命名建议为cog_menu.xml，代码如下：

<?xml version="1.0" encoding="utf-8" ?>
<!-- 定义Odoo模板，xml:space="preserve"用于保留空格格式 -->
<templates xml:space="preserve">
    <!-- 模板名称需与JS组件中static.template的值一致（cog_menu.NewCogMenu） -->
    <t t-name="cog_menu.NewCogMenu">
        <!-- 引用DropdownItem组件，设置自定义类名和点击事件绑定 -->
        <DropdownItem  class="'o_new_cog_menu'" onSelected.bind="onClickCogMenu">
            <!-- 菜单项显示的文本（可改为自定义内容，如"导出数据报表"） -->
            Test Cog Menu!
        </DropdownItem >
    </t>
</templates>

步骤 3：在__manifest__.py 配置清单文件中注册资源

需将上述创建的 JS 和 XML 文件添加到模块的资源配置中，确保 Odoo 后端能加载这些文件。在模块根目录的__manifest__.py文件中，找到assets（资源）配置项，添加如下内容：

    'assets': {
        # 后端资源（web.assets_backend对应Odoo后端界面的资源集合）
        'web.assets_backend': [
            # 加载自定义齿轮菜单的JS文件
            'cog_menu/static/src/cog_menu.js',
            # 加载自定义齿轮菜单的XML模板文件
            'cog_menu/static/src/cog_menu.xml',
        ],
},

效果与显示规则说明

完成上述三步后，所有模型的齿轮菜单中都会新增一个名为 “Test Cog Menu！” 的选项（可在 XML 中修改显示文本）。

1. 点击事件与自定义功能

当点击该新菜单项时，会触发 JS 文件中定义的onClickCogMenu方法。开发者需在该方法内编写自定义逻辑（如打开报表、执行批量操作、触发数据同步等），实现业务所需功能。

2. 显示条件控制（isDisplayed 函数）

通过NewCogMenuItem对象中的isDisplayed函数，可精准控制菜单项在哪些场景下显示：

  • 显示场景：仅当 “动作类型为窗口动作（ir.actions.act_window）、存在有效动作 ID、视图类型非表单视图（form）” 时，菜单项才显示（即仅在列表视图、看板视图等非表单视图中可见）。
  • 隐藏场景：若不满足上述任一条件（如在表单视图中、动作类型无效），菜单项会自动隐藏。

3. 菜单项排序（groupNumber 与 sequence）

  • groupNumber（分组序号）：用于将菜单项分组，同分组的菜单项会聚集显示，数值越小的分组在菜单中越靠上（示例中设为 20，可根据需求调整）。
  • sequence（同组排序）：在同一分组内，sequence数值越小，菜单项位置越靠前（示例中设为 10，确保在同组内优先显示）。

总结

通过以上步骤，即可在 Odoo 19 中成功为齿轮菜单添加自定义新项。该功能支持根据不同模型、不同视图动态定制菜单，有效提升用户操作体验。开发者可进一步扩展：在onClickCogMenu方法中定义复杂业务逻辑，或调整isDisplayed条件适配更多场景（如仅在特定模型（如销售订单、采购订单）中显示）。

详解 Odoo 19 齿轮菜单（CogMenu）：新增自定义菜单项的完整步骤
中国 Odoo, 苏州远鼎 January 12, 2026
Tags
Our blogs
Archive