控制器 – ERPNext中国企业实施指南

控制器（Controller）是一个普通的 Python 类，它继承自 frappe.model.Document 基类。该基类是 DocType 的核心逻辑，负责处理值如何从数据库加载、如何解析以及如何保存回数据库。

当你创建一个名为 Person 的 DocType 时，系统会生成一个名为 person.py 的 Python 文件，其内容如下：

import frappe
from frappe.model.document import Document

class Person(Document):
    pass

所有字段都可以作为类的属性来访问。

控制器方法

你可以向控制器添加自定义方法，并通过 doc 对象来调用它们。例如：

# controller class
class Person(Document):
    def get_full_name(self):
        """Returns the person's full name"""
        return f"{self.first_name} {self.last_name}"

# somewhere in your code
>>> doc = frappe.get_doc("Person", "000001")
>>> doc.get_full_name()
John Doe

控制器钩子

为了在文档的生命周期中添加自定义行为，我们提供了控制器钩子。

方法名称	描述	插入	保存	提交	取消	提交后更新
`before_insert`	在文档准备插入之前调用。	X
`before_naming`	在设置文档的 `name` 属性之前调用。	X
`autoname`	如果在控制器中定义，此方法用于设置文档的 `name` 属性。	X
`before_validate`	此钩子在验证之前调用，用于自动设置缺失的值。	X	X	X
`validate`	使用此方法抛出任何验证错误并阻止文档保存。	X	X	X
`before_save`	此方法在文档保存之前调用。	X	X
`before_submit`	此方法在文档提交之前调用。	X		X
`before_cancel`	此方法在文档取消之前调用。				X
`before_update_after_submit`	当已提交文档的字段被更新时调用此方法。					X
`db_insert`	此方法将文档插入数据库，除非你在处理虚拟 DocType，否则不要覆盖此方法。	X
`after_insert`	在文档插入数据库之后调用。	X
`db_update`	此方法更新数据库中的文档，除非你在处理虚拟 DocType，否则不要覆盖此方法。		X	X	X	X
`on_update`	当现有文档的值被更新时调用。	X	X	X
`on_submit`	当文档被提交时调用。			X
`on_cancel`	当已提交的文档被取消时调用。				X
`on_update_after_submit`	当已提交文档的值被更新时调用。					X
`on_change`	当文档的值被更改时调用。此方法也会在 db_set 执行时被调用，因此在此方法中执行的操作应该是幂等的。	X	X	X	X	X

除了针对典型操作的文档事件外，你还可以挂钩到其他操作。

方法名称	描述
`before_rename`	在文档重命名之前调用。
`after_rename`	在文档重命名之后调用。
`on_trash`	当文档被删除时调用。
`after_delete`	在文档被删除之后调用。

要使用控制器钩子，只需定义一个具有该名称的类方法。例如：

class Person(Document):
    def validate(self):
        if self.age <= 18:
            frappe.throw("Person's age must be at least 18")

    def after_insert(self):
        frappe.sendmail(recipients=[self.email], message="Thank you for registering!")

如果钩子不能满足你的需求，你也可以覆盖预定义的文档方法以添加你自己的行为。例如，要覆盖 save() 方法：

class Person(Document):
    def save(self, *args, **kwargs):
        super().save(*args, **kwargs) # call the base save method
        do_something() # eg: trigger an API call or a Rotating File Logger that "User X has tried updating this particular record"

doc 对象默认提供了许多方法。你可以在这里找到完整的列表。

1. 创建文档

要创建新文档并将其保存到数据库：

doc = frappe.get_doc({
    'doctype': 'Person',
    'first_name': 'John',
    'last_name': 'Doe'
})
doc.insert()

doc.name # 000001

2. 加载文档

要从数据库获取现有文档：

doc = frappe.get_doc('Person', '000001')

# doctype fields
doc.first_name # John
doc.last_name # Doe

# standard fields
doc.creation # datetime.datetime(2018, 9, 20, 12, 39, 34, 236801)
doc.owner # [email protected]

文档（Document）

文档是 DocType 的一个实例。它通常映射到数据库表中的一行。在代码中我们称之为 doc。

示例

假设我们有一个名为 ToDo 的 DocType，包含以下字段：

description
status
priority

现在，如果我们想从数据库中查询文档，可以使用 ORM。

>>> doc = frappe.get_doc("ToDo", "0000001")
<todo:>

>>> doc.as_dict()
{'name': '0000001',
 'owner': 'Administrator',
 'creation': datetime.datetime(2022, 3, 28, 18, 20, 23, 275229),
 'modified': datetime.datetime(2022, 3, 28, 18, 20, 23, 275229),
 'modified_by': 'Administrator',
 'docstatus': 0,
 'idx': 0,
 'status': 'Open',
 'priority': 'Medium',
 'color': None,
 'date': None,
 'allocated_to': None,
 'description': 'Test',
 'reference_type': None,
 'reference_name': None,
 'role': None,
 'assigned_by': 'Administrator',
 'assigned_by_full_name': 'Administrator',
 'sender': None,
 'assignment_rule': None,
 'doctype': 'ToDo'}
</todo:>

你可以获取 description、status 和 priority 的值，同时也会得到像 creation、owner 和 modified_by 这样的字段，这些字段是框架默认在所有 docs 上添加的。

类型注解

在版本 15 中引入。

Frappe 支持在控制器文件中自动生成 Python 类型注解。这些注解可用于控制器文件中的自动补全、参考和类型检查。

class Person(Document):
    # begin: auto-generated types
    # This code is auto-generated. Do not modify anything in this block.

    from typing import TYPE_CHECKING

    if TYPE_CHECKING:
        from frappe.types import DF

        first_name: DF.Data
        last_name: DF.Data 
        user: DF.Link
    # end: auto-generated types
    pass

注意：这些注解在创建或更新文档类型时生成。如果你修改了代码块，它将在下次更新时被覆盖。

你可以通过添加以下钩子来配置应用中的自动导出。

# hooks.py

export_python_type_annotations = True

了解更多关于类型注解的信息：

https://docs.python.org/3/library/typing.html
VS Code 用户可以安装 Python 扩展以获得更好的自动补全功能 – https://code.visualstudio.com/docs/languages/python
大多数其他编辑器都有使用 LSP 的等效插件系统。