frappe-syntax-clientscripts

Frappe 客户端脚本语法

客户端脚本在浏览器中运行，控制 Frappe/ERPNext 中的所有 UI 交互。通过 Setup > Client Script 创建，或将脚本放在自定义应用的 public/js/ 目录下。

重要：客户端脚本验证仅在浏览器表单视图中生效。API 调用和 System Console 会绕过这些验证。对于安全关键的验证，务必配合使用服务器脚本。

快速参考

操作	代码
设置值	frm.set_value('field', value)
获取值	frm.doc.fieldname
隐藏字段	frm.toggle_display('field', false)
设为必填	frm.toggle_reqd('field', true)
设为只读	frm.toggle_enable('field', false)
设置字段属性	frm.set_df_property('field', 'options', [...])
筛选 Link 字段	frm.set_query('field', () => ({filters: {}}))
调用服务器	frappe.call({method: 'path.to.fn', args: {}})
调用文档方法	frm.call('method_name', {args})
阻止保存	frappe.throw(__('Error message'))
添加按钮	frm.add_custom_button(__('Label'), callback, group)
添加子表行	frm.add_child('table', {values}); frm.refresh_field('table')
显示提示	frappe.show_alert({message: __('Done'), indicator: 'green'})
翻译字符串	__('Text') 或 __('Hello {0}', [name])

事件决策树

What do you need to do?
│
├─ One-time setup (queries, formatters)?
│  └─ ALWAYS use setup — runs once per form instance
│
├─ Show/hide fields, add buttons, update UI?
│  └─ ALWAYS use refresh — fires after every load/reload
│
├─ Validate data before save?
│  └─ ALWAYS use validate — use frappe.throw() to block save
│
├─ Modify data right before server save?
│  └─ Use before_save — last chance to change values
│
├─ Run logic after successful save?
│  └─ Use after_save — document is persisted
│
├─ React to a field value change?
│  └─ Use the fieldname as the event name
│
├─ Intercept workflow state change?
│  └─ Use before_workflow_action / after_workflow_action
│
└─ Manipulate DOM after full render?
   └─ Use onload_post_render — NEVER use jQuery selectors directly

完整的事件列表和执行顺序请参阅 references/events.md。

表单事件注册

// Parent form events
frappe.ui.form.on('Sales Order', {
    setup(frm) { },           // Once per form instance
    refresh(frm) { },         // After every load/reload
    validate(frm) { },        // Before save — throw to block
    fieldname(frm) { }        // On field value change
});

// Child table events — ALWAYS register on the CHILD doctype
frappe.ui.form.on('Sales Order Item', {
    qty(frm, cdt, cdn) {
        let row = frappe.get_doc(cdt, cdn);
        frappe.model.set_value(cdt, cdn, 'amount', row.qty * row.rate);
    },
    items_add(frm, cdt, cdn) { },     // Row added
    items_remove(frm) { },            // Row removed (no cdt/cdn)
    items_move(frm) { }               // Row reordered
});

值操作

// ALWAYS use frm.set_value() — NEVER assign frm.doc.field directly
frm.set_value('status', 'Approved');                        // Single
frm.set_value({status: 'Approved', priority: 'High'});      // Multiple

// Read values (read-only — NEVER write via frm.doc)
let val = frm.doc.fieldname;
let items = frm.doc.items;  // Child table array

字段属性

// Show/hide (accepts single field or array)
frm.toggle_display(['priority', 'due_date'], frm.doc.status === 'Open');

// Mandatory toggle
frm.toggle_reqd('due_date', true);

// Read-only toggle
frm.toggle_enable('amount', false);  // false = read-only

// Arbitrary property change
frm.set_df_property('status', 'options', ['New', 'Open', 'Closed']);
frm.set_df_property('amount', 'read_only', 1);
frm.set_df_property('notes', 'label', 'Internal Notes');

// Intro message at form top
frm.set_intro('This document is pending review', 'orange');

Link 字段筛选器

// ALWAYS set queries in setup event — NEVER in refresh
frappe.ui.form.on('Sales Order', {
    setup(frm) {
        // Simple filter
        frm.set_query('customer', () => ({
            filters: { disabled: 0 }
        }));

        // Child table filter
        frm.set_query('item_code', 'items', (doc, cdt, cdn) => {
            let row = locals[cdt][cdn];
            return { filters: { is_sales_item: 1 } };
        });

        // Server-side query for complex logic
        frm.set_query('customer', () => ({
            query: 'myapp.queries.get_filtered_customers',
            filters: { region: frm.doc.region }
        }));
    }
});

服务器通信

// frappe.call — whitelisted Python method
let r = await frappe.call({
    method: 'myapp.api.process_data',
    args: { customer: frm.doc.customer },
    freeze: true,
    freeze_message: __('Processing...')
});
if (r.message) { /* use r.message */ }

// frm.call — document controller method
let result = await frm.call('calculate_taxes', { include_shipping: true });

// frappe.db shortcuts
let val = await frappe.db.get_value('Customer', name, 'credit_limit');
let list = await frappe.db.get_list('Sales Order', {
    filters: { customer: frm.doc.customer },
    fields: ['name', 'grand_total'],
    order_by: 'creation desc',
    limit: 10
});

子表操作

// Add row — ALWAYS call refresh_field after
let row = frm.add_child('items', { item_code: 'ITEM-001', qty: 5 });
frm.refresh_field('items');

// Clear all rows
frm.clear_table('items');
frm.refresh_field('items');

// Modify existing rows — refresh_field ONCE after loop
frm.doc.items.forEach(row => {
    row.discount = row.qty > 10 ? 5 : 0;
});
frm.refresh_field('items');

// Set child row value (inside child event handler)
frappe.model.set_value(cdt, cdn, 'amount', row.qty * row.rate);

// Mark form dirty after programmatic changes
frm.dirty();

自定义按钮

refresh(frm) {
    if (frm.doc.docstatus === 1) {
        // Grouped dropdown
        frm.add_custom_button(__('Invoice'), () => {
            frappe.model.open_mapped_doc({
                method: 'erpnext.selling.doctype.sales_order.sales_order.make_sales_invoice',
                frm: frm
            });
        }, __('Create'));

        // Primary action
        frm.page.set_primary_action(__('Process'), () => {
            frm.call('process').then(() => frm.reload_doc());
        });
    }

    // ALWAYS guard buttons with state checks
    if (!frm.is_new() && frm.doc.docstatus === 0) {
        frm.add_custom_button(__('Validate'), () => { /* ... */ });
    }
}

列表视图自定义

frappe.listview_settings['Task'] = {
    add_fields: ['status', 'priority'],
    filters: [['status', '!=', 'Cancelled']],
    hide_name_column: true,

    get_indicator(doc) {
        // ALWAYS return [label, color, filter_field + ',' + filter_value]
        if (doc.status === 'Open') return [__('Open'), 'orange', 'status,=,Open'];
        if (doc.status === 'Closed') return [__('Closed'), 'green', 'status,=,Closed'];
    },

    button: {
        show(doc) { return doc.status === 'Open'; },
        get_label() { return __('Close'); },
        action(doc) { frappe.call({method: 'myapp.api.close', args: {name: doc.name}}); }
    },

    formatters: {
        priority(val) { return val === 'High' ? `<b>${val}</b>` : val; }
    },

    onload(listview) { /* runs once */ },
    refresh(listview) { /* runs on every refresh */ }
};

对话框和提示词

// Quick prompt
frappe.prompt({label: 'Reason', fieldname: 'reason', fieldtype: 'Data'},
    (values) => { console.log(values.reason); },
    __('Enter Reason')
);

// Full dialog
let d = new frappe.ui.Dialog({
    title: __('Enter Details'),
    fields: [
        {label: 'Name', fieldname: 'name', fieldtype: 'Data', reqd: 1},
        {label: 'Date', fieldname: 'date', fieldtype: 'Date'}
    ],
    size: 'small',
    primary_action_label: __('Submit'),
    primary_action(values) { d.hide(); /* use values */ }
});
d.show();

// Progress indicator
frappe.show_progress(__('Importing'), 45, 100, __('Please wait'));

关键规则

1. 修改子表后，务必调用 frm.refresh_field('table')
2. 绝不要赋值 frm.doc.field = value——务必使用 frm.set_value()
3. 面向用户的字符串务必使用 __('text')
4. 务必在 setup 中设置 set_query——绝不要在 refresh 中设置
5. 绝不要使用 async: false——这会冻结浏览器
6. 添加操作按钮前，务必检查 frm.is_new()
7. 操作字段时，绝不要直接使用 jQuery 选择器——请使用 Frappe API
8. 绝不要在全局变量中存储状态——应将其附加到 frm 对象
9. 使用服务器调用的响应前，务必检查 r.message
10. 在 validate 中阻止保存时，务必使用 frappe.throw()——绝不要在异步处理程序中使用 return false

完整的 API 参考请参阅 references/methods.md。 实际应用模式请参阅 references/examples.md。 常见错误请参阅 references/anti-patterns.md。

相关技能

• frappe-impl-clientscripts — 实现工作流和决策树
• frappe-errors-clientscripts — 错误处理和调试模式
• frappe-syntax-whitelisted — 从客户端脚本调用的服务器端方法
• frappe-syntax-doctypes — 脚本中引用的 DocType 字段定义