Frappe DocField 详解DocType 字段的模型与视图双重元数据【免费下载链接】frappeLow code web framework for real world applications, in Python and Javascript项目地址: https://gitcode.com/GitHub_Trending/fr/frappeDocField 是 Frappe 低代码框架中描述一个 DocType 字段的元数据 Doctype它与数据库表列column一一对应或仅作为布局/展示节点存在同时承载字段的数据模型语义类型、长度、索引、默认值、校验约束与视图渲染语义标签、占位符、显隐、只读、折叠、布局断点。本文以 DocField 官方 README 为骨架结合 docfield.json 中 60 余个字段定义与 meta.py、schema.py 等源码系统讲解 DocField 的核心概念、字段类型体系、全部配置属性及其在模型同步、表单渲染、列表/搜索与权限体系中的落地方式。读完本文你将能在自定义 Doctype 中精确设计字段、理解字段属性对数据库 DDL 的影响并掌握 DocField 与 Custom Field、Property Setter 之间的协作关系。一、DocField 是什么一张表两种职责官方 README 用一句话给出了 DocField 的定义Represents a field of a DocType analogous to a table column in the database. DocFields represent the properties both the model and the view and hence may or may not have database columns associated (for example, Section Break does not have any column associated.)这段话包含三个关键信息模型视角DocField 之于 DocType如同数据库列之于数据库表。DocType 的 JSON 文件如 docfield.json 中的fields数组里每一个元素在运行时就是一个DocField记录。视图视角DocField 同时描述字段在表单Form、列表List、报表Report、打印Print中的呈现方式包括标签、宽度、显隐、布局断点等。列的有无并不必须布局型字段Section Break、Column Break、Tab Break、HTML、Button、Image、Fold、Heading、Attachment Gallery不产生数据库列。这一点在 frappe/model/init.py 中被固化为一组no_value_fields常量凡属于该集合的字段类型都被视为无值字段不会进入_valid_fields与列同步流程。1.1 DocField 自身也是一个 DocTypeDocField 本身是一个istable: 1的 DocType见 docfield.json即一个子表Child Table它作为 DocType 的fields子表被内嵌引用。因此你无法独立创建一条 DocField 记录它总是依附于某个 DocType 或 Custom Field 存在。DocField 没有显式权限记录permissions: []其访问完全由所属 DocType 的权限系统代理。1.2 从文件加载的引导过程由于 DocField 是框架自举bootstrap所用的特殊 Doctype之一当数据库里不存在它时meta.py 的load_doctype_from_file会直接从磁盘 JSON 加载读取frappe/core/doctype/docfield/docfield.json将fields数组中每个元素标注doctype DocFieldmeta.py把每个元素包装成BaseDocument保证后续所有字段属性都能以对象属性方式访问如df.fieldname、df.fieldtype。Meta.special_doctypesmeta.py将DocField与DocPerm、DocType等一并列为特殊类型process()对这些类型跳过自定义字段注入与属性覆盖流程避免循环依赖。二、字段类型体系从 Select 选项到 Python 常量DocField 的fieldtype是一个必填的 Select 字段其可选项完整枚举了 Frappe 支持的全部字段类型见 docfield.jsonAutocomplete, Attach, Attach Image, Attachment Gallery, Barcode, Button, Check, Code, Color, Column Break, Currency, Data, Date, Datetime, Duration, Dynamic Link, Float, Fold, Geolocation, Heading, HTML, HTML Editor, Icon, Image, Int, JSON, Link, Long Text, Markdown Editor, Password, Percent, Phone, Read Only, Rating, Section Break, Select, Signature, Small Text, Tab Break, Table, Table MultiSelect, Text, Text Editor, Time在 Python 侧这些类型被组织为几组语义集合frappe/model/init.py集合包含类型语义data_fieldtypesCurrency、Int、Long Int、Float、Percent、Check、Small Text、Long Text、Code、Text Editor、Markdown Editor、HTML Editor、Date、Datetime、Time、Text、Data、Link、Dynamic Link、Password、Select、Rating、Read Only、Attach、Attach Image、Signature、Color、Barcode、Geolocation、Duration、Icon、Phone、Autocomplete、JSON拥有实际数据库列的值型字段float_like_fieldsFloat、Currency、Percent精度与四舍五入逻辑适用的浮点型字段datetime_fieldsDatetime、Date、Time日期时间型字段no_value_fieldsSection Break、Column Break、Tab Break、Attachment Gallery、HTML、Table、Table MultiSelect、Button、Image、Fold、Heading无数据库列/无值的布局与展示型字段这套常量被 meta.py 的_valid_fields用于计算哪些 DocField 拥有数据库列——只有fieldtype in data_fieldtypes的字段才会被纳入表的合法列集合其余字段类型布局类与Table/Table MultiSelect子表由独立表承载则被排除。三、DocField 全部属性详解基于 docfield.json本节逐组讲解 docfield.json 中定义的全部字段并说明每个属性的适用字段类型、默认值及其在源码中的落地位置。JSON 中的depends_on表达式直接反映了属性与字段类型之间的耦合关系。3.1 标识与基础定义Label Type属性类型说明labelData字段在界面显示的标签长度上限 255列表视图中加粗显示fieldtypeSelect必填字段类型默认Data见上文完整枚举fieldnameData字段在代码与数据库中的内部名称蛇形命名必须唯一lengthInt列长度仅适用于 Data、Link、Dynamic Link、Password、Select、Read Only、Attach、Attach Image、Int、Float、Currency、Percent 等类型。schema 校验其取值须在 11000 之间frappe/database/schema.py未设置时回退到frappe.db.VARCHAR_LENreqdCheck必填默认0对 Section Break、Column Break、Button、HTML、Attachment Gallery 不可用is_virtualCheck虚拟字段不建数据库列默认0对 Link 与 Attachment Gallery 不可用search_indexCheck是否为该列建立索引默认0not_nullableCheck是否生成 NOT NULL 约束默认0对 Check、Currency、Float、Int、Percent、Rating、Select、Table、Table MultiSelect、Attachment Gallery 不可用maskCheck启用字段掩码按权限等级脱敏显示仅对 Select、Read Only、Phone、Percent、Password、Link、Int、Float、Dynamic Link、Duration、Datetime、Currency、Data、Date 可用在数据库同步层面frappe/database/schema.py 的get_columns_from_docfields将 DocField 映射为DbColumnfieldname→ 列名、fieldtype→ 数据库类型通过type_map、length→ 长度、default→ 默认值、search_index→ 是否加索引、options→ 部分数据库方言所需信息、unique→ 唯一约束、precision→ 精度、not_nullable→ NOT NULL 约束。is_virtual字段在此被直接跳过第 96-97 行因此不会产生任何 DDL。3.2 Options 与 Defaults值语义属性类型说明optionsSmall Text多语义属性Select 字段为候选项列表每行一个Link 字段为目标 DocTypeDynamic Link 字段为承载目标 DocType 名的字段Table 字段为子表 DocType。对 Attachment Gallery 不可用sort_optionsCheck仅 Select 字段可用开启后下拉选项按字母序排序defaultSmall Text字段默认值可写固定值或表达式fetch_fromSmall Text联动取值表达式形如link_field.source_field从被引用的 Link 文档中带出字段值fetch_if_emptyCheck若关闭保存时始终重新拉取若开启仅在字段为空时拉取见 docfield.json 的说明fetch_from在 meta.py 的get_fields_to_fetch中被集中解析框架会找出所有fetch_from以某个 Link 字段名开头的 DocField在保存时从被引用文档拉取并回填。3.3 可见性与布局Visibility Display属性类型说明hiddenCheck在表单中隐藏字段默认0show_on_timelineCheck仅当hidden开启时可用把隐藏字段的值显示到文档时间线boldCheck字段标签加粗allow_in_quick_entryCheck是否出现在快速录入Quick Entry表单默认0对 Tab Break、Table、Attachment Gallery 不可用translatableCheck是否参与 i18n 翻译仅对 Data、Select、Text、Small Text、Text Editor 可用print_hideCheck打印时不显示print_hide_if_no_valueCheck仅 Int、Float、Currency、Percent 可用值为空时不打印report_hideCheck报表中不显示in_import_templateCheck是否包含在数据导入模板中depends_onCode(JS)显示依赖表达式如eval:doc.status Submitted或doc.field valuecollapsibleCheck仅 Section Break 可用该节默认可折叠collapsible_depends_onCode(JS)仅当 Section Break 且 collapsible 时可用折叠状态的 JS 条件hide_borderCheck仅 Section Break 可用隐藏区块分隔边框hide_days/hide_secondsCheck仅 Duration 字段可用分别隐藏天与秒单位in_list_viewCheck在列表视图显示默认0in_standard_filterCheck作为标准过滤器出现在列表筛选栏in_previewCheck出现在列表预览卡片in_filterCheck可参与筛选in_global_searchCheck参与全局搜索仅对 Data、Select、Table、Text、Text Editor、Link、Small Text、Long Text、Read Only、Heading、Dynamic Link 可用stickyCheck列表/网格中该列吸顶固定对 Table、Table MultiSelect、Attachment Gallery 不可用columnsInt字段在 List View 或 Grid 中占用的列数总列数应小于 11列表视图的字段筛选在 meta.py 的get_list_fields中实现只有in_list_view 1且fieldtype in data_fieldtypes的字段才会进入列表查询列。全局搜索则由in_global_search驱动meta.py 处按该标记筛选字段。3.4 权限与数据保护Permissions Constraints属性类型说明read_onlyCheck表单中只读默认0allow_on_submitCheck已提交Submitted文档仍可编辑仅当所属 DocType 可提交或为子表时可用ignore_user_permissionsCheck仅 Link、Dynamic Link、Table MultiSelect 可用查询该字段的目标文档时忽略用户权限allow_bulk_editCheck仅 Table 字段可用允许批量编辑子表make_attachment_publicCheck仅 Attach、Attach Image、Attachment Gallery 可用上传的附件默认公开permlevelInt字段权限等级0 为默认可配合 DocPerm 做分级的字段级权限控制对 Section Break、Column Break、Tab Break 不可用ignore_xss_filterCheck跳过对script、、等 HTML 字符的转义字段内容可能有意包含标记时开启uniqueCheck字段值唯一约束默认0no_copyCheck使用另存为/复制时该字段值不复制set_only_onceCheck仅在创建未保存前时可设置一次之后只读remember_last_selected_valueCheck仅 Link 字段可用记住用户上次选择的值作为默认ignore_versioningCheck不参与版本跟踪Version仅当 DocType 开启track_changes或是子表时可用且虚拟字段除外mandatory_depends_onCode(JS)动态必填的 JS 条件表达式read_only_depends_onCode(JS)动态只读的 JS 条件表达式permlevel与mask的协作在 meta.py 的get_masked_fields中体现框架会检查当前用户的mask权限等级访问集合未获得对应permlevel访问权的掩码字段会被深度复制并标记mask_readonly从而以只读方式展示。3.5 展示样式与扩展信息Display Extras属性类型说明alignmentSelect文本对齐Left / Center / Right仅 Data、Int、Float、Currency、Percent 可用print_widthData打印时的宽度widthData表单/网格中的列宽度max_heightData内容最大高度如 Code/Text 类字段的滚动高度descriptionSmall Text表单中的帮助说明文字documentation_urlURL字段的在线文档链接对 Tab Break、Section Break、Column Break、Button、HTML、Attachment Gallery 不可用placeholderData输入框占位文本show_description_on_clickCheck点击后才展开显示描述button_colorSelect仅 Button 字段取 Default / Primary / Info / Success / Warning / Dangershow_dashboardCheck仅 Tab Break 字段在 Dashboard 中展示该 Tablink_filtersJSON仅 Attachment Gallery 与 Link 字段对 Link 查询与附件库文件应用过滤条件non_negative/min_value/max_valueCheck / Float / Float仅 Int、Float、Currency、Percent 可用限制数值范围非负、最小值、最大值precisionSelect仅 Float、Currency、Percent 可用自定义小数位09为空则使用默认精度四、从 DocField 到数据库模型同步链路DocField 是 Frappebench migrate/ 自动表同步的输入源头整条链路可概括为DocFieldfields 数组 → Meta.get_fieldnames_with_value() # meta.py筛选拥有值的字段 → Table.get_columns_from_docfields() # database/schema.py映射为 DbColumn → DbColumn / Column 定义 # 生成 CREATE TABLE / ALTER TABLE DDL → 数据库执行索引、唯一、NOT NULL、精度、默认值关键落点有三处meta.py_valid_fields决定一个字段是否有数据库列——仅data_fieldtypes中的类型进入列表布局类与Table类被排除。database/schema.pyget_columns_from_docfields把每个非虚拟字段转成DbColumn其中fieldtype决定数据库列类型由各数据库驱动的type_map映射length、precision、unique、not_nullable、search_index、default分别对应列定义中的长度、精度、唯一约束、NOT NULL、索引与默认值is_virtual字段被显式跳过。长度校验database/schema.py字段名fieldname不得超过 64 字符VARCHAR 列长度必须在 11000 之间未设置时使用frappe.db.VARCHAR_LEN默认值。这也是为什么在 Doctype 表单里勾选search_indexIndex、uniqueUnique、not_nullableNot Nullable后运行迁移即可看到对应索引/约束生效——它们最终都会进入DbColumn并转成 DDL。五、DocField 与其他元数据机制的协作5.1 DocField 与 Custom Field、Property Setter自定义字段Custom Field本质上是外挂到现有 DocType 上的 DocField 记录因此 custom_field.py 会复用supports_translation等 DocField 校验逻辑。Property Setter 则用于覆盖单个 DocField 的属性如宽度、只读在 meta.py 的apply_property_setters()中被应用。5.2 翻译与 DocField 属性frappe/model/docfield.py 定义了唯一的工具函数def supports_translation(fieldtype): return fieldtype in [Data, Select, Text, Small Text, Text Editor]它被三处复用保证不可翻译的字段永远不会被标记为可翻译doctype.py 的set_default_translatable()DocType 保存时把translatable1但不支持翻译的字段强制归零custom_field.py自定义字段创建时同样的校验customize_form.py表单定制器中修改translatable属性时的校验。这解释了为什么translatable复选框在界面上仅对 Data、Select、Text、Small Text、Text Editor 五类字段开放见 docfield.json 的depends_on。5.3 索引与 Dashboard 联动doctype.py 的check_indexing_for_dashboard_links展示了search_index的隐性影响若某个 Link 字段被用作其他 DocType 的 Dashboard 连接引用且未设置unique也未勾选search_index框架会提示开发者为其建立索引以保证 Dashboard 连接的查询性能。六、实操建议设计一个 DocField 的检查清单先定fieldtype值型字段进数据库还是布局型字段不建列需要子表用Table/Table MultiSelect。命名fieldname蛇形小写、全库唯一、≤ 64 字符否则迁移报错见 database/schema.py。按需配置列属性lengthVARCHAR 11000、precision小数位、unique、not_nullable、search_index。设定值语义default、optionsSelect 候选项 / Link 目标 / Table 子表、fetch_from联动、fetch_if_empty。配置表单交互reqd、read_only、hidden、depends_on、mandatory_depends_on、read_only_depends_on、collapsible。配置列表/搜索可见性in_list_view、in_standard_filter、in_preview、in_global_search、columns、sticky。配置权限与安全permlevel、ignore_user_permissions、ignore_xss_filter、allow_on_submit、set_only_once、no_copy。打印与导入print_hide、print_hide_if_no_value、print_width、in_import_template。按上述顺序在 Doctype 表单的对应分组Label Type、Options、Defaults、Visibility、Permissions、Constraints、Display、List / Search Settings中逐项勾选即可得到一个数据库模型正确、视图行为符合预期的字段定义随后运行bench migrate即可将 DocField 定义同步为真实的表结构。【免费下载链接】frappeLow code web framework for real world applications, in Python and Javascript项目地址: https://gitcode.com/GitHub_Trending/fr/frappe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Frappe DocField 详解：DocType 字段的模型与视图双重元数据
Frappe DocField 详解DocType 字段的模型与视图双重元数据【免费下载链接】frappeLow code web framework for real world applications, in Python and Javascript项目地址: https://gitcode.com/GitHub_Trending/fr/frappeDocField 是 Frappe 低代码框架中描述一个 DocType 字段的元数据 Doctype它与数据库表列column一一对应或仅作为布局/展示节点存在同时承载字段的数据模型语义类型、长度、索引、默认值、校验约束与视图渲染语义标签、占位符、显隐、只读、折叠、布局断点。本文以 DocField 官方 README 为骨架结合 docfield.json 中 60 余个字段定义与 meta.py、schema.py 等源码系统讲解 DocField 的核心概念、字段类型体系、全部配置属性及其在模型同步、表单渲染、列表/搜索与权限体系中的落地方式。读完本文你将能在自定义 Doctype 中精确设计字段、理解字段属性对数据库 DDL 的影响并掌握 DocField 与 Custom Field、Property Setter 之间的协作关系。一、DocField 是什么一张表两种职责官方 README 用一句话给出了 DocField 的定义Represents a field of a DocType analogous to a table column in the database. DocFields represent the properties both the model and the view and hence may or may not have database columns associated (for example, Section Break does not have any column associated.)这段话包含三个关键信息模型视角DocField 之于 DocType如同数据库列之于数据库表。DocType 的 JSON 文件如 docfield.json 中的fields数组里每一个元素在运行时就是一个DocField记录。视图视角DocField 同时描述字段在表单Form、列表List、报表Report、打印Print中的呈现方式包括标签、宽度、显隐、布局断点等。列的有无并不必须布局型字段Section Break、Column Break、Tab Break、HTML、Button、Image、Fold、Heading、Attachment Gallery不产生数据库列。这一点在 frappe/model/init.py 中被固化为一组no_value_fields常量凡属于该集合的字段类型都被视为无值字段不会进入_valid_fields与列同步流程。1.1 DocField 自身也是一个 DocTypeDocField 本身是一个istable: 1的 DocType见 docfield.json即一个子表Child Table它作为 DocType 的fields子表被内嵌引用。因此你无法独立创建一条 DocField 记录它总是依附于某个 DocType 或 Custom Field 存在。DocField 没有显式权限记录permissions: []其访问完全由所属 DocType 的权限系统代理。1.2 从文件加载的引导过程由于 DocField 是框架自举bootstrap所用的特殊 Doctype之一当数据库里不存在它时meta.py 的load_doctype_from_file会直接从磁盘 JSON 加载读取frappe/core/doctype/docfield/docfield.json将fields数组中每个元素标注doctype DocFieldmeta.py把每个元素包装成BaseDocument保证后续所有字段属性都能以对象属性方式访问如df.fieldname、df.fieldtype。Meta.special_doctypesmeta.py将DocField与DocPerm、DocType等一并列为特殊类型process()对这些类型跳过自定义字段注入与属性覆盖流程避免循环依赖。二、字段类型体系从 Select 选项到 Python 常量DocField 的fieldtype是一个必填的 Select 字段其可选项完整枚举了 Frappe 支持的全部字段类型见 docfield.jsonAutocomplete, Attach, Attach Image, Attachment Gallery, Barcode, Button, Check, Code, Color, Column Break, Currency, Data, Date, Datetime, Duration, Dynamic Link, Float, Fold, Geolocation, Heading, HTML, HTML Editor, Icon, Image, Int, JSON, Link, Long Text, Markdown Editor, Password, Percent, Phone, Read Only, Rating, Section Break, Select, Signature, Small Text, Tab Break, Table, Table MultiSelect, Text, Text Editor, Time在 Python 侧这些类型被组织为几组语义集合frappe/model/init.py集合包含类型语义data_fieldtypesCurrency、Int、Long Int、Float、Percent、Check、Small Text、Long Text、Code、Text Editor、Markdown Editor、HTML Editor、Date、Datetime、Time、Text、Data、Link、Dynamic Link、Password、Select、Rating、Read Only、Attach、Attach Image、Signature、Color、Barcode、Geolocation、Duration、Icon、Phone、Autocomplete、JSON拥有实际数据库列的值型字段float_like_fieldsFloat、Currency、Percent精度与四舍五入逻辑适用的浮点型字段datetime_fieldsDatetime、Date、Time日期时间型字段no_value_fieldsSection Break、Column Break、Tab Break、Attachment Gallery、HTML、Table、Table MultiSelect、Button、Image、Fold、Heading无数据库列/无值的布局与展示型字段这套常量被 meta.py 的_valid_fields用于计算哪些 DocField 拥有数据库列——只有fieldtype in data_fieldtypes的字段才会被纳入表的合法列集合其余字段类型布局类与Table/Table MultiSelect子表由独立表承载则被排除。三、DocField 全部属性详解基于 docfield.json本节逐组讲解 docfield.json 中定义的全部字段并说明每个属性的适用字段类型、默认值及其在源码中的落地位置。JSON 中的depends_on表达式直接反映了属性与字段类型之间的耦合关系。3.1 标识与基础定义Label Type属性类型说明labelData字段在界面显示的标签长度上限 255列表视图中加粗显示fieldtypeSelect必填字段类型默认Data见上文完整枚举fieldnameData字段在代码与数据库中的内部名称蛇形命名必须唯一lengthInt列长度仅适用于 Data、Link、Dynamic Link、Password、Select、Read Only、Attach、Attach Image、Int、Float、Currency、Percent 等类型。schema 校验其取值须在 11000 之间frappe/database/schema.py未设置时回退到frappe.db.VARCHAR_LENreqdCheck必填默认0对 Section Break、Column Break、Button、HTML、Attachment Gallery 不可用is_virtualCheck虚拟字段不建数据库列默认0对 Link 与 Attachment Gallery 不可用search_indexCheck是否为该列建立索引默认0not_nullableCheck是否生成 NOT NULL 约束默认0对 Check、Currency、Float、Int、Percent、Rating、Select、Table、Table MultiSelect、Attachment Gallery 不可用maskCheck启用字段掩码按权限等级脱敏显示仅对 Select、Read Only、Phone、Percent、Password、Link、Int、Float、Dynamic Link、Duration、Datetime、Currency、Data、Date 可用在数据库同步层面frappe/database/schema.py 的get_columns_from_docfields将 DocField 映射为DbColumnfieldname→ 列名、fieldtype→ 数据库类型通过type_map、length→ 长度、default→ 默认值、search_index→ 是否加索引、options→ 部分数据库方言所需信息、unique→ 唯一约束、precision→ 精度、not_nullable→ NOT NULL 约束。is_virtual字段在此被直接跳过第 96-97 行因此不会产生任何 DDL。3.2 Options 与 Defaults值语义属性类型说明optionsSmall Text多语义属性Select 字段为候选项列表每行一个Link 字段为目标 DocTypeDynamic Link 字段为承载目标 DocType 名的字段Table 字段为子表 DocType。对 Attachment Gallery 不可用sort_optionsCheck仅 Select 字段可用开启后下拉选项按字母序排序defaultSmall Text字段默认值可写固定值或表达式fetch_fromSmall Text联动取值表达式形如link_field.source_field从被引用的 Link 文档中带出字段值fetch_if_emptyCheck若关闭保存时始终重新拉取若开启仅在字段为空时拉取见 docfield.json 的说明fetch_from在 meta.py 的get_fields_to_fetch中被集中解析框架会找出所有fetch_from以某个 Link 字段名开头的 DocField在保存时从被引用文档拉取并回填。3.3 可见性与布局Visibility Display属性类型说明hiddenCheck在表单中隐藏字段默认0show_on_timelineCheck仅当hidden开启时可用把隐藏字段的值显示到文档时间线boldCheck字段标签加粗allow_in_quick_entryCheck是否出现在快速录入Quick Entry表单默认0对 Tab Break、Table、Attachment Gallery 不可用translatableCheck是否参与 i18n 翻译仅对 Data、Select、Text、Small Text、Text Editor 可用print_hideCheck打印时不显示print_hide_if_no_valueCheck仅 Int、Float、Currency、Percent 可用值为空时不打印report_hideCheck报表中不显示in_import_templateCheck是否包含在数据导入模板中depends_onCode(JS)显示依赖表达式如eval:doc.status Submitted或doc.field valuecollapsibleCheck仅 Section Break 可用该节默认可折叠collapsible_depends_onCode(JS)仅当 Section Break 且 collapsible 时可用折叠状态的 JS 条件hide_borderCheck仅 Section Break 可用隐藏区块分隔边框hide_days/hide_secondsCheck仅 Duration 字段可用分别隐藏天与秒单位in_list_viewCheck在列表视图显示默认0in_standard_filterCheck作为标准过滤器出现在列表筛选栏in_previewCheck出现在列表预览卡片in_filterCheck可参与筛选in_global_searchCheck参与全局搜索仅对 Data、Select、Table、Text、Text Editor、Link、Small Text、Long Text、Read Only、Heading、Dynamic Link 可用stickyCheck列表/网格中该列吸顶固定对 Table、Table MultiSelect、Attachment Gallery 不可用columnsInt字段在 List View 或 Grid 中占用的列数总列数应小于 11列表视图的字段筛选在 meta.py 的get_list_fields中实现只有in_list_view 1且fieldtype in data_fieldtypes的字段才会进入列表查询列。全局搜索则由in_global_search驱动meta.py 处按该标记筛选字段。3.4 权限与数据保护Permissions Constraints属性类型说明read_onlyCheck表单中只读默认0allow_on_submitCheck已提交Submitted文档仍可编辑仅当所属 DocType 可提交或为子表时可用ignore_user_permissionsCheck仅 Link、Dynamic Link、Table MultiSelect 可用查询该字段的目标文档时忽略用户权限allow_bulk_editCheck仅 Table 字段可用允许批量编辑子表make_attachment_publicCheck仅 Attach、Attach Image、Attachment Gallery 可用上传的附件默认公开permlevelInt字段权限等级0 为默认可配合 DocPerm 做分级的字段级权限控制对 Section Break、Column Break、Tab Break 不可用ignore_xss_filterCheck跳过对script、、等 HTML 字符的转义字段内容可能有意包含标记时开启uniqueCheck字段值唯一约束默认0no_copyCheck使用另存为/复制时该字段值不复制set_only_onceCheck仅在创建未保存前时可设置一次之后只读remember_last_selected_valueCheck仅 Link 字段可用记住用户上次选择的值作为默认ignore_versioningCheck不参与版本跟踪Version仅当 DocType 开启track_changes或是子表时可用且虚拟字段除外mandatory_depends_onCode(JS)动态必填的 JS 条件表达式read_only_depends_onCode(JS)动态只读的 JS 条件表达式permlevel与mask的协作在 meta.py 的get_masked_fields中体现框架会检查当前用户的mask权限等级访问集合未获得对应permlevel访问权的掩码字段会被深度复制并标记mask_readonly从而以只读方式展示。3.5 展示样式与扩展信息Display Extras属性类型说明alignmentSelect文本对齐Left / Center / Right仅 Data、Int、Float、Currency、Percent 可用print_widthData打印时的宽度widthData表单/网格中的列宽度max_heightData内容最大高度如 Code/Text 类字段的滚动高度descriptionSmall Text表单中的帮助说明文字documentation_urlURL字段的在线文档链接对 Tab Break、Section Break、Column Break、Button、HTML、Attachment Gallery 不可用placeholderData输入框占位文本show_description_on_clickCheck点击后才展开显示描述button_colorSelect仅 Button 字段取 Default / Primary / Info / Success / Warning / Dangershow_dashboardCheck仅 Tab Break 字段在 Dashboard 中展示该 Tablink_filtersJSON仅 Attachment Gallery 与 Link 字段对 Link 查询与附件库文件应用过滤条件non_negative/min_value/max_valueCheck / Float / Float仅 Int、Float、Currency、Percent 可用限制数值范围非负、最小值、最大值precisionSelect仅 Float、Currency、Percent 可用自定义小数位09为空则使用默认精度四、从 DocField 到数据库模型同步链路DocField 是 Frappebench migrate/ 自动表同步的输入源头整条链路可概括为DocFieldfields 数组 → Meta.get_fieldnames_with_value() # meta.py筛选拥有值的字段 → Table.get_columns_from_docfields() # database/schema.py映射为 DbColumn → DbColumn / Column 定义 # 生成 CREATE TABLE / ALTER TABLE DDL → 数据库执行索引、唯一、NOT NULL、精度、默认值关键落点有三处meta.py_valid_fields决定一个字段是否有数据库列——仅data_fieldtypes中的类型进入列表布局类与Table类被排除。database/schema.pyget_columns_from_docfields把每个非虚拟字段转成DbColumn其中fieldtype决定数据库列类型由各数据库驱动的type_map映射length、precision、unique、not_nullable、search_index、default分别对应列定义中的长度、精度、唯一约束、NOT NULL、索引与默认值is_virtual字段被显式跳过。长度校验database/schema.py字段名fieldname不得超过 64 字符VARCHAR 列长度必须在 11000 之间未设置时使用frappe.db.VARCHAR_LEN默认值。这也是为什么在 Doctype 表单里勾选search_indexIndex、uniqueUnique、not_nullableNot Nullable后运行迁移即可看到对应索引/约束生效——它们最终都会进入DbColumn并转成 DDL。五、DocField 与其他元数据机制的协作5.1 DocField 与 Custom Field、Property Setter自定义字段Custom Field本质上是外挂到现有 DocType 上的 DocField 记录因此 custom_field.py 会复用supports_translation等 DocField 校验逻辑。Property Setter 则用于覆盖单个 DocField 的属性如宽度、只读在 meta.py 的apply_property_setters()中被应用。5.2 翻译与 DocField 属性frappe/model/docfield.py 定义了唯一的工具函数def supports_translation(fieldtype): return fieldtype in [Data, Select, Text, Small Text, Text Editor]它被三处复用保证不可翻译的字段永远不会被标记为可翻译doctype.py 的set_default_translatable()DocType 保存时把translatable1但不支持翻译的字段强制归零custom_field.py自定义字段创建时同样的校验customize_form.py表单定制器中修改translatable属性时的校验。这解释了为什么translatable复选框在界面上仅对 Data、Select、Text、Small Text、Text Editor 五类字段开放见 docfield.json 的depends_on。5.3 索引与 Dashboard 联动doctype.py 的check_indexing_for_dashboard_links展示了search_index的隐性影响若某个 Link 字段被用作其他 DocType 的 Dashboard 连接引用且未设置unique也未勾选search_index框架会提示开发者为其建立索引以保证 Dashboard 连接的查询性能。六、实操建议设计一个 DocField 的检查清单先定fieldtype值型字段进数据库还是布局型字段不建列需要子表用Table/Table MultiSelect。命名fieldname蛇形小写、全库唯一、≤ 64 字符否则迁移报错见 database/schema.py。按需配置列属性lengthVARCHAR 11000、precision小数位、unique、not_nullable、search_index。设定值语义default、optionsSelect 候选项 / Link 目标 / Table 子表、fetch_from联动、fetch_if_empty。配置表单交互reqd、read_only、hidden、depends_on、mandatory_depends_on、read_only_depends_on、collapsible。配置列表/搜索可见性in_list_view、in_standard_filter、in_preview、in_global_search、columns、sticky。配置权限与安全permlevel、ignore_user_permissions、ignore_xss_filter、allow_on_submit、set_only_once、no_copy。打印与导入print_hide、print_hide_if_no_value、print_width、in_import_template。按上述顺序在 Doctype 表单的对应分组Label Type、Options、Defaults、Visibility、Permissions、Constraints、Display、List / Search Settings中逐项勾选即可得到一个数据库模型正确、视图行为符合预期的字段定义随后运行bench migrate即可将 DocField 定义同步为真实的表结构。【免费下载链接】frappeLow code web framework for real world applications, in Python and Javascript项目地址: https://gitcode.com/GitHub_Trending/fr/frappe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考