项目简介
json-render 是一个生成式 UI 框架，让 AI 根据自然语言提示生成界面，且只能使用你预先定义的组件。输出的 JSON 始终符合你的 schema，安全可靠并支持流式渲染。提供 React、Vue、Svelte、React Native、3D、视频、PDF、邮件和终端等多平台渲染器。
README 预览
# json-render\n\n**The Generative UI framework.**\n\nGenerate dynamic, personalized UIs from prompts without sacrificing reliability. Predefined components and actions for safe, predictable output.\n\n\n \n \n \n \n\n\n```bash\n# for React\nnpm install @json-render/core @json-render/react\n# for React with pre-built shadcn/ui components\nnpm install @json-render/shadcn\n# or for React Native\nnpm install @json-render/core @json-render/react-native\n# or for video\nnpm install @json-render/core @json-render/remotion\n# or for PDF documents\nnpm install @json-render/core @json-render/react-pdf\n# or for HTML email\nnpm install @json-render/core @json-render/react-email @react-email/components @react-email/render\n# or for Vue\nnpm install @json-render/core @json-render/vue\n# or for Svelte\nnpm install @json-render/core @json-render/svelte\n# or for SolidJS\nnpm install @json-render/core @json-render/solid\n# or for terminal UIs\nnpm install @json-render/core @json-render/ink ink react\n# or for full Next.js apps (routes, layouts, SSR, metadata)\nnpm install @json-render/core @json-render/react @json-render/next\n# or for 3D scenes (and gaussian splatting via the GaussianSplat component)\nnpm install @json-render/core @json-render/react-three-fiber @react-three/fiber @react-three/drei three\n```\n\n## Why json-render?\n\njson-render is a **Generative UI** framework: AI generates interfaces from natural language prompts, constrained to components you define. You set the guardrails, AI generates within them:\n\n- **Guardrailed** - AI can only use components in your catalog\n- **Predictable** - JSON output matches your schema, every time\n- **Fast** - Stream and render progressively as the model responds\n- **Cross-Platform** - React, Vue, Svelte, Solid (web), React Native (mobile) from the same catalog\n- **Batteries Included** - 36 pre-built shadcn/ui components ready to use\n\n## Quick Start\n\n### 1. Define Your Catalog\n\n```typescript\nimport { defineCatalog } 常见问题 (5)
故障排除升级到 Zod 4.4 后，如何修复 @json-render 中出现的 "Invalid input: expected nonoptional, received undefined" 可见字段错误？
这是 @json-render（≤0.19.0）中的一个 Zod 4.4 兼容性 bug：元素上可选的 visible 字段在 catalog.validate() 执行期间被错误地当作必填字段处理。修复方法：将所有 @json-render 包（core、react、shadcn、react-email）升级到 v0.20.0 或更高版本——该修复已在 PR #299 中合入，并已在 v0.21.1 搭配 zod 4.6 的环境下验证有效。如果暂时无法升级，可以将 zod 锁定到 4.3.6 作为临时变通方案（pnpm add zod@4.3.6），因为任何 zod 4.4.x 版本都会触发该故障。
故障排除如何修复在 @json-render/solid 中使用 useBoundProp 时出现的 'value is not a function' 错误？
README 中的示例有误：useBoundProp(propsValue, binding) 返回一个元组 [T | undefined, (value: T) => void]，其中第一个元素是原始的 prop 值，而不是 Solid 的 accessor。不要以 value() 的方式调用它。正确用法：
Input: (ctx) => {
const [value, setValue] = useBoundProp(ctx.props.value, ctx.bindings?.value);
return (
<input
value={String(value ?? "")}
onInput={(event) => setValue(event.currentTarget.value)}
/>
);
}在 JSX 中直接读取解析后的值，以便 Solid 跟踪响应式读取，并使用 setter（setValue）进行更新。文档示例已在 PR #401（连同 #381）中修正，涵盖了初始值、外部状态更新和 null 值。
故障排除为什么在 @json-render/solid 的 defineRegistry 回调中会出现 'Cannot read properties of undefined (reading props)' 错误？
defineRegistry() 回调的上下文中不包含 element 字段 —— 旧版 README 示例错误地使用了 renderProps.element.props。该回调通过 ctx.props 直接接收解析后的 props（同时还有 children、emit、on、bindings 和 loading）。请修复你的组件回调，从上下文根部读取 props：
const { registry } = defineRegistry(catalog, {
components: {
Card: (ctx) => (
<div class="card">
<h3>{ctx.props.title as string}</h3>
{ctx.children}
</div>
),
},
});注意：只有较低层的 ComponentRenderer 契约才暴露 element；defineRegistry() 适配器并不暴露。README 示例已在 PR #401 中修正，改为使用解析后的上下文、保持输入值的响应性，并包含渲染器所需的 providers。
故障排除如何修复 json-render 中的 "setValue does not exist on useFieldValidation" 错误？
useFieldValidation 仅处理验证（返回 errors 和 validate）——它不提供 value 或 setValue。这些值应改用 useBoundProp hook 获取。正确用法：
import { useBoundProp, useFieldValidation } from '@json-render/react';
function TextField({ element }) {
const [value, setValue] = useBoundProp(element.props.valuePath);
const { errors, validate } = useFieldValidation(
element.props.valuePath,
element.props.checks
);
return (
<div>
<label>{element.props.label}</label>
<input
value={value || ''}
onChange={(e) => setValue(e.target.value)}
onBlur={() => validate()}
/>
{errors.map((error, i) => (
<p key={i} className="text-red-500 text-sm">{error}</p>
))}
</div>
);
}这是一个文档错误，已在 issue #107 中修复。不通过 useBoundProp 的 setValue 而直接设置数据会绕过绑定层，这正是验证无法正确触发的原因。
故障排除为什么在 json-render 的 action params 中，$item 返回的是类似 "list/0/url" 的路径字符串，而不是实际值？
在 json-render 0.19.0（React）中，在重复元素（repeat 绑定 /list）内部的 action.params 中使用 { "$item": "url" } 时，会被错误地解析为 JSON 路径字符串（例如 "list/0/url"），而不是字段的实际值。**解决方法：** 在 action params 中将 $item 替换为 $bindItem："params": { "url": { "$bindItem": "url" } } —— 这样可以正确返回字段的实际值。