JSON‑Render：受限 AI 提示式 UI 库（React）
JSON‑Render：受限 AI 提示式 UI 库（React）
在大型语言模型时代，开发者总在寻找把纯文本提示转化为可执行的用户界面的方法。JSON‑Render 通过为 AI 提供可预测且安全的词汇表，填补了这一空白，使输出始终为可在 React 中渲染的 JSON 树——无意外，零安全漏洞。
什么是 JSON‑Render？
JSON‑Render 是一套轻量级、面向 TypeScript 的工具包，由两个 NPM 包组成：
- @json-render/core —— 模式定义、守卫、可见性逻辑和动作处理。
- @json-render/react —— React 组件、hooks 与渲染器，将 JSON 转化为实时 UI。
主要优势：
| 特性 | 重要性 |
|---|---|
| 受限 | AI 只被允许使用预定义的组件类型，防止恶意代码注入。 |
| 可预测 | JSON 遵循 Zod 模式。每个属性可在运行时进行类型检查。 |
| 快速 | 流式渲染可在模型发送数据时立即呈现，用户实时看到更新。 |
| 可组合 | 能将自定义 React 组件与守卫组合使用；库对样式保持中立。 |
快速入门指南
以下是一段最小化示例的逐步演练。假设你使用 pnpm 创建一个全新的 Node 项目。
# 克隆并启动
# Clone and bootstrap
git clone https://github.com/vercel-labs/json-render
cd json-render
pnpm install
pnpm dev
dev 命令会启动四个服务： *
localhost:3000— 文档与 Playground *localhost:3001— 示例仪表盘应用 * 用于 API 的 websocket 端点 * 当地兼容 ChatGPT 的后端（参考仓库了解自定义 LLM 集成）
1. 定义组件目录
在 packages/core/src/catalog.ts，你声明 AI 可使用的所有组件。以下是一个简洁示例：
import { createCatalog } from '@json-render/core'
import { z } from 'zod'
const catalog = createCatalog({
components: {
Card: {
props: z.object({ title: z.string() }),
hasChildren: true,
},
Metric: {
props: z.object({
label: z.string(),
valuePath: z.string(),
format: z.enum(['currency', 'percent', 'number']),
}),
},
Button: {
props: z.object({ label: z.string(), action: ActionSchema }),
},
},
actions: {
export_report: { description: 'Export dashboard to PDF' },
refresh_data: { description: 'Refresh all metrics' },
},
})
export default catalog
ActionSchema是你从@json-render/core导入的 Zod 模式，用于验证action负载的结构。
2. 注册 React 渲染器
创建一个小型注册表，将组件名映射到实际的 React 元素。
const registry = {
Card: ({ element, children }) => (
<div className='card'>
<h3>{element.props.title}</h3>
{children}
</div>
),
Metric: ({ element }) => {
const value = useDataValue(element.props.valuePath)
return <div className='metric'>{format(value)}</div>
},
Button: ({ element, onAction }) => (
<button onClick={() => onAction(element.props.action)}>
{element.props.label}
</button>
),
}
3. 把它们连接在一起
import { useUIStream, DataProvider, ActionProvider, Renderer } from '@json-render/react'
function Dashboard() {
const { tree, send } = useUIStream({ api: '/api/generate' })
return (
<DataProvider initialData={{ revenue: 125000, growth: 0.15 }}>
<ActionProvider actions={{
export_report: () => downloadPDF(),
refresh_data: () => refetch(),
}}>
<input
placeholder='Create a revenue dashboard…'
onKeyDown={(e) => e.key === 'Enter' && send(e.target.value)}
/>
<Renderer tree={tree} components={registry} />
</ActionProvider>
</DataProvider>
)
}
当用户键入自然语言提示并按 Enter 时，库会流式输出 AI 的 JSON 响应，注册表渲染它，任何已定义的动作都会触发相应的回调函数。
高级功能
条件可见性
根据数据、身份验证或自定义逻辑显示或隐藏元素：
{ 'type': 'Alert', 'props': { 'message': 'Error occurred' }, 'visible': { 'and': [ { 'path': '/form/hasError' }, { 'not': { 'path': '/form/errorDismissed' } } ] } }
带确认的丰富动作
{ 'type': 'Button', 'props': { 'label': 'Refund Payment', 'action': { 'name': 'refund', 'params': { 'paymentId': { 'path': '/selected/id' } }, 'confirm': { 'title': 'Confirm Refund', 'variant': 'danger' } } } }
内置校验
{ 'type': 'TextField', 'props': { 'label': 'Email', 'valuePath': '/form/email', 'checks': [ { 'fn': 'required', 'message': 'Email is required' }, { 'fn': 'email', 'message': 'Invalid email' } ], 'validateOn': 'blur' } }
何时使用 JSON‑Render
- 快速原型 – 仅用数分钟即可将提示转换为功能性仪表盘。
- 解耦 UI 生成 – 将设计系统与 LLM 分离。
- 安全 UI 渲染 – 守卫机制防止任意组件注入。
- 跨平台 – 核心可在 React、React‑Native 或任何消费 JSON 的 UI 框架中使用。
开始使用
克隆仓库，添加你自己的 LLM 后端或使用提供的 OpenAI 适配器，随后执行 pnpm dev。新的 React 项目会自动导入渲染逻辑。欢迎根据自己的设计系统扩展目录或替换 registry 为更具样式的组件。
小贴士 – 在
localhost:3000访问内置的 docs & playground，即可在不改动代码的情况下实验提示、更改目录并实时预览。
结论
JSON‑Render 为开发者提供了一条干净、类型安全的路径，让 LLM 能生成 UI 组件。通过始终保持可预测且受限的 JSON 格式，你可以在不牵安全、性能和用户体验的前提下，利用自然语言构建强大 UI。准备将 AI 生成的仪表盘融入你的产品了吗？从 NPM 获取包，今天就开始实验吧。