odoo-qweb-templates

Odoo QWeb 模板

概览

QWeb 是 Odoo 的主要模板引擎，用于 PDF 报告、网站页面和邮件模板。此技能可生成正确、结构良好的 QWeb XML，并包含适当的指令、翻译支持和报告操作绑定。

何时使用此技能

• 创建自定义 PDF 报告（发票、送货单、证书）。
• 构建由工作流操作触发的 QWeb 邮件模板。
• 设计包含动态内容的 Odoo 网站页面。
• 调试 QWeb 渲染错误（t-if、t-foreach 问题）。

工作原理

1. 激活：提及 @odoo-qweb-templates，并描述所需的报告或模板。
2. 生成：获取完整的 ir.actions.report 记录和 QWeb 模板。
3. 调试：粘贴有问题的模板，以定位并修复渲染问题。

示例

示例 1：自定义 PDF 报告

<record id="action_report_patient_card" model="ir.actions.report">
    <field name="name">Patient Card</field>
    <field name="model">hospital.patient</field>
    <field name="report_type">qweb-pdf</field>
    <field name="report_name">hospital_management.report_patient_card</field>
    <field name="binding_model_id" ref="model_hospital_patient"/>
</record>


<template id="report_patient_card">
    <t t-call="web.html_container">
        <t t-foreach="docs" t-as="doc">
            <t t-call="web.external_layout">
                <div class="page">
                    <h2>Patient Card</h2>
                    <table class="table table-bordered">
                        <tr>
                            <td><strong>Name:</strong></td>
                            <td><t t-field="doc.name"/></td>
                        </tr>
                        <tr>
                            <td><strong>Doctor:</strong></td>
                            <td><t t-field="doc.doctor_id.name"/></td>
                        </tr>
                        <tr>
                            <td><strong>Status:</strong></td>
                            <td><t t-field="doc.state"/></td>
                        </tr>
                    </table>
                </div>
            </t>
        </t>
    </t>
</template>

示例 2：条件渲染

<t t-if="doc.state == 'draft'">
    <div class="alert alert-warning">
        <strong>Warning:</strong> This patient has not been confirmed yet.
    </div>
</t>

最佳实践

• ✅ 应做： 对模型字段使用 t-field——Odoo 会自动正确格式化日期、金额和布尔值。
• ✅ 应做： 对普通字符串使用 t-out 进行转义输出；在 Odoo 17 中，t-esc 仍是其别名。对于已标记为安全的值，需单独进行信任审查。
• ✅ 应做： 在 PDF 报告中调用 web.external_layout，以自动包含公司页眉、页脚和徽标。
• ✅ 应做： 在 Python 报告辅助函数中对可翻译的字符串字面量使用 _lt()（延迟翻译），而不是内联使用 t-esc。
• ❌ 不要： 在 QWeb 中放入复杂业务逻辑或副作用——它支持简单表达式；复杂值应在模型或报告的 _get_report_values() 辅助函数中计算。
• ❌ 不要： 使用 t-foreach 时忘记添加 t-as；没有它，就无法在循环体中访问当前记录。
• ❌ 不要： 绕过转义来渲染不受信任的 HTML。使用目标 Odoo 版本支持的机制清理富文本内容；将内容标记为安全是一种安全断言。

参考：Odoo 17 QWeb。此示例需要自定义模型、字段、访问规则和模块 XML 封装；请使用获授权的用户测试渲染，并避免暴露患者数据。

限制

• 不涵盖动态 QWeb 页面的网站控制器路由——这需要 Python http.route 方面的知识。
• 邮件模板 QWeb 的变量作用域与报告 QWeb 不同（object 与 docs）——此技能主要关注 PDF 报告。
• QWeb JavaScript（用于 Kanban/Form 小部件）属于不同的引擎；此技能仅涵盖服务端 QWeb。
• 不涵盖 PDF 渲染问题的 wkhtmltopdf 配置（页面大小、页边距、页眉/页脚重叠）。