客户端脚本 – ERPNext中国企业实施指南

客户端脚本让你可以动态定义一个自定义表单脚本，该脚本会在用户的浏览器上执行。如果你选择使用非标准工具或库，请务必在不同浏览器上进行测试，以确保在你的用户群体中具备兼容性。

在版本 13 中，自定义脚本已重命名为客户端脚本

如何创建客户端脚本

创建客户端脚本的方法

要添加/编辑客户端脚本，请确保你的角色是系统管理员。
在搜索栏中输入“新建客户端脚本”并按回车，创建一个新的客户端脚本文档。
选择你想要自定义表单的文档类型。
使用预设模板更新脚本并保存。
前往你已自定义的文档类型，查看更改效果。
功能特性

与服务器脚本的诸多限制相比，客户端脚本中一切皆可自由使用。这是因为前端 API 在设计上就是安全的。你可以使用所有 JavaScript API，以及 Frappe 的 API 和你可能已用于自定义 Desk 的任何其他 JS 或 CSS 库。

你通过客户端脚本添加的验证只会在通过浏览器访问的标准表单视图中生效。如果你希望这些验证也能通过 API 或系统控制台访问时生效，请使用服务器脚本。

示例

3.1 自定义验证

在通过 Frappe 标准表单视图创建或更新文档时，添加额外的表单验证。

// additional validation on Task dates
frappe.ui.form.on('Task', 'validate', function(frm) {
    if (frm.doc.from_date < get_today()) {
        msgprint('You can not select past date in From Date');
    }
});

3.2 在字段更新时获取值

在更改 customer 字段的值时获取 local_tax_no。

cur_frm.add_fetch('customer', 'local_tax_no', 'local_tax_no');

3.3 自定义字段属性

在创建文档后将字段 ibsn 设为只读。

// make a field read-only after saving
frappe.ui.form.on('Task',  {
    refresh: function(frm) {
        frm.set_df_property('ibsn', 'read_only', !frm.is_new());
    }
});

3.4 自定义字段属性

在保存时计算销售发票表单上的佣金。

// calculate sales incentive
frappe.ui.form.on('Sales Invoice',  {
    validate: function(frm) {
        // calculate incentives for each person on the deal
        total_incentive = 0
        $.each(frm.doc.sales_team,  function(i,  d) {
            // calculate incentive
            let incentive_percent = 2;
            if(frm.doc.base_grand_total > 400) incentive_percent = 4;
            // actual incentive
            d.incentives = flt(frm.doc.base_grand_total) * incentive_percent / 100;
            total_incentive += flt(d.incentives)
        });
        frm.doc.total_incentive = total_incentive;
    }
});

3.5 筛选邮件收件人

你可以通过客户端脚本限制可用的邮件地址。每个表单都可以指定哪些电子邮件地址应该可供选择。这可以减少用户的认知负担，并避免将邮件发送给错误的收件人。

CommunicationComposer（邮件对话框）会检查是否存在为“收件人”、“抄送”和“密送”字段提供筛选条件的客户端脚本。例如，如果某个报价单只应显示与该报价单收件人关联的电子邮件地址，我们可以添加以下脚本：

frappe.ui.form.on("Quotation", {
    get_email_recipient_filters: function (frm, field) {
        // field can be "recipients", "cc" or "bcc"
        if (field === "recipients") {
            return [
                [
                    "Dynamic Link",
                    "link_doctype",
                    "=",
                    frm.doc.quotation_to
                ],
                [
                    "Dynamic Link",
                    "link_name",
                    "=",
                    frm.doc.party_name
                ],
            ];
        }
    },
    // ...
};

这些筛选条件引用的是联系人文档类型及其链接子表。

即使有筛选条件，仍然可以粘贴任意收件人。

3.6 设置默认邮件收件人

在诸如销售订单 -> 交货单 -> 销售发票这样的标准流程中，邮件收件人通常是预先定义好的。例如，这可以由客户经理提前完成。

你可以通过客户端脚本设置默认邮件收件人。每个表单都可以通过编程方式提供自己的默认收件人。

CommunicationComposer（邮件对话框）会检查是否存在提供默认收件人的客户端脚本。例如，如果你的报价单文档类型包含一个名为密送（"custom_bcc"）的字段，你可以添加以下客户端脚本，将其用作邮件对话框中的默认密送地址：

frappe.ui.form.on("Quotation", {
    get_email_recipients: function (frm, field) {
        // field can be "recipients", "cc" or "bcc"
        if (field === "bcc") {
            return [frm.doc.custom_bcc]
        }
    },
    // ...
};