第22讲、Odoo18 QWeb 模板引擎详解
Odoo QWeb 模板引擎详解与实战
Odoo 的 QWeb 是其自研的模板引擎，广泛应用于 HTML、XML、PDF 等内容的生成，支撑了前端页面渲染、报表输出、门户页面、邮件模板等多种场景。本文将系统介绍 QWeb 的核心用法、工作原理，并通过实战案例演示如何在门户页面实现表单提交与数据存储。
一、QWeb 简介
QWeb 是 Odoo 原生的 XML/HTML 模板引擎，采用 XML 语法，通过丰富的 t- 前缀指令（如 t-foreach、t-if、t-call 等）实现模板逻辑控制。与 Jinja2 相比，QWeb 更加结构化、安全，适合可视化编辑器和网页构建器场景。
QWeb 支持两大类渲染方式：
- 前端渲染：用于 Web 页面（如门户、报表、邮件预览等）
- 后端渲染：用于生成 PDF 报表、邮件内容等（通过 Python 代码调用）
二、QWeb 核心指令（t-指令）
| 指令 | 用法 | 示例 |
|---|---|---|
t-foreach | 遍历 | <t t-foreach="docs" t-as="doc">...</t> |
t-if / t-elif / t-else | 条件判断 | <t t-if="doc.state == 'done'">完成</t> |
t-set | 设置变量 | <t t-set="total" t-value="sum(docs.mapped('amount'))"/> |
t-call | 引用模板 | <t t-call="module_name.template_name"/> |
t-field | 渲染字段 | <span t-field="doc.partner_id"/> |
t-esc | 转义输出 | <span t-esc="doc.name"/> |
t-raw | 原样输出（不转义） | <div t-raw="doc.html_description"/> |
三、QWeb 应用场景
1. Web 前端视图（门户、自定义页面等）
QWeb 模板常用于 ir.ui.view（type=‘qweb’）视图，广泛应用于门户表单、公共页面等。例如：
<template id="my_portal_form" name="My Portal Form"><form action="/my/form/submit" method="post"><input type="text" name="name"/><t t-if="user_id"><input type="hidden" name="user_id" t-att-value="user_id"/></t></form>
</template>
通过控制器渲染模板：
return request.render('my_module.my_portal_form', {'user_id': user.id})
2. 报表生成（PDF 报表）
Odoo 利用 QWeb 生成 PDF 报表（如发票、订单等），通过 report_qweb 模块实现。
模板定义：
<template id="report_order_document"><t t-call="web.external_layout"><t t-set="doc" t-value="docs[0]"/><div class="page"><h2>订单号：<span t-field="doc.name"/></h2></div></t>
</template>
渲染调用：
return self.env.ref('sale.report_saleorder').report_action(self)
3. 控制器网页（如公开网站或门户）
结合 Web Controller 使用：
@http.route('/public/page', type='http', auth='public', website=True)
def public_page(self, **kwargs):return request.render('my_module.public_template', {'data': some_data})
四、QWeb 工作原理
1. 模板加载
QWeb 模板存储于 ir.ui.view 表（type=‘qweb’），Odoo 启动时会将其缓存至内存，供后续渲染调用。
2. 渲染引擎
QWeb 的核心为 QWebEngine（Python 实现）：
- 解析模板为 DOM 树结构
- 根据上下文渲染 t-指令
- 输出最终 HTML 字符串
常见调用方式：
- Web 控制器：
request.render(template_name, context) - 后端报表：
self.env.ref('module.report_template_id').render(context)
3. 继承机制（t-inherit）
QWeb 支持模板继承，类似 XML 视图继承：
<template id="my_template_inherit" inherit_id="base.template_to_inherit"><xpath expr="//div[@id='target']" position="replace"><div>新的内容</div></xpath>
</template>
五、开发与调试建议
- 开启开发者模式，便于查看 QWeb 模板结构
- 使用
<t t-debug="1">触发前端调试工具 - 报表调试可用
--log-level=debug输出渲染上下文 t-field可自动格式化输出复杂字段（如货币、日期）
六、实战案例：门户表单 + 控制器
1. 业务场景
实现门户页面 /project/apply，展示项目申请表，用户提交后由控制器处理并保存至数据库。
2. 数据模型
# models/project_application.py
from odoo import models, fieldsclass ProjectApplication(models.Model):_name = 'project.application'_description = 'Project Application'name = fields.Char(string='Applicant Name', required=True)email = fields.Char(string='Email')project_name = fields.Char(string='Project Name')description = fields.Text(string='Project Description')
3. QWeb 表单模板
<!-- views/project_application_templates.xml -->
<odoo><template id="project_application_form" name="Project Application Form"><t t-call="website.layout"><div class="container mt-5"><h2>项目申请表</h2><form action="/project/apply/submit" method="post" class="form-group"><input type="hidden" name="csrf_token" t-att-value="request.csrf_token()"/><div class="form-group"><label>姓名</label><input type="text" name="name" class="form-control" required/></div><div class="form-group"><label>Email</label><input type="email" name="email" class="form-control"/></div><div class="form-group"><label>项目名称</label><input type="text" name="project_name" class="form-control"/></div><div class="form-group"><label>项目描述</label><textarea name="description" class="form-control"></textarea></div><button type="submit" class="btn btn-primary mt-2">提交申请</button></form></div></t></template><template id="project_application_success" name="Application Success"><t t-call="website.layout"><div class="container mt-5"><h2>提交成功！</h2><p>感谢您的申请，我们会尽快处理。</p></div></t></template>
</odoo>
4. 控制器逻辑
# controllers/main.py
from odoo import http
from odoo.http import requestclass ProjectApplicationController(http.Controller):@http.route('/project/apply', type='http', auth='public', website=True)def apply_form(self, **kwargs):return request.render('your_module_name.project_application_form')@http.route('/project/apply/submit', type='http', auth='public', website=True, csrf=True)def apply_form_submit(self, **post):request.env['project.application'].sudo().create({'name': post.get('name'),'email': post.get('email'),'project_name': post.get('project_name'),'description': post.get('description'),})return request.render('your_module_name.project_application_success')
5. Manifest 配置
# __manifest__.py
'data': ['views/project_application_templates.xml',
],
6. 访问测试
启动 Odoo 后，访问 http://localhost:8069/project/apply，填写并提交表单，系统将保存数据并显示成功页面。
七、进阶建议
| 功能 | 实现方式 |
|---|---|
| 表单校验 | HTML5 校验 + 控制器后端校验 |
| 自动填充用户信息 | 控制器中通过 request.env.user 获取当前用户信息 |
| 文件上传 | 表单添加 enctype="multipart/form-data"，后端用 request.httprequest.files 处理 |
| 提交后跳转页面 | 使用 return request.redirect('/thank-you') |
八、总结
| 项目 | 描述 |
|---|---|
| 渲染引擎 | QWebEngine（Python 层） |
| 应用场景 | Web 页面、报表模板、控制器页面、门户表单 |
| 优点 | 安全、结构化、可嵌套、支持继承 |
| 与 Jinja2 比较 | 更偏向 XML 结构控制，适合 B2B 页面、门户、报表；Jinja 更灵活 |
