Jiess Plus 介绍与上手

项目概述

@jiess/plus 是基于 @jiess/core 的业务级高级拓展库，采用配置式开发模式。它通过统一的声明式 API，在 Vue3+ElementPlus、Vue3+Vant、React+AntDesign 三种技术栈上提供一致的开发体验。

前置依赖：@jiess/plus 依赖 @jiess/core、@jiess/utils、@jiess/http 三个底层库，安装时会自动关联。

核心特性

特性	说明
配置式开发	用 JS 对象描述 UI 结构，无需手写模板/JSX
跨框架统一 API	`$JiessTable()` / `$Input()` / `$JiessDialog()` 在 Vue3 和 React 中写法一致
无限级弹框栈	支持多层嵌套弹框，自动管理层级和资源清理
14 条内置校验规则	身份证（含校验码）、URL、IP、邮箱、手机号等开箱即用
PC/移动端双支持	`SuperTable`（PC 端表格）和 `SuperList`（移动端列表）自动适配
完整 TypeScript 支持	所有 API 提供类型定义

与同类方案的差异

维度	@jiess/plus	Formily	传统手写
开发方式	纯 JS 配置对象	JSON Schema + 组件	模板/JSX + 逻辑
跨框架成本	同一份配置，切换导入路径	需不同适配器	完全重写
学习曲线	低（JS 对象即可）	中（需学 Schema 语法）	高（框架 + UI 库双学）
弹框管理	内置无限级栈	不内置	完全手写

三大核心模块

┌─────────────────────────────────────────────────┐
│                  @jiess/plus                     │
├───────────────┬───────────────┬─────────────────┤
│  通用列表模块  │  弹框模块      │  快捷表单模块    │
│  BuildTable   │  BuildDialog  │  BuildArea      │
│  BuildList    │  $JiessDialog()    │  ItemBuilder    │
│               │               │  RuleManger     │
├───────────────┴───────────────┴─────────────────┤
│           跨框架适配层（Hook）                     │
│  vue3element/  │  vue3vant/  │  react168antd/  │
├─────────────────────────────────────────────────┤
│  基础库: @jiess/core │ @jiess/utils │ @jiess/http │
└─────────────────────────────────────────────────┘

导入路径速查

javascript

// Vue3 + ElementPlus
import { $initHook, $JiessTable, $JiessDialog, $Input } from '@jiess/plus/vue3';

// Vue3 + Vant（移动端）
import { $initHook, $JiessList, $JiessDialog, $Input } from '@jiess/plus/vant';

// React + AntDesign
import { $initHook, $JiessTable, $JiessDialog, $Input } from '@jiess/plus/react';

// 自动检测框架（不推荐，体积大）
import { $initHook, $JiessTable, $JiessDialog, $Input } from '@jiess/plus/auto';

自动适配模块（auto）

@jiess/plus/auto 提供 PC/移动端自动切换能力，适合一套代码同时支持 PC 与移动端的应用：

javascript

import { isMobileEnv, selectByEnv, $Area, $Input } from '@jiess/plus/auto';

// 环境检测工具
isMobileEnv()                        // 基于 innerWidth <= 768 + UA 判断
selectByEnv(mobileModule, pcModule)  // 根据环境选择模块

// 同名组件按环境自动选择
$Area(config)   // mobile → vant 版 / pc → element 版
$Input(config)  // 同上

导出清单：16 个同名组件 + 16 个 Vant 独有 + 19 个 Element 独有。

注意：auto 模块会同时引入 Vant 和 ElementPlus 两套 UI 库，体积较大。生产环境推荐使用精确导入（@jiess/plus/vue3 或 @jiess/plus/vant）。

快速上手：5 分钟搭建 CRUD 页面

第一步：初始化 Jiess

javascript

// jiessConfig/index.js
import * as Vue from 'vue';
import * as element from 'element-plus';
import { $initHook } from '@jiess/plus/vue3';

// 创建 hook 并注入 UI 库 + Vue 环境
const hook = $initHook({
    $name: 'my-app',
    ui: element,          // UI 组件库
    ...Vue,               // Vue 响应式 API（reactive/ref/watch 等）
    globalConfig: {
        _SuperTable: {
            fieldPage: 'page',
            fieldPageSize: 'limit',
            fieldTotal: 'total',
            fieldDatas: 'list',
        },
    },
});

// 启动并注入运行时服务
export const jiess = hook.start();
export const JiessComponent = jiess.JiessComponent;

第二步：全局注册组件

javascript

// main.js
import { createApp } from 'vue';
import App from './App.vue';
import ElementPlus from 'element-plus';
import 'element-plus/dist/index.css';
import { JiessComponent } from '@/jiessConfig';

const app = createApp(App);
app.use(ElementPlus);
app.component('jiess', JiessComponent);  // 全局注册 Jiess 容器组件
app.mount('#app');

第三步：编写第一个列表页

javascript

// 在 Vue 组件的 setup() 中使用
import { jiess } from '@/jiessConfig';
import { $JiessTable } from '@jiess/plus/vue3';

export default {
    setup() {
        return {
            listConfig: $JiessTable({
                rowKey: 'id',
                action: 'http://api.example.com/users',  // 自动请求
                $search: {                                // 搜索栏
                    $content: {
                        $keyword: { $label: '关键词' },
                    },
                },
                $header: {
                    $title: '用户管理',
                    $tools: [$add, $refresh],
                },
                $fields: [
                    { $label: '姓名', $name: 'name', $width: 120 },
                    { $label: '邮箱', $name: 'email', $width: 200 },
                    { $label: '状态', $name: 'status', $map: { 0: '禁用', 1: '启用' } },
                    { $label: '操作', $tools: [$edit, $del] },
                ],
            }),
        };
    },
};

第四步：在模板中使用

html

<template>
    <jiess :config="listConfig" />
</template>

以上 4 步即可完成一个带搜索、分页、增删改查的完整列表页。详细配置参见通用列表系列。

文档导航

文档	内容
安装与配置	正确的导入路径、`$initHook` 详解、globalConfig 配置
核心概念	Jiess 上下文、配置对象规范、响应式系统
全局弹框系列	`$JiessDialog()` 创建、弹框栈管理、嵌套弹框
快捷表单系列	`$Input` / `$Select` / `$DatePicker` + 14 条校验规则
通用列表系列	`$JiessTable` / `$JiessList` 分页、排序、远程加载
功能组件系列	`$Space` / `$ActionButtons` / `$TipText` 等
高级特性	`start()` 注入、`JiessMidder`、流程引擎 `$JiessFlow`

核心概念速览

1. 配置对象规范

所有 Jiess Plus 组件都接受一个普通 JS 对象作为参数，对象的 key 以 $ 开头的是 Jiess 内置属性：

javascript

$JiessTable({
    $search: { ... },     // $ 开头：Jiess 内置属性
    $header: { ... },     // 控制搜索栏、标题栏等模块
    $fields: [ ... ],     // 控制表格列
    rowKey: 'id',         // 非 $ 开头：透传给底层 UI 组件
    bordered: true,
})

2. 字段驱动 vs 手动构建

Jiess Plus 支持两种开发模式：

javascript

// 模式一：字段驱动（推荐，适用于标准 CRUD）
$JiessTable({ $fields: [{ $label: '姓名', $name: 'name' }] })

// 模式二：手动构建（适用于复杂布局）
$JiessTable({
    children: [
        {
            $Search: { children: { keyword: { $Input: {} } } }
        },
        {
            $field: [
                { $label: '姓名', $name: 'name', $TableField: {} },
            ]
        }
    ]
})

3. 上下文注入

在组件内部，通过 this 可以访问 Jiess 注入的上下文：

javascript

$JiessTable({
    render(item) {
        // this.area      —— 当前构建区域
        // this.jiess     —— Jiess 实例（store/router/tools）
        // this.midder    —— 中介者（广播/订阅）
        // this.emit(data) —— 向父组件发射事件
    }
})

预览模式（Preview Mode）

表单区域支持编辑/预览双模式切换，预览模式下所有表单组件自动转为只读展示。

启用方式

javascript

// 方式一：静态字符串
this.$Area({
    initialValues: { name: '张三', age: 28 },
    mode: 'preview',   // 整个表单区域进入预览模式
});

// 方式二：JiessRef 动态切换（响应式）
const mode = $ref('edit');
this.$Area({
    initialValues: { name: '张三' },
    mode,  // mode 是 JiessRef，底层 unwrapVal() 自动提取 .value
});
// 切换为预览模式
mode.value = 'preview';  // → 表单 UI 自动重渲染

预览策略优先级

表单组件在预览模式下按以下优先级渲染：

优先级	策略	触发条件	说明
1	`$preview` 函数	组件定义了 `$preview` 函数	完全接管预览渲染，可返回自定义节点
2	`valueBuilder`	工厂函数内置	自动计算文本展示值
3	`treeBuilder`	树形组件（TreeSelect/Cascader）	自动计算树形路径
4	`selects` 系列	Select/CheckboxGroup/RadioGroup	自动匹配 options 文本标签
5	纯文本	以上均不满足	直接展示原始值

PC 端 vs 移动端差异

预览维度	buildNode（Element/Antd）	buildNodeVant（Vant）
Select 等选择组件	通过 `$proxy` 计算属性展示	通过 `$TipText` 组件展示标签
普通组件（无名）	保持原样渲染	`readonly: true` + 特定组件（Rate/Slider 等）添加 `disabled: true`
`$preview` 对象模式	合并至 `$TipText` attrs	合并至对应渲染 attrs

组件级覆盖

javascript

// 在预览模式下，让单个组件保持交互状态
$Input({
    $name: 'remark',
    $label: '备注',
    $mode: 'edit',   // 即使外层是 preview，此组件仍可编辑
});

更多预览模式细节参见快捷表单系列。

表单取值与校验

获取表单数据

javascript

// ⚠️ area.action.value() 永远返回 Promise，必须 await！
const values = await area.action.value();      // 先校验再取值
const values = await area.action.value(false); // 跳过校验，直接取值
const values = await area.action.value(obj);   // 使用入参对象作为原始值

常见陷阱：

javascript

// ❌ 忘记 await —— values 是 Promise 对象，不是表单数据！
const values = area.action.value();
values.parentId = parentId;  // 在 Promise 上设置属性，无效！

// ✅ 正确写法
const values = await area.action.value();
values.parentId = parentId;

内置校验规则速查

@jiess/plus 内置 14 条校验规则，通过 $rules 声明：

规则名	说明	示例
`required`	必填校验	`$rules: ['required']`
`email`	邮箱格式	`$rules: ['email']`
`phone`	手机号格式	`$rules: ['phone']`
`card`	身份证号（含校验码验证）	`$rules: ['card']`
`url`	URL 格式	`$rules: ['url']`
`range`	长度范围	`$rules: [['range', 2, 20]]`
`number`	纯数字	`$rules: ['number']`
`mark`	标识格式（字母/数字/下划线）	`$rules: ['mark']`
`positiveInt`	正整数	`$rules: ['positiveInt']`
`requireArr`	数组非空	`$rules: ['requireArr']`

完整 14 条规则列表 + 自定义校验规则注入方式参见快捷表单系列。

常见问题

弹框内表单获取不到数据？

使用 area.nameManger.getData() 或 await area.action.value()，确保表单通过 area.render() 正确关联。

列表数据不刷新？

检查 midder.table.reload() 是否被调用，或 immedicat 参数是否正确设置。

预览模式切换后组件没变化？

确保 mode 是 JiessRef 且通过 unwrapVal() 可提取 .value。静态字符串 mode: 'preview' 仅在初始化时生效。

忘记 await area.action.value() 导致数据丢失？

这是最常见的错误。area.action.value() 永远返回 Promise，必须 await，否则拿到的不是表单数据而是 Promise 对象。

下一步

阅读安装与配置了解 $initHook 和 globalConfig 的完整配置
阅读核心概念深入理解配置式开发范式
按需查阅各功能模块的详细 API 文档

Jiess Plus 介绍与上手 ​

项目概述 ​

核心特性 ​

与同类方案的差异 ​

三大核心模块 ​

导入路径速查 ​

自动适配模块（auto） ​

快速上手：5 分钟搭建 CRUD 页面 ​

第一步：初始化 Jiess ​

第二步：全局注册组件 ​

第三步：编写第一个列表页 ​

第四步：在模板中使用 ​

文档导航 ​

核心概念速览 ​

1. 配置对象规范 ​

2. 字段驱动 vs 手动构建 ​

3. 上下文注入 ​

预览模式（Preview Mode） ​

启用方式 ​

预览策略优先级 ​

PC 端 vs 移动端差异 ​

组件级覆盖 ​

表单取值与校验 ​

获取表单数据 ​

内置校验规则速查 ​

常见问题 ​

弹框内表单获取不到数据？ ​

列表数据不刷新？ ​

预览模式切换后组件没变化？ ​

忘记 await area.action.value() 导致数据丢失？ ​

下一步 ​

Jiess Plus 介绍与上手

项目概述

核心特性

与同类方案的差异

三大核心模块

导入路径速查

自动适配模块（auto）

快速上手：5 分钟搭建 CRUD 页面

第一步：初始化 Jiess

第二步：全局注册组件

第三步：编写第一个列表页

第四步：在模板中使用

文档导航

核心概念速览

1. 配置对象规范

2. 字段驱动 vs 手动构建

3. 上下文注入

预览模式（Preview Mode）

启用方式

预览策略优先级

PC 端 vs 移动端差异

组件级覆盖

表单取值与校验

获取表单数据

内置校验规则速查

常见问题

弹框内表单获取不到数据？

列表数据不刷新？

预览模式切换后组件没变化？

忘记 await area.action.value() 导致数据丢失？

下一步