Jiess文档

Appearance

快捷表单 · Vant ​

核心 API 请查阅 快捷表单-基础篇，本文档仅说明 Vant 框架下的特化配置。

导入路径 ​

javascript
import { $initHook, $Input, $Select } from '@jiess/plus/vant';

Vant 表单组件映射 ​

Jiess 组件Vant 组件说明
$Inputvan-field文本输入
$Selectvan-field + van-action-sheet下拉选择（弹出动作面板）
$DatePickervan-field + van-popup + van-datetime-picker日期选择（弹出层+日期选择器）
$Switchvan-switch开关
$CheckboxGroupvan-checkbox-group复选框组
$TreeSelectvan-field + van-popup树形选择（弹出层）
$Cascadervan-field + van-popup级联选择（弹出层）

Vant 特有属性 ​

表单布局 ​

javascript
{
    $Form: {
        labelWidth: '6em',       // 标签宽度
        inputAlign: 'right',     // 输入框对齐：'left' / 'center' / 'right'
        colon: true,             // 是否显示冒号
        children: { /* */ },
    },
}

表单项透传属性 ​

javascript
$Input({
    $label: '姓名',
    $name: 'name',
    // 以下透传给 van-field
    placeholder: '请输入姓名',
    clearable: true,
    autosize: true,          // 自适应高度（textarea 模式）
    type: 'textarea',        // 多行文本
    rows: 3,
});

// Vant Select 使用弹出动作面板
$Select({
    $label: '状态',
    $name: 'status',
    options: [
        { label: '启用', value: '1' },
        { label: '禁用', value: '0' },
    ],
    $popupParam: {
        title: '选择状态',
        round: true,
    },
});

安全区适配 ​

javascript
{
    $Form: {
        falgLevel: 1,           // 启用 Jiess 表单容器
        safeAreaInsetBottom: true,
        children: {
            name: { $Input: { $label: '姓名' } },
            $Button: {
                children: '提交',
                type: 'primary',
                size: 'large',
            },
        },
    },
}

注意事项 ​

事项说明
$Select 实现Vant 无原生 Select，Jiess 用 van-field + van-action-sheet 模拟
$DatePicker 实现用 van-field + van-popup + van-datetime-picker 组合实现
$formItemParam可透传额外 van-cell-group / van-field 属性

实战示例 ​

示例1：移动端完整注册表单 ​

javascript
import { $initHook, $Input, $Select } from '@jiess/plus/vant';

export default {
    $Form: {
        safeAreaInsetBottom: true,
        children: {
            name: {
                $Input: {
                    $label: '姓名',
                    $rules: [
                        { required: true, message: '请输入姓名' },
                        { minLen: 2, message: '姓名至少2个字符' },
                    ],
                    placeholder: '请输入姓名',
                    clearable: true,
                },
            },
            phone: {
                $Input: {
                    $label: '手机号',
                    $rules: [{ phone: true, message: '请输入正确的手机号' }],
                    placeholder: '请输入手机号',
                    type: 'tel',
                    clearable: true,
                },
            },
            wechat: {
                $Input: {
                    $label: '微信号',
                    placeholder: '请输入微信号',
                    clearable: true,
                },
            },
            gender: {
                $Select: {
                    $label: '性别',
                    $rules: [{ required: true, message: '请选择性别' }],
                    options: [
                        { label: '男', value: 'male' },
                        { label: '女', value: 'female' },
                    ],
                    $popupParam: {
                        title: '选择性别',
                        round: true,
                    },
                },
            },
            company: {
                $Input: {
                    $label: '公司',
                    placeholder: '请输入公司名称',
                    clearable: true,
                },
            },
            position: {
                $Select: {
                    $label: '职位',
                    options: [
                        { label: '开发工程师', value: 'dev' },
                        { label: '产品经理', value: 'pm' },
                        { label: '设计师', value: 'design' },
                        { label: '其他', value: 'other' },
                    ],
                    $popupParam: {
                        title: '选择职位',
                        round: true,
                    },
                },
            },
            intro: {
                $Input: {
                    $label: '个人简介',
                    placeholder: '请输入个人简介',
                    type: 'textarea',
                    rows: 3,
                    autosize: true,
                    maxlength: 200,
                    showWordLimit: true,
                },
            },
        },
    },
    $Button: {
        children: '提交注册',
        type: 'primary',
        size: 'large',
        block: true,
        round: true,
    },
};

示例2：表单数据回填 + 编辑模式 ​

javascript
// 编辑场景：使用 hook.start() 注入数据，设置表单初始值
const editConfig = {
    $Form: {
        children: {
            name: {
                $Input: {
                    $label: '姓名',
                    $value: userData.name,        // 通过 $value 回填
                    $rules: [{ required: true }],
                },
            },
            phone: {
                $Input: {
                    $label: '手机号',
                    $value: userData.phone,       // 通过 $value 回填
                    $rules: [{ phone: true }],
                },
            },
            status: {
                $Select: {
                    $label: '状态',
                    $value: userData.status,      // 选择框回填
                    options: [
                        { label: '启用', value: 1 },
                        { label: '禁用', value: 0 },
                    ],
                },
            },
        },
    },
    $Button: {
        children: '保存',
        type: 'primary',
        size: 'large',
        block: true,
    },
};

示例3：多步骤表单（分步收集信息） ​

javascript
// 步骤1：基本信息
const step1Config = {
    $Form: {
        children: {
            name: {
                $Input: {
                    $label: '姓名',
                    $rules: [{ required: true, message: '请输入姓名' }],
                },
            },
            phone: {
                $Input: {
                    $label: '手机号',
                    $rules: [{ phone: true, message: '手机号格式不正确' }],
                    type: 'tel',
                },
            },
        },
    },
    $Button: {
        children: '下一步',
        type: 'primary',
        size: 'large',
        block: true,
        round: true,
        onClick: () => {
            // 校验当前步骤 -> 切换到步骤2
            // currentStep.value = 2
        },
    },
};

// 步骤2：补充信息
const step2Config = {
    $Form: {
        children: {
            company: {
                $Input: { $label: '公司', placeholder: '请输入公司名称' },
            },
            position: {
                $Select: {
                    $label: '职位',
                    options: [
                        { label: '工程师', value: 'engineer' },
                        { label: '经理', value: 'manager' },
                    ],
                },
            },
        },
    },
    $Button: {
        children: '提交',
        type: 'primary',
        size: 'large',
        block: true,
        round: true,
        onClick: () => {
            // 合并步骤1和步骤2的数据 -> 提交
            // submit({ ...step1Data, ...step2Data })
        },
    },
};

下一步 ​

蜀ICP备19017195号-2