Skip to content

README_CN.md

Latest commit

 

History

History
205 lines (164 loc) · 5.2 KB

README_CN.md

File metadata and controls

205 lines (164 loc) · 5.2 KB

json-render 功能示例项目

全面展示 vercel-labs/json-render 的所有功能

English

项目简介

json-render 是 Vercel Labs 开源的 Generative UI 框架，让 AI 能够根据自然语言提示生成动态、个性化的 UI，同时保持可预测性和安全性。

核心特性

特性 说明
🛡️ 安全边界 AI 只能使用 Catalog 中定义的组件
📊 可预测输出 JSON 输出始终匹配预定义的 Schema
⚡ 流式渲染 支持增量更新 UI
🌐 跨平台 React, Vue, React Native, Remotion, PDF, Email, Image
📦 内置组件 36 个预构建的 shadcn/ui 组件

快速开始

# 克隆项目
git clone https://github.com/wangjs-jacky/json-render-examples.git

# 进入项目目录
cd json-render-examples

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 访问示例页面
open http://localhost:3000

示例列表

编号 示例 说明
01 基础渲染 Catalog, Registry, Renderer 的基本使用
02 状态管理 StateStore, $state, $bindState
03 可见性条件 visible, $cond, AND/OR 逻辑
04 动态属性 $computed, $template, $cond/$then/$else
05 动作系统 actions, setState, handlers
06 重复作用域 repeat, $item, $index
07 流式渲染 SpecStream, JSON Patch
08 表单验证 checks, validateOn, 内置验证函数
09 shadcn 组件 36 个预构建 shadcn/ui 组件
10 AI 集成 AI SDK, prompt 生成
11 嵌套格式 nestedToFlat 转换
12 Spec 验证 validateSpec, autoFixSpec
13 状态监听 watch, 级联选择

核心概念

三层架构

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Catalog   │────▶│  Registry   │────▶│  Renderer   │
│  (词汇表)   │     │  (实现层)   │     │  (渲染器)   │
└─────────────┘     └─────────────┘     └─────────────┘

Catalog - 定义词汇表

const catalog = defineCatalog(schema, {
  components: {
    Card: {
      props: z.object({ title: z.string() }),
      description: "卡片容器",
    },
  },
  actions: {
    submit: { description: "提交表单" },
  },
});

Registry - 组件实现

const { registry } = defineRegistry(catalog, {
  components: {
    Card: ({ props, children }) => (
      <div className="card">
        <h3>{props.title}</h3>
        {children}
      </div>
    ),
  },
});

Spec - UI 规范

const spec = {
  root: "card-1",
  elements: {
    "card-1": {
      type: "Card",
      props: { title: "Hello" },
      children: [],
    },
  },
};

动态属性表达式

表达式 说明
{ $state: "/path" } 从状态模型读取值
{ $bindState: "/path" } 双向绑定到状态
{ $item: "field" } 从 repeat 项读取字段
{ $index: true } 获取 repeat 索引
{ $cond, $then, $else } 条件表达式
{ $computed: "fn" } 调用计算函数
{ $template: "text ${/path}" } 模板字符串

可见性条件

// 简单条件
visible: { $state: "/isLoggedIn" }

// 反转条件
visible: { $state: "/isAdmin", not: true }

// 比较操作
visible: { $state: "/count", gt: 5 }

// AND 条件
visible: [{ $state: "/a" }, { $state: "/b" }]

// OR 条件
visible: { $or: [{ $state: "/a" }, { $state: "/b" }] }

动作系统

// 内置 setState 动作
on: {
  press: {
    action: "setState",
    actionParams: { statePath: "/count", value: 0 },
    confirm: { title: "确认重置?" },
    onSuccess: { action: "notify", actionParams: { message: "成功" } },
  },
}

Repeat 遍历

{
  type: "TodoItem",
  repeat: { statePath: "/todos", key: "id" },
  props: {
    title: { $item: "title" },
    index: { $index: true },
  },
}

项目结构

json-render-examples/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── page.tsx            # 首页
│   │   ├── layout.tsx          # 布局
│   │   ├── examples/           # 示例页面路由
│   │   └── examples.ts         # 示例配置
│   ├── examples/               # 示例实现
│   │   ├── 01-basic-rendering.tsx
│   │   ├── 02-state-management.tsx
│   │   └── ...
│   └── lib/                    # 工具库
│       ├── catalog.ts
│       └── registry.tsx
├── docs/
│   └── FEATURES.md             # 功能详细文档
├── README.md                   # 英文文档
├── README_CN.md                # 中文文档（本文件）
└── package.json

相关资源

许可证

MIT