基本用法
本节介绍 SunlightForm 组件的基本使用方法，包括各种常用表单控件的配置和组合使用示例。
表单基础
基本表单
最简单的表单使用方式，只需要提供表单数据、列配置和操作按钮。
vue
<template>
<div>
<SunlightForm v-model="formData" :columns="columns" :rules="rules">
<template #operation>
<el-button type="primary" @click="handleSubmit">提交</el-button>
<el-button @click="handleReset">重置</el-button>
</template>
</SunlightForm>
</div>
</template>
<script setup>
import { ref } from "vue";
import { SunlightForm } from "sunlight-ui";
// 表单数据
const formData = ref({
name: "",
email: "",
age: null,
department: "",
});
// 表单列配置
const columns = ref([
{
prop: "name",
label: "姓名",
type: "input",
span: 12,
placeholder: "请输入姓名",
},
{
prop: "email",
label: "邮箱",
type: "input",
span: 12,
placeholder: "请输入邮箱",
},
{
prop: "age",
label: "年龄",
type: "input",
span: 12,
inputType: "number",
placeholder: "请输入年龄",
},
{
prop: "department",
label: "部门",
type: "select",
span: 12,
placeholder: "请选择部门",
options: [
{ label: "技术部", value: "tech" },
{ label: "市场部", value: "market" },
{ label: "销售部", value: "sales" },
{ label: "人事部", value: "hr" },
],
},
]);
// 表单验证规则
const rules = ref({
name: [{ required: true, message: "请输入姓名", trigger: "blur" }],
email: [
{ required: true, message: "请输入邮箱", trigger: "blur" },
{ type: "email", message: "请输入正确的邮箱格式", trigger: "blur" },
],
age: [{ required: true, message: "请输入年龄", trigger: "blur" }],
department: [{ required: true, message: "请选择部门", trigger: "change" }],
});
// 提交表单
const handleSubmit = () => {
console.log("表单数据:", formData.value);
// 这里可以调用 API 提交表单数据
};
// 重置表单
const handleReset = () => {
console.log("重置表单");
// 重置表单数据
formData.value = {
name: "",
email: "",
age: null,
department: "",
};
};
</script>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
隐藏源代码
配置说明
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model | 表单数据双向绑定 | Record<string, any> | {} |
| columns | 表单列配置 | FormColumn[] | - |
| rules | 表单验证规则 | Record<string, any[]> | {} |
常用表单控件
综合展示常用的表单控件，包括输入框、文本域、下拉选择器、单选框和多选框的组合使用。
vue
<template>
<div>
<SunlightForm v-model="formData" :columns="columns" :rules="rules">
<template #operation>
<el-button type="primary" @click="handleSubmit">提交</el-button>
<el-button @click="handleReset">重置</el-button>
</template>
</SunlightForm>
</div>
</template>
<script setup>
import { ref } from "vue";
import { SunlightForm } from "sunlight-ui";
// 表单数据
const formData = ref({
// 输入框
text: "",
password: "",
number: null,
email: "",
// 文本域
description: "",
// 下拉选择器
department: "",
roles: [],
// 单选框
gender: "",
// 多选框
hobbies: [],
});
// 部门选项
const departmentOptions = [
{ label: "技术部", value: "tech" },
{ label: "市场部", value: "market" },
{ label: "销售部", value: "sales" },
{ label: "人事部", value: "hr" },
{ label: "财务部", value: "finance" },
];
// 角色选项
const roleOptions = [
{ label: "管理员", value: "admin" },
{ label: "编辑", value: "editor" },
{ label: "审核员", value: "reviewer" },
{ label: "访客", value: "visitor" },
];
// 性别选项
const genderOptions = [
{ label: "男", value: "male" },
{ label: "女", value: "female" },
{ label: "其他", value: "other" },
];
// 爱好选项
const hobbyOptions = [
{ label: "阅读", value: "reading" },
{ label: "运动", value: "sports" },
{ label: "音乐", value: "music" },
{ label: "旅行", value: "travel" },
{ label: "摄影", value: "photography" },
];
// 表单列配置
const columns = ref([
// 输入框组
{
prop: "text",
label: "文本输入",
type: "input",
span: 12,
placeholder: "请输入文本",
},
{
prop: "password",
label: "密码输入",
type: "input",
inputType: "password",
span: 12,
placeholder: "请输入密码",
},
{
prop: "number",
label: "数字输入",
type: "input",
inputType: "number",
span: 12,
placeholder: "请输入数字",
config: {
min: 0,
max: 100,
step: 1,
},
},
{
prop: "email",
label: "邮箱输入",
type: "input",
inputType: "email",
span: 12,
placeholder: "请输入邮箱",
},
// 文本域
{
prop: "description",
label: "个人简介",
type: "textarea",
span: 24,
rows: 4,
maxlength: 200,
showWordLimit: true,
placeholder: "请输入个人简介",
},
// 下拉选择器组
{
prop: "department",
label: "所属部门",
type: "select",
span: 12,
placeholder: "请选择部门",
options: departmentOptions,
},
{
prop: "roles",
label: "角色权限",
type: "select",
span: 12,
placeholder: "请选择角色",
options: roleOptions,
multiple: true,
clearable: true,
},
// 单选框组
{
prop: "gender",
label: "性别",
type: "radio",
span: 12,
options: genderOptions,
},
// 多选框组
{
prop: "hobbies",
label: "兴趣爱好",
type: "checkbox",
span: 12,
options: hobbyOptions,
},
]);
// 表单验证规则
const rules = ref({
text: [{ required: true, message: "请输入文本", trigger: "blur" }],
email: [
{ required: true, message: "请输入邮箱", trigger: "blur" },
{ type: "email", message: "请输入正确的邮箱格式", trigger: "blur" },
],
department: [{ required: true, message: "请选择部门", trigger: "change" }],
gender: [{ required: true, message: "请选择性别", trigger: "change" }],
description: [{ required: true, message: "请输入个人简介", trigger: "blur" }],
});
// 提交表单
const handleSubmit = () => {
console.log("表单数据:", formData.value);
};
// 重置表单
const handleReset = () => {
formData.value = {
text: "",
password: "",
number: null,
email: "",
description: "",
department: "",
roles: [],
gender: "",
hobbies: [],
};
};
</script>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
隐藏源代码
配置说明
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 表单控件类型 | string | - |
| inputType | 输入框类型 | string | 'text' |
| placeholder | 占位符 | string | - |
| disabled | 是否禁用 | boolean | false |
| clearable | 是否可清空 | boolean | true |
| options | 选项列表 | Array<any> | [] |
| multiple | 是否支持多选 | boolean | false |
| rows | 行数（文本域） | number | 3 |
| maxlength | 最大长度 | number | 150 |
| showWordLimit | 是否显示字数统计 | boolean | true |
日期时间控件
综合展示各种日期时间相关的表单控件，包括日期选择器、日期时间选择器、月份选择器和年份选择器的组合使用。
vue
<template>
<div>
<SunlightForm v-model="formData" :columns="columns" :rules="rules">
<template #operation>
<el-button type="primary" @click="handleSubmit">提交</el-button>
<el-button @click="handleReset">重置</el-button>
</template>
</SunlightForm>
</div>
</template>
<script setup>
import { ref } from "vue";
import { SunlightForm } from "sunlight-ui";
// 表单数据
const formData = ref({
// 日期选择器
date: "",
dateRange: [],
// 日期时间选择器
datetime: "",
datetimeRange: [],
// 月份选择器
month: "",
// 年份选择器
year: "",
});
// 表单列配置
const columns = ref([
// 日期选择器组
{
prop: "date",
label: "日期选择",
type: "date-picker",
span: 12,
placeholder: "请选择日期",
valueFormat: "YYYY-MM-DD",
clearable: true,
},
{
prop: "dateRange",
label: "日期范围",
type: "date-picker",
span: 12,
placeholder: ["开始日期", "结束日期"],
valueFormat: "YYYY-MM-DD",
range: true,
clearable: true,
},
// 日期时间选择器组
{
prop: "datetime",
label: "日期时间",
type: "datetime-picker",
span: 12,
placeholder: "请选择日期时间",
valueFormat: "YYYY-MM-DD HH:mm:ss",
clearable: true,
},
{
prop: "datetimeRange",
label: "日期时间范围",
type: "datetime-picker",
span: 12,
placeholder: ["开始时间", "结束时间"],
valueFormat: "YYYY-MM-DD HH:mm:ss",
range: true,
clearable: true,
},
// 月份选择器
{
prop: "month",
label: "月份选择",
type: "date-picker",
span: 12,
placeholder: "请选择月份",
valueFormat: "YYYY-MM",
pickerOptions: {
type: "month",
},
clearable: true,
},
// 年份选择器
{
prop: "year",
label: "年份选择",
type: "date-picker",
span: 12,
placeholder: "请选择年份",
valueFormat: "YYYY",
pickerOptions: {
type: "year",
},
clearable: true,
},
]);
// 表单验证规则
const rules = ref({
date: [{ required: true, message: "请选择日期", trigger: "change" }],
datetime: [{ required: true, message: "请选择日期时间", trigger: "change" }],
});
// 提交表单
const handleSubmit = () => {
console.log("表单数据:", formData.value);
};
// 重置表单
const handleReset = () => {
formData.value = {
date: "",
dateRange: [],
datetime: "",
datetimeRange: [],
month: "",
year: "",
};
};
</script>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
隐藏源代码
配置说明
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 表单控件类型 | string | 'date-picker' 或 'datetime-picker' |
| placeholder | 占位符 | string 或 string[] | - |
| valueFormat | 日期/时间格式 | string | 'YYYY-MM-DD' 或 'YYYY-MM-DD HH:mm:ss' |
| range | 是否为范围选择 | boolean | false |
| clearable | 是否可清空 | boolean | true |
基础表单功能
综合展示表单的各种基础功能，包括响应式布局、表单验证、操作按钮、表单禁用和表单尺寸的组合使用。
vue
<template>
<div>
<div class="control-buttons">
<el-button type="warning" @click="toggleDisabled">切换禁用状态</el-button>
<el-button type="info" @click="toggleSize">切换表单尺寸</el-button>
</div>
<SunlightForm v-model="formData" :columns="columns" :rules="rules" :formOptions="formOptions">
<template #operation>
<el-button type="primary" @click="handleSubmit">提交</el-button>
<el-button @click="handleReset">重置</el-button>
</template>
</SunlightForm>
</div>
</template>
<script setup>
import { ref } from "vue";
import { SunlightForm } from "sunlight-ui";
// 表单数据
const formData = ref({
// 响应式布局
name: "",
email: "",
phone: "",
// 表单验证
idCard: "",
password: "",
confirmPassword: "",
// 表单禁用
disabledField: "这个字段被禁用了",
// 表单尺寸
sizeDemo: "",
});
// 表单选项
const formOptions = ref({
disabled: false,
size: "default",
buttonAlign: "center",
});
// 部门选项
const departmentOptions = [
{ label: "技术部", value: "tech" },
{ label: "市场部", value: "market" },
{ label: "销售部", value: "sales" },
{ label: "人事部", value: "hr" },
{ label: "财务部", value: "finance" },
];
// 表单列配置
const columns = ref([
// 响应式布局示例
{
prop: "name",
label: "姓名",
type: "input",
span: 12,
placeholder: "请输入姓名",
},
{
prop: "email",
label: "邮箱",
type: "input",
inputType: "email",
span: 12,
placeholder: "请输入邮箱",
},
{
prop: "phone",
label: "电话",
type: "input",
inputType: "tel",
span: 12,
placeholder: "请输入电话",
},
// 表单验证示例
{
prop: "idCard",
label: "身份证号",
type: "input",
span: 12,
placeholder: "请输入身份证号",
},
{
prop: "password",
label: "密码",
type: "input",
inputType: "password",
span: 12,
placeholder: "请输入密码",
},
{
prop: "confirmPassword",
label: "确认密码",
type: "input",
inputType: "password",
span: 12,
placeholder: "请再次输入密码",
},
// 表单禁用示例
{
prop: "disabledField",
label: "禁用字段",
type: "input",
span: 12,
disabled: true,
placeholder: "这个字段被禁用了",
},
// 表单尺寸示例
{
prop: "sizeDemo",
label: "尺寸演示",
type: "select",
span: 12,
placeholder: "请选择",
options: departmentOptions,
},
]);
// 表单验证规则
const rules = ref({
name: [
{ required: true, message: "请输入姓名", trigger: "blur" },
{ min: 2, max: 10, message: "姓名长度在 2 到 10 个字符", trigger: "blur" },
],
email: [
{ required: true, message: "请输入邮箱", trigger: "blur" },
{ type: "email", message: "请输入正确的邮箱格式", trigger: "blur" },
],
phone: [
{ required: true, message: "请输入电话", trigger: "blur" },
{ pattern: /^1[3-9]\d{9}$/, message: "请输入正确的手机号码", trigger: "blur" },
],
idCard: [
{ required: true, message: "请输入身份证号", trigger: "blur" },
{ pattern: /(^\d{15}$)|(^\d{18}$)|(^\d{17}(\d|X|x)$)/, message: "请输入正确的身份证号码", trigger: "blur" },
],
password: [
{ required: true, message: "请输入密码", trigger: "blur" },
{ min: 6, max: 20, message: "密码长度在 6 到 20 个字符", trigger: "blur" },
],
confirmPassword: [
{ required: true, message: "请确认密码", trigger: "blur" },
{
validator: (rule, value, callback) => {
if (value !== formData.value.password) {
callback(new Error("两次输入密码不一致"));
} else {
callback();
}
},
trigger: "blur",
},
],
});
// 提交表单
const handleSubmit = () => {
console.log("表单数据:", formData.value);
};
// 重置表单
const handleReset = () => {
formData.value = {
name: "",
email: "",
phone: "",
idCard: "",
password: "",
confirmPassword: "",
disabledField: "这个字段被禁用了",
sizeDemo: "",
};
};
// 切换禁用状态
const toggleDisabled = () => {
formOptions.value.disabled = !formOptions.value.disabled;
};
// 切换表单尺寸
const toggleSize = () => {
const sizes = ["large", "default", "small"];
const currentIndex = sizes.indexOf(formOptions.value.size);
formOptions.value.size = sizes[(currentIndex + 1) % sizes.length];
};
</script>
<style scoped>
.control-buttons {
margin-bottom: 20px;
display: flex;
gap: 10px;
}
</style>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
隐藏源代码
配置说明
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| rules | 表单验证规则 | Record<string, any[]> | {} |
| span | 所占列数（支持响应式） | number | 24 |
| offset | 偏移列数 | number | 0 |
| formOptions.disabled | 是否禁用整个表单 | boolean | false |
| formOptions.size | 表单尺寸 | string | 'default' |
| buttonAlign | 按钮对齐方式 | string | 'left' |
| operation | 操作按钮插槽 | slot | - |