# ERPNext Jinja 模板 - 实施此技能可帮助您确定如何实施 Jinja 模板。有关确切的语法，请参阅“erpnext-syntax-jinja”。 **版本**：v14/v15/v16 兼容（注明了 V16 特定功能） ## 主要决定：你想创造什么？ ┌────────────────────────────────────────────────────────────────────────┐ │ 你想创造什么？ │ ├────────────────────────────────────────────────────────────────────────┤ │ │ │ ► 可打印文档（发票、采购订单、报告）？ │ │ ├── 标准DocType → 打印格式(Jinja) │ │ └── 查询/脚本报告 → 报告打印格式（JavaScript！） │ │ │ │ ► 包含动态内容的自动电子邮件？ │ │ └── 电子邮件模板(Jinja) │ │ │ │ ► 面向客户的网页？ │ │ └── 门户页面 (www/*.html + *.py) │ │ │ │ ► 可重复使用的模板函数/过滤器？ │ │ └── hooks.py 中自定义 jenv 方法 │ │ │ │ ► 通知内容？ │ │ └── 通知模板（使用 Jinja 语法） │ │ │ └──────────────────────────────────────────────────────────────────────────┘ ⚠️ 重要：报告打印格式使用 JAVASCRIPT 模板，而不是 Jinja！ - 金贾：{{变量}} - JS 报告：{%= 变量 %} ** ** ## 决策树：打印格式类型您要打印什么？ │ ├─► 标准文档类型（发票、采购订单、报价单）？ │ │ │ │ 在哪里创建？ │ ├─► 快速/简单格式→打印格式生成器（设置>打印） │ │ - 拖放界面 │ │ - 有限定制 │ │ │ └─► 需要复杂的布局 → 自定义 HTML 打印格式 │ - 完全 Jinja 控制 │ - 自定义 CSS 样式 │ - 动态逻辑 │ ├─► 查询报告还是脚本报告？ │ └─► 报告打印格式（JAVASCRIPT模板！） │ ⚠️ 不是 Jinja！使用 {%= %} 和 {% %} │ └─► 信函还是独立文件？ └─► 信头+打印格式组合 ** ** ## 决策树：模板的存储位置这是一次性的还是可重复使用的？ │ ├─► 特定于站点，通过 UI 管理？ │ └─► 通过设置 > 打印格式/电子邮件模板创建 │ - 存储在数据库中 │ - 无需代码即可轻松编辑 │ ├─► 您的定制应用程序的一部分？ │ │ │ │ 什么类型？ │ ├─► 打印格式 → myapp/fixtures 或 db 记录 │ │ │ ├─► 门户页面 → myapp/www/pagename/ │ │ -index.html（模板） │ │ -index.py（上下文） │ │ │ └─► 自定义方法/过滤器 → myapp/jinja/ │ - 通过 hooks.py jenv 注册 │ └─► 多个站点的模板？ └─► 包含在应用程序中，导出为夹具 ** ** ## 实施工作流程：打印格式 ### 第 1 步：通过 UI 创建（推荐开始）设置 > 打印 > 打印格式 > 新建 - 文件类型：销售发票 - 模块：账户标准：否（定制） - 打印格式类型：Jinja ### 步骤 2：基本模板结构 {# 始终在顶部包含样式#} <风格> .print-format { 字体系列：Arial、sans-serif； } .header { 背景：#f5f5f5;内边距：15px； } .table { 宽度：100%；边界崩溃：崩溃； } .table th, .table td { 边框：1px 实心 #ddd;内边距：8px； } .text-right { 文本对齐：右； } .footer { 顶部边距：30px;顶部边框：1px 实线#ddd； } {# 文档标题#}

{{ 文档名称 }}

{{ _("日期") }}: {{ doc.get_formatted("posting_date") }}

{# 项目表#} <表类=“表”> <标题> {{ _("项目") }} {{ _("数量") }} {{ _("金额") }} <正文> {% for row in doc.items %} {{ row.item_name }} {{ row.qty }} {{ row.get_formatted("金额", doc) }} {% 结束 %} {# 总计 #}

{{ _("总计") }}: {{ doc.get_formatted("grand_total") }}

### 第 3 步：测试和优化 1. 打开文档（例如销售发票） 2. 菜单 > 打印 > 选择格式 3.检查布局，根据需要调整CSS 4. 测试PDF生成 ** ** ## 实施工作流程：电子邮件模板 ### 第 1 步：通过 UI 创建设置 > 电子邮件 > 电子邮件模板 > 新建 - 名称：付款提醒 - 主题：发票 {{ doc.name }} - 应付付款 - 文件类型：销售发票 ### 第 2 步：模板内容

{{ _("亲爱的") }} {{ doc.customer_name }},

{{ _("这是发票的提醒") }} {{ doc.name }} {{ _("for") }} {{ doc.get_formatted("grand_total") }} {{ _("到期。") }}

{% if doc.items %}

{{ _("物品") }}：

{{ item.item_name }} ({{ item.qty }})

{% 结束 %}

{{ _("最诚挚的问候") }},
{{ frappe.db.get_value("公司", doc.company, "company_name") }}

### 步骤 3：在通知或代码中使用 # 在服务器脚本或控制器中冰沙.sendmail( 收件人=[文档.电子邮件], 主题=frappe.render_template( frappe.db.get_value("邮件模板", "付款提醒", "主题"), {“文档”：文档} ), message=frappe.get_template("付款提醒").render({"doc": doc}) ） ** ** ## 实施工作流程：门户页面 ### 第 1 步：创建目录结构我的应用程序/ └── www/ └── 项目/ ├── index.html # Jinja 模板 └──index.py # Python 上下文 ### 第 2 步：创建模板 (index.html) {% 扩展“templates/web.html” %} {% 块标题 %}{{ _("项目") }}{% endblock %} {% 阻止 page_content %}

{% if frappe.session.user != 'Guest' %}

{{ _("欢迎") }}, {{ frappe.get_fullname() }}

{% 结束 %} {% 项目中的项目 %}

{%其他%}

{% 结束 %} {% 末端嵌段 %} ### 步骤 3：创建上下文 (index.py) 进口冰沙 def get_context(上下文): context.title = "项目" context.no_cache = True # 动态内容 # 获取数据 context.projects = frappe.get_all( “项目”，过滤器={“is_public”：1}， fields=[“名称”,“标题”,“描述”], order_by="创建描述" ）返回上下文 ### 第 4 步：测试访问：https://yoursite.com/projects ** ** ## 实现工作流程：自定义 Jinja 方法 ### 步骤1：在hooks.py中注册 # myapp/hooks.py jenv = { "methods": ["myapp.jinja.methods"], “过滤器”：[“myapp.jinja.filters”] } ### 第 2 步：创建方法模块 # myapp/jinja/methods.py 进口冰沙 def get_company_logo(公司): """返回公司徽标 URL - 可在任何模板中使用""" 返回 frappe.db.get_value("公司", 公司, "company_logo") 或 "" def get_address_display(地址名称): """显示地址格式""" 如果不是地址名称：返回“” return frappe.get_doc("地址", address_name).get_display() def get_outstanding_amount(客户): """获取客户的总未付款项""" 结果 = frappe.db.sql(""" SELECT COALESCE(SUM(未结金额), 0) 来自“tab销售发票” 其中客户 = %s 并且 docstatus = 1 “””，客户）如果结果为 0，则返回结果[0][0] ### 步骤 3：创建过滤器模块 # myapp/jinja/filters.py def format_phone(值): """格式电话号码：1234567890 → (123) 456-7890""" 如果没有值：返回“” digits = ''.join(c for c in str(value) if c.isdigit()) 如果 len(数字) == 10: 返回 f"({digits[:3]}) {digits[3:6]}-{digits[6:]}" 返回值 defcurrency_words（金额，货币=“欧元”）： """将数字转换为单词（简体）""" 返回 f"{货币} {金额:,.2f}" ### 步骤 4：在模板中使用 {# 方法 - 作为函数调用 #}

杰出：{{ get_outstanding_amount(doc.customer) }}

{# 过滤器 - 在值之后通过管道传送#}

电话：{{ doc.phone |格式电话 }}

金额：{{ doc.grand_total |货币词 }}

### 第 5 步：部署工作台--站点站点名称迁移 ** ** ## 快速参考：上下文变量模板类型 |可用对象 ---|--- 打印格式| `doc`、`frappe`、`_()` 电子邮件模板| `doc`、`frappe` （有限）门户页面| `frappe.session`、`frappe.form_dict`、自定义上下文通知 | “文档”、“冰沙” ** ** ## 快速参考：基本方法需要|方法 ---|--- 格式货币/日期| `doc.get_formatted("字段名")` 设置子行格式 | `row.get_formatted("字段", doc)` 翻译字符串 | `_(“字符串”)` 获取链接文档 | `frappe.get_doc("DocType", 名称)` 获取单个字段 | `frappe.db.get_value("DT", 名称, "字段")` 当前日期 | `frappe.utils.nowdate()` 格式化日期 | `frappe.format_date(日期)` ** ** ## 关键规则 ### 1\.始终使用 get_formatted 来显示值 {# ❌ 原始数据库值#} {{ doc.grand_total }} {# ✅ 货币格式正确#} {{ doc.get_formatted("grand_total") }} ### 2\.始终传递父文档以进行子表格式化 {% for row in doc.items %} {# ❌ 缺少货币背景#} {{ row.get_formatted("rate") }} {# ✅ 具有来自父级的货币上下文#} {{ row.get_formatted("rate", doc) }} {% 结束 %} ### 3\.始终对用户文本使用翻译功能 {# ❌ 不可翻译#}

发票

{# ✅ 可翻译#}

### 4\.切勿在报告打印格式中使用 Jinja {% for(var i=0; i {% } %} ### 5\.切勿在循环中执行查询 {# ❌ N+1 查询问题#} {% for item in doc.items %} {% set stock = frappe.db.get_value("Bin", ...) %} {% 结束 %} {# ✅ 在控制器/上下文中预取数据#} {% for items_with_stock %} {{ item.stock_qty }} {% 结束 %} ** ** ## 版本差异特色| V14 | V15 | V16 ---|---|---|--- Jinja 模板 | ✅ | ✅ | ✅ 获取格式化（）| ✅ | ✅ | ✅ jenv 钩子 | ✅ | ✅ | ✅ pdf | wkhtmltopdf | ✅ | ✅ | ⚠️ **Chrome PDF** | ❌ | ❌ | ✅ ### V16 Chrome PDF 注意事项有关详细的 Chrome PDF 文档，请参阅“erpnext-syntax-jinja”。 ** ** ## 参考文件文件 |内容 ---|--- [decision-tree.md]() |完成模板类型选择 [workflows.md]() |分步实施模式 [examples.md]() |完整的工作示例 [anti-patterns.md]() |要避免的常见错误

{{ _("截止日期") }}	{{ frappe.format_date(doc.due_date) }}
{{ _("杰出") }}	{{ doc.get_formatted("outstanding_amount") }}
{%= data[i].name %}

{{ doc.select_print_heading 或 _("发票") }}

{{标题}}

{{ 项目.标题 }}

发票

{{ _("发票") }}

Erpnext Impl Jinja

包含技能