@xiaohaih/json-form-core

@xiaohaih/json-form-core 是 json-form 库的核心模块，提供零 UI 依赖的纯逻辑实现。它通过组合式 API 实现表单项的状态管理、依赖关系追踪、数据源管理等核心功能。

✨ 特性

• 🚀 零 UI 依赖: 纯逻辑实现，不依赖任何 UI 框架
• 🔄 组合式 API: 基于 Vue 3 Composition API，支持 Vue 2.7+
• 📦 TypeScript: 完整的类型定义和类型推导
• 🎯 依赖追踪: 智能的字段间依赖关系管理
• 🔍 数据源管理: 支持静态和动态数据源，优先级自动处理
• ✅ 表单校验: 内置简单的全局校验机制，支持异步校验
• 🔗 生命周期钩子: 丰富的钩子函数用于自定义逻辑
• 🧩 模块化设计: 核心功能解耦，支持扩展

📦 安装

# 使用 pnpm
pnpm add @xiaohaih/json-form-core

# 或使用 npm
npm install @xiaohaih/json-form-core

# 或使用 yarn
yarn add @xiaohaih/json-form-core

🏗️ 架构设计

核心概念

json-form 采用 组合式架构设计，将表单逻辑与 UI 层完全解耦：

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   UI 适配层     │    │   核心逻辑层     │    │   业务逻辑层     │
│                 │    │                 │    │                 │
│ • Element Plus  │◄──►│ • useWrapper     │◄──►│ • 表单配置      │
│ • Element UI    │    │ • usePlain       │    │ • 数据处理      │
│ • 其他 UI 库    │    │ • 状态管理       │    │ • 业务规则      │
└─────────────────┘    └─────────────────┘    └─────────────────┘

核心组件

useWrapper (容器组件)

表单容器的核心逻辑，负责：

• 管理整个表单的状态 (query 对象)
• 协调所有表单项的注册和通信
• 处理搜索事件和校验流程
• 支持 backfill 和 model 双模式

usePlain (表单项组件)

单个表单项的核心逻辑，负责：

• 管理字段值的状态同步
• 处理依赖关系和级联更新
• 管理数据源的获取和缓存
• 执行字段级校验

🚀 快速开始

基础用法

import { usePlain, useWrapper } from '@xiaohaih/json-form-core';

// 1. 创建容器
const wrapperProps = {
    backfill: { username: '', status: 'active' },
    realtime: true,
    onSearch: (query) => {
        console.log('搜索条件:', query);
    // 执行搜索逻辑
    }
};

const wrapper = useWrapper(wrapperProps);

// 2. 创建表单项
const plainProps = {
    field: 'username',
    query: wrapper.query,
    validator: (query) => {
        if (!query.username) return '用户名不能为空';
    }
};

const plain = usePlain(plainProps);

// 3. 使用
console.log(plain.checked.value); // 获取当前值
plain.change('new value'); // 改变值
wrapper.search(); // 触发搜索

依赖关系

// 省份选择影响城市选项
const provincePlain = usePlain({
    field: 'province',
    query: wrapper.query,
    options: [
        { label: '北京市', value: 'beijing' },
        { label: '上海市', value: 'shanghai' }
    ]
});

const cityPlain = usePlain({
    field: 'city',
    depend: true,
    dependFields: 'province',
    getOptions: (cb, query) => {
    // 根据省份获取城市列表
        fetchCities(query.province).then(cb);
    }
});

📚 API 参考

useWrapper

Props

| 属性名 | 类型 | 默认值 | 描述 | | :--------- | :------------------------------------ | :---------- | :------------------- | | realtime | boolean | undefined | 是否实时触发搜索事件 | | backfill | Record<string, any> | - | 回填数据 | | model | Record<string, any> | - | 双向绑定值 | | validator | (query: Record<string, any>) => any | - | 表单级校验函数 | | toast | (msg: string) => void | - | 校验失败提示 | | readonly | boolean | - | 表单只读状态 | | disabled | boolean | - | 表单禁用状态 |

返回值

interface WrapperExpose {
    child: CommonMethod[]; // 已注册的子组件
    query: Ref<Record<string, any>>; // 表单查询对象
    search: () => Promise<void>; // 触发搜索
    reset: () => void; // 重置表单
    validateToast: () => Promise<any>; // 执行校验
}

usePlain

Props

| 属性名 | 类型 | 默认值 | 描述 | | :----------- | :-------------------- | :----- | :--------------- | | field | string | - | 字段名 | | query | Record<string, any> | - | 查询对象 | | options | any[] | [] | 静态数据源 | | getOptions | GetOptions | - | 动态数据源函数 | | depend | boolean | - | 是否依赖其他字段 | | dependFields | string \| string[] | - | 依赖字段 | | validator | Validator | - | 字段校验函数 | | initialValue | any | - | 初始值 | | defaultValue | any | - | 默认值 |

返回值

interface PlainExpose {
    checked: ComputedRef<any>; // 当前值
    loading: Ref<boolean>; // 加载状态
    finalOption: ComputedRef<any[]>; // 最终数据源
    change: (value: any) => void; // 改变值
    reset: () => void; // 重置字段
    search: () => void; // 触发搜索
}

🗂️ 目录结构

packages/core/
├── index.ts              # 入口文件
├── interface.ts          # 类型定义
├── version.ts            # 版本信息
├── use/                  # 核心逻辑
│   ├── index.ts          # use 层导出
│   ├── constant.ts       # 常量和接口定义
│   ├── wrapper/          # 容器组件逻辑
│   │   ├── index.ts      # useWrapper 实现
│   │   ├── types.ts      # wrapper 类型定义
│   │   └── README.md     # wrapper 文档
│   └── plain/            # 表单项逻辑
│       ├── index.ts      # usePlain 实现
│       ├── types.ts      # plain 类型定义
│       └── README.md     # plain 文档
├── utils/                # 工具函数
│   ├── index.ts          # 工具导出
│   └── base.ts           # 基础工具
└── README.md             # 模块文档

🔧 开发指南

环境要求

• Vue: 3.0+ 或 2.7+ 或 @vue/composition-api 支持的版本
• TypeScript: 4.0+
• Node.js: 16+

Peer Dependencies

{
    "vue": "^3.0.0-0 || ^2.0.0",
    "@vue/composition-api": "^1.0.0-rc.1" // Vue 2.7+ 可选
}

构建

# 构建核心模块
pnpm run build

# 运行测试
pnpm run test

扩展开发

添加新的表单项类型

1. 在 use/plain/ 目录下实现新的逻辑
2. 在 types.ts 中定义对应的 props
3. 在 UI 适配层使用该逻辑

自定义数据源

const customPlain = usePlain({
    field: 'customField',
    getOptions: async (cb, query, option) => {
        const data = await fetchCustomData(query);
        cb(data);

        // 可通过 option 控制行为
        option.changeDefaultValue(data[0]);
    }
});

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

ISC License

🔗 相关链接

• 项目主页
• Element Plus 适配
• Element UI 适配
• 使用示例