mirror of https://github.com/halo-dev/halo
372 lines
10 KiB
Markdown
372 lines
10 KiB
Markdown
# 自定义 FormKit 输入组件
|
||
|
||
## 原由
|
||
|
||
目前在 Console 端的所有表单都使用了 FormKit，但 FormKit 内置的 Input 组件并不满足所有的需求，因此需要自定义一些 Input 组件。此外，为了插件和主题能够更加方便的使用系统内的一些数据，所以同样需要自定义一些带数据的选择组件。
|
||
|
||
## 使用方式
|
||
|
||
目前已提供以下类型：
|
||
|
||
- `code`: 代码编辑器
|
||
- 参数
|
||
1. language: 目前支持 `yaml`, `html`, `css`, `javascript`, `json`
|
||
2. height: 编辑器高度，如：`100px`
|
||
- `attachment`: 附件选择
|
||
- 参数
|
||
1. accepts：允许上传的文件类型，如：`image/*`
|
||
- `repeater`: 定义一个对象集合，可以让使用者可视化的操作集合。
|
||
- 参数
|
||
1. min: 最小数量，默认为 `0`
|
||
2. max: 最大数量，默认为 `Infinity`，即无限制。
|
||
3. addLabel: 添加按钮的文本，默认为 `添加`
|
||
4. addButton: 是否显示添加按钮，默认为 `true`
|
||
5. upControl: 是否显示上移按钮，默认为 `true`
|
||
6. downControl: 是否显示下移按钮，默认为 `true`
|
||
7. insertControl: 是否显示插入按钮，默认为 `true`
|
||
8. removeControl: 是否显示删除按钮，默认为 `true`
|
||
- `list`: 动态列表，定义一个数组列表。
|
||
- 参数
|
||
1. itemType: 列表项的数据类型，用于初始化数据类型，可选参数 `string`, `number`, `boolean`, `object`，默认为 `string`
|
||
2. min: 最小数量，默认为 `0`
|
||
3. max: 最大数量，默认为 `Infinity`，即无限制。
|
||
4. addLabel: 添加按钮的文本，默认为 `添加`
|
||
5. addButton: 是否显示添加按钮，默认为 `true`
|
||
6. upControl: 是否显示上移按钮，默认为 `true`
|
||
7. downControl: 是否显示下移按钮，默认为 `true`
|
||
8. insertControl: 是否显示插入按钮，默认为 `true`
|
||
9. removeControl: 是否显示删除按钮，默认为 `true`
|
||
- `menuCheckbox`：选择一组菜单
|
||
- `menuRadio`：选择一个菜单
|
||
- `menuItemSelect`：选择菜单项
|
||
- `postSelect`：选择文章
|
||
- `singlePageSelect`：选择自定义页面
|
||
- `categorySelect`：选择分类
|
||
- 参数
|
||
1. multiple: 是否多选，默认为 `false`
|
||
- `categoryCheckbox`：选择多个分类
|
||
- `tagSelect`：选择标签
|
||
- 参数
|
||
1. multiple: 是否多选，默认为 `false`
|
||
- `tagCheckbox`：选择多个标签
|
||
- `verificationForm`: 远程验证一组数据是否符合某个规则
|
||
- 参数
|
||
1. action: 对目标数据进行验证的接口地址
|
||
2. label: 验证按钮文本
|
||
3. buttonAttrs: 验证按钮的额外属性
|
||
- `secret`: 用于选择或者管理密钥（Secret）
|
||
- 参数
|
||
1. requiredKey：用于确认所需密钥的字段名称
|
||
- `select`: 自定义的选择器组件，用于在备选项中选择一个或多个选项
|
||
- 参数
|
||
1. `options`：静态数据源。当 `action` 或 `remote` 存在时，此参数无效。
|
||
2. `action`：远程动态数据源的接口地址。
|
||
3. `requestOption`： 动态数据源的请求参数，可以通过此参数来指定如何获取数据，适配不同的接口。当 `action` 存在时，此参数有效。
|
||
4. `remote`：标识当前是否由用户自定义的远程数据源。
|
||
5. `remoteOption`：当 `remote` 为 `true` 时，此配置项必须存在，用于为 Select 组件提供处理搜索及查询键值对的方法。
|
||
6. `remoteOptimize`：是否开启远程数据源优化，默认为 `true`。开启后，将会对远程数据源进行优化，减少请求次数。仅在动态数据源下有效。
|
||
7. `allowCreate`：是否允许创建新选项，默认为 `false`。仅在静态数据源下有效。
|
||
8. `clearable`：是否允许清空选项，默认为 `false`。
|
||
9. `multiple`：是否多选，默认为 `false`。
|
||
10. `maxCount`：多选时最大可选数量，默认为 `Infinity`。仅在多选时有效。
|
||
11. `sortable`：是否支持拖动排序，默认为 `false`。仅在多选时有效。
|
||
12. `searchable`：是否支持搜索内容，默认为 `false`。
|
||
13. `autoSelect`：当 value 不存在时，是否自动选择第一个选项，默认为 `true`。仅在单选时有效。
|
||
|
||
在 Vue 单组件中使用：
|
||
|
||
```vue
|
||
<script lang="ts" setup>
|
||
const postName = ref("");
|
||
</script>
|
||
|
||
<template>
|
||
<FormKit
|
||
v-model="postName"
|
||
placeholder="请选择文章"
|
||
label="文章"
|
||
type="postSelect"
|
||
validation="required"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
在 FormKit Schema 中使用（插件 / 主题设置表单定义）：
|
||
|
||
```yaml
|
||
- $formkit: menuRadio
|
||
name: menus
|
||
label: 底部菜单组
|
||
```
|
||
|
||
### select
|
||
|
||
select 是一个选择器类型的输入组件，使用者可以从一批待选数据中选择一个或多个选项。它支持单选、多选操作，并且支持静态数据及远程动态数据加载等多种方式。
|
||
|
||
#### 在 Vue SFC 中以组件形式使用
|
||
|
||
静态数据源：
|
||
|
||
```vue
|
||
<script lang="ts" setup></script>
|
||
<template>
|
||
<FormKit
|
||
type="select"
|
||
label="What country makes the best food?"
|
||
name="countries"
|
||
placeholder="Select a country"
|
||
allow-create
|
||
clearable
|
||
sortable
|
||
multiple
|
||
searchable
|
||
:options="[
|
||
{ label: 'China', value: 'China' },
|
||
{ label: 'USA', value: 'USA' },
|
||
{ label: 'Japan', value: 'Japan' },
|
||
{ label: 'Korea', value: 'Korea' },
|
||
{ label: 'France', value: 'France' },
|
||
{ label: 'Italy', value: 'Italy' },
|
||
{ label: 'Germany', value: 'Germany' },
|
||
{ label: 'UK', value: 'UK' },
|
||
{ label: 'Canada', value: 'Canada' },
|
||
{ label: 'Australia', value: 'Australia' },
|
||
]"
|
||
help="Don’t worry, you can’t get this one wrong."
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
动态数据源：
|
||
|
||
```vue
|
||
<script lang="ts" setup>
|
||
const ANONYMOUSUSER_NAME = "anonymousUser";
|
||
const DELETEDUSER_NAME = "ghost";
|
||
|
||
const handleSelectPostAuthorRemote = {
|
||
search: async ({ keyword, page, size }) => {
|
||
const { data } = await consoleApiClient.user.listUsers({
|
||
page,
|
||
size,
|
||
keyword,
|
||
fieldSelector: [
|
||
`name!=${ANONYMOUSUSER_NAME}`,
|
||
`name!=${DELETEDUSER_NAME}`,
|
||
],
|
||
});
|
||
return {
|
||
options: data.items.map((item) => ({
|
||
label: item.user.spec.displayName,
|
||
value: item.user.metadata.name,
|
||
})),
|
||
total: data.total,
|
||
page: data.page,
|
||
size: data.size,
|
||
};
|
||
},
|
||
|
||
findOptionsByValues: () => {
|
||
return [];
|
||
},
|
||
};
|
||
</script>
|
||
<template>
|
||
<FormKit
|
||
type="select"
|
||
label="The author of the post is?"
|
||
name="post_author"
|
||
placeholder="Select a user"
|
||
searchable
|
||
remote
|
||
:remote-option="handleSelectPostAuthorRemote"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
#### 在 FormKit Schema 中使用
|
||
|
||
静态数据源：
|
||
|
||
```yaml
|
||
- $formkit: select
|
||
name: countries
|
||
label: What country makes the best food?
|
||
sortable: true
|
||
multiple: true
|
||
clearable: true
|
||
placeholder: Select a country
|
||
options:
|
||
- label: China
|
||
value: cn
|
||
- label: France
|
||
value: fr
|
||
- label: Germany
|
||
value: de
|
||
- label: Spain
|
||
value: es
|
||
- label: Italy
|
||
value: ie
|
||
- label: Greece
|
||
value: gr
|
||
```
|
||
|
||
远程动态数据源：
|
||
|
||
支持远程动态数据源，通过 `action` 和 `requestOption` 参数来指定如何获取数据。
|
||
|
||
请求的接口将会自动拼接 `page`、`size` 与 `keyword` 参数，其中 `keyword` 为搜索关键词。
|
||
|
||
```yaml
|
||
- $formkit: select
|
||
name: postName
|
||
label: Choose an post
|
||
clearable: true
|
||
action: /apis/api.console.halo.run/v1alpha1/posts
|
||
requestOption:
|
||
method: GET
|
||
pageField: page
|
||
sizeField: size
|
||
totalField: total
|
||
itemsField: items
|
||
labelField: post.spec.title
|
||
valueField: post.metadata.name
|
||
```
|
||
|
||
> [!NOTE]
|
||
> 当远程数据具有分页时，可能会出现默认选项不在第一页的情况，此时 Select 组件将会发送另一个查询请求，以获取默认选项的数据。此接口会携带如下参数 `fieldSelector: ${requestOption.valueField}=(value1,value2,value3)`。
|
||
|
||
> 其中，value1, value2, value3 为默认选项的值。返回值与查询一致，通过 `requestOption` 解析。
|
||
|
||
### list
|
||
|
||
list 是一个数组类型的输入组件，可以让使用者可视化的操作数组。它支持动态添加、删除、上移、下移、插入数组项等操作。
|
||
|
||
在 Vue SFC 中以组件形式使用：
|
||
|
||
```vue
|
||
<script lang="ts" setup>
|
||
const users = ref([]);
|
||
</script>
|
||
|
||
<template>
|
||
<FormKit
|
||
:min="1"
|
||
:max="3"
|
||
type="list"
|
||
label="Users"
|
||
add-label="Add User"
|
||
item-type="string"
|
||
>
|
||
<template #default="{ index }">
|
||
<FormKit
|
||
type="text"
|
||
:index="index"
|
||
validation="required"
|
||
/>
|
||
</template>
|
||
</FormKit>
|
||
</template>
|
||
```
|
||
|
||
在 FormKit Schema 中使用：
|
||
|
||
```yaml
|
||
- $formkit: list
|
||
name: users
|
||
label: Users
|
||
addLabel: Add User
|
||
min: 1
|
||
max: 3
|
||
itemType: string
|
||
children:
|
||
- $formkit: text
|
||
index: "$index"
|
||
validation: required
|
||
```
|
||
|
||
> [!NOTE]
|
||
> `list` 组件有且只有一个子节点，并且必须为子节点传递 `index` 属性。若想提供多个字段，则建议使用 `group` 组件包裹。
|
||
|
||
最终得到的数据类似于：
|
||
|
||
```json
|
||
{
|
||
"users": [
|
||
"Jack",
|
||
"John"
|
||
]
|
||
}
|
||
```
|
||
|
||
### Repeater
|
||
|
||
Repeater 是一个集合类型的输入组件，可以让使用者可视化的操作集合。
|
||
|
||
在 Vue SFC 中以组件形式使用：
|
||
|
||
```vue
|
||
<script lang="ts" setup>
|
||
const users = ref([]);
|
||
</script>
|
||
|
||
<template>
|
||
<FormKit
|
||
v-model="users"
|
||
:min="1"
|
||
:max="3"
|
||
addLabel="Add User"
|
||
type="repeater"
|
||
label="Users"
|
||
>
|
||
<FormKit
|
||
type="text"
|
||
label="Full Name"
|
||
name="full_name"
|
||
validation="required"
|
||
/>
|
||
<FormKit
|
||
type="email"
|
||
label="Email"
|
||
name="email"
|
||
validation="required|email"
|
||
/>
|
||
</FormKit>
|
||
</template>
|
||
```
|
||
|
||
在 FormKit Schema 中使用：
|
||
|
||
```yaml
|
||
- $formkit: repeater
|
||
name: users
|
||
label: Users
|
||
addLabel: Add User
|
||
min: 1
|
||
max: 3
|
||
items:
|
||
- $formkit: text
|
||
name: full_name
|
||
label: Full Name
|
||
validation: required
|
||
- $formkit: email
|
||
name: email
|
||
label: Email
|
||
validation: required|email
|
||
```
|
||
|
||
最终得到的数据类似于：
|
||
|
||
```json
|
||
[
|
||
{
|
||
"full_name": "Jack",
|
||
"email": "jack@example.com"
|
||
},
|
||
{
|
||
"full_name": "John",
|
||
"email": "john@example.com"
|
||
}
|
||
]
|
||
```
|