JSON Forms - Ant Design Renderers

这是 JSON Forms 的 Ant Design 渲染器集合，提供了基于 Ant Design 5.x 的表单控件和布局组件。

简介

boyc-jsonforms-antd-renderers 是一套完整的 JSON Forms 渲染器实现，使用 Ant Design 组件库构建。它提供了与 boyc-jsonforms-material-renderers 功能对等的渲染器，让您可以使用 Ant Design 的设计语言来渲染 JSON Schema 驱动的表单。

特性

• 🎨 Ant Design 5.x - 基于最新的 Ant Design 设计系统
• 🌈 主题支持 - 原生支持亮色和暗色主题，可自定义 Design Token
• 📱 响应式设计 - 自适应不同屏幕尺寸
• ♿ 无障碍支持 - 遵循 WCAG 标准，支持键盘导航和屏幕阅读器
• 🔧 TypeScript - 完全类型化，提供优秀的开发体验
• 🎯 完全兼容 - 与 JSON Forms 核心完全兼容，支持所有标准功能
• 🚀 高性能 - 优化的渲染性能，支持大型表单
• 🌍 国际化 - 支持 Ant Design 的国际化配置

安装

npm install boyc-jsonforms-antd-renderers boyc-jsonforms-core boyc-jsonforms-react antd

或使用 yarn:

yarn add boyc-jsonforms-antd-renderers boyc-jsonforms-core boyc-jsonforms-react antd

或使用 pnpm:

pnpm add boyc-jsonforms-antd-renderers boyc-jsonforms-core boyc-jsonforms-react antd

快速开始

import React from 'react';
import { JsonForms } from 'boyc-jsonforms-react';
import { antdRenderers, antdCells } from 'boyc-jsonforms-antd-renderers';
import { ConfigProvider } from 'antd';

const schema = {
  type: 'object',
  properties: {
    name: {
      type: 'string',
      minLength: 3,
    },
    age: {
      type: 'integer',
      minimum: 0,
    },
  },
  required: ['name'],
};

const uischema = {
  type: 'VerticalLayout',
  elements: [
    {
      type: 'Control',
      scope: '#/properties/name',
    },
    {
      type: 'Control',
      scope: '#/properties/age',
    },
  ],
};

const initialData = {};

function App() {
  const [data, setData] = React.useState(initialData);

  return (
    <ConfigProvider>
      <JsonForms
        schema={schema}
        uischema={uischema}
        data={data}
        renderers={antdRenderers}
        cells={antdCells}
        onChange={({ data }) => setData(data)}
      />
    </ConfigProvider>
  );
}

export default App;

主题配置

使用暗色主题

使用 Ant Design 的 ConfigProvider 来配置主题：

import { ConfigProvider, theme } from 'antd';
import { JsonForms } from 'boyc-jsonforms-react';
import { antdRenderers, antdCells } from 'boyc-jsonforms-antd-renderers';

function App() {
  return (
    <ConfigProvider
      theme={{
        algorithm: theme.darkAlgorithm, // 使用暗色主题
      }}
    >
      <JsonForms
        schema={schema}
        uischema={uischema}
        data={data}
        renderers={antdRenderers}
        cells={antdCells}
        onChange={({ data }) => setData(data)}
      />
    </ConfigProvider>
  );
}

自定义主题颜色

import { ConfigProvider } from 'antd';

function App() {
  return (
    <ConfigProvider
      theme={{
        token: {
          colorPrimary: '#00b96b', // 自定义主色
          borderRadius: 4, // 自定义圆角
        },
      }}
    >
      <JsonForms
        schema={schema}
        uischema={uischema}
        data={data}
        renderers={antdRenderers}
        cells={antdCells}
        onChange={({ data }) => setData(data)}
      />
    </ConfigProvider>
  );
}

动态切换主题

import React, { useState } from 'react';
import { ConfigProvider, theme, Switch } from 'antd';
import { JsonForms } from 'boyc-jsonforms-react';
import { antdRenderers, antdCells } from 'boyc-jsonforms-antd-renderers';

function App() {
  const [isDark, setIsDark] = useState(false);

  return (
    <ConfigProvider
      theme={{
        algorithm: isDark ? theme.darkAlgorithm : theme.defaultAlgorithm,
      }}
    >
      <div>
        <Switch
          checked={isDark}
          onChange={setIsDark}
          checkedChildren="🌙"
          unCheckedChildren="☀️"
        />
        <JsonForms
          schema={schema}
          uischema={uischema}
          data={data}
          renderers={antdRenderers}
          cells={antdCells}
          onChange={({ data }) => setData(data)}
        />
      </div>
    </ConfigProvider>
  );
}

支持的控件

基础控件

• TextControl - 文本输入
• NumberControl - 数字输入
• IntegerControl - 整数输入
• BooleanControl - 复选框
• BooleanToggleControl - 开关
• DateControl - 日期选择器
• DateTimeControl - 日期时间选择器
• TimeControl - 时间选择器

选择控件

• EnumControl - 下拉选择
• RadioGroupControl - 单选按钮组
• OneOfEnumControl - OneOf 枚举选择
• OneOfRadioGroupControl - OneOf 单选按钮组
• AnyOfStringOrEnumControl - AnyOf 字符串或枚举选择

其他控件

• SliderControl - 滑块
• NativeControl - 原生控件

支持的布局

• VerticalLayout - 垂直布局
• HorizontalLayout - 水平布局
• GroupLayout - 分组布局（使用 Card 组件）
• CategorizationLayout - 分类布局（使用 Tabs 组件）
• CategorizationStepperLayout - 步进式分类布局（使用 Steps 组件）
• ArrayLayout - 数组布局（使用 Collapse 组件）

支持的复杂渲染器

• ArrayControlRenderer - 数组控件渲染器（使用 Table 组件）
• ObjectRenderer - 对象渲染器
• AllOfRenderer - AllOf 组合渲染器
• AnyOfRenderer - AnyOf 组合渲染器
• OneOfRenderer - OneOf 组合渲染器
• EnumArrayRenderer - 枚举数组渲染器（使用 Checkbox.Group）

支持的单元格渲染器

用于表格或数组中的单个数据项：

• TextCell - 文本单元格
• NumberCell - 数字单元格
• IntegerCell - 整数单元格
• BooleanCell - 布尔单元格
• BooleanToggleCell - 开关单元格
• DateCell - 日期单元格
• TimeCell - 时间单元格
• EnumCell - 枚举单元格
• OneOfEnumCell - OneOf 枚举单元格

从 Material-UI Renderers 迁移

如果您正在使用 boyc-jsonforms-material-renderers，可以按照以下步骤迁移到 boyc-jsonforms-antd-renderers：

1. 更新依赖

卸载 Material-UI 相关依赖：

npm uninstall boyc-jsonforms-material-renderers @mui/material @mui/icons-material @emotion/react @emotion/styled

安装 Ant Design 相关依赖：

npm install boyc-jsonforms-antd-renderers antd

2. 更新导入

之前（Material-UI）：

import {
  materialRenderers,
  materialCells,
} from 'boyc-jsonforms-material-renderers';
import { ThemeProvider, createTheme } from '@mui/material/styles';

之后（Ant Design）：

import { antdRenderers, antdCells } from 'boyc-jsonforms-antd-renderers';
import { ConfigProvider, theme } from 'antd';

3. 更新主题配置

之前（Material-UI）：

const muiTheme = createTheme({
  palette: {
    mode: 'dark',
    primary: {
      main: '#00b96b',
    },
  },
});

<ThemeProvider theme={muiTheme}>
  <JsonForms
    renderers={materialRenderers}
    cells={materialCells}
    // ...
  />
</ThemeProvider>;

之后（Ant Design）：

<ConfigProvider
  theme={{
    algorithm: theme.darkAlgorithm,
    token: {
      colorPrimary: '#00b96b',
    },
  }}
>
  <JsonForms
    renderers={antdRenderers}
    cells={antdCells}
    // ...
  />
</ConfigProvider>

4. 更新渲染器引用

如果您在代码中直接引用了特定的渲染器组件，需要更新导入路径：

之前（Material-UI）：

import { MaterialTextControl } from 'boyc-jsonforms-material-renderers';

之后（Ant Design）：

import { AntdTextControl } from 'boyc-jsonforms-antd-renderers';

5. 功能对等性

boyc-jsonforms-antd-renderers 提供了与 boyc-jsonforms-material-renderers 完全对等的功能：

• ✅ 所有控件类型
• ✅ 所有布局类型
• ✅ 所有复杂渲染器
• ✅ 所有单元格渲染器
• ✅ 验证错误显示
• ✅ 禁用状态
• ✅ 必填字段标识
• ✅ 主题支持

6. 注意事项

• 日期处理：Ant Design 使用 dayjs 而不是 moment，但 API 基本兼容
• 样式系统：Ant Design 使用 Design Token 而不是 CSS-in-JS
• 组件 API：某些组件的 props 可能略有不同，但核心功能保持一致

国际化

使用 Ant Design 的国际化配置：

import { ConfigProvider } from 'antd';
import zhCN from 'antd/locale/zh_CN';
import enUS from 'antd/locale/en_US';

function App() {
  return (
    <ConfigProvider locale={zhCN}>
      <JsonForms
        schema={schema}
        uischema={uischema}
        data={data}
        renderers={antdRenderers}
        cells={antdCells}
        onChange={({ data }) => setData(data)}
      />
    </ConfigProvider>
  );
}

示例

查看 example 目录获取完整的示例应用，展示了所有渲染器的使用方法。

运行示例应用：

cd packages/antd-renderers
npm run dev

测试

单元测试

运行单元测试：

npm test

运行测试并生成覆盖率报告：

npm run test-cov

E2E 测试

本包包含完整的 Cypress E2E 测试套件，覆盖所有主要功能。

运行 E2E 测试

方式 1: 自动启动服务器（推荐）

# 交互模式
npm run test:e2e:open

# Headless 模式（CI/CD）
npm run test:e2e

方式 2: 使用已运行的开发服务器

如果你已经在运行 npm run dev，可以在另一个终端运行：

# 交互模式
npm run cypress:open

# Headless 模式
npm run cypress:run

# 指定浏览器
npm run cypress:run:chrome
npm run cypress:run:firefox
npm run cypress:run:edge

E2E 测试覆盖

E2E 测试覆盖以下场景：

• ✅ 所有基础控件（文本、数字、布尔、枚举、日期等）
• ✅ 所有布局渲染器（垂直、水平、分组、分类等）
• ✅ 复杂渲染器（数组、对象、组合器）
• ✅ 验证和错误处理
• ✅ 主题切换（明亮/暗色）
• ✅ 示例场景（person、arrays、dates 等）
• ✅ 可访问性特性
• ✅ 性能测试

详细的测试文档请查看 cypress/README.md。

API 文档

详细的 API 文档请参考：

• JSON Forms 官方文档
• Ant Design 官方文档
• 本包的 API 文档 - 使用 TypeDoc 生成的完整 API 文档
• 本包的 TypeScript 类型定义

生成 API 文档

如果您需要重新生成 API 文档，可以运行：

npm run doc

生成的文档将位于 docs 目录下。

许可证

MIT License

Copyright (c) 2017-2019 EclipseSource Munich

贡献

欢迎贡献！请查看 CONTRIBUTING.md 了解更多信息。

相关链接

• JSON Forms 官网
• Ant Design 官网
• GitHub 仓库