Odoo 11发票布局修改疑问：修改external_layout

Odoo 11发票布局修改疑问：修改external_layout_clean的QWeb问题

阿华AIGC实验室

2026-5-22

我经常帮开发者处理Odoo QWeb报表布局定制的问题，针对你在Odoo 11里修改external_layout_clean布局（既要调整CSS样式又要修改内容）遇到的问题，我整理了一套靠谱的解决流程和常见坑点，你可以跟着一步步排查：

一、绝对不要直接修改核心代码！用继承方式才是正确姿势

直接改动Odoo核心模块的QWeb文件是大忌——后续模块升级会直接覆盖你的所有修改。正确的做法是创建一个自定义模块，通过Odoo的QWeb继承机制来修改布局：

先搭建自定义模块的基础结构
- 新建一个名为my_custom_invoice_layout的模块，在根目录下创建__manifest__.py，确保依赖包含account和web模块：
```
{
    'name': 'Custom Invoice Layout',
    'version': '1.0',
    'depends': ['account', 'web'],
    'data': [
        'views/layouts.xml',
    ],
    'installable': True,
    'auto_install': False,
}
```
- 在模块内创建views/layouts.xml文件，用来编写继承和修改的QWeb代码

继承并修改web.external_layout_clean
用t-extend继承原模板，再通过xpath定位到要修改的元素，进行替换、新增或修改操作。这里给你一个完整的示例：

<?xml version="1.0" encoding="utf-8"?>
<odoo>
    <!-- 继承干净布局模板，并重命名为自定义布局 -->
    <template id="external_layout_custom_clean" inherit_id="web.external_layout_clean" name="Custom Clean External Layout">
        <!-- 替换原有头部内容 -->
        <xpath expr="//div[@class='header o_clean_header']/div[@class='row']" position="replace">
            <div class="row">
                <div class="col-xs-6">
                    <!-- 自定义Logo显示 -->
                    <img t-if="company.logo" t-att-src="image_data_uri(company.logo)" class="img img-responsive" style="max-height: 80px;"/>
                </div>
                <div class="col-xs-6 text-right">
                    <h2 t-field="company.name" style="color: #2d3748; margin-bottom: 8px;"/>
                    <div t-field="company.phone" style="font-size: 14px;"/>
                    <div t-field="company.email" style="font-size: 14px;"/>
                    <!-- 新增自定义字段 -->
                    <div t-if="company.vat" style="font-size: 12px; margin-top: 5px;">税号: <span t-field="company.vat"/></div>
                </div>
            </div>
        </xpath>

        <!-- 新增全局自定义CSS样式 -->
        <xpath expr="//div[@class='header o_clean_header']" position="before">
            <style type="text/css">
                .o_clean_header {
                    background-color: #f7fafc;
                    padding: 25px 0;
                    border-bottom: 1px solid #e2e8f0;
                }
                .page .invoice-content {
                    margin-top: 30px;
                }
            </style>
        </xpath>

        <!-- 如果要修改发票主体内容，继承account模块的发票报表模板 -->
        <template id="custom_invoice_report" inherit_id="account.report_invoice" name="Custom Invoice Report">
            <xpath expr="//div[@class='page']" position="inside">
                <!-- 在发票页面底部添加自定义提示 -->
                <div class="mt-4 p-3 bg-blue-50 rounded">
                    <p style="margin:0; color: #2b6cb0;">温馨提示：请在收到发票后15日内完成付款，感谢您的合作！</p>
                </div>
            </xpath>
        </template>
    </template>
</odoo>

二、常见问题排查指南

如果你已经按上面的方法操作但没生效，检查以下几个关键点：

模块是否正确安装并升级：在Odoo后台应用列表找到你的自定义模块，确保已安装；每次修改XML后必须点击模块的「升级」按钮，否则改动不会生效
XPath表达式是否精准：如果xpath找不到目标元素，修改就不会起作用。可以用浏览器开发者工具打开发票预览页面，查看HTML结构，确认目标元素的class、id或层级是否正确
权限是否足够：确保你的用户账号有访问该自定义模块的权限，以及查看发票报表的权限
缓存是否清理：Odoo会缓存QWeb模板，修改后要清除浏览器缓存，或者在后台「设置->技术->用户界面->视图」中找到对应的模板，点击「刷新」按钮

三、设置自定义布局为默认

修改完成后，记得把自定义布局设为发票的默认布局：