MobX State Tree converter for JSON Forms
npm install jsonforms-mst-converterbash
npm install boyc-jsonforms-mst-converter mobx mobx-state-tree boyc-jsonforms-core
`
或使用 yarn:
`bash
yarn add boyc-jsonforms-mst-converter mobx mobx-state-tree boyc-jsonforms-core
`
快速开始
$3
`typescript
import { toMstTypesDef } from 'boyc-jsonforms-mst-converter';
// 定义 JSON Schema
const schema = {
type: 'object',
properties: {
name: { type: 'string', minLength: 3 },
age: { type: 'number', minimum: 0 },
email: { type: 'string', format: 'email' }
},
required: ['name', 'email']
};
// 转换为 MST 类型
const result = toMstTypesDef(schema);
// 使用 MST 类型创建实例
const user = result.mainType.create({
name: 'Alice',
age: 30,
email: 'alice@example.com'
});
console.log(user.name); // 'Alice'
`
$3
`typescript
import { types } from 'mobx-state-tree';
import { toJsonSchemaDef } from 'boyc-jsonforms-mst-converter';
// 定义 MST 模型
const UserModel = types.model('User', {
name: types.string,
age: types.number,
email: types.string
});
// 转换为 JSON Schema
const schema = toJsonSchemaDef(UserModel);
console.log(schema);
// {
// type: 'object',
// properties: {
// name: { type: 'string' },
// age: { type: 'number' },
// email: { type: 'string' }
// },
// required: ['name', 'age', 'email']
// }
`
$3
`typescript
import { toMstTypesDef } from 'boyc-jsonforms-mst-converter';
const schema = {
type: 'object',
properties: {
name: { type: 'string' }
}
};
const uiSchema = {
type: 'Control',
scope: '#/properties/name',
label: '姓名'
};
// 转换并保留 UI Schema
const result = toMstTypesDef(schema, uiSchema);
// 访问原始 schema 和 uiSchema
console.log(result.jsonFormModel.jsonSchema.json); // 原始 JSON Schema
console.log(result.jsonFormModel.uiSchema.json); // 原始 UI Schema
`
API 概览
$3
#### toMstTypesDef(jsonSchema, uiSchema?)
将 JSON Schema 转换为 MST 类型定义。
参数:
- jsonSchema: JsonSchemaProperties - JSON Schema 对象
- uiSchema?: UISchemaElement - 可选的 UI Schema
返回:
`typescript
{
mainType: IAnyModelType; // 主 MST 模型类型
subTypes?: Map; // 子类型(来自 definitions)
jsonFormModel: JsonFormModelInstance; // 包含原始 schema 的模型
}
`
#### toJsonSchemaDef(mstType)
将 MST 类型转换为 JSON Schema。
参数:
- mstType: IAnyModelType - MST 模型类型
返回:
- JsonSchemaProperties - JSON Schema 对象
$3
#### JsonSchema
存储 JSON Schema 的 MST 模型。
`typescript
const jsonSchema = JsonSchema.create({
schema: { type: 'string' }
});
console.log(jsonSchema.json); // { type: 'string' }
`
#### UISchema
存储 UI Schema 的 MST 模型。
`typescript
const uiSchema = UISchema.create({
schema: { type: 'Control', scope: '#/properties/name' }
});
console.log(uiSchema.json); // { type: 'Control', scope: '#/properties/name' }
`
#### JsonFormModel
组合 JSON Schema 和 UI Schema 的模型。
`typescript
const formModel = JsonFormModel.create();
formModel.init(
{ type: 'string' },
{ type: 'Control', scope: '#' }
);
console.log(formModel.json);
// {
// jsonSchema: { type: 'string' },
// uiSchema: { type: 'Control', scope: '#' }
// }
`
$3
#### 类型映射
- getMstTypeFromJsonSchemaType(schemaType, format?) - 获取对应的 MST 类型
- getJsonSchemaTypeFromMstType(mstType) - 获取对应的 JSON Schema 类型
- isMstPrimitiveType(mstType) - 检查是否为基本类型
- isJsonSchemaPrimitiveType(schemaType) - 检查是否为基本类型
#### Schema 解析
- resolveRef(ref, rootSchema) - 解析 $ref 引用
- extractDefinitions(schema) - 提取 definitions
- generateModelName(baseName, existingNames) - 生成唯一模型名称
#### 验证约束
- createRefinementFromConstraints(baseType, constraints, typeName) - 创建 MST refinement
- extractConstraintsFromSchema(schema) - 提取验证约束
- hasConstraints(schema) - 检查是否包含约束
支持的 JSON Schema 特性
$3
- ✅ string
- ✅ number
- ✅ integer
- ✅ boolean
- ✅ null
$3
- ✅ object - 对象类型
- ✅ array - 数组类型
- ✅ properties - 对象属性
- ✅ required - 必需属性
- ✅ items - 数组项类型
$3
- ✅ date - 日期
- ✅ date-time - 日期时间
- ✅ email - 邮箱
- ✅ 其他字符串格式
$3
- ✅ minLength / maxLength - 字符串长度
- ✅ pattern - 正则表达式
- ✅ minimum / maximum - 数值范围
- ✅ exclusiveMinimum / exclusiveMaximum - 独占数值范围
- ✅ multipleOf - 倍数
- ✅ minItems / maxItems - 数组长度
- ✅ uniqueItems - 数组唯一性
- ✅ minProperties / maxProperties - 对象属性数量
$3
- ✅ $ref - 引用
- ✅ definitions - 定义
- ✅ oneOf - 枚举(const 值)
- ⚠️ allOf - 部分支持
- ⚠️ anyOf - 部分支持
$3
- ✅ default - 默认值
- ✅ const - 常量值
- ✅ enum - 枚举值
示例
查看 examples 目录获取更多示例:
- 基本类型转换
- 复杂对象
- 数组和嵌套
- 引用和 Definitions
- 验证约束
- JSON Forms 集成
限制和注意事项
1. 循环引用:使用 types.late() 处理,但可能影响类型推断
2. 复杂组合:allOf、anyOf 的复杂组合可能无法完美转换
3. 自定义格式:只支持标准的 JSON Schema 格式
4. Refinement 反向转换:从 MST refinement 提取约束信息有限
在线演示
启动交互式演示页面:
`bash
npm run dev
`
演示页面将在 http://localhost:12116 打开,包含 10 个精心设计的示例,展示:
- 基本类型转换
- 复杂对象和数组
- 验证约束
- 双向转换测试
- JSON Forms 集成
特色功能:
- 🎯 下拉选择器快速切换示例
- 🔗 URL Hash 支持(可直接访问特定示例)
- ⏮️ 支持浏览器前进/后退
查看 demo/README.md 了解更多详情。
开发
`bash
安装依赖
npm install
运行测试
npm test
运行测试(watch 模式)
npm run test:watch
生成测试覆盖率
npm run test:coverage
构建
npm run build
类型检查
npm run typecheck
Lint
npm run lint
启动演示页面
npm run dev
``