@ a2ui- sdk/ 反应
渲染 A2UI 协议的反应执行 。 此软件包提供 React 组件和钩子,用于将 A2UI 渲染器集成到您的应用程序中.
安装
npm install @a2ui-sdk/react
同伴依赖关系
react^19.0react-dom^19.0
使用量
v. 0.8 (中文(简体) )
基本用途
import {
A2UIProvider,
A2UIRenderer,
type A2UIMessage,
type A2UIAction,
} from '@a2ui-sdk/react/0.8'
function App() {
const messages: A2UIMessage[] = [
// A2UI messages from your backend
]
const handleAction = (action: A2UIAction) => {
console.log('Action received:', action)
}
return (
<A2UIProvider messages={messages}>
<A2UIRenderer onAction={handleAction} />
</A2UIProvider>
)
}
自定义组件
您可以通过 catalog 打开道具 A2UIProvider启用 standardCatalog 作为基础,并用您的自定义组件扩展它.
import {
A2UIProvider,
A2UIRenderer,
standardCatalog,
type A2UIMessage,
type A2UIAction,
} from '@a2ui-sdk/react/0.8'
// Extend standard catalog with custom components
const customCatalog = {
...standardCatalog,
components: {
...standardCatalog.components,
// Override default Button component with a custom one
Button: CustomButtonComponent,
// Add a new custom Switch component
Switch: CustomSwitchComponent,
},
}
function App() {
return (
<A2UIProvider catalog={customCatalog} messages={messages}>
<A2UIRenderer onAction={handleAction} />
</A2UIProvider>
)
}
执行带有动作调度的自定义按钮组件 :
import {
useDispatchAction,
ComponentRenderer,
type ButtonComponentProps,
} from '@a2ui-sdk/react/0.8'
export function CustomButtonComponent({
surfaceId,
componentId,
child,
action,
}: ButtonComponentProps) {
const dispatchAction = useDispatchAction()
const handleClick = () => {
if (action) {
dispatchAction(surfaceId, componentId, action)
}
}
return (
<button onClick={handleClick}>
<ComponentRenderer surfaceId={surfaceId} componentId={child} />
</button>
)
}
执行带有数据约束的自定义开关组件:
import { useDataBinding, useFormBinding } from '@a2ui-sdk/react/0.8'
export function CustomSwitchComponent({
surfaceId,
componentId,
label,
value,
}: SwitchComponentProps) {
const labelText = useDataBinding<string>(surfaceId, label, '')
const [checked, setChecked] = useFormBinding<boolean>(surfaceId, value, false)
const handleChange = (newChecked: boolean) => {
setChecked(newChecked)
}
return (
<Switch checked={checked} onChange={handleChange}>
{labelText}
</Switch>
)
}
页:1
基本用途
import {
A2UIProvider,
A2UIRenderer,
type A2UIMessage,
type A2UIAction,
} from '@a2ui-sdk/react/0.9'
function App() {
const messages: A2UIMessage[] = [
// A2UI messages from your backend
]
const handleAction = (action: A2UIAction) => {
console.log('Action:', action.name, action.context)
}
return (
<A2UIProvider messages={messages}>
<A2UIRenderer onAction={handleAction} />
</A2UIProvider>
)
}
自定义组件
覆盖或扩展标准目录的方式与v0.8相同:
import {
A2UIProvider,
A2UIRenderer,
standardCatalog,
type A2UIMessage,
type A2UIAction,
} from '@a2ui-sdk/react/0.9'
// Extend standard catalog with custom components
const customCatalog = {
...standardCatalog,
components: {
...standardCatalog.components,
// Override default components or add new ones
Button: CustomButtonComponent,
},
}
function App() {
return (
<A2UIProvider catalog={customCatalog} messages={messages}>
<A2UIRenderer onAction={handleAction} />
</A2UIProvider>
)
}
出口
v0.9 (最晚) (中文(简体) )
import {
// Components
A2UIProvider,
A2UIRenderer,
ComponentRenderer,
// Catalog
standardCatalog,
// Hooks
useDispatchAction,
useDataBinding,
useFormBinding,
useStringBinding,
useDataModel,
useValidation,
useSurfaceContext,
useScope,
useScopeBasePath,
useA2UIMessageHandler,
// Context Providers & Hooks
ActionProvider,
useActionContext,
// Types
type A2UIMessage,
type A2UIAction,
type A2UIProviderProps,
type A2UIRendererProps,
type ComponentsMap,
type Component,
type Action,
type DynamicValue,
type DynamicString,
type DynamicNumber,
type DynamicBoolean,
type DynamicStringList,
type ChildList,
type TemplateBinding,
type CheckRule,
type Checkable,
type ValidationResult,
type ScopeValue,
type DataModel,
type A2UIMessageHandler,
} from '@a2ui-sdk/react/0.9'
v. 0.8 (中文(简体) )
import {
// Components
A2UIProvider,
A2UIRenderer,
ComponentRenderer,
// Catalog
standardCatalog,
// Hooks
useDispatchAction,
useDataBinding,
useFormBinding,
useSurfaceContext,
useDataModelContext,
useScope,
useScopeBasePath,
useA2UIMessageHandler,
// Context Providers & Hooks
ActionProvider,
useActionContext,
// Types
type A2UIMessage,
type A2UIAction,
type A2UIProviderProps,
type A2UIRendererProps,
type ComponentsMap,
type Action,
type ValueSource,
type ScopeValue,
type A2UIMessageHandler,
} from '@a2ui-sdk/react/0.8'
命名空间导入
import { v0_8, v0_9 } from '@a2ui-sdk/react'
// Use v0.9 API
const { A2UIProvider, A2UIRenderer } = v0_9
递增信件处理
V0.8 & v0.9 中新建 : 对于递增接收信件的应用程序(例如通过WebSocket或SSE),您可以使用 useA2UIMessageHandler 钩键以驱动新消息而不清除状态 。 这保存了用户编辑功能.
问题
使用时 messages 打开道具 A2UIProvider,更改消息阵列会让提供者从头清除所有状态并重新处理. 这将失去用户编辑 :
// ❌ This loses user edits when new messages arrive
function App() {
const [messages, setMessages] = useState<A2UIMessage[]>([])
useEffect(() => {
const ws = new WebSocket('ws://example.com')
ws.onmessage = (event) => {
const newMessage = JSON.parse(event.data)
setMessages((prev) => [...prev, newMessage]) // Triggers full clear & reprocess!
}
}, [])
return (
<A2UIProvider messages={messages}>
<A2UIRenderer onAction={handleAction} />
</A2UIProvider>
)
}
解决方案
使用 useA2UIMessageHandler 连接到递增处理信件 :
import {
A2UIProvider,
A2UIRenderer,
useA2UIMessageHandler,
type A2UIMessage,
type A2UIAction,
} from '@a2ui-sdk/react/0.8' // or '@a2ui-sdk/react/0.9'
function App() {
const handleAction = (action: A2UIAction) => {
console.log('Action:', action)
}
return (
<A2UIProvider>
<MessageHandler>
<A2UIRenderer onAction={handleAction} />
</MessageHandler>
</A2UIProvider>
)
}
function MessageHandler({ children }: { children: React.ReactNode }) {
const { processMessage } = useA2UIMessageHandler()
useEffect(() => {
// Listen for incremental updates
const ws = new WebSocket('ws://example.com')
ws.onmessage = (event) => {
const newMessage = JSON.parse(event.data)
processMessage(newMessage) // Incremental - preserves user edits!
}
return () => ws.close()
}, [processMessage])
return <>{children}</>
}
这个 useA2UIMessageHandler 钩子返回 :
processMessage(message: A2UIMessage): 递增处理单个消息processMessages(messages: A2UIMessage[]): 按顺序处理多条消息clear(): 清除所有表面和状态( 不需要)
钩子
使用 A2UIMessage 汉德勒
见 递增信件处理 详情见上文.
使用数据框
确定数据模型的动态值:
const value = useDataBinding({ path: '/user/name' })
// Returns the value at /user/name in the data model
使用FormBinding
形式组件双向绑定:
const [value, setValue] = useFormBinding({ path: '/form/email' })
// value: current value
// setValue: update the data model
使用发送动作
从自定义组件发送动作 :
const dispatch = useDispatchAction()
const handleClick = () => {
dispatch({
name: 'submit',
context: { formId: 'contact' },
})
}
参数
对照检查规则验证窗体输入 :
const { valid, errors } = useValidation(checks)
// valid: boolean
// errors: string[] - list of failed validation messages
动作 提供和使用动作关联
对于高级使用大小写,您可以通过使用 ActionProvider 财务报告和审定财务报表 useActionContext 直接说 当您需要截取、转换或增强动作时.
import {
A2UIProvider,
A2UIRenderer,
ActionProvider,
useActionContext,
} from '@a2ui-sdk/react/0.9'
function ActionLogger({ children }: { children: React.ReactNode }) {
const { onAction } = useActionContext()
// You can access the action handler here
// and potentially wrap it with logging or other middleware logic
return <>{children}</>
}
function App() {
const handleAction = (action: A2UIAction) => {
console.log('Action:', action)
}
return (
<A2UIProvider messages={messages}>
<ActionProvider onAction={handleAction}>
<ActionLogger>
<A2UIRenderer />
</ActionLogger>
</ActionProvider>
</A2UIProvider>
)
}
说明: 在大多数情况下,你不需要使用 ActionProvider 直接为 A2UIProvider 已经包括了 仅用于高级定制方案 .
许可证
阿帕奇 - 2.0