[TITLE]
Odoo Studio PDF 报表编辑与自定义完整指南

[DESCRIPTION]
本文详细介绍如何在 Odoo Studio 中创建、编辑和自定义 PDF 报表，包括布局设置、背景、字体、公司标志、颜色、页眉页脚、纸张格式，以及使用条件块、表格和 XML 进行高级定制。

[KEYWORDS]
Odoo Studio,PDF 报表,报表布局,报表编辑,报表模板,条件块,动态表格,静态表格,XML 编辑,打印预览

PDF 报表

使用 Studio，您可以
编辑已有的 PDF 报表 <studio/pdf-reports/edit>（例如发票、报价单等）或
创建新报表 <studio/pdf-reports/edit>。

报表的默认布局在 Studio 之外进行管理。前往
设置，然后在主页面的
公司 部分，点击 配置文档布局。
布局设置是针对公司独立的，但会应用到所有报表。

:::: tip
::: title
提示
:::

您可以在 配置文档布局 窗口右侧的报表预览中查看不同设置对布局的影响。创建或编辑报表时，可通过点击左侧的 打印预览 查看报表预览。
::::

使用以下设置：

::: {#studio/pdf-reports/default-layout-layout}

  • 布局：提供七种布局可供选择：

    :::::::::: tabs
    ::: tab
    Light


    :::

    ::: tab
    Boxed


    :::

    ::: tab
    Bold


    :::

    ::: tab
    Striped


    :::

    ::: tab
    Bubble


    :::

    ::: tab
    Wave


    :::

    ::: tab
    Folder


    :::
    ::::::::::
    :::

::: {#studio/pdf-reports/default-layout-background}

  • 背景：可用背景包括：
    • Blank：不显示任何内容。
    • Demo logo：在背景中显示演示徽标。
    • Custom：上传自定义背景图片。
      :::

::: {#studio/pdf-reports/default-layout-font}

  • 文字：提供八种字体：Lato、Roboto、Open Sans、Montserrat、Oswald、Raleway、Tajawal（支持阿拉伯文和拉丁文）以及 Fira Mono。可前往 Google Fonts 网站 预览。
    :::

::: {#studio/pdf-reports/default-layout-logo}

  • 公司徽标：点击 编辑 按钮上传或更换徽标。该徽标会保存到 公司 模型的记录中，可通过 设置 → 更新信息（在 公司 部分）查看。
    :::

::: {#studio/pdf-reports/default-layout-colors}

  • 颜色：更改用于构建报表的主色和次色。默认颜色会依据徽标颜色自动生成。
    :::

::: {#studio/pdf-reports/default-layout-address}

  • 地址：公司名称和地址会显示在 外部报表 <studio/pdf-reports/header-footer> 的页眉中，可添加多行文字。
    :::

::: {#studio/pdf-reports/default-layout-tagline}

  • 标语：在 Light、Striped、Bubble、Wave、Folder 布局的外部报表页眉以及 Boxed、Bold 布局的页脚中显示，可添加多行文字。
    :::

::: {#studio/pdf-reports/default-layout-footer}

  • 页脚：在 外部报表 <studio/pdf-reports/header-footer> 的页脚中使用的文字，可添加多行文字，也可通过 报表编辑器 <studio/pdf-reports/edit> 进行编辑。
    :::

::: {#studio/pdf-reports/default-layout-paper}

  • 纸张格式：定义报表的默认纸张大小。可选择 A4（21 cm × 29.7 cm）或 US Letter（21.59 cm × 27.54 cm）。也可在 报表编辑 <studio/pdf-reports/edit-options> 的 纸张格式 字段为单个报表单独设定。

    :::: note
    ::: title
    注意
    :::

    根据已安装的应用或模块，可能会出现其他纸张格式，例如库存应用的标签纸或活动应用的胸卡。
    :::
    :::

要为某个 模型 </applications/studio/models_modules_apps>（如销售订单）创建报表，先打开该模型，点击 oi-studio（切换 Studio）按钮，再点击 报表。点击 新建，在弹出的窗口中选择报表类型。此选择仅决定页眉和页脚的显示方式：

::: {#studio/pdf-reports/header-footer}

  • External（外部）：

    • 页眉显示公司 徽标 <studio/pdf-reports/default-layout-logo>、名称和地址 <studio/pdf-reports/default-layout-address>。在 Light、Striped、Bubble、Wave、Folder 布局中，还会显示 标语 <studio/pdf-reports/default-layout-tagline>。
    • 页脚显示 页脚 <studio/pdf-reports/default-layout-footer> 中的内容以及页码；在 Boxed、Bold 布局中，页脚同样会显示 标语。

  • Internal（内部）：页眉显示当前用户的日期时间、公司 名称和地址 以及页码；无页脚。

  • Blank（空白）：既无页眉也无页脚，点击页面左上角即可编辑报表。
    :::

创建完报表后，即可 编辑它 <studio/pdf-reports/edit>。

要访问模型下的报表，打开该模型，点击 oi-studio（切换 Studio）按钮，再点击 报表，选择已有报表打开。

也可以直接打开 Studio，点击 报表，搜索特定报表或模型。

:::: important
::: title
重要
:::

强烈建议 复制 标准报表后再进行修改。复制报表的操作：将鼠标悬停在报表右上角，点击 fa-ellipsis-vertical（垂直省略号）图标，然后选择 复制。


::::

选择或创建报表后，可在左侧面板使用以下选项：

  • 报表名称：更改后会同步更新 Studio、表单视图的 打印 菜单（齿轮图标）以及 PDF 文件名。
  • 纸张格式：若未选择，则使用 默认布局 <studio/pdf-reports/default-layout-paper> 中定义的格式。
  • 在打印菜单中显示：将报表加入表单视图的 打印 菜单。
  • 从附件重新加载：首次生成报表时将其保存为记录的附件，之后每次重新加载原始版本。此功能在发票等场景下是法律要求。
  • 限制可见组：仅对特定 用户组 <../general/users/access_rights> 可见。
  • 编辑源代码：直接在 XML 文件 <studio/pdf-reports/XML-editing> 中修改报表。
  • 重置报表：丢弃所有修改，恢复为标准版本。
  • 打印预览：生成并下载报表预览。

报表编辑器用于修改报表的内容和格式。

:::: tip
::: title
提示
:::

  • 可使用 撤销 / 重做 按钮或快捷键 Ctrl+Z / Ctrl+Y。
  • 离开报表或点击 保存 按钮时，修改会自动保存。
  • 在左侧面板点击 重置报表 可恢复为标准版本。
    ::::

:::: important
::: title
重要
:::

编辑报表的页眉和页脚会影响所有标准报表和自定义报表。
::::

虚线矩形表示 条件块（if/else 语句），用于根据条件显示或隐藏内容。点击块可查看或编辑条件。

选择不同的值即可预览对应输出并进行编辑。

:::: note
::: title
注意
:::

条件只能在 XML <studio/pdf-reports/XML-editing> 中编辑。
::::

报表中的文字分为两类：

  • 静态文字：未被蓝色高亮的文字，可直接在编辑器中修改。
  • 动态文字：蓝色高亮的文字，在生成报表时会被相应的 字段 </applications/studio/fields> 值替换（如销售订单号、报价日期）。

可通过输入 [/] 打开 powerbox <essentials/html_editor/commands>，输入命令名称或从列表中选择，以向报表添加字段、列表、表格、图片、横幅等。直接输入文字即可添加静态文本。

如需更高级的修改，可直接 编辑 XML <studio/pdf-reports/XML-editing>。

添加字段 {#studio/pdf-reports/add-field}

输入 [/] 并选择 字段 命令。弹出列表后，搜索或选择字段；如需关联字段，可点击字段名右侧的箭头。随后设定字段未填时的默认值，回车确认。

添加或编辑表格 {#studio/pdf-reports/add-edit-table}

报表中有两种表格：

  • 静态表格 <studio/pdf-reports/static-table>：用于显示静态文字或字段。添加时需指定列数和行数。

  • 动态表格 <studio/pdf-reports/dynamic-table>：用于显示关联模型的记录数据。添加时只需指定列数，行数由关联记录数量决定。

    ::: example
    在销售订单报表中，动态表格用于显示与订单关联的订单行。若订单有 10 行，则报表中表格有 10 行；若只有 2 行，则表格有 2 行。
    :::

添加或编辑静态表格 {#studio/pdf-reports/static-table}

输入 [/] 并选择 表格 命令，设定列数和行数后即可编辑。使用表格工具可插入、移动、删除列或行。将光标置于列上方或行左侧，点击紫色矩形并选择相应操作。

拖动列边框可调整宽度，使用 重置大小 可恢复默认宽度。随后可在单元格中添加 字段 <studio/pdf-reports/add-field> 或直接输入静态文字。

:::: tip
::: title
提示
:::

若不想使用表格，也可以通过 [/] 添加 2 列、3 列、4 列 等列布局，实现结构化排版。
::::

添加或编辑动态表格 {#studio/pdf-reports/dynamic-table}

:::: note
::: title
注意
:::

  • 仅支持 one2many 或 many2many 关系的字段可显示为动态表格。
  • 标准报表中已有的动态表格结构更为复杂，用户只能插入或删除列，不能移动列或增删行。
    :::

输入 [/] 并选择 动态表格 命令，弹出列表后选择关联字段（如订单行），回车确认。添加后同样可使用表格工具插入、移动、删除列，并可在生成的行上方或下方插入静态行。

在单元格中添加字段时，先删除占位文字，再使用 添加字段 命令。弹窗会显示字段所属对象（如 订单行 模型）及可用字段列表。

将 Column name 替换为自定义标签即可。

:::: note
::: title
注意
:::

默认行会自动遍历字段内容，为每个字段值生成一行（例如每个订单行生成一行）。
::::

格式化

选中文本后，可使用 文本编辑器 </applications/essentials/html_editor> 中的选项进行加粗、斜体、颜色等格式化操作。

:::: warning
::: title
警告
:::

直接修改 XML 可能导致在 升级 <../../../administration/upgrade> 时出现报表错误。若出现此类问题，只需将旧库中的修改复制到升级后的库中即可。
::::

在左侧面板点击 编辑源代码 即可打开 XML 编辑器。

::: spoiler
修改字段的小部件

通过 t-options 中的 widget 参数，可自定义字段的显示方式。例如默认情况下，订单日期显示日期时间，单价显示两位小数：

<div class="oe_structure">
 <span t-field="doc.date_order"/>
 <span t-field="doc.price_unit"/>
</div>

使用 t-options 可改为仅显示日期且单价保留四位小数：

<div class="oe_structure">
 <span t-field="doc.date_order" t-options="{'widget': 'date'}"/>
 <span t-field="doc.price_unit" t-options="{'widget': 'float', 'precision': 4}"/>
</div>

:::

::: spoiler
条件块

通过在 XML 中添加 t-if / t-else 语句，可实现条件显示。例如：

<table class="table" t-if="len(doc.tag_ids) > 0">
    <thead>
        <tr><th>ID</th><th>Name</th></tr>
    </thead>
    <tbody>
        <tr t-foreach="doc.tag_ids" t-as="tag">
            <td t-out="tag.id"/>
            <td t-out="tag.name"/>
        </tr>
    </tbody>
</table>
<div class="text-muted" t-else="">No tag present on this document.</div>

使用 `t-if/t-