NocoBase RunJS 单条记录资源SingleRecordResource完全指南按主键加载、创建/更新与删除【免费下载链接】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/nocobaseSingleRecordResource 是 NocoBase RunJS 运行环境中面向单条记录的 Resource 实现专门服务于详情区块、表单区块以及 JSBlock 中一次只处理一条记录的场景。读完本文你将掌握如何通过ctx.initResource/ctx.makeResource创建单条记录资源如何用setFilterByTk指定主键、用save()自动区分新建与更新、用destroy()删除记录并深入理解其底层请求 URL 的构建与事件机制。什么是 SingleRecordResource在 RunJSNocoBase 的前端脚本运行环境中Resource 是对后端数据 API 的一层封装。SingleRecordResource与面向列表的 MultiRecordResource 相对它的数据形态是单条记录对象即 get 接口返回的data字段而不是记录数组。其继承关系为FlowResource → APIResource → BaseRecordResource → SingleRecordResource这一继承链在源码中有完整对应。FlowResource定义了响应式数据容器与事件系统flowResource.tsAPIResource负责接入ctx.apiAPIClient并管理请求配置apiResource.tsBaseRecordResource提供了资源名、关联资源、筛选、字段、关联展开等通用能力baseRecordResource.ts而SingleRecordResource在 singleRecordResource.ts 中实现了单条记录特有的isNewRecord状态、save()分流和refresh()逻辑。与 MultiRecordResource 的核心差异维度SingleRecordResourceMultiRecordResourcegetData()返回值单条记录对象记录数组主键指定setFilterByTk(id)设置后isNewRecord为 falsesetFilterByTk(tk)仅作为请求参数保存行为save()根据isNewRecord自动走 create 或 update需显式调用create()/update()适用场景详情、新建/编辑表单、JSBlock 详情表格、列表、批量操作适用场景场景说明详情区块详情区块默认使用 SingleRecordResource按主键加载单条记录表单区块新建/编辑表单使用 SingleRecordResourcesave()自动区分 create/updateJSBlock 详情在 JSBlock 中加载单条用户、订单等并自定义展示关联资源使用users.profile等形式加载关联单条记录需配合setSourceId(父记录ID)创建方式initResource 与 makeResource文档与源码均确认两种创建方式区别在于是否绑定到ctx.resourcectx.initResource(SingleRecordResource)若ctx.resource不存在则创建并绑定已存在则直接返回保证ctx.resource可用。ctx.makeResource(SingleRecordResource)仅创建新实例并返回不写入ctx.resource适合需要多个独立 resource 或临时查询的场景。源码层面这两个方法都最终走向FlowEngine.createResource从已注册的资源类表中取出SingleRecordResource并实例化flowEngine.ts。createResource在构造时传入当前上下文从而让实例获得ctx.api等运行环境能力flowEngine.ts// initResource绑定到 ctx.resourceflowContext.ts 中懒创建 ctx.initResource(SingleRecordResource); ctx.resource.setResourceName(users); ctx.resource.setFilterByTk(1); await ctx.resource.refresh(); const user ctx.resource.getData();// makeResource独立实例不污染 ctx.resource const res ctx.makeResource(SingleRecordResource); res.setResourceName(orders); await res.refresh();注意initResource仅应在 JSBlock 等默认没有ctx.resource的上下文中使用多数区块表格、表单、详情与弹窗场景中ctx.resource已由运行环境预绑定无需手动初始化。useResource为已废弃别名等价于initResource。资源名、关联资源与数据源使用前必须调用setResourceName(数据表名)否则无法构建请求 URL。方法说明setResourceName(name)/getResourceName()资源名如users、users.profile关联资源setSourceId(id)/getSourceId()关联资源时的父记录 ID如users.profile需传 users 的主键setDataSourceKey(key)/getDataSourceKey()数据源标识多数据源时使用setFilterByTk(tk)/getFilterByTk()当前记录主键设置后isNewRecord为 false这三个配置在BaseRecordResource中都有对应实现baseRecordResource.tsURL 构建buildURL()会判断资源名是否含.。普通资源拼出users:get、users:update这类形如资源名:action的地址关联资源users.profile则拆分为父资源与子资源拼出users/${sourceId}/profile:getbaseRecordResource.ts。这就是为什么关联资源必须先setSourceId(父记录主键)。数据源setDataSourceKey()实际是写入请求头X-Data-Source多数据源应用据此路由到目标数据源。主键序列化setFilterByTk()通过jsonStringify处理对象形式的主键会被 JSON 序列化后作为filterByTk请求参数baseRecordResource.ts。状态isNewRecordisNewRecord是 SingleRecordResource 最重要的内部状态singleRecordResource.ts属性说明isNewRecord是否为新建状态未设置 filterByTk 或新创建时为 true关键行为初始值为false调用setFilterByTk(tk)会把它置为false表示当前绑定了已有记录singleRecordResource.ts。新建记录时不要调用setFilterByTk保持isNewRecord true。supportsFiltergetter 返回!isNewRecord即只有非新建状态才允许使用筛选条件singleRecordResource.ts。新建态下refresh()会直接短路返回不会发起无谓的 API 请求singleRecordResource.ts。请求参数筛选、字段与关联展开方法说明setFilter(filter)/getFilter()筛选非新建时可用setFields(fields)/getFields()请求字段白名单如[id, nickname, email]setAppends(appends)/getAppends()/addAppends/removeAppends关联展开如[profile, roles]底层实现同样位于 baseRecordResource.tssetFilter将筛选对象 JSON 序列化后写入请求参数filtersetFields支持传入字符串或数组自动按逗号拆分并去空格addAppends会做去重追加removeAppends按名称移除。这些参数最终随 get 请求一并发出用于服务端裁剪字段与展开关联。CRUD 操作方法说明refresh()按当前filterByTk请求 get更新getData()新建态时不请求save(data, options?)新建时调 create否则调 update可选{ refresh: false }不自动刷新destroy(options?)按当前filterByTk删除并清空本地数据runAction(actionName, options)调用任意资源 actionrefresh()按主键重新拉取refresh()先清空错误状态若isNewRecord为 true 则直接返回避免无主键时的无效请求否则调用getaction 发起请求成功后用setData(data).setMeta(meta)更新数据与元信息并触发refresh事件失败则写入error并抛出singleRecordResource.ts。getData()返回的即 get 接口data字段——单条记录对象。save()自动分流 create / updatesave()的核心逻辑singleRecordResource.ts合并setSaveActionOptions保存的配置与本次传入的 options剔除refresh字段若isNewRecord为 trueaction 名为create直接用传入数据作为 body否则 action 名为update并自动把当前filterByTk写入请求参数让后端知道更新哪条记录请求成功后调用markDataSourceDirty()标记数据源为脏——这是 NocoBase 跨视图激活时刷新的协调机制其他依赖同一数据源的视图在重新激活时会感知变化并刷新触发saved事件回调可拿到本次保存的数据默认紧接着自动执行refresh()拉取最新数据传入{ refresh: false }可跳过此步。destroy()按主键删除destroy()把当前filterByTk序列化后作为destroyaction 的请求参数发出成功后同样标记数据源为脏并调用setData(null)清空本地数据singleRecordResource.ts。因此删除后getData()返回null。runAction()任意 actionrunAction(actionName, options)是底层通用方法refresh、save、destroy最终都经由它发出请求以资源 URL 加:action形式构建地址默认post方法响应数据做解包处理data.data与data.meta异常统一包装为ResourceErrorbaseRecordResource.ts。你也可用它调用 NocoBase 资源支持的其他 action。配置与事件方法说明setSaveActionOptions(options)save 时的请求配置Axios 请求配置对象on(refresh, fn)/on(saved, fn)刷新完成、保存后触发事件能力继承自FlowResourceflowResource.ts除on外还提供once一次性监听、off移除监听与emit触发。getData()返回的底层数据由formily/reactive的observable.ref管理是响应式数据——在 JSBlock 中修改并重新渲染时UI 会自动跟随数据变化。完整示例基础获取与更新ctx.initResource(SingleRecordResource); ctx.resource.setResourceName(users); ctx.resource.setFilterByTk(1); await ctx.resource.refresh(); const user ctx.resource.getData(); // 更新已设置 filterByTkisNewRecord 为 falsesave 走 update await ctx.resource.save({ name: 李四 });新建记录const newRes ctx.makeResource(SingleRecordResource); newRes.setResourceName(users); // 未调用 setFilterByTkisNewRecord 为 truesave 走 create await newRes.save({ name: 王五, email: wangwuexample.com });删除记录ctx.resource.setResourceName(users); ctx.resource.setFilterByTk(1); await ctx.resource.destroy(); // destroy 后 getData() 为 null关联展开与字段ctx.resource.setResourceName(users); ctx.resource.setFilterByTk(1); ctx.resource.setFields([id, nickname, email]); ctx.resource.setAppends([profile, roles]); await ctx.resource.refresh(); const user ctx.resource.getData();关联资源如 users.profileconst res ctx.makeResource(SingleRecordResource); res.setResourceName(users.profile); res.setSourceId(ctx.record?.id); // 父记录主键 res.setFilterByTk(profileId); // 若 profile 为 hasOne 可省略 filterByTk await res.refresh(); const profile res.getData();关联资源users.profile会构建为users/${sourceId}/profile:get的请求地址因此setSourceId是必需前提若 profile 与 users 是一对一hasOne关系可省略setFilterByTk。save 不自动刷新await ctx.resource.save({ status: active }, { refresh: false }); // 保存后不触发 refreshgetData() 保持旧值监听 refresh / saved 事件ctx.resource?.on?.(refresh, () { const data ctx.resource.getData(); ctx.render(div用户: {data?.nickname}/div); }); ctx.resource?.on?.(saved, (savedData) { ctx.message.success(保存成功); }); await ctx.resource?.refresh?.();注意事项setResourceName 必填使用前必须调用setResourceName(数据表名)否则无法构建请求 URL。filterByTk 与 isNewRecord未设置setFilterByTk时isNewRecord为 truerefresh()不会发起请求save()会走 create。关联资源资源名为parent.child时如users.profile需先setSourceId(父记录主键)。getData 为对象单条接口返回的data为记录对象getData()直接返回该对象destroy()后为 null。环境前提RunJS 中ctx.api由运行环境注入Resource 实例的请求默认走X-Data-Source指定的数据源未指定时为主数据源。相关文档ctx.resource当前上下文中的 resource 实例ctx.initResource()初始化并绑定到 ctx.resourcectx.makeResource()新建 resource 实例不绑定APIResource通用 API 资源按 URL 请求MultiRecordResource面向数据表/列表支持 CRUD、分页【免费下载链接】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），仅供参考
NocoBase RunJS 单条记录资源SingleRecordResource完全指南按主键加载、创建/更新与删除【免费下载链接】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/nocobaseSingleRecordResource 是 NocoBase RunJS 运行环境中面向单条记录的 Resource 实现专门服务于详情区块、表单区块以及 JSBlock 中一次只处理一条记录的场景。读完本文你将掌握如何通过ctx.initResource/ctx.makeResource创建单条记录资源如何用setFilterByTk指定主键、用save()自动区分新建与更新、用destroy()删除记录并深入理解其底层请求 URL 的构建与事件机制。什么是 SingleRecordResource在 RunJSNocoBase 的前端脚本运行环境中Resource 是对后端数据 API 的一层封装。SingleRecordResource与面向列表的 MultiRecordResource 相对它的数据形态是单条记录对象即 get 接口返回的data字段而不是记录数组。其继承关系为FlowResource → APIResource → BaseRecordResource → SingleRecordResource这一继承链在源码中有完整对应。FlowResource定义了响应式数据容器与事件系统flowResource.tsAPIResource负责接入ctx.apiAPIClient并管理请求配置apiResource.tsBaseRecordResource提供了资源名、关联资源、筛选、字段、关联展开等通用能力baseRecordResource.ts而SingleRecordResource在 singleRecordResource.ts 中实现了单条记录特有的isNewRecord状态、save()分流和refresh()逻辑。与 MultiRecordResource 的核心差异维度SingleRecordResourceMultiRecordResourcegetData()返回值单条记录对象记录数组主键指定setFilterByTk(id)设置后isNewRecord为 falsesetFilterByTk(tk)仅作为请求参数保存行为save()根据isNewRecord自动走 create 或 update需显式调用create()/update()适用场景详情、新建/编辑表单、JSBlock 详情表格、列表、批量操作适用场景场景说明详情区块详情区块默认使用 SingleRecordResource按主键加载单条记录表单区块新建/编辑表单使用 SingleRecordResourcesave()自动区分 create/updateJSBlock 详情在 JSBlock 中加载单条用户、订单等并自定义展示关联资源使用users.profile等形式加载关联单条记录需配合setSourceId(父记录ID)创建方式initResource 与 makeResource文档与源码均确认两种创建方式区别在于是否绑定到ctx.resourcectx.initResource(SingleRecordResource)若ctx.resource不存在则创建并绑定已存在则直接返回保证ctx.resource可用。ctx.makeResource(SingleRecordResource)仅创建新实例并返回不写入ctx.resource适合需要多个独立 resource 或临时查询的场景。源码层面这两个方法都最终走向FlowEngine.createResource从已注册的资源类表中取出SingleRecordResource并实例化flowEngine.ts。createResource在构造时传入当前上下文从而让实例获得ctx.api等运行环境能力flowEngine.ts// initResource绑定到 ctx.resourceflowContext.ts 中懒创建 ctx.initResource(SingleRecordResource); ctx.resource.setResourceName(users); ctx.resource.setFilterByTk(1); await ctx.resource.refresh(); const user ctx.resource.getData();// makeResource独立实例不污染 ctx.resource const res ctx.makeResource(SingleRecordResource); res.setResourceName(orders); await res.refresh();注意initResource仅应在 JSBlock 等默认没有ctx.resource的上下文中使用多数区块表格、表单、详情与弹窗场景中ctx.resource已由运行环境预绑定无需手动初始化。useResource为已废弃别名等价于initResource。资源名、关联资源与数据源使用前必须调用setResourceName(数据表名)否则无法构建请求 URL。方法说明setResourceName(name)/getResourceName()资源名如users、users.profile关联资源setSourceId(id)/getSourceId()关联资源时的父记录 ID如users.profile需传 users 的主键setDataSourceKey(key)/getDataSourceKey()数据源标识多数据源时使用setFilterByTk(tk)/getFilterByTk()当前记录主键设置后isNewRecord为 false这三个配置在BaseRecordResource中都有对应实现baseRecordResource.tsURL 构建buildURL()会判断资源名是否含.。普通资源拼出users:get、users:update这类形如资源名:action的地址关联资源users.profile则拆分为父资源与子资源拼出users/${sourceId}/profile:getbaseRecordResource.ts。这就是为什么关联资源必须先setSourceId(父记录主键)。数据源setDataSourceKey()实际是写入请求头X-Data-Source多数据源应用据此路由到目标数据源。主键序列化setFilterByTk()通过jsonStringify处理对象形式的主键会被 JSON 序列化后作为filterByTk请求参数baseRecordResource.ts。状态isNewRecordisNewRecord是 SingleRecordResource 最重要的内部状态singleRecordResource.ts属性说明isNewRecord是否为新建状态未设置 filterByTk 或新创建时为 true关键行为初始值为false调用setFilterByTk(tk)会把它置为false表示当前绑定了已有记录singleRecordResource.ts。新建记录时不要调用setFilterByTk保持isNewRecord true。supportsFiltergetter 返回!isNewRecord即只有非新建状态才允许使用筛选条件singleRecordResource.ts。新建态下refresh()会直接短路返回不会发起无谓的 API 请求singleRecordResource.ts。请求参数筛选、字段与关联展开方法说明setFilter(filter)/getFilter()筛选非新建时可用setFields(fields)/getFields()请求字段白名单如[id, nickname, email]setAppends(appends)/getAppends()/addAppends/removeAppends关联展开如[profile, roles]底层实现同样位于 baseRecordResource.tssetFilter将筛选对象 JSON 序列化后写入请求参数filtersetFields支持传入字符串或数组自动按逗号拆分并去空格addAppends会做去重追加removeAppends按名称移除。这些参数最终随 get 请求一并发出用于服务端裁剪字段与展开关联。CRUD 操作方法说明refresh()按当前filterByTk请求 get更新getData()新建态时不请求save(data, options?)新建时调 create否则调 update可选{ refresh: false }不自动刷新destroy(options?)按当前filterByTk删除并清空本地数据runAction(actionName, options)调用任意资源 actionrefresh()按主键重新拉取refresh()先清空错误状态若isNewRecord为 true 则直接返回避免无主键时的无效请求否则调用getaction 发起请求成功后用setData(data).setMeta(meta)更新数据与元信息并触发refresh事件失败则写入error并抛出singleRecordResource.ts。getData()返回的即 get 接口data字段——单条记录对象。save()自动分流 create / updatesave()的核心逻辑singleRecordResource.ts合并setSaveActionOptions保存的配置与本次传入的 options剔除refresh字段若isNewRecord为 trueaction 名为create直接用传入数据作为 body否则 action 名为update并自动把当前filterByTk写入请求参数让后端知道更新哪条记录请求成功后调用markDataSourceDirty()标记数据源为脏——这是 NocoBase 跨视图激活时刷新的协调机制其他依赖同一数据源的视图在重新激活时会感知变化并刷新触发saved事件回调可拿到本次保存的数据默认紧接着自动执行refresh()拉取最新数据传入{ refresh: false }可跳过此步。destroy()按主键删除destroy()把当前filterByTk序列化后作为destroyaction 的请求参数发出成功后同样标记数据源为脏并调用setData(null)清空本地数据singleRecordResource.ts。因此删除后getData()返回null。runAction()任意 actionrunAction(actionName, options)是底层通用方法refresh、save、destroy最终都经由它发出请求以资源 URL 加:action形式构建地址默认post方法响应数据做解包处理data.data与data.meta异常统一包装为ResourceErrorbaseRecordResource.ts。你也可用它调用 NocoBase 资源支持的其他 action。配置与事件方法说明setSaveActionOptions(options)save 时的请求配置Axios 请求配置对象on(refresh, fn)/on(saved, fn)刷新完成、保存后触发事件能力继承自FlowResourceflowResource.ts除on外还提供once一次性监听、off移除监听与emit触发。getData()返回的底层数据由formily/reactive的observable.ref管理是响应式数据——在 JSBlock 中修改并重新渲染时UI 会自动跟随数据变化。完整示例基础获取与更新ctx.initResource(SingleRecordResource); ctx.resource.setResourceName(users); ctx.resource.setFilterByTk(1); await ctx.resource.refresh(); const user ctx.resource.getData(); // 更新已设置 filterByTkisNewRecord 为 falsesave 走 update await ctx.resource.save({ name: 李四 });新建记录const newRes ctx.makeResource(SingleRecordResource); newRes.setResourceName(users); // 未调用 setFilterByTkisNewRecord 为 truesave 走 create await newRes.save({ name: 王五, email: wangwuexample.com });删除记录ctx.resource.setResourceName(users); ctx.resource.setFilterByTk(1); await ctx.resource.destroy(); // destroy 后 getData() 为 null关联展开与字段ctx.resource.setResourceName(users); ctx.resource.setFilterByTk(1); ctx.resource.setFields([id, nickname, email]); ctx.resource.setAppends([profile, roles]); await ctx.resource.refresh(); const user ctx.resource.getData();关联资源如 users.profileconst res ctx.makeResource(SingleRecordResource); res.setResourceName(users.profile); res.setSourceId(ctx.record?.id); // 父记录主键 res.setFilterByTk(profileId); // 若 profile 为 hasOne 可省略 filterByTk await res.refresh(); const profile res.getData();关联资源users.profile会构建为users/${sourceId}/profile:get的请求地址因此setSourceId是必需前提若 profile 与 users 是一对一hasOne关系可省略setFilterByTk。save 不自动刷新await ctx.resource.save({ status: active }, { refresh: false }); // 保存后不触发 refreshgetData() 保持旧值监听 refresh / saved 事件ctx.resource?.on?.(refresh, () { const data ctx.resource.getData(); ctx.render(div用户: {data?.nickname}/div); }); ctx.resource?.on?.(saved, (savedData) { ctx.message.success(保存成功); }); await ctx.resource?.refresh?.();注意事项setResourceName 必填使用前必须调用setResourceName(数据表名)否则无法构建请求 URL。filterByTk 与 isNewRecord未设置setFilterByTk时isNewRecord为 truerefresh()不会发起请求save()会走 create。关联资源资源名为parent.child时如users.profile需先setSourceId(父记录主键)。getData 为对象单条接口返回的data为记录对象getData()直接返回该对象destroy()后为 null。环境前提RunJS 中ctx.api由运行环境注入Resource 实例的请求默认走X-Data-Source指定的数据源未指定时为主数据源。相关文档ctx.resource当前上下文中的 resource 实例ctx.initResource()初始化并绑定到 ctx.resourcectx.makeResource()新建 resource 实例不绑定APIResource通用 API 资源按 URL 请求MultiRecordResource面向数据表/列表支持 CRUD、分页【免费下载链接】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），仅供参考
