Odoo： Owl Props 深度解析技术指南

1. Props 核心概念

1.1 什么是 Props (Properties)？

在 Owl 组件模型中，props (Properties 的缩写) 是一个普通的 JavaScript 对象，它是实现组件间通信，特别是父组件向子组件传递数据的主要机制。

想象一下，一个父组件（比如一个产品列表页面 ProductList）需要渲染多个子组件（比如单个产品卡片 ProductCard）。每个 ProductCard 组件都需要展示不同的产品信息（如名称、价格、图片等）。父组件 ProductList 就是通过 props 将这些独有的信息"传递"给每一个 ProductCard 实例的。

1.2 props 的核心作用：单向数据流 (One-Way Data Flow)

props 的核心设计理念是单向数据流。这意味着：

• 数据流向是固定的：数据总是从父组件流向子组件，永远不会反向。
• 可预测性：这种单向流动使得应用的数据状态变得非常容易追踪和理解。当出现问题时，你可以沿着数据流向快速定位到是哪个组件传递了错误的数据。
• 数据源唯一 ：组件的数据来源只有两个：它自己的状态 (state) 和从父组件接收的 props。这大大降低了应用逻辑的复杂性。

1.3 props 是只读的 (Read-Only) ❗

这是使用 props 时必须遵守的黄金法则：子组件永远不应该尝试直接修改它接收到的 props。

// 错误示范：在子组件内部修改 prop
class MyChildComponent extends Component {
    static template = xml`<div>...</div>`;
    someMethod() {
        // 🚨 绝对禁止！这将导致不可预测的行为并可能破坏应用状态。
        this.props.name = "A New Name";
    }
}

为什么不能修改 props？

1. 破坏数据源：如果子组件可以随意修改来自父组件的数据，那么父组件和其他同样使用该数据的兄弟组件的状态就会变得混乱且不可控。这违背了"单向数据流"的原则。
2. 难以调试：当应用状态出现问题时，你将无法确定是哪个组件在何时何地修改了数据，调试过程会变成一场噩梦。
3. 组件复用性降低 ：一个设计良好的组件应该是"无副作用"的，它只根据接收的 props 来渲染自己。如果它会修改 props，那么它的行为就变得不纯粹，难以在不同场景下复用。

如果子组件需要改变某些数据，正确的做法是：通过调用一个从 props 接收的函数（回调函数），通知父组件去更新它自己的状态。 父组件状态更新后，新的 props 会自动向下传递，从而触发子组件的重新渲染。我们将在后面详细探讨这个模式。

---

2. props 的定义与接收

在 Owl 中，props 的传递和接收分为两步：父组件在模板中"传递"，子组件在 JavaScript 类中"声明并接收"。

2.1 子组件 (Child): 声明 props

子组件必须通过一个静态属性 props 来明确声明它期望接收哪些数据。这不仅是最佳实践，也是 Owl 框架的要求。

my_module/static/src/components/child_component/child_component.js

/** @odoo-module */

import { Component } from "@odoo/owl";

export class ChildComponent extends Component {
    static template = "my_module.ChildComponent";

    // 使用静态属性 `props` 声明期望接收的属性
    static props = {
        // 最简单的声明方式，只关心属性名
        title: true,
        recordId: true,
    };

    setup() {
        // 在 setup 或组件的其他方法、getter 中，通过 this.props 访问
        console.log("接收到的标题:", this.props.title);
        console.log("接收到的记录ID:", this.props.recordId);
    }
}

2.2 父组件 (Parent): 传递 props

父组件在其 XML 模板中调用子组件时，通过标签属性的方式将数据传递下去。

my_module/static/src/components/parent_component/parent_component.xml

<t t-name="my_module.ParentComponent" owl="1">
    <div>
        <h1>父组件标题</h1>

        <ChildComponent title="'这是一个静态标题'" recordId="123"/>

        <ChildComponent t-props="getDynamicProps()"/>

        <ChildComponent title="state.dynamicTitle" recordId="state.currentId"/>
    </div>
</t>

my_module/static/src/components/parent_component/parent_component.js

/** @odoo-module */

import { Component, useState } from "@odoo/owl";
import { ChildComponent } from "../child_component/child_component";

export class ParentComponent extends Component {
    static template = "my_module.ParentComponent";
    static components = { ChildComponent }; // 注册子组件

    setup() {
        this.state = useState({
            dynamicTitle: "这是一个动态标题",
            currentId: 456,
        });
    }

    // 使用 t-props 传递一个动态对象
    getDynamicProps() {
        return {
            title: this.state.dynamicTitle,
            recordId: this.state.currentId,
        };
    }
}

2.3 子组件: 在模板中使用 props

在子组件的 XML 模板中，可以直接访问 props 对象。

my_module/static/src/components/child_component/child_component.xml

<t t-name="my_module.ChildComponent" owl="1">
    <div class="child-card">
        <h2>子组件标题: <t t-esc="props.title"/></h2>
        <p>记录 ID: <t t-esc="props.recordId"/></p>
    </div>
</t>

---

3. Props 校验与配置 (Props Validation)

为了创建更健壮、更易于维护的组件，Owl 强烈建议对 props 进行详细的定义和校验。这能帮助你和你的团队在开发阶段就捕捉到潜在的错误。

props 的声明不仅仅是 propName: true，它可以是一个包含详细规则的对象。

3.1 类型校验 (Type Validation)

使用 type 关键字指定期望的数据类型。如果父组件传递的类型不匹配，Owl 会在控制台打印警告信息。

|------------|---------------|
| 类型 | 描述 |
| String | 字符串 |
| Number | 数字 |
| Boolean | 布尔值 |
| Object | JavaScript 对象 |
| Array | JavaScript 数组 |
| Function | JavaScript 函数 |

3.2 可选 Props (Optional Props)

默认情况下，所有声明的 props 都是必需的。如果父组件没有提供，Owl 会发出警告。你可以使用 optional: true 将其标记为可选。

3.3 默认值 (Default Values)

当一个 prop 是可选的 (optional: true) 且父组件没有提供它时，你可以使用 default 关键字为其提供一个默认值。

3.4 综合示例

让我们来创建一个包含各种校验规则的复杂 props 定义。

my_module/static/src/components/advanced_card/advanced_card.js

/** @odoo-module */

import { Component } from "@odoo/owl";

export class AdvancedCard extends Component {
    static template = "my_module.AdvancedCard";

    static props = {
        // 必填的字符串
        title: { type: String },

        // 必填的数字
        priority: { type: Number },

        // 可选的布尔值，带有默认值
        isActive: { type: Boolean, optional: true, default: true },

        // 必填的对象
        config: { type: Object },

        // 可选的数组
        tags: { type: Array, optional: true },

        // 必填的函数（用于回调）
        onSelect: { type: Function },

        // 自定义校验函数 (高级)
        // `validate` 函数接收 prop 的值，如果校验通过返回 true，否则返回 false
        userId: {
            type: Number,
            optional: true,
            validate: (id) => id > 0, // 校验 userId 必须是正数
        },

        // 允许多种类型
        value: { type: [String, Number], optional: true },
    };

    // ...
}

---

4. 传递不同类型的数据

4.1 传递静态值与动态值

回顾之前的例子，静态值直接写在 XML 属性中（字符串加引号），动态值则不加引号，直接引用 JS 表达式。

<MyComponent title="'你好世界'" count="10" is-enabled="true"/>

<MyComponent title="state.productName" count="state.quantity" is-enabled="state.isVisible"/>

4.2 传递对象和数组

传递复杂数据结构非常直接，只需将其绑定到父组件的状态即可。

父组件 JS:

// ...
this.state = useState({
    product: { id: 1, name: "书桌", price: 300 },
    tags: ["家具", "办公", "木质"],
});
// ...

父组件 XML:

<ProductDetailCard product="state.product" tags="state.tags"/>

子组件 JS:

// ...
static props = {
    product: { type: Object },
    tags: { type: Array },
};
// ...

4.3 传递函数 (回调)：实现子向父通信 🚀

这是 props 最强大的用途之一。通过传递函数，子组件可以在不直接修改 props 的情况下，请求父组件执行操作或更新状态。

场景 : 一个子组件 ConfirmButton 有一个按钮，点击后需要通知父组件 FormView 执行保存操作。

父组件: FormView

// FormView.js
export class FormView extends Component {
    static template = "my_module.FormView";
    static components = { ConfirmButton };

    setup() {
        this.state = useState({ isSaving: false });
    }

    // 1. 定义一个将要传递给子组件的方法
    async saveForm() {
        this.state.isSaving = true;
        console.log("父组件收到了保存请求，正在保存...");
        // 模拟异步保存
        await new Promise(resolve => setTimeout(resolve, 1000));
        this.state.isSaving = false;
        console.log("保存完成！");
    }
}

<t t-name="my_module.FormView" owl="1">
    <div>
        <p>
            <t t-if="state.isSaving">正在保存...</t>
            <t t-else="">请点击下方按钮保存</t>
        </p>

        <ConfirmButton onConfirm="saveForm" />
    </div>
</t>

子组件: ConfirmButton

// ConfirmButton.js
export class ConfirmButton extends Component {
    static template = "my_module.ConfirmButton";

    // 3. 声明接收一个函数类型的 prop
    static props = {
        onConfirm: { type: Function },
    };

    onClick() {
        // 4. 在事件处理函数中，调用从 props 接收的函数
        this.props.onConfirm();
    }
}

<t t-name="my_module.ConfirmButton" owl="1">
    <button class="btn btn-primary" t-on-click="onClick">
        确认保存
    </button>
</t>

通过这个模式，ConfirmButton 保持了其通用性（它只知道要调用一个叫 onConfirm 的函数），而具体的保存逻辑则由父组件 FormView 完全控制。

---

# 5. 高级技巧与最佳实践

5.1 响应 Props 变化: onWillUpdateProps 生命周期

有时，子组件需要在其接收的 props 发生变化时执行特定逻辑（例如，重新获取数据）。onWillUpdateProps 这个生命周期钩子就是为此设计的。

它在组件接收到新的 props，并且即将重新渲染之前被调用。

用例 : 一个 UserProfile 组件根据传入的 userId prop 来获取用户数据。当父组件切换用户时，userId prop 会改变，UserProfile 需要重新获取新用户的数据。

// UserProfile.js
export class UserProfile extends Component {
    static template = "my_module.UserProfile";
    static props = {
        userId: { type: Number },
    };

    setup() {
        this.state = useState({
            user: null,
            isLoading: true,
        });

        // onWillStart 在组件首次挂载时执行
        onWillStart(async () => {
            await this.fetchUserData();
        });

        // onWillUpdateProps 在 props 更新时执行
        onWillUpdateProps(async (nextProps) => {
            // 检查关心的 prop 是否真的发生了变化
            if (this.props.userId !== nextProps.userId) {
                this.state.isLoading = true;
                // 使用 nextProps 中的新值来获取数据
                await this.fetchUserData(nextProps.userId);
            }
        });
    }

    async fetchUserData(id) {
        // 如果没有传入 id，则使用当前 props 的 id
        const userId = id || this.props.userId;
        const data = await this.env.orm.call("res.users", "read", [userId], { fields: ["name", "email"] });
        this.state.user = data[0];
        this.state.isLoading = false;
    }
}

5.2 性能考量

• 避免在 render 中创建新对象/函数 : 如果你在父组件的 render 方法（或 XML 模板的表达式中）每次都创建一个新的对象或函数并作为 prop 传递，这可能会导致子组件不必要地重新渲染，即使数据内容没有改变。

<MyComponent config="{ x: 1, y: 2 }" />

<MyComponent config="state.myConfig" />

• 传递大数据 : 尽量避免通过 props 传递非常庞大的数据集。如果需要，可以考虑只传递 ID，然后让子组件自己根据 ID 去获取所需数据，或者使用服务 (Service) 来管理共享的大状态。

5.3 解构 Props (Destructuring)

为了让代码更简洁，可以在 setup 中使用 ES6 解构赋值来获取 props。

// UserProfile.js
export class UserProfile extends Component {
    // ...
    setup() {
        // 不使用解构
        console.log(this.props.userId);
        console.log(this.props.title);

        // 使用解构，代码更清爽
        const { userId, title } = this.props;
        console.log(userId);
        console.log(title);
    }
    // ...
}

注意 : 解构后的变量 (userId, title) 不会自动响应 props 的更新。它们只是在 setup 执行时刻的一个快照。在模板或 getter 中，你仍然应该使用 this.props.userId 来确保获取到最新的值。

5.4 常见错误与解决方案

• 错误1: 直接修改 props
  • 问题 : this.props.title = "New Title";
  • 解决方案: 永远不要这样做。通过回调函数通知父组件更新其状态。
• 错误2: 忘记在子组件中声明 props
  • 问题 : 父组件传递了 title，但子组件的 static props 中没有定义 title。
  • 后果 : Owl 会在控制台显示警告，并且 this.props.title 在子组件中会是 undefined。
  • 解决方案 : 始终在子组件中明确声明所有期望接收的 props。
• 错误3: 传递字符串时忘记加引号
  • 问题 : <MyComponent title="my_static_title" />
  • 后果 : Owl 会尝试在父组件的环境中寻找一个名为 my_static_title 的变量，如果找不到，会传递 undefined。
  • 解决方案 : 静态字符串必须用单引号或双引号包裹：<MyComponent title="'my_static_title'" />。

---

# 6. 总结: Props 定义速查表

下表总结了在 static props 中定义一个 prop 时的所有可用配置选项：

|-------------|--------------------------|--------------------------------------------------------------------------------------------------|------------------------------------------------|
| 键 (Key) | 类型 | 描述 | 示例 |
| type | (Constructor|String)[] | 指定 prop 的期望类型。可以是 String, Number, Boolean, Object, Array, Function。也支持数组形式定义多种可接受类型。 | type: String <br> type: [String, Number] |
| optional | Boolean | 如果为 true，则该 prop 变为可选。默认为 false（即必填）。 | optional: true |
| default | any | 为可选的 prop 提供一个默认值。只有当 optional 为 true 时才生效。 | default: "N/A" <br> default: [] |
| validate | (val) => Boolean | 一个函数，用于对 prop 的值进行自定义校验。返回 true 表示通过，false 表示失败。 | validate: id => id > 0 |

---

通过深入理解和熟练运用这份指南中的知识点，你将能够构建出结构清晰、数据流明确、易于维护和扩展的 Odoo 18 Owl 应用。祝你编码愉快！