Skip to content

Commit b842e6b

Browse files
authored
docs: add formkit select component (#400)
#### What this PR does / why we need it: 添加 formkit select 组件的文档 #### Does this PR introduce a user-facing change? ```release-note None ```
1 parent fcdda68 commit b842e6b

File tree

1 file changed

+131
-0
lines changed

1 file changed

+131
-0
lines changed

docs/developer-guide/form-schema.md

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,137 @@ spec:
6767

6868
除了 FormKit 官方提供的常用输入组件之外,Halo 还额外提供了一些输入组件,这些输入组件可以在 Form Schema 中使用。
6969

70+
### select
71+
72+
#### 描述
73+
74+
自定义的选择器组件,支持静态和动态数据源,支持多选等功能。
75+
76+
#### 参数
77+
78+
- `options`:静态数据源。当 `action` 存在时,此参数无效。
79+
- `action`:远程动态数据源的接口地址。
80+
- `requestOption`: 动态数据源的请求参数,可以通过此参数来指定如何获取数据,适配不同的接口。当 `action` 存在时,此参数有效。
81+
- `remoteOptimize`:是否开启远程数据源优化,默认为 `true`。开启后,将会对远程数据源进行优化,减少请求次数。仅在动态数据源下有效。
82+
- `allowCreate`:是否允许创建新选项,默认为 `false`。仅在静态数据源下有效。
83+
- `clearable`:是否允许清空选项,默认为 `false`。
84+
- `multiple`:是否多选,默认为 `false`。
85+
- `maxCount`:多选时最大可选数量,默认为 `Infinity`。仅在多选时有效。
86+
- `sortable`:是否支持拖动排序,默认为 `false`。仅在多选时有效。
87+
- `searchable`: 是否支持搜索,默认为 `false`。
88+
89+
#### 参数类型定义
90+
91+
```ts
92+
{
93+
options?: Array<
94+
Record<string, unknown> & {
95+
label: string;
96+
value: string;
97+
}
98+
>;
99+
action?: string;
100+
requestOption?: {
101+
method?: "GET" | "POST";
102+
103+
/**
104+
* 请求结果中 page 的字段名,默认为 `page`。
105+
*/
106+
pageField?: PropertyPath;
107+
108+
/**
109+
* 请求结果中 size 的字段名,默认为 `size`。
110+
*/
111+
sizeField?: PropertyPath;
112+
113+
/**
114+
* 请求结果中 total 的字段名,默认为 `total`。
115+
*/
116+
totalField?: PropertyPath;
117+
118+
/**
119+
* 从请求结果中解析数据的字段名,默认为 `items`。
120+
*/
121+
itemsField?: PropertyPath;
122+
123+
/**
124+
* 从 items 中解析出 label 的字段名,默认为 `label`。
125+
*/
126+
labelField?: PropertyPath;
127+
128+
/**
129+
* 从 items 中解析出 value 的字段名,默认为 `value`。
130+
*/
131+
valueField?: PropertyPath;
132+
};
133+
remoteOptimize?: boolean;
134+
allowCreate?: boolean;
135+
clearable?: boolean;
136+
multiple?: boolean;
137+
maxCount?: number;
138+
sortable?: boolean;
139+
searchable?: boolean;
140+
}
141+
```
142+
143+
#### 静态数据示例
144+
145+
```yaml
146+
- $formkit: select
147+
name: countries
148+
label: What country makes the best food?
149+
sortable: true
150+
multiple: true
151+
clearable: true
152+
searchable: true
153+
placeholder: Select a country
154+
options:
155+
- label: China
156+
value: cn
157+
- label: France
158+
value: fr
159+
- label: Germany
160+
value: de
161+
- label: Spain
162+
value: es
163+
- label: Italy
164+
value: ie
165+
- label: Greece
166+
value: gr
167+
```
168+
169+
#### 远程动态数据示例
170+
171+
支持远程动态数据源,通过 `action` 和 `requestOption` 参数来指定如何获取数据。
172+
173+
请求的接口将会自动拼接 `page`、`size` 与 `keyword` 参数,其中 `keyword` 为搜索关键词。
174+
175+
```yaml
176+
- $formkit: select
177+
name: postName
178+
label: Choose an post
179+
clearable: true
180+
action: /apis/api.console.halo.run/v1alpha1/posts
181+
requestOption:
182+
method: GET
183+
pageField: page
184+
sizeField: size
185+
totalField: total
186+
itemsField: items
187+
labelField: post.spec.title
188+
valueField: post.metadata.name
189+
```
190+
191+
:::tip
192+
当远程数据具有分页时,可能会出现默认选项不在第一页的情况,此时 Select 组件将会发送另一个查询请求,以获取默认选项的数据。此接口会携带如下参数:
193+
194+
```ts
195+
labelSelector: `${requestOption.valueField}=in(value1,value2,value3)`
196+
```
197+
198+
其中,value1, value2, value3 为默认选项的值。返回值与查询一致,通过 `requestOption` 解析。
199+
:::
200+
70201
### list
71202

72203
#### 描述

0 commit comments

Comments
 (0)