NocoBase 字段数据范围Data Scope配置指南关联字段筛选、变量联动与源码原理【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase在 NocoBase 的无代码界面搭建中关系字段关联字段的可选项默认来自目标表全量数据。字段数据范围Data Scope为关系字段设定默认筛选条件只展示符合条件的关联数据可用于限定数据录入范围、按权限过滤可选数据以及通过变量实现字段与字段之间的动态联动。本文基于官方文档《设置数据范围》展开并结合仓库源码讲解配置方式、变量用法、联动机制与底层解析原理读完即可在表单、详情、表格等区块中落地关系字段的精确筛选。数据范围是什么数据范围Data Scope是一组筛选条件filter用于限制某个数据源中可被选择或可被展示的数据。NocoBase 中数据范围有两种典型应用场景区块的数据范围限制区块展示哪些数据例如「表格区块只显示未删除的商品」字段的数据范围限制关系字段可选的数据例如「商品字段只允许选择未删除的商品」。字段的数据范围设置与区块的数据范围设置在交互与配置方式上保持一致区别在于作用对象。字段数据范围配置后最终会写入该字段组件对应的请求参数service.params.filter中作为关联数据下拉列表的查询条件。在界面搭建Schema 设计模式下点击表单区块中的关系字段在字段设置面板中找到「设置数据范围」Set the data scope入口即可打开配置弹窗。该弹窗由SchemaSettingsDataScope组件实现源码位置内部基于Filter组件与VariableInput变量输入组件构建左侧是目标表字段列表useCollectionFilterOptionsV2动态获取右侧填写条件值与比较运算符条件值既可以写死静态值也可以选择变量动态值。字段数据范围本质上与区块数据范围共用同一套 Filter 配置 UI 与变量解析能力因此掌握区块数据范围后可以无缝迁移到字段上。使用说明打开与配置数据范围进入配置界面后可配置任意条件组合在区块如表单、详情、表格中选择一个关系字段打开字段设置找到「数据范围」/「设置数据范围」菜单在弹窗中选择目标表字段、运算符与值保存即可。弹窗中的字段列表为关系字段目标表的字段而非当前表字段。例如在「订单」表的「商品」多对一关系字段上配置数据范围可选字段来自「商品」表如deleted、price、serviceDate等。保存后的筛选条件最终以filter参数写入关联字段的服务请求。以关联选择组件为例源码中将数据范围回写到组件参数// packages/core/client/src/schema-component/antd/association-select/AssociationSelect.tsx SchemaSettingsDataScope collectionName{field.target} defaultFilter{field.componentProps?.service?.params?.filter || {}} onSubmit{({ filter }) { // 更新字段的 service.params.filter驱动关联数据重新请求 }} /其中collectionName指向关系字段的目标表defaultFilter为当前已保存的筛选条件onSubmit负责把新条件写回字段配置。静态值固定筛选条件静态值指条件中的比较值直接写死不随页面状态变化。适合表达「永远成立」的业务约束。示例仅在未删除的商品可以选择关联。配置步骤在订单表单中选中「商品」关系字段打开「设置数据范围」选择目标表字段deleted条件选择「等于」/「不等于」值填写静态值false或0取决于字段类型即可。对应生成的条件结构等价于{ $and: [ { deleted: { $eq: false } } ] }这类条件不依赖任何上下文无论在新增、编辑还是详情场景都会生效。变量值动态筛选条件变量值指条件的比较值来自某个变量运行时由系统解析为实际值。相比静态值变量值让数据范围随当前上下文动态变化是实现「按当前用户」「按当前表单值」「按当前记录」等场景的关键手段。示例仅商品服务日期晚于订单日期的商品可以选择关联。配置步骤在订单表单的「商品」字段数据范围中选择目标表字段serviceDate运算符选择「晚于」/「大于」值通过变量输入框选择「当前表单」→orderDate。此时筛选条件写入形如{{$nForm.orderDate}}的变量占位符运行时被解析为表单中订单日期的实际值。NocoBase 已支持的变量详见变量文档变量含义典型场景当前用户当前登录用户的数据数据范围按创建人/负责人过滤当前角色当前登录用户的角色标识role name按角色范围过滤可选数据当前表单当前表单的值仅表单区块可用关系字段数据范围、字段默认值、联动规则当前记录数据表中的当前行记录行操作的联动规则当前弹窗记录弹窗中当前行/关系记录弹窗内区块与字段的数据范围URL 查询参数页面 URL 中的查询参数配合链接操作传参筛选API token访问 NocoBase API 的凭证字符串身份校验相关场景当前设备类型当前访问设备类型按设备显隐操作其中「当前表单」变量与字段数据范围关系最密切。变量文档中明确列出其使用场景之一即「关系字段的数据范围设置」根据上游字段动态筛选下游字段的可选项确保数据录入准确参考 变量文档。说明变量只有在对应上下文存在时才可用例如「当前表单」仅在表单区块中可选「URL 查询参数」仅在页面 URL 存在查询字符串时可用。关系字段联动数据范围驱动的级联筛选关系字段之间可以通过设置数据范围实现联动——这是字段数据范围最典型的实战用法。示例订单表中有「商机产品」一对多关系字段与「商机」多对一关系字段「商机产品」目标表「商机产品」又有多对一关系字段「商机」。需求是在订单表单中「商机产品」字段的可选数据只能是当前表单所选「商机」所关联的商机产品。配置核心在「商机产品」字段的「设置数据范围」中选择目标表字段商机多对一关系字段条件选择「等于」值选择变量「当前表单」→商机表单中已选择的商机字段。这样当表单中「商机」变化时「商机产品」下拉列表会实时刷新为所选商机的关联产品实现多级联动级联筛选。该场景在 e2e 测试中有完整复现测试模板定义了三张表school、class、student其中student.class字段的数据范围被配置为{ filter: { $and: [ { school: { id: { $eq: {{$nForm.school.id}} } } } ] } }即「班级」字段的可选项 当前表单所选「学校」下的班级测试模板源码。对应 e2e 测试验证了两点测试用例联动前未选择学校时请求api/class:list的filter参数为{ $and: [{ school: { id: { $eq: null } } }] }即无可选班级选择学校后选择学校 id1 后再次请求filter变为{ $and: [{ school: { id: { $eq: 1 } } }] }下拉列表只展示该学校下的班级。同样测试还覆盖了多级关联字段取值字段 b 的数据范围引用{{$nForm.a.b.id}}即「当前表单字段 a 所关联对象 b 的 id」当 a 的选择变化时b 的可选项随之变化测试用例。这说明数据范围的变量值可以穿透多级关系链如a.b.id实现更深层的级联过滤。变量解析与联动原理字段数据范围之所以能实现「表单字段变化 → 下拉数据刷新」的实时联动依赖客户端对筛选条件中变量的持续监听与重解析。核心逻辑位于useParsedFilter源码解析变量调用useParseDataScopeFilter提供的parseFilter把{{$nForm.school.id}}等占位符解析为当前上下文中的实际值收集依赖通过reaction来自formily/reactive对筛选条件做扁平化遍历遇到变量时读取变量上下文ctx对应路径的值从而把「当前表单.school」等作为响应式依赖注册变化重算一旦依赖的变量值变化reaction触发防抖后的重新解析DEBOUNCE_WAIT防抖得到新 filter 并通过onFilterChange通知组件组件随即携带新filter重新请求关联数据。变量解析本身由useParseDataScopeFilter完成源码它对 filter 做flatten/unflatten处理通过variables.parseVariable将变量占位符替换为实际值值为undefined的解析结果会被剔除对应「未选择学校时$eq: null」的表现并默认排除$user、$date、$nDate、$nRole等系统变量不解析、按原值返回。整个数据流可以概括为配置数据范围filter 变量占位符 ↓ useParsedFilter 监听变量依赖 ↓ 变量变化 → reaction 触发 → parseFilter 重解析 ↓ 新 filter 写入关联字段 service.params ↓ 关联数据重新请求如 api/class:list?filter... ↓ 下拉列表展示过滤后的可选项数据范围中的值约束在数据范围弹窗中值的可选字段受当前字段类型约束。SchemaSettingsDataScope中的isDisabled函数源码定义了以下规则json类型字段允许设置任意类型的值对多/对一的关系字段始终可选option.target存在即可选input、markdown、richText、textarea、username等输入类字段值必须为string或number类型其余情况值的字段interface必须与当前字段interface一致且组件类型x-component必须相同。这些约束保证了配置出的条件在类型上自洽避免「日期字段与文本值比较」这类运行时错误。小结字段数据范围是 NocoBase 关系字段配置中实现「精确可选数据」的标准化手段核心要点如下入口字段设置 → 设置数据范围Set the data scope字段列表为关系字段目标表字段静态值固定条件适合恒定业务约束如排除已删除数据变量值动态条件可引用当前用户、当前表单、当前记录、URL 查询参数等变量完整变量清单见变量文档关系字段联动通过「当前表单」变量引用上游关系字段实现级联筛选变量值支持多级关联链如a.b.id底层机制useParsedFilterreaction监听变量依赖并自动重解析联动过程无需刷新页面。配置时注意区分静态值与变量值的使用边界跨页面、跨用户、随表单变化的场景一律使用变量值而业务上恒定不变的条件如软删除标记使用静态值即可语义更清晰、也便于后期维护。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考