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导读数据范围Data Scope是 NocoBase 界面搭建中为数据区块与关系字段定义默认筛选条件的核心能力无论用户后续在界面上进行何种筛选、排序或分页操作系统都会自动叠加这组默认条件保证数据始终处于你限定的视野之内。本文以官方文档《设置数据范围》为主体结合 NocoBase 源码中数据范围设置项、变量解析与操作符机制的实现细节系统讲解如何配置静态筛选、基于变量的动态筛选以及关系字段之间的数据范围联动帮助你在不写代码的前提下完成行级数据隔离与字段级可选数据收敛。一、什么是数据范围设置数据范围是指为数据区块定义一组默认筛选条件。它的核心行为特征是用户可根据业务需求在界面上灵活调整数据范围如使用筛选操作但无论进行何种筛选操作系统都会自动应用该默认筛选条件因此区块展示的数据始终被限定在指定范围内适合用于权限隔离、数据分区、按人/按组织过滤等场景。从实现上看这组条件本质上是挂载在区块 schema 的x-decorator-props.params.filter上的一组过滤表达式由数据范围设置项在提交时写入。参见 setTheDataScopeSchemaSettingsItem.tsx其中onDataScopeSubmit会执行field.decoratorProps.params { ...params, filter }并通过dn.emit(patch, ...)将 schema 变更持久化同时把列表服务拉回第一页service.params[0].page 1。二、使用手册如何配置区块的数据范围配置入口位于数据区块表格、列表、详情、看板、日历、甘特图等的区块设置中操作路径为区块右上角「配置区块」→「设置数据范围」打开配置弹窗后即可像使用普通筛选器一样添加条件每个条件由「字段 操作符 值」三部分组成。数据范围条件中的字段来源有两类本表字段当前数据区块所属数据表的全部字段关系表字段通过一对一、一对多、多对一、多对多等关系字段可以进入关联目标表选择字段实现跨表过滤例如按「客户.等级」筛选订单。在源码 SchemaSettingsDataScope.tsx 中可以看到字段选项通过useCollectionFilterOptionsV2(props.collectionName)生成渲染使用Filter组件x-component: Filter值输入区使用支持变量注入的VariableInput从而同时支持静态值与变量值两种模式。三、操作符不同字段类型对应不同过滤语义不同类型的字段支持不同的操作符这是由字段的「接口interface」声明决定的文本类字段单行文本、多行文本、富文本、Markdown 等支持等于、不等于、包含、不包含、为空、不为空等数字类字段支持大于、小于、大于等于、小于等于、等于、不等于、在两者之间等日期类字段支持在范围内、在特定日期之前、在特定日期之后、等于某个日期等布尔/开关字段支持是/否关系字段支持存在有关系记录、不存在等关联语义操作符。这一机制的底层实现位于 useOperators.tsuseOperatorList会读取当前字段的interface并通过getInterface(fieldInterface).filterable.operators取回该类型字段允许的操作符列表当条件选择的是关系表字段时则按目标表对应字段的接口类型取操作符。因此操作符列表是「按字段类型动态收敛」的你只能在界面中看到当前字段真正支持的操作符。四、静态值筛选固定条件下拉数据静态值模式适用于条件取值在配置时就已确定的场景配置后对所有用户、所有时刻恒定生效。示例根据订单「状态」字段筛选数据。在数据范围弹窗中点击「添加条件」字段选择本表的「状态」操作符选择「等于」或「包含」等值选择具体的状态选项例如「已付款」保存后该区块将只展示状态为「已付款」的订单。静态值既可以是下拉选项、手动输入的具体值也可以来自字段类型所允许的任意合法取值json 字段在源码中允许设置任意类型的值见SchemaSettingsDataScope.tsx中的isDisabled判断。五、变量值筛选基于运行上下文动态过滤变量值模式使用系统提供的「变量」作为条件取值变量会在数据请求发出时被实时解析为当前上下文中的具体值因此同一份配置可以适配不同用户、不同页面状态。示例筛选当前用户的订单数据。在数据范围弹窗中添加条件字段选择本表的「客户」或「所属用户」等关系字段操作符选择「等于」值切换为变量模式选择「当前用户」变量保存后每个登录用户在该区块看到的都只是自己的订单数据。变量解析的源码实现在 useParseDataScopeFilter.ts它通过flatten将嵌套的过滤表达式拍平对以$开头的变量键如$user、$date、$nRole默认排除列表见defaultExclude调用variables.parseVariable异步求值再unflatten还原为完整的过滤条件对象。这意味着数据范围条件中的变量是在查询前被真正求值的而不是把变量字符串原样发给后端。六、变量体系数据范围可用的上下文标记数据范围条件中可用的变量由 变量 文档统一说明常见的有以下几类变量含义典型数据范围场景当前用户当前登录用户记录只显示「我」的数据、按用户归属过滤当前角色当前登录用户的角色标识role name按角色范围过滤数据当前表单当前表单区块中的值仅表单区块可用关系字段数据范围随表单字段值动态变化当前记录数据表中当前行记录行操作联动、详情区块范围当前弹窗记录当前弹窗所对应的记录行操作弹窗、关系字段弹窗弹窗内区块只显示与弹窗记录相关的数据URL 查询参数当前页面 URL 中的查询字符串配合链接操作实现跨页面传参过滤API token访问 NocoBase API 的凭证字符串身份相关校验场景当前设备类型当前访问设备类型如电脑端/移动端按设备维度控制数据展示其中与数据范围强相关的组合玩法当前表单 关系字段数据范围用户先选择表单中的上游字段如 Owner关系字段如 Account的可选项随即被系统按所选 Owner 的 userName 自动过滤确保数据录入准确当前弹窗记录 区块数据范围弹窗操作是 NocoBase 界面配置的核心交互行操作的弹窗与关系字段的弹窗都会提供「当前弹窗记录」变量弹窗内的所有区块都可基于它收敛数据范围。七、关系字段的数据范围从「看什么」到「能选什么」除了区块级数据范围关系字段本身也支持设置数据范围用于限制该字段在表单/详情中的可选数据完整说明见 字段数据范围。配置方式与区块数据范围类似区别在于条件字段列表为关系字段目标表Target Collection的字段生效位置在字段选择器下拉、弹窗选择等中。静态值示例仅在未删除的商品中允许选择关联可配置条件「删除标记 等于 false」。变量值示例仅商品服务日期晚于订单日期的商品可以选择关联可在值中使用日期变量或表单中的日期字段。关系字段联动示例这是 NocoBase 表单中最常用的动态下拉方案订单表中有「商机产品」一对多与「商机」多对一两个关系字段商机产品表本身也有「商机」多对一关系字段。在订单表单区块中为「商机产品」字段设置数据范围商机产品.商机 等于 当前表单.商机。这样用户选定商机后「商机产品」的可选项就只包含该商机关联的商机产品实现两级下拉联动。八、数据范围与筛选操作条件合并而非覆盖需要特别注意的是当区块同时配置了数据范围与筛选操作时二者不会互相覆盖而是合并为最终的过滤条件——数据范围是默认条件、始终生效用户通过筛选面板追加的条件在此基础上叠加。官方文档明确说明「如果区块已经配置了数据范围筛选操作将与数据范围的条件合并作为最终过滤条件」。这一设计意味着数据范围适合承载「必须满足」的硬性约束如权限边界、租户隔离筛选操作适合承载「用户临时想看的」柔性条件两者的职责划分清晰互不干扰。九、底层机制小结数据范围从配置到查询的链路结合源码可以把数据范围的完整链路概括为配置阶段在区块设置弹窗SchemaSettingsDataScope中编辑条件字段来自useCollectionFilterOptionsV2值输入支持静态值与变量提交时经removeNullCondition清理空条件后写入x-decorator-props.params.filtersetTheDataScopeSchemaSettingsItem.tsx解析阶段请求数据前useParseDataScopeFilter对条件中的$变量进行异步求值解析失败/为 undefined 的变量对应条件会被剔除useParseDataScopeFilter.ts查询阶段解析后的 filter 作为请求参数传给数据源与用户筛选操作的条件合并后执行查询最终决定区块返回的数据集。通过这套机制你可以用纯界面配置的方式实现「按人看数据、按表单联动选数、按角色收敛范围」等典型业务需求而无需编写任何后端代码。相关文档与源码索引数据范围区块设置主文档docs/docs/cn/interface-builder/blocks/block-settings/data-scope.md变量体系docs/docs/cn/interface-builder/variables.md关系字段数据范围docs/docs/cn/interface-builder/fields/field-settings/data-scope.md筛选操作条件合并行为docs/docs/cn/interface-builder/actions/types/filter.md数据范围设置项源码packages/core/client/src/schema-settings/setTheDataScopeSchemaSettingsItem.tsx数据范围配置弹窗packages/core/client/src/schema-settings/SchemaSettingsDataScope.tsx变量解析实现packages/core/client/src/schema-settings/hooks/useParseDataScopeFilter.ts操作符机制packages/core/client/src/schema-component/antd/filter/useOperators.ts【免费下载链接】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），仅供参考