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 的国际化配置

安装

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

或使用 yarn:

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

或使用 pnpm:

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

快速开始

`tsx
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 (

schema={schema}
uischema={uischema}
data={data}
renderers={antdRenderers}
cells={antdCells}
onChange={({ data }) => setData(data)}
/>

);
}

export default App;
`

主题配置

$3

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

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

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

);
}
`

$3

`tsx
import { ConfigProvider } from 'antd';

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

);
}
`

$3

`tsx
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 (
theme={{
algorithm: isDark ? theme.darkAlgorithm : theme.defaultAlgorithm,
}}
>

checked={isDark}
onChange={setIsDark}
checkedChildren="🌙"
unCheckedChildren="☀️"
/>
schema={schema}
uischema={uischema}
data={data}
renderers={antdRenderers}
cells={antdCells}
onChange={({ data }) => setData(data)}
/>

);
}
`

支持的控件

$3

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

$3

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

$3

- 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：

$3

卸载 Material-UI 相关依赖：

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

安装 Ant Design 相关依赖：

`bash
npm install boyc-jsonforms-antd-renderers antd
`

$3

之前（Material-UI）：

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

之后（Ant Design）：

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

$3

之前（Material-UI）：

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


renderers={materialRenderers}
cells={materialCells}
// ...
/>
;
`

之后（Ant Design）：

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

`

$3

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

之前（Material-UI）：

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

之后（Ant Design）：

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

$3

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

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

$3

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

国际化

使用 Ant Design 的国际化配置：

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

function App() {
return (

schema={schema}
uischema={uischema}
data={data}
renderers={antdRenderers}
cells={antdCells}
onChange={({ data }) => setData(data)}
/>

);
}
`

示例

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

运行示例应用：

`bash
cd packages/antd-renderers
npm run dev
`

测试

$3

运行单元测试：

`bash
npm test
`

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

`bash
npm run test-cov
`

$3

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

#### 运行 E2E 测试

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

`bash

交互模式

npm run test:e2e:open

Headless 模式（CI/CD）

npm run test:e2e
`

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

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

`bash

交互模式

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 类型定义

$3

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

`bash
npm run doc
`

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

许可证

MIT License

Copyright (c) 2017-2019 EclipseSource Munich

贡献

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

相关链接

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