frappe-impl-clientscripts

クライアントスクリプト — 実装ワークフロー

クライアント側のフォーム機能を構築するための、ステップごとのワークフローです。API の正確な構文については、frappe-syntax-clientscripts を参照してください。

バージョン：v14/v15/v16 | 注記：v13 では「Custom Script」の名称が「Client Script」に変更されました

クイック判断：クライアント側かサーバー側か？

MUST the logic ALWAYS execute (imports, API, Data Import)?
├── YES → Server Script or Controller
└── NO  → What is the goal?
         ├── UI feedback / UX → Client Script
         ├── Show/hide fields → Client Script
         ├── Link filters → Client Script
         ├── Data validation → BOTH (client for UX, server for integrity)
         └── Calculations → Client for display, server for critical

ルール：UX には必ずクライアントスクリプトを使用してください。重要なロジックは必ずサーバー側の検証で補強してください。

ワークフロー 1：UI からクライアントスクリプトを作成する

1. Setup > Client Script に移動します（または awesomebar に「New Client Script」と入力します）
2. 対象の DocType を選択します
3. Enabled チェックボックスを必ずオンにします
4. frappe.ui.form.on パターンを使用してスクリプトを記述します
5. 保存します — スクリプトはすぐに有効になります（再起動は不要です）
6. 対象の DocType フォームを開き、動作をテストします
7. デバッグするには、ブラウザーの DevTools Console（F12）を開きます

カスタムアプリへの移行が必要な場合：スクリプトが 50 行を超える場合、バージョン管理が必要な場合、または複数の環境にデプロイする必要がある場合は、必ず移行してください。

ワークフロー 2：適切なイベントを選択する

WHAT DO YOU WANT?
├── Set link filters         → setup (once, earliest lifecycle)
├── Add custom buttons       → refresh (re-added after each render)
├── Show/hide fields         → refresh + {fieldname} (BOTH needed)
├── Validate before save     → validate (frappe.throw stops save)
├── Action after save        → after_save
├── Calculate on change      → {fieldname} handler
├── Child row added          → {tablename}_add
├── Child row removed        → {tablename}_remove
├── Child field changed      → Child DocType: {fieldname}
├── One-time init            → setup or onload
└── After full DOM render    → onload_post_render

イベントのタイミングの全体像については、references/decision-tree.md を参照してください。

ワークフロー 3：フィールドの表示切り替え

目標：「requires_delivery」がチェックされている場合にのみ、「delivery_date」を表示します。

ステップ 1：refresh とフィールド名のイベントの両方を実装します。

frappe.ui.form.on('Sales Order', {
    refresh(frm) {
        frm.trigger('requires_delivery'); // Set initial state
    },
    requires_delivery(frm) {
        frm.toggle_display('delivery_date', frm.doc.requires_delivery);
        frm.toggle_reqd('delivery_date', frm.doc.requires_delivery);
    }
});

両方が必要な理由：refresh はフォームの読み込み時に状態を設定します。{fieldname} はユーザーの操作に応答します。片方だけを使用しないでください。フォームの読み込み時または変更時に、誤った状態が表示されます。

ワークフロー 4：連動するリンクフィルター

目標：選択した「country」に基づいて「city」をフィルターします。

frappe.ui.form.on('Customer', {
    setup(frm) {
        // ALWAYS set filters in setup — ensures consistency
        frm.set_query('city', () => ({
            filters: { country: frm.doc.country || '' }
        }));
    },
    country(frm) {
        frm.set_value('city', ''); // ALWAYS clear dependent field
    }
});

ルール：set_query は必ず setup に記述してください。親フィールドが変更されたら、必ず子フィールドをクリアしてください。

ワークフロー 5：計算フィールド（子テーブル）

目標：行の金額とドキュメントの合計を計算します。

frappe.ui.form.on('Invoice Item', {
    qty(frm, cdt, cdn) { calculate_row(frm, cdt, cdn); },
    rate(frm, cdt, cdn) { calculate_row(frm, cdt, cdn); },
    amount(frm) { calculate_totals(frm); }
});

frappe.ui.form.on('Invoice', {
    items_remove(frm) { calculate_totals(frm); }
});

function calculate_row(frm, cdt, cdn) {
    let row = frappe.get_doc(cdt, cdn);
    frappe.model.set_value(cdt, cdn, 'amount',
        flt(row.qty) * flt(row.rate));
}

function calculate_totals(frm) {
    let total = (frm.doc.items || []).reduce(
        (sum, row) => sum + flt(row.amount), 0);
    frm.set_value('grand_total', flt(total, 2));
}

ルール：

• 数値演算には必ず flt() を使用してください（null/undefined を処理します）
• 必ず items_remove を処理してください — 行の削除時にも合計を再計算する必要があります
• set_value の後に refresh_field を呼び出さないでください — 自動的に呼び出されます

ワークフロー 6：サーバー呼び出し：使用するメソッド

NEED TO CALL THE SERVER?
├── Fetch a single value?
│   └── frappe.db.get_value(doctype, name, fields)
│       Returns: Promise — lightweight, no whitelist needed
│
├── Call a document's controller method?
│   └── frm.call(method, args)
│       Requires: @frappe.whitelist() on controller method
│       Auto-includes: doctype, docname, doc context
│
├── Call a standalone whitelisted function?
│   └── frappe.call({method: 'dotted.path', args: {}})
│       Requires: @frappe.whitelist() decorator
│       Returns: Promise with r.message
│
└── Need Promise-only (no callback)?
    └── frappe.xcall('dotted.path', args)
        Same as frappe.call but returns clean Promise

例 — frm.call：

frm.call('calculate_taxes').then(r => {
    frm.reload_doc();  // Refresh after server-side changes
});

例 — frappe.xcall：

let result = await frappe.xcall(
    'myapp.api.check_credit', { customer: frm.doc.customer });

ワークフロー 7：カスタムボタンの実装

frappe.ui.form.on('Sales Order', {
    refresh(frm) {
        // ALWAYS check conditions before adding buttons
        if (!frm.is_new() && frm.doc.docstatus === 1) {
            frm.add_custom_button(__('Create Invoice'), () => {
                create_invoice(frm);
            }, __('Create'));  // Group label
        }
    }
});

ルール：

• ボタンは必ず refresh に追加してください — レンダリングごとにクリアされます
• 保存されていないドキュメントのボタンはエラーの原因になるため、必ず frm.is_new() を確認してください
• ボタンのラベルは必ず __() で囲んで翻訳可能にしてください
• UI の準備ができていないため、setup や onload にボタンを追加しないでください

ワークフロー 8：サーバーで確認する非同期検証

frappe.ui.form.on('Sales Order', {
    async validate(frm) {
        if (!frm.doc.customer || !frm.doc.grand_total) return;

        let r = await frappe.call({
            method: 'myapp.api.check_credit',
            args: {
                customer: frm.doc.customer,
                amount: frm.doc.grand_total
            }
        });

        if (r.message && !r.message.allowed) {
            frappe.throw(__('Credit limit exceeded. Available: {0}',
                [r.message.available]));
        }
    }
});

ルール：

• validate 内でのサーバー呼び出しには必ず async/await を使用してください
• 保存を中止するには必ず frappe.throw() を使用してください — msgprint では中止されません
• ユーザーが予期しない遅いサーバー呼び出しを validate に含めないでください

ワークフロー 9：ブラウザーでのデバッグ

1. F12 DevTools > Console を開きます
2. イベントハンドラーに console.log(frm.doc) を追加します
3. Console で cur_frm を使用して、現在のフォーム状態を確認します
4. Network タブで失敗した frappe.call リクエストを確認します
5. frappe.ui.form.handlers を使用して、登録済みのイベントハンドラーを確認します

デバッグパターン：

frappe.ui.form.on('MyDocType', {
    my_field(frm) {
        console.log('Field changed:', frm.doc.my_field);
        // ... actual logic
    }
});

ワークフロー 10：クライアントスクリプトをカスタムアプリに移行する

1. JS ファイルを作成します：myapp/myapp/public/js/sales_order.js
2. スクリプトの内容をファイルに移します（frappe.ui.form.on ラッパーはそのまま残します）
3. hooks.py に登録します：

   doctype_js = {
       "Sales Order": "public/js/sales_order.js"
   }
   

4. bench build を実行します（開発時は bench watch を実行します）
5. Setup から Client Script ドキュメントを削除します
6. フォームでテストします — 動作が完全に同じである必要があります

必ず移行してください：バージョン管理が必要な場合、複数環境へのデプロイが必要な場合、スクリプトが 50 行を超える場合、チームでの共同作業が必要な場合。

パフォーマンスに関するルール

ルール	理由
set_query は setup のみで設定する	refresh のたびに再登録されるのを防ぎます
set_value の呼び出しをまとめる	frm.set_value({a: 1, b: 2}) — 2 回ではなく 1 回の更新で済みます
サーバー応答をキャッシュする	frm._cache_key に保存して、繰り返しの呼び出しを避けます
ループ内でクエリを実行しない	すべてのデータを一度に取得し、検索用マップを作成します
frappe.db.get_value を使用する	単純な検索では frappe.call より軽量です

関連スキル

• frappe-syntax-clientscripts — 正確な API 構文とメソッドシグネチャ
• frappe-errors-clientscripts — エラー処理とよくある落とし穴
• frappe-syntax-whitelisted — クライアントから呼び出し可能なサーバーメソッド
• frappe-core-database — frappe.db.* のクライアント側 API
• frappe-impl-serverscripts — ロジックをサーバー側に移すタイミング

イベントの選択については、references/decision-tree.md を参照してください。 拡張パターンについては、references/workflows.md を参照してください。 10 個以上の完全な例については、references/examples.md を参照してください。