@collective-intelligence/external-apps-client-sdk-react
UI-最小反应绑定在承诺客户端SDK上. 该软件包没有私有应用程序 UI 依赖性.
CollectiveIntelligenceProvider 拥有稳定、请求同位素查询; 应用程序不
配置 SDK CRUD 的查询程序 。 要使用 SDK 钩和应用程序的缓存, 请通过
应用程序的客户端为 queryClient。然后,该客户端的默认情况适用于 /resources
读取,应用程序将服务器上的请求隔离。 实体钩子保存 retry: false。 。 。 .
在应用程序中安装这些所需的对等依赖 : react, (中文(简体) ), react-dom, (中文(简体) ),
@tanstack/react-query, (中文(简体) ), xstate, (中文(简体) ), effect 财务报告和审定财务报表 @collective-intelligence/ui-react软件包
取决于 @collective-intelligence/external-apps-client-sdk 作为正常的依赖。 包装
JavaScript 捆绑了这些软件包,所以应用程序每个软件包都持有一份. 这个 ./effect 条目
拿着 效果桥 x国产机器.
配置提供者 entitySource 一次,与它现有的承诺 client。 。 。 . EntitySource
暴露出一个马厩 getSnapshot页:1 subscribe 函数,并输入 bind(contract) 函数返回
共同承诺 EntityClient。认证快照可以识别配置的逻辑源,
应用程序、用户和组织。 从经认证的申请中获得这些身份
会话;它们是缓存边界,而不是访问权限。 为每次会话返回新的稳定快照
转换,登录时立即通知订户,并将客户绑定在该快照的权威.
后端授权仍然具有权威性. CollectiveIntelligenceLoginProvider 转发相同
配置;实体源必须订阅应用程序的 CI 从会话生命周期 .
;<CollectiveIntelligenceProvider client={appSdk} entitySource={entitySource}>
<Orders />
</CollectiveIntelligenceProvider>
// Import these hooks from /resources. Use the portable entity contract.
const rows = useEntityList(orderContract, query)
const record = useEntityRecord(orderContract, { id: selectedId })
const create = useEntityCreate(orderContract)
const update = useEntityUpdate(orderContract, { id: selectedId })
const remove = useEntityDelete(orderContract, { id: selectedId })
await update.submit({ value: draft, expectedRevision: editedRecord.revision })
// Only on an explicit user request to deliver the same action again:
await update.resubmit()
阅读曝光 data, (中文(简体) ), loading, (中文(简体) ), refreshing, (中文(简体) ), error, (中文(简体) ), authState,有效约束 capabilities, (中文(简体) ),
和明确 refresh;列表也显示 empty. 等同请求分享不同观点的数据.
缓存身份包括源/应用程序/用户/组织以及资源/版本/query,永不查看
命名空间或布局设置.
写作曝光 available,记录范围 pending, (中文(简体) ), status, (中文(简体) ), data, (中文(简体) ), error, (中文(简体) ), submitted, (中文(简体) ), submit, (中文(简体) ),
财务报告和审定财务报表 resubmit. 地位区别 conflict, (中文(简体) ), rejected,以及 uncertain 从普通
idle编号 :pending编号 :success. 提交复制和冻结草案并审查修订和生成
一个操作键。 新的提交创建了新的动作;重新提交完全保留了以前的动作.
保留格式和使用的可编辑草稿 submitted ; 成功的重放
不覆盖更新的草稿。 同一记录的更新/删除连接到钩子的序列;
不同的记录和单独的创建保持独立。 排队写作保留原作
订正。 窗体卸载不会取消已发送的写入 。 源代码转换 :
并拒绝在发送前排队的行动。 查询和突变不会自动重试;
不存在持久性、再装入回收或自动修正的再定位.
实体在客户端SDK的Effect Core上读取和写作,通过实体客户端
实体源绑定。 他们的错误留了下来 ResourceResult 值: 失败的读取
error页:1 ResourceQueryError 带有资源错误; 飞行中失败的写入是
uncertain。其他客户端 SDK 呼叫遵循客户端 SDK 错误模型: a CiResult 操作
决定 { ok: false, error } 带有 CiError,并拒绝 CiTransportError 当
请求无法到达 CI. useAgentInvocation 显示此拒绝为 error 状态.
原有的公立坦斯塔克选择工厂和本土-成果资源钩已经不再出口.
使用上面的故意实体钩. 现有通用档期 Resource* 列报方式
与共同实体 CRUD 分离.
乐观写作
实体写作是"乐观写作". 值位于查询缓存中, 因此每个视图 立即读取记录更改 :
- CI 在回答更新或删除之前,记录视图和每个缓存列表页面显示
新价值。 一个删除的记录有
deletedAt在记录视图和列表页中. - 创建显示每个缓存首页开头的待决行 。 内容
id这是 一能钥匙及其value是创建输入。 CI的记录取代了它. - 仅在 CI 回答时更改缓存, 通过
optimistic: false在目标中:useEntityUpdate(contract, { id, optimistic: false }),用于useEntityDelete。 。 。 . - 写到一个记录一次跑一次, 按呼叫顺序。 共享 QueryClient 共享此命令; 单独的 QueryClients 和记录身份仍然独立 。 读取记录的实体等待到 和一份清单读取 等待待写 资源。 因此,在实时更改或Resync之后的回溯不会取代显示的值.
- 关于成功,视图显示CI的记录,而写作结束. 然后,每个列表视图 资源再次读取 CI , 因为写入可以更改记录列表所持有和在 哪个命令。 记录视图保存CI记录时不再读取;失败后, 或者,当另一个接头取代它, 它再次读CI了。 书写不等待 这些读取.
- 在失败或中断时,视图会追溯到其写作前的值,但只有
当它仍然显示 写值。 在列表页面中,只有写作本身的行变化,所以
将待决的行写到其他记录中。 例如,实体钩外读取
一个应用程序
fetchQuery在实体密钥上,不等待写入;然后视图保留该内容 新的值。 写作后读出CI在每个案件中的价值.
onWriteFailed 打开 CollectiveIntelligenceProvider 或者说 CollectiveIntelligenceLoginProvider
获得一个 WriteFailed 对每个实体写 CI 拒绝或没有到达 CI 之后
视图回落. error 是一个 CiError (CI拒绝写)或 CiTransportError (单位:千美元)
请求没有达到CI,或者其答复丢失; operation 实值 create, (中文(简体) ), update 或者说
delete· ; label 是资源 id (contract.id) (中文(简体) ). 它不要求中断,或
当实体源在写作过程中发生变化时。 提供商打电话 onWriteFailed 会 议 日 程 和 议 程
最新进展. . 财务报告和审定财务报表 ./effect 导出 WriteFailed 类型。 此软件包没有显示祝酒词 :
ciWriteFailedToast(messages?) 联 合 国 @collective-intelligence/ui-react/ui 返回处理器
在应用程序中显示一个 Toaster。 。 。 .
import {
Toaster,
ciWriteFailedToast
} from "@collective-intelligence/ui-react/ui"
;<CollectiveIntelligenceProvider
client={appSdk}
entitySource={entitySource}
onWriteFailed={ciWriteFailedToast()}
>
<Orders />
<Toaster />
</CollectiveIntelligenceProvider>
已宣布实体的意见
导入 defineEntity, (中文(简体) ), EntityTable, (中文(简体) ), EntityList,以及 EntityForm 从
@collective-intelligence/external-apps-client-sdk-react/resources声明
与便携式合同一并提交:
const orders = defineEntity({
contract: orderContract,
config: {
fields: { number: { label: "Order number" } },
table: {
columns: ["number"],
variants: { compact: { columns: ["number"] } }
},
list: { title: "number" },
forms: {
create: { fields: ["number"] },
update: { fields: ["number"] }
}
}
})
// Inside the SDK provider and the host framework's NuqsAdapter:
<EntityTable entity={orders} namespace="orders-main" />
<EntityList entity={orders} namespace="orders-sidebar" />
<EntityTable entity={orders} viewState="memory" variant="compact" />
<EntityForm entity={orders} mode="update" record={selectedOrder} />
声明包含标签、字段/控制/交接键和布局
没有JSX, 证书或存储配置。 从
; 配置的字段也必须存在于其可移植的图案中.
意见公布 ui-react 演示文稿和共享授权查询数据
当他们正常的查询匹配时.
由 URL 支持的表格/列表需要一个稳定,独特的命名空间. 安装主机
适配器一次; 已被验证的 TanStack Start 集成使用
NuqsAdapter 从 nuqs/adapters/tanstack-router 在路由器根内.
Nuqs 2.10.1拥有URL序列化并替换-历史更新. 默认为
省略; 不相关的密钥、 其他命名空间和散列被保存 。 无效
拥有的值会回到默认值。 搜索/过滤/类型更改重置页面.
对于自定义控制, 使用 useEntityViewState(namespace, { contract, pageSize })· ;
它会暴露 state,规范化 query,并设置页面大小,
搜索、过滤和排序. useMemoryEntityViewState 财务报告和审定财务报表
viewState="memory" 不需要 URL 适配器 。 查看命名空间从不输入数据密钥 .
表格推断出可移植的scalar、enum、日期、无效和需要设置
计划 仅读 schema 字段无法通过配置变为可写
并在提交材料中省略。 更丰富的值需要在
表单 controls 注册; 缺失控件产生明确的反馈.
自定义控制接收字段元数据并返回JSON线值.
命名的显示渲染器分别通过 renderers。 。 。 .
待写禁用相重叠的保存 。 冲突和未知结果国家
保留当地草案; 重新提交 发送抓取的原始动作,包括
其关键、价值和修订。 成功重新提交还会保持更新的编辑.
更新表保留了修订版,其草稿在刷新后开始编辑
记录道具到达。 有意重载( 例如使用反应) key(中文(简体) )
在用户选择丢弃草稿并编辑更新服务器修订后.
草稿和操作密钥从未输入 URL .
实时话题
RealtimeProvider 选择 createRealtimeClient 作为道具。 这个
为它的树创建一个客户端,从而连接一个, 当它关闭时
树出山. 它的效果和下面的钩子 以参考的方式牵住客户
计数。 因此,一个严格模式双挂载打开一个流,一个服务器渲染
创建任何客户端。 没有 document 支持客户端遵循
浏览器。 客户端读取其他道具,例如 ticketUrl 财务报告和审定财务报表
fetch,一次,当提供者创建它时;后一变化没有效果. 改为:
使用新值, 重挂载提供者, 例如使用反应 key。 。 。 .
useRealtimeTopic(topic, onChanges) 组件挂载时订阅
和卸载的未订阅者。 同一主题的新主题对象保留
订阅; null 认购什么。 最近一个 onChanges 名为
不重新签名。 它分批收到专题的变化:
每分页的交付量,在第一次待修改后250至1000毫秒
每个记录的最新变化.
过 onReset 并调试其中每一个实时驱动的查询。 客户打电话
当服务器无法重放空隙时, 并且当一个流打开后没有了空隙时
上一个事件 ID, 包含每个页面的第一个。 无 onReset 页:1
客户端无法从这样的空隙中恢复,所以改变可能会丢失。 客户
电话 onAccessChanged 当用户的访问权限发生变化时。 都保持召回状态
应用程序; 客户端调用最新渲染中的应用程序, 以及当
使一个添加或删除。 只有客户端 onReset 重新同步,所以一个渲染
添加或删除 onReset 替换客户及其流。 新的
流开时没有最后一个事件 id,所以 onReset 有一次会再同步.
const AppRealtime = ({ children }: { children: ReactNode }) => {
const queryClient = useQueryClient()
return (
<RealtimeProvider
ticketUrl="/api/realtime/ticket"
onReset={() => queryClient.invalidateQueries()}
onAccessChanged={() => queryClient.invalidateQueries()}
>
{children}
</RealtimeProvider>
)
}
const LeadBoard = () => {
const queryClient = useQueryClient()
useRealtimeTopic({ schema: "crm.lead" }, () =>
// One invalidation per batch, however many leads changed.
queryClient.invalidateQueries({ queryKey: ["leads"] })
)
// …
}
对于实体钩, useEntityChanges(contract) 联 合 国 ./resources 给
onChanges 让他们的读物恢复活力 已更改 ID 的记录条目
除非已经对修改进行了修改,例如:
标签自己所保存的文字记录。 每个资源列表已读取
CI再次出现,因为一个变化会改变记录一个列表所持有的. 每个字读作
等待其未完成的记录.
const LeadRealtime = () => {
useRealtimeTopic({ schema: "crm.lead" }, useEntityChanges(leadContract))
return null
}
效果桥
./effect 将 X State 机器连接到效果和应用程序
腾讯克通. 它没有效果原子绑定.
WriteFailed是类型onWriteFailed活动.fromEffect(run)从“效果”中实现演员逻辑。 演员负责效果 打开input.runtime,所以注释input带有runtime: EffectRunner<R>提供效果的每一个服务。 演员的输出是 效果值; 失败时,onError获得输入错误或缺陷. 演员一站打断了纤维,跑道就结束了. 停车后, 该运行的输出、出错或中断, 都无法到达 React 严格模式开始useActorRef再来一次.EffectRuntimeProvider给它的树一个运行时间QueryCache超过 最近的查询;useEffectRuntime()返回它。 放进去CollectiveIntelligenceProvider。运行时间没有资源,所以 供货商从来不处理它.QueryCache是机器角色读取和写入远程数据的一种方式; 机器上下文没有.fetch({ queryKey, query, staleTime? })返回时 新的缓存值或运行query一次,没有自动重试,还有缓存 它的价值.CiError财务报告和审定财务报表CiTransportError保留已键入错误; 另一个失败 是个缺陷。 期间afetch等待,它保持 键作为挂载 观想. 当最后一个视图或fetch键停止等待,等待 举例来说,由于它的演员停止了, TanStack 查询取消了获取和query被中断。 因此,在反应严格模式,演员useActorRef重新开始可以运行query再来一次 取消 键,例如queryClient.cancelQueries({ queryKey }),同时中断queryA级fetch等待然后返回缓存值,或为 当密钥没有值时中断.invalidate(queryKey)标记 值 :.cancel(queryKey)取消运行抓取并中断 查询, 因此它们不会写值; 它保留了缓存值, 并开始不 获取。 一个乐观的写作电话cancel,则update{\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}写一下, 和电话invalidate当书写安定的时候.setData(queryKey, value)写入一次视图显示的值.update(queryKey, (current) => next)以 其当前值的函数结果,不含回切值,用于 以乐观切换或更改行为例;视图显示的新值为 一次 一次吗 每个键下queryKey必须有类型中的值 函数需要.current实值undefined对于一个没有值的条目,aundefined结果保存值, 并保存缓存没有的密钥 保持缺席.update不取消可替换的运行中的抓取 终止时的新值:调用cancel先说.remove(queryKey)删除缓存的条目而无需调试, 例如 在签出时; 它取消了一个正在运行的已删除密钥的获取, 以及下一个fetch运行它的查询。 对已删除密钥的挂载视图保留其最后 结果是,直到它再次产生.invalidate, (中文(简体) ),cancel, (中文(简体) ),update财务报告和审定财务报表remove适用于queryKey和它下面的每一把钥匙 (单位:千美元)["crm", "lead"]匹配["crm", "lead", "7"]没有["crm", "leads"](三);setData写入queryKey只有这个 视图读取相同的密钥useQuery。 。 。 .
import type { EffectRunner } from "@collective-intelligence/external-apps-client-sdk-react/effect"
import {
EffectRuntimeProvider,
QueryCache,
fromEffect,
useEffectRuntime
} from "@collective-intelligence/external-apps-client-sdk-react/effect"
const loadLead = fromEffect(
(input: Readonly<{ id: string; runtime: EffectRunner<QueryCache> }>) =>
QueryCache.use((cache) =>
cache.fetch({ queryKey: ["crm", "lead", input.id], query: readLead(input.id) })
)
)
<CollectiveIntelligenceProvider client={appSdk} queryClient={queryClient}>
<EffectRuntimeProvider>
<LeadEditor id={leadId} />
</EffectRuntimeProvider>
</CollectiveIntelligenceProvider>
const LeadEditor = ({ id }: { id: string }) => {
const runtime = useEffectRuntime()
// `leadMachine` invokes `loadLead` with `{ id, runtime }` from its input.
const lead = useActorRef(leadMachine, { input: { id, runtime } })
// …
}
机器测试
测试机器 makeTestQueryCache(options?)从来没有用双倍制成
与 QueryCache.of({ ... }): 当 QueryCache 获得一个新的
成员. makeTestQueryCache 返回 :
layer: 提供QueryCache联 合 国./effect服务EffectRuntimeProvider提供。 拿来ManagedRuntime.make联 合 国runtime输入.queryClient: 真正的坦斯塔克语NameQueryClient在缓存下面 每个成员 就像在应用中一样 使用相同的密钥前缀,cancel财务报告和审定财务报表remove。其条目将一直保留到测试结束(gcTime: Infinity) (中文(简体) ).calls页:1{ member, queryKey }每个成员按 电话响了。 机器所创造的效应就是没有呼叫.
选项, 全部可选 : seed (单位:千美元)[queryKey, data] 条目
QueryClient 持有第一, queryClient (使用你自己的)和 overrides
联合国 Partial 成员:每个成员仅取代其成员
记录下来.
在条目上显示, 所以一个跳过呼叫的机器会失败测试 :
import {
QueryCache,
makeTestQueryCache
} from "@collective-intelligence/external-apps-client-sdk-react/effect"
import * as ManagedRuntime from "effect/ManagedRuntime"
const cache = makeTestQueryCache({
seed: [[["ci-entities", "lead", "7"], lead]]
})
const runtime = ManagedRuntime.make(cache.layer)
const actor = createActor(sessionMachine, { input: { runtime } }).start()
actor.send({ type: "session.signOut" })
await waitFor(actor, (snapshot) => snapshot.matches("idle"))
// Sign-out removed the reads of the user.
expect(
cache.queryClient.getQueryCache().findAll({ queryKey: ["ci-entities"] })
).toEqual([])
expect(cache.calls).toEqual([{ member: "remove", queryKey: ["ci-entities"] }])
// After an invalidate: cache.queryClient.getQueryState(key)?.isInvalidated === true
await runtime.dispose()
makeTestQueryCache 不增加依赖性,生产捆绑
不导入它不包含它( e)sideEffects: false) (中文(简体) ).
工作空间发展
见寄存器的 效果演示 与本地网关、代理CI、, 和直接CI捆绑.
每个软件包导出时都声明选入 ci-source 工作空间发展的条件。 当地
TypeScript 配置允许它用于框架中立的客户端 SDK, 所以两个软件包的修改
在没有中间重建的情况下消耗。 释放建立禁用自定义条件;已安装 npm
消费者决心生成 dist Java脚本与宣言. 共享运行时间块保留提供者
根和根的上下文相同 /resources 入门口.
运行 bun run test:unit, (中文(简体) ), bun run type-check, (中文(简体) ), bun run lint,以及 bun run test:pack检查包
执行一个真正的根提供者/资源锁定消费者而不使用调用者 TanStack 设置,以及 a ./effect
消费者共享应用程序的查询卡。 它在成功时取消其临时安装
或失败。 仓库根运行 bun run lint:effect 为效果规则.
Enum 值相容性
存储器所属的 enum 值使用更低 snake_case更新网关清单,
与消费者一起请求有效载荷并保存资源过滤器。 对于
例如,使用资源过滤器 starts_with 财务报告和审定财务报表 is_null,生命周期操作
使用值 soft_delete 财务报告和审定财务报表 hard_delete,并使用网关主类型
detached_user 财务报告和审定财务报表 service_principal公共方法和能力财产
诸如 softDelete 保持不变。 外部 HTTP, OAuth, JSON Schema
并且提供者值保留它们在适配器边界上所需的拼写.