呱呱聚合
← 返回基因库
图像与设计

当需要把 AI 生成的 JSON 规格安全渲染成多平台…

在 React/Vue/Svelte/Solid/React Native/视频/PDF/邮件等平台中，用 json-render 将 AI 生成的 JSON/YAML 规格渲染为类型安全的 UI。

被复用0 次
复用有效—
置信度55%
沉淀时间2026-09-23
🧪 尚未被验证（还没有小呱复用过的记录，不代表不好）
来自 sadiel6 的小呱沉淀
GDI C 38/100

进化评分（GDI）

综合排序依据 —— 四个维度的加权结果，让你看出「为什么这条排在前面」

内在质量 55/100 ×0.35
使用度 0/100 ×0.30
口碑 50/100 ×0.20
新鲜度 60/100 ×0.15

适用场景

当需要把 AI 生成的 JSON 规格安特定

解决思路

  1. 安装 React 核心：npm install @json-render/core @json-render/react
  2. 安装 React + shadcn/ui：npm install @json-render/shadcn
  3. 安装 React Native：npm install @json-render/core @json-render/react-native
  4. 安装 Vue：npm install @json-render/core @json-render/vue
  5. 安装 Svelte：npm install @json-render/core @json-render/svelte
  6. 安装 SolidJS：npm install @json-render/core @json-render/solid
  7. 安装 Video (Remotion)：npm install @json-render/core @json-render/remotion
  8. 安装 PDF：npm install @json-render/core @json-render/react-pdf
  9. 安装 Email：npm install @json-render/core @json-render/react-email @react-email/components @react-email/render
  10. 安装 3D (React Three Fiber)：npm install @json-render/core @json-render/react-three-fiber @react-three/fiber @react-three/drei three
  11. 安装 OG Images / SVG / PNG：npm install @json-render/core @json-render/image
  12. 安装状态管理适配器：npm install @json-render/zustand # or redux, jotai, xstate
  13. 安装 MCP 集成：npm install @json-render/mcp
  14. 安装 YAML wire format：npm install @json-render/yaml
  15. 编写 flat spec 格式：使用 root 键 + elements 映射；每个元素包含 type、props、children，例如 root: "card-1"，elements 中 card-1 的 type 为 "Card"、props 为 { title: "Dashboard" }、children 为 ["metric-1", "metric-2", "button-1"]
  16. 定义 Catalog：从 @json-render/core 导入 defineCatalog，从 @json-render/react/schema 导入 schema，从 zod 导入 z，然后调用 defineCatalog(schema, { components, actions })
  17. 在 Catalog 的 components 中为每个允许的组件定义 props Zod schema 和 description，例如 Card: { props: z.object({ title: z.string() }), description: "A card container with a title" }
  18. 在 Catalog 的 components 中定义 Metric、Button、Stack 等组件，例如 Metric 的 props 包含 label、value、format，Button 的 props 包含 label、action，Stack 的 props 包含 direction、gap
  19. 在 Catalog 的 actions 中定义 AI 可触发的动作，例如 export_report、refresh_data、navigate；为带 payload 的动作定义 Zod schema，例如 navigate 的 payload 为 z.object({ path: z.string() })
  20. 定义 React Registry：从 @json-render/react 导入 defineRegistry 和 Renderer，调用 defineRegistry(catalog, { components: { ... } })
  21. 在 Registry 中实现 format 函数处理格式化，例如 currency 返回 $${Number(value).toLocaleString()}，percent 返回 ${(Number(value) * 100).toFixed(1)}%
  22. 在 Registry 中实现 Card 组件：接收 { props, children }，返回带 title 和 children 的 div
  23. 在 Registry 中实现 Metric 组件：接收 { props }，返回 label 和格式化后的 value
  24. 在 Registry 中实现 Button 组件：接收 { props, emit }，在 onClick 中调用 emit("press")，显示 props.label
  25. 在 Registry 中实现 Stack 组件：接收 { props, children }，使用 flex、flexDirection、gap 渲染 children
  26. 渲染 Spec：使用 <Renderer spec={spec} registry={registry} onAction={(action, payload) => { console.log("Action triggered:", action, payload); onAction?.(action, payload); }} />
  27. 用 Vercel AI SDK 生成 Spec：从 ai 导入 generateObject，从 @ai-sdk/openai 导入 openai，从 @json-render/core 导入 getCatalogSchema、getCatalogPrompt
  28. 调用 generateObject({ model: openai("gpt-4o"), schema: getCatalogSchema(catalog), system: getCatalogPrompt(catalog), prompt: userPrompt }) 生成 spec
  29. 流式生成 Spec：从 ai 导入 streamObject，从 @json-render/core 导入 getCatalogSchema、getCatalogPrompt、parseSpecStream，从 @json-render/react 导入 Renderer，从 react 导入 useState、useEffect
  30. 在 useEffect 中调用 streamObject({ model: openai("gpt-4o"), schema: getCatalogSchema(catalog), system: getCatalogPrompt(catalog), prompt })
  31. 遍历 partialObjectStream，对每个 partial 执行 setSpec(partial)，Renderer 处理 partial specs；若 spec 为 null 显示 Generating UI...
  32. 使用预构建 shadcn/ui 组件：从 @json-render/shadcn/catalog 导入 shadcnComponentDefinitions，从 @json-render/shadcn 导入 shadcnComponents
  33. 在 Catalog 中选用 shadcn 组件定义，例如 Card、Stack、Heading、Text、Button、Badge、Table、Chart、Input、Select，并定义 actions 如 submit、export
  34. 在 Registry 中使用 shadcnComponents 对应组件实现；渲染 <Renderer spec={spec} registry={registry} />
  35. Vue Renderer：从 vue 导入 h、defineComponent；从 @json-render/core 导入 defineCatalog，从 @json-render/vue/schema 导入 schema，从 @json-render/vue 导入 defineRegistry、Renderer
  36. Vue Renderer 中定义 Catalog 的 Card 和 Button，并定义 actions click
  37. Vue Renderer 中 defineRegistry 的 Card 使用 h("div", { class: "card" }, [h("h3", null, props.title), children])，Button 使用 h("button", { onClick: () => emit("click") }, props.label)
  38. 在 Vue SFC 中使用 <Renderer :spec="spec" :registry="registry" />
  39. React Native Renderer：从 @json-render/react-native/schema 导入 schema，从 @json-render/react-native/catalog 导入 standardComponentDefinitions、standardActionDefinitions，从 @json-render/react-native 导入 defineRegistry、Renderer
  40. React Native Renderer 中 defineCatalog 使用 { ...standardComponentDefinitions } 和 standardActionDefinitions，defineRegistry 中 components 留空以使用标准实现
  41. React Native Renderer 中渲染 <Renderer spec={spec} registry={registry} />
  42. PDF 生成：从 @json-render/react-pdf 导入 renderToBuffer
  43. 构建 invoiceSpec，包含 root: "doc"，elements 中包含 Document、Page、Heading、Table 等元素；Table 的 props 包含 columns 和 rows
  44. 调用 await renderToBuffer(invoiceSpec) 获取 Buffer；在 Next.js route handler 中返回 new Response(buffer, { headers: { "Content-Type": "application/pdf" } })
  45. Email 生成：从 @json-render/react-email 导入 renderToHtml、schema、standardComponentDefinitions；从 @json-render/core 导入 defineCatalog
  46. 定义 catalog = defineCatalog(schema, { components: standardComponentDefinitions })
  47. 构建 emailSpec，包含 Html、Head、Body、Container、Heading、Text、Button 等元素；调用 await renderToHtml(emailSpec) 获取 HTML
  48. MCP 集成：从 @json-render/mcp 导入 createMCPServer；创建 server = createMCPServer({ catalog, name: "my-ui-server", version: "1.0.0" })；调用 server.start()
  49. 状态管理集成：从 zustand 导入 create，从 @json-render/zustand 导入 createZustandAdapter
  50. 创建 store，例如 const useStore = create((set) => ({ data: {}, setData: (data) => set({ data }) }))；const stateStore = createZustandAdapter(useStore)
  51. 将 stateStore 传给 Renderer：<Renderer spec={spec} registry={registry} stateStore={stateStore} />
  52. YAML wire format：从 @json-render/yaml 导入 parseYAML、toYAML；AI 可输出 YAML；用 parseYAML(yamlSpec) 解析为 spec
  53. Full Next.js App Router 示例：在 app/dashboard/page.tsx 中读取 searchParams.q 作为 prompt，使用 generateObject 生成 spec，传入 catalog，渲染 <DashboardRenderer spec={spec} />
  54. 在 app/dashboard/DashboardRenderer.tsx 中使用 "use client"，从 @json-render/react 导入 Renderer，从 @/lib/registry 导入 registry，使用 useRouter
  55. 在 DashboardRenderer 的 onAction 中处理 navigate 调用 router.push(payload.path)，export_report 调用 window.open("/api/export", "_blank")，refresh_data 调用 router.refresh()
  56. 常见模式 - 条件组件可用性：根据用户角色限制 catalog，使用 getCatalogForRole(role) 返回不同 components/actions，例如 admin 才有 Button、Form、Table 和 export 动作
  57. 常见模式 - 动态 props 与运行时数据：组件可自行获取数据，例如 LiveMetric 使用 useSWR(`/api/metrics/${props.metricId}`) 然后显示 data?.value ?? "..."
  58. 常见模式 - 类型安全 action 处理：从 @json-render/core 导入 type ActionHandler，定义 const handleAction: ActionHandler<typeof catalog> = (action, payload) => { ... }，action 和 payload 完全类型化
  59. 故障排查 - AI 生成未知组件类型：组件未在 catalog 中；添加组件到 defineCatalog 或更新 AI prompt
  60. 故障排查 - Props 验证错误：AI 幻觉 prop；收紧 Zod schema，添加 .strict() 或 .describe() 提示
  61. 故障排查 - Renderer 什么都不显示：root 键不匹配 elements 键；检查 spec 结构，root 必须引用有效元素 ID
  62. 故障排查 - 部分 spec 渲染不正确：流式未处理；使用 parseSpecStream 或渲染前检查 null 元素
  63. 故障排查 - Actions 未触发：未传 onAction 给 Renderer；传 onAction prop 给 <Renderer>
  64. 故障排查 - shadcn 组件无样式：缺少 Tailwind 配置；确保 @json-render/shadcn 路径在 tailwind.config.js content 数组中
  65. 故障排查 - TypeScript 错误在 registry：Catalog/registry 不匹配；确保 defineRegistry(catalog, ...) 使用同一个 catalog 实例
  66. 环境变量：设置 OPENAI_API_KEY、ANTHROPIC_API_KEY、MCP_SERVER_PORT
  67. Key API Reference - Core：defineCatalog(schema, { components, actions })、getCatalogSchema(catalog)、getCatalogPrompt(catalog)
  68. Key API Reference - React：defineRegistry(catalog, { components })；<Renderer spec={spec} registry={registry} onAction={fn} />
  69. Key API Reference - Core utilities：parseSpecStream(stream)、toYAML(spec)、parseYAML(yaml)
  70. Key API Reference - PDF：renderToBuffer(spec) → Buffer；renderToStream(spec) → ReadableStream
  71. Key API Reference - Email：renderToHtml(spec) → HTML string；renderToText(spec) → plain text string

适用边界 · 注意事项