json-ui-renderer

JSON 驱动的 UI 组件渲染器。传入 JSON schema，渲染出生产级交互组件。

基于 shadcn/ui + Tailwind CSS 构建，支持 45+ 组件类型，样式完全隔离，不影响宿主应用。

安装

# npm
npm install json-ui-renderer

# pnpm
pnpm add json-ui-renderer

# yarn
yarn add json-ui-renderer

Peer dependencies：react >= 18、react-dom >= 18

快速开始

1. 引入样式

// 在你的入口文件 (main.tsx / index.tsx) 中用 JS import 引入
import 'json-ui-renderer/renderer.css';

⚠️ 重要：必须用 JS import 引入，不要在 CSS 中用 @import "json-ui-renderer/renderer.css"。 因为 Tailwind 4 的 Vite 插件会把 CSS @import 的内容纳入处理管线，导致已编译的 renderer.css 被重新解析出错。

一行搞定。无需安装 Tailwind，无需额外配置。兼容 Tailwind 3 / 4 或无 Tailwind 项目。

2. 使用组件

import { ComponentRenderer } from 'json-ui-renderer';
import type { ComponentNode, RendererEvent } from 'json-ui-renderer';

const schema: ComponentNode = {
  component: 'Form',
  props: { title: '联系我们', submitLabel: '提交', columns: 2 },
  children: [
    { component: 'Input', props: { name: 'name', label: '姓名', required: true } },
    { component: 'Input', props: { name: 'email', label: '邮箱', type: 'email', required: true } },
    { component: 'Textarea', props: { name: 'message', label: '留言', rows: 4 }, style: { gridColumn: 'span 2' } },
  ],
};

function App() {
  const handleEvent = (event: RendererEvent) => {
    console.log(event.type, event.payload);
    // event.type: 'form:submit' | 'button:click' | 'table:page' | ...
  };

  return <ComponentRenderer schema={schema} onEvent={handleEvent} dark />;
}

Props

| Prop | 类型 | 说明 | |------|------|------| | schema | ComponentNode \| ComponentNode[] | JSON schema | | onEvent | (event: RendererEvent) => void | 事件回调 | | dark | boolean | 深色模式 | | theme | string | 主题色：purple / blue / green / orange / rose | | className | string | 自定义 class |

JSON Schema 结构

{
  "component": "ComponentType",
  "props": {},
  "children": [],
  "style": {}
}

支持的组件

表单输入

Input · Textarea · NumberInput · Select · MultiSelect · Checkbox · Radio · Switch · DatePicker · Slider · TagInput · FileUpload

表单容器

Form · StepForm · FilterBar

数据展示

DataTable · StatCard · DescriptionList · Timeline · Steps · Progress · Badge · Skeleton · Calendar

反馈

Alert · Empty · Loading · Dialog · ConfirmDialog

布局

Card · Tabs · Accordion · Grid · Stack · Breadcrumb · PageHeader · ScrollArea · Separator

覆盖层

Tooltip · Popover · DropdownMenu · Command · Drawer

事件系统

所有交互通过 onEvent 回调统一输出：

interface RendererEvent {
  type: string;       // 'form:submit' | 'button:click' | 'table:page' | ...
  component: string;  // 'Form' | 'Button' | 'DataTable' | ...
  name?: string;      // 组件名称
  payload: Record<string, unknown>;
  timestamp: number;
}

| 事件 | 来源 | Payload | |------|------|---------| | form:submit | Form, StepForm | 所有字段值 | | button:click | Button, DataTable | {action, label} 或 {action, row} | | table:page | DataTable | {page, limit} | | dialog:confirm | Dialog, ConfirmDialog | {} | | filter:search | FilterBar | 筛选条件 | | form:change | DatePicker, Slider, FileUpload | {value} |

样式隔离

• 所有 CSS 变量使用 --jur-* 前缀，不与宿主应用冲突
• 组件样式 scope 在 .json-ui-renderer 容器内
• 不注入任何全局样式（无 :root、body、* 污染）
• contain: layout style 防止布局泄漏
• Radix Portal 组件（Dialog、Popover）渲染在容器内部

DataTable 增强

{
  "component": "DataTable",
  "props": {
    "title": "订单列表",
    "columns": [
      { "key": "name", "title": "客户", "sortable": true },
      { "key": "status", "title": "状态", "type": "tag", "tagMap": {
        "active": { "label": "活跃", "color": "green" },
        "pending": { "label": "待处理", "color": "orange" }
      }},
      { "key": "amount", "title": "金额", "type": "currency", "align": "right" },
      { "key": "actions", "title": "操作", "type": "actions", "actions": [
        { "label": "查看", "event": "view" },
        { "label": "删除", "event": "delete", "danger": true, "confirm": "确认删除？" }
      ]}
    ],
    "data": [...],
    "toolbar": [{ "label": "新建", "type": "primary", "event": "create" }],
    "pagination": true,
    "pageSize": 10
  }
}

多步表单

{
  "component": "StepForm",
  "props": {
    "title": "注册",
    "submitLabel": "完成",
    "steps": [
      {
        "title": "基本信息",
        "fields": [
          { "component": "Input", "props": { "name": "name", "label": "姓名" } }
        ]
      },
      {
        "title": "上传文件",
        "fields": [
          { "component": "FileUpload", "props": { "name": "doc", "label": "文件", "multiple": true } }
        ]
      }
    ]
  }
}

提交时自动收集所有步骤的数据（包括 FileUpload、DatePicker 等自定义组件）。

License

MIT