Odoo17 0.1常见的QWeb 模板语言指令的详细总结

Odoo QWeb 模板语言提供了许多指令 (directives) 来增强 HTML 模板的功能，使其能够动态地展示数据、进行条件判断、循环遍历、以及实现更复杂的逻辑。这些指令都以 t- 开头作为属性添加到 HTML 标签上。

以下是一些常见的 Odoo QWeb 模板语言指令的详细总结，并附带解释和示例：

1. 条件渲染指令:

t-if="condition": 条件判断指令。只有当 condition 表达式求值为真 (truthy) 时，指令所在的 HTML 元素及其内容才会被渲染。
- 语法:
```
<tag t-if="condition">
</tag>
```
- 解释: condition 可以是一个布尔值、一个表达式、或者一个变量。 QWeb 会评估这个条件。如果条件为 true, 非零数字, 非空字符串, 非空列表, 非空字典 等 truthy 值，则元素会被渲染。否则，元素及其内部的内容会被完全忽略，不会出现在最终的 HTML 输出中。
- 示例:
```
<p t-if="user.is_admin">您是管理员用户。
</p>
<p t-if="order_count > 0">您有 <t t-esc="order_count"/> 个订单。
</p>
```

t-elif="condition": else if 条件判断指令，必须紧跟在 t-if 或另一个 t-elif 之后。当之前的 t-if 或 t-elif 条件为假，并且当前 t-elif 的 condition 为真时，指令所在的 HTML 元素及其内容才会被渲染。

语法:

<tag t-if="condition1"><!-- 当 condition1 为真时渲染的内容 -->
</tag>
<tag t-elif="condition2"><!-- 当 condition1 为假且 condition2 为真时渲染的内容 -->
</tag>

解释: t-elif 提供了多分支条件判断的能力。可以有多个 t-elif 指令，按顺序评估条件。

示例:

<p t-if="user_role == 'admin'">您是管理员。
</p>
<p t-elif="user_role == 'manager'">您是经理。
</p>
<p t-elif="user_role == 'user'">您是普通用户。
</p>

t-else="": else 条件指令，必须紧跟在 t-if 或 t-elif 之后。当之前的所有 t-if 和 t-elif 条件都为假时，指令所在的 HTML 元素及其内容才会被渲染。
- 语法:
```
<tag t-if="condition">
</tag>
<tag t-else="">
</tag>
```
- 解释: t-else 提供了一个默认分支，当所有前面的条件都不满足时执行。 t-else 后面通常不需要写条件表达式，直接使用空字符串 "" 即可。
- 示例:
```
<p t-if="is_logged_in">欢迎回来，<t t-esc="user.name"/>!
</p>
<p t-else="">请先登录。
</p>
```

2. 循环指令:

t-foreach="items" t-as="item": 循环遍历指令。用于遍历一个列表 (list) 或元组 (tuple) items 中的每个元素，并将当前元素赋值给变量 item (可以自定义变量名)。
- 语法:
```
<tag t-foreach="items" t-as="item">
</tag>
```
- 解释: items 可以是一个列表、元组或者任何可迭代对象。 t-as="item" 定义了循环变量 item，在循环体内部可以使用 item 访问当前迭代到的元素。
- 示例:
```
<ul><li t-foreach="product_list" t-as="product"><t t-esc="product.name"/> - <t t-esc="product.price"/></li>
</ul>
```
- 循环上下文变量: 在 t-foreach 循环中，QWeb 还会自动提供一些特殊的上下文变量，以 _ 开头：
  - _index: 当前循环的索引 (从 0 开始)。
  - _first: 布尔值，指示是否是第一次循环迭代。
  - _last: 布尔值，指示是否是最后一次循环迭代。
  - _even: 布尔值，指示当前索引是否为偶数。
  - _odd: 布尔值，指示当前索引是否为奇数。
  - _size: 循环迭代的总次数。
  - 示例使用循环上下文变量:
```
<ul class="list-unstyled"><li t-foreach="items" t-as="item"><span t-if="_first">这是第一个元素: </span><span t-esc="item"/><span t-if="_last">, 这是最后一个元素。</span><span t-else>, </span></li>
</ul>
```
t-foreach="dictionary" t-as="key, value": 循环遍历字典 (dictionary) 指令。用于遍历一个字典 dictionary 中的键值对，并将当前键赋值给 key 变量，值赋值给 value 变量。
- 语法:
```
<tag t-foreach="dictionary" t-as="key, value">
</tag>
```
- 解释: dictionary 必须是一个字典对象。 t-as="key, value" 定义了键变量 key 和值变量 value。
- 示例:
```
<dl><div t-foreach="user_info" t-as="info_key, info_value"><dt><t t-esc="info_key"/></dt><dd><t t-esc="info_value"/></dd></div>
</dl>
```

3. 变量设置指令:

t-set="variable_name" t-value="expression": 设置变量指令。用于在模板中定义或修改变量 variable_name，并将 expression 的求值结果赋值给该变量。

语法:

<t t-set="variable_name" t-value="expression"/>

或者 (内容作为变量值):

<t t-set="variable_name"><!-- 这里的内容会被作为变量的值 --><p>一些内容</p><t t-esc="another_value"/>
</t>

解释:
- variable_name: 要设置的变量名 (字符串)。
- t-value="expression": 要赋给变量的值的表达式。如果省略 t-value 属性，则 t-set 标签内部的内容会被作为变量的值。

示例:

<t t-set="current_date" t-value="datetime.date.today()"/>
<p>今天是: <t t-esc="current_date"/></p><t t-set="greeting"><h1>欢迎来到我们的网站！</h1><p>希望您喜欢这里。</p>
</t>
<t t-raw="greeting"/> <!-- 使用 t-raw 来渲染 HTML 内容 -->

4. 值输出指令:

t-value="expression": 表达式求值指令。用于计算 expression 的值，并将结果不进行 HTML 转义直接输出到 HTML 中。 通常不直接使用 t-value 进行输出，因为它不安全，容易导致 XSS 攻击。 它主要用在 t-set 指令中赋值。
- 语法:
```
<tag t-value="expression">
</tag>
```
- 解释: expression 可以是任何 Python 表达式，可以访问模板上下文中的变量。 输出结果不会进行 HTML 转义。
- 示例 (通常不直接用于输出，多用于赋值):
```
<t t-set="calculated_value" t-value="price * quantity"/>

<p t-value="unsafe_data_from_user"/>
```
t-esc="expression": 表达式求值并进行 HTML 转义 输出指令。用于计算 expression 的值，并将结果进行 HTML 转义 后输出到 HTML 中。 这是最常用的输出指令，用于安全地显示动态数据，防止 XSS 攻击。
- 语法:
```
<tag t-esc="expression">
</tag>
```
- 解释: expression 可以是任何 Python 表达式。 输出结果会进行 HTML 转义，例如将 < 转换为 <, > 转换为 >, " 转换为 ", & 转换为 & 等。这样可以防止恶意用户注入 HTML 代码。
- 示例 (推荐使用):
```
<p>当前用户姓名: <t t-esc="user.name"/></p>
<p>商品价格: <t t-esc="product.price"/> 元</p>
<p>用户输入的内容: <t t-esc="user_input"/> </p>
```
t-raw="expression": 表达式求值并 原始输出 指令。用于计算 expression 的值，并将结果 不进行任何 HTML 转义，直接作为原始 HTML 输出到页面中。 使用 t-raw 需要非常谨慎，只在输出的内容是完全可信且安全的 HTML 代码时才使用，否则可能存在 XSS 漏洞风险。 通常用于输出预先处理好的 HTML 代码片段。
- 语法:
```
<tag t-raw="expression">
</tag>
```
- 解释: expression 可以是任何 Python 表达式，但通常应该返回 HTML 字符串。 输出结果不会进行 HTML 转义，直接作为 HTML 代码渲染。
- 示例 (谨慎使用):
```
<t t-set="safe_html_content" t-value="'<h1>这是一个标题</h1><p>这是一个段落。</p>'"/>
<div t-raw="safe_html_content"/> 

```

5. 模板调用指令:

t-call="template_name": 调用子模板指令。用于在当前模板中调用另一个已定义的 QWeb 模板 template_name。

语法:

<tag t-call="template_name"><!-- 可选： 可以使用 t-set 在这里向子模板传递参数 --><t t-set="param1" t-value="value1"/><t t-set="param2" t-value="value2"/>
</tag>

解释: template_name 是要调用的子模板的名称 (字符串)。 t-call 指令会将子模板的 HTML 输出嵌入到当前模板的指定位置。可以在 t-call 标签内部使用 t-set 指令来向子模板传递参数 (变量)。子模板可以通过访问这些参数变量来接收父模板传递的数据。

示例:

<!-- 父模板 -->
<template id="parent_template"><div><h1>父模板标题</h1><p>这是父模板的内容。</p><t t-call="child_template"><t t-set="username" t-value="user.name"/></t><p>父模板内容结束。</p></div>
</template><!-- 子模板 -->
<template id="child_template"><div><h2>子模板标题</h2><p>欢迎您，<t t-esc="username"/>!</p> <!-- 子模板可以使用父模板传递的 username 参数 --></div>
</template>

t-call="template_name" t-options="...": 调用子模板并传递选项。 t-options 属性允许向子模板传递更复杂的选项字典，用于控制子模板的渲染行为。 t-options 的具体内容取决于子模板的定义和期望接收的选项。

语法:

<tag t-call="template_name" t-options="options_dict"><!-- 可选： 仍然可以使用 t-set 传递参数，与 t-options 可以同时使用 -->
</tag>

解释: options_dict 是一个 Python 字典，包含了要传递给子模板的选项。子模板需要预先定义好如何处理这些选项。常见的 t-options 用途包括：
- 传递 widget 参数: 例如用于格式化日期、货币等。
- 传递格式化选项: 例如控制日期显示的格式、数字的小数位数等。
- 传递渲染模式或配置参数: 例如控制子模板的显示风格或行为。

示例 (假设子模板 formatted_date 接收 format 选项):

<template id="date_template"><p>原始日期: <t t-esc="date_obj"/></p><p>格式化日期 (年-月-日): <t t-call="formatted_date" t-options="{&quot;format&quot;: &quot;yyyy-MM-dd&quot;, &quot;date&quot;: date_obj}"/></p><p>格式化日期 (月/日/年): <t t-call="formatted_date" t-options="{&quot;format&quot;: &quot;MM/dd/yyyy&quot;, &quot;date&quot;: date_obj}"/></p>
</template><template id="formatted_date"><t t-set="format_str" t-value="options.get(&quot;format&quot;, &quot;yyyy-MM-dd HH:mm:ss&quot;)"/> <!-- 默认格式 --><t t-set="date_to_format" t-value="options.get(&quot;date&quot;)"/><t t-esc="date_to_format.strftime(format_str) if date_to_format else ''"/>
</template>

6. 属性指令:

t-att-attribute_name="expression": 动态属性指令。用于动态设置 HTML 元素的属性值。 attribute_name 会被替换成实际的 HTML 属性名，expression 的求值结果会作为属性值。
- 语法:
```
<tag t-att-attribute_name="expression">
</tag>
```
- 解释: attribute_name 可以是任何有效的 HTML 属性名 (例如 id, class, href, src, data-* 等)。 expression 的求值结果会被转换为字符串，并赋值给 attribute_name 属性。
- 示例:
```
<div t-att-id="'product_' + product.id" t-att-class="'product-card ' + ('featured' if product.is_featured else 'normal')">
</div>
<a t-att-href="'/product/' + product.id" t-att-title="product.name"><t t-esc="product.name"/>
</a>
```
t-attf-attribute_name="string_interpolation": 属性格式化指令 (Attribute Formatting)。使用 f-string 风格的字符串插值来动态设置 HTML 元素的属性值。更简洁易读，尤其是在属性值需要拼接多个动态部分时。
- 语法:
```
<tag t-attf-attribute_name="f-string_expression">
</tag>
```
- 解释: attribute_name 是 HTML 属性名。 f-string_expression 是一个 f-string 风格的字符串，可以使用花括号 {} 包裹 Python 表达式，表达式的值会被插入到字符串中。
- 示例:
```
<div t-attf-id="product-{product.id}" t-attf-class="product-card {'featured' if product.is_featured else 'normal'}">
</div>
<a t-attf-href="/product/{product.id}" t-attf-title="{product.name}"><t t-esc="product.name"/>
</a>
```

7. 其他指令 (简要介绍):

t-translation="on": 启用模板翻译。用于标记模板需要进行国际化 (i18n) 翻译。通常在模板的根元素上使用。

示例:

<template id="my_template" t-translation="on"><!-- 模板内容，可以使用 <t t-translatable="1">...</t> 标记可翻译的文本 -->
</template>

t-lang="language_code": 设置模板的语言。用于指定模板渲染时使用的语言，通常用于多语言环境。
- 示例:
```
<template id="my_template" t-lang="lang_code">
</template>
```
t-cache="directive": 模板缓存指令。用于控制模板的缓存行为，提高性能。 directive 可以是 cache, nocache, clear. 通常与 t-key 和 t-context 配合使用。 (高级用法，初学者可以先忽略)
t-debug="expression": 调试指令。用于在模板渲染过程中输出 expression 的值到控制台，方便调试模板逻辑。通常在开发阶段使用。