@next-bricks/form 1.21.11 → 1.21.13

package/docs/eo-auto-complete.react.md

@@ -0,0 +1,229 @@
+---
+tagName: eo-auto-complete
+displayName: WrappedEoAutoComplete
+description: 带候选项的输入框
+category: form-input-basic
+source: "@next-bricks/form"
+---
+
+# WrappedEoAutoComplete
+
+> 带候选项的输入框
+
+## 导入
+
+```tsx
+import { WrappedEoAutoComplete } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性            | 类型                          | 必填 | 默认值 | 说明                             |
+| --------------- | ----------------------------- | ---- | ------ | -------------------------------- |
+| name            | `string`                      | 否   | -      | 字段名称                         |
+| placeholder     | `string`                      | 否   | -      | 占位说明                         |
+| label           | `string`                      | 否   | -      | 字段文本                         |
+| inputStyle      | `React.CSSProperties`         | 否   | -      | 输入框样式                       |
+| disabled        | `boolean`                     | 否   | -      | 是否禁用                         |
+| required        | `boolean`                     | 否   | -      | 是否必填                         |
+| value           | `string`                      | 否   | -      | 输入框当前值                     |
+| options         | `string[] \| OptionType[]`    | 否   | -      | 选项列表                         |
+| filterByCaption | `boolean`                     | 否   | -      | 搜索时是否根据caption过滤options |
+| validator       | `(value: any) => MessageBody` | 否   | -      | 表单项校验方法                   |
+| pattern         | `string`                      | 否   | -      | 正则校验规则                     |
+| message         | `Record<string, string>`      | 否   | -      | 校验文本信息                     |
+
+## Events
+
+| 事件     | detail                    | 说明       |
+| -------- | ------------------------- | ---------- |
+| onChange | `string` — 当前输入框的值 | 值改变事件 |
+
+## Slots
+
+| 名称            | 说明               |
+| --------------- | ------------------ |
+| options-toolbar | 下拉列表底部工具栏 |
+
+## Examples
+
+### Basic
+
+展示带候选项输入框的最基本用法，通过字符串数组提供候选选项。
+
+```tsx
+<WrappedEoAutoComplete
+  options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+/>
+```
+
+### Caption
+
+通过 `OptionType` 对象格式为每个选项添加 `caption` 附加说明文字。
+
+```tsx
+<WrappedEoAutoComplete
+  options={[
+    { label: "选项1", value: "1", caption: "说明1" },
+    { label: "选项2", value: "2", caption: "说明2" },
+    { label: "选项3", value: "3", caption: "说明3" },
+  ]}
+/>
+```
+
+### 分组
+
+通过 `OptionGroup` 格式对选项进行分组展示，组内每个选项可包含 `label`、`value` 和 `caption`。
+
+```tsx
+<WrappedEoAutoComplete
+  options={[
+    { label: "选项1", value: "1", caption: "说明1" },
+    { label: "选项2", value: "2", caption: "说明2" },
+    {
+      label: "分组1",
+      options: [
+        { label: "选项3-1", value: "3-1", caption: "说明3-1" },
+        { label: "选项3-2", value: "3-2", caption: "说明3-2" },
+      ],
+    },
+  ]}
+/>
+```
+
+### filterByCaption
+
+设置 `filterByCaption` 为 `true`，搜索时同时匹配选项的 `caption` 字段。
+
+```tsx
+<WrappedEoAutoComplete
+  filterByCaption
+  options={[
+    { label: "选项1", value: "1", caption: "说明1" },
+    { label: "选项2", value: "2", caption: "说明2" },
+    {
+      label: "分组1",
+      options: [
+        { label: "选项3-1", value: "3-1", caption: "说明3-1" },
+        { label: "选项3-2", value: "3-2", caption: "说明3-2" },
+      ],
+    },
+  ]}
+/>
+```
+
+### Value
+
+通过 `value` 属性设置输入框的默认值。
+
+```tsx
+<WrappedEoAutoComplete
+  value="Beijing"
+  options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+/>
+```
+
+### Placeholder
+
+通过 `placeholder` 属性设置输入框的占位提示文字。
+
+```tsx
+<WrappedEoAutoComplete
+  placeholder="请输入城市名称"
+  options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+/>
+```
+
+### Input Style
+
+通过 `inputStyle` 属性自定义输入框的内联样式。
+
+```tsx
+<WrappedEoAutoComplete
+  inputStyle={{ width: "300px" }}
+  options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+/>
+```
+
+### Disabled
+
+设置 `disabled` 属性禁用输入框。
+
+```tsx
+<WrappedEoAutoComplete
+  disabled
+  options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+/>
+```
+
+### Events
+
+监听 `onChange` 事件获取用户输入或选中的实时值。
+
+```tsx
+<WrappedEoAutoComplete
+  options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+  onChange={(e) => console.log(e.detail)}
+/>
+```
+
+### With Form
+
+在 `WrappedEoForm` 中使用，通过 `name`、`label` 属性集成表单功能，并可配合 `required`、`pattern`、`message` 属性实现表单校验。
+
+```tsx
+<WrappedEoForm
+  onValidateSuccess={(e) => console.log(e.detail)}
+  onValuesChange={(e) => console.log(e.detail)}
+>
+  <WrappedEoAutoComplete
+    name="city"
+    label="城市"
+    required
+    pattern="^[A-Za-z]+"
+    message={{
+      required: "请选择城市",
+      pattern: "城市名称只能包含字母",
+    }}
+    options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+  />
+  <WrappedEoSubmitButtons />
+</WrappedEoForm>
+```
+
+### Validator
+
+通过 `validator` 属性自定义表单项的校验逻辑，返回 `null` 表示校验通过，返回包含 `message` 的对象表示校验失败。
+
+```tsx
+<WrappedEoForm onValidateSuccess={(e) => console.log(e.detail)}>
+  <WrappedEoAutoComplete
+    name="city"
+    label="城市"
+    options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+    validator={(value) =>
+      value && value.length > 10
+        ? { message: "城市名称不能超过10个字符" }
+        : null
+    }
+  />
+  <WrappedEoSubmitButtons />
+</WrappedEoForm>
+```
+
+### Options Toolbar Slot
+
+通过 `options-toolbar` 插槽在下拉列表底部添加自定义工具栏内容。
+
+```tsx
+<WrappedEoAutoComplete
+  options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+>
+  <span
+    slot="options-toolbar"
+    style={{ padding: "4px 8px", color: "#999", fontSize: "12px" }}
+  >
+    自定义工具栏
+  </span>
+</WrappedEoAutoComplete>
+```

package/docs/eo-checkbox.md

@@ -1,4 +1,44 @@
-表单复选框构件。
+---
+tagName: eo-checkbox
+displayName: WrappedEoCheckbox
+description: 表单复选框构件
+category: form-input-basic
+source: "@next-bricks/form"
+---
+
+# eo-checkbox
+
+> 表单复选框构件
+
+## Props
+
+| 属性         | 类型                     | 必填 | 默认值      | 说明                                                                  |
+| ------------ | ------------------------ | ---- | ----------- | --------------------------------------------------------------------- |
+| name         | `string`                 | -    | -           | 字段名称                                                              |
+| label        | `string`                 | -    | -           | 字段说明                                                              |
+| value        | `CheckboxValueType[]`    | -    | -           | 值                                                                    |
+| options      | `CheckboxOptionType[]`   | -    | `[]`        | 多选框选项表                                                          |
+| type         | `CheckboxType`           | -    | `"default"` | 类型                                                                  |
+| disabled     | `boolean`                | -    | -           | 是否禁用                                                              |
+| isCustom     | `boolean`                | -    | `false`     | 是否为自定义样式，仅在 type="icon" 时生效，启用后图标尺寸更大（52px） |
+| required     | `boolean`                | -    | -           | 是否必填                                                              |
+| message      | `Record<string, string>` | -    | -           | 校验文本                                                              |
+| isGroup      | `boolean`                | -    | -           | 是否启用分组模式，为 true 时，则可设置分组数据 optionGroups           |
+| optionGroups | `OptionGroup[]`          | -    | -           | 多选框选项分组数据，需要设置 isGroup 为 true 才生效                   |
+| themeVariant | `"default" \| "elevo"`   | -    | -           | 主题变体                                                              |
+
+## Events
+
+| 事件           | detail                                                                                                               | 说明                       |
+| -------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| change         | `CheckboxOptionType[]` — { value: 选中项的值, label: 选中项的标签, disabled: 是否禁用, checkboxColor: 复选框颜色 }[] | 复选框选中项发生变化时触发 |
+| options.change | `OptionsChangeEventDetail` — { options: 最新的选项列表, name: 字段名称 }                                             | 复选框选项数据变化时触发   |
+
+## Examples
+
+### Basic
+
+基本用法，展示简单的多选框列表。
 
 ```yaml preview
 - brick: eo-checkbox
@@ -10,10 +50,10 @@
       - Shenzhen
 ```
 
-## Examples
-
 ### Label
 
+设置 label 属性为复选框添加字段说明。
+
 ```yaml preview
 - brick: eo-checkbox
   properties:
@@ -37,6 +77,8 @@
 
 ### Value
 
+设置 value 属性指定默认选中项。
+
 ```yaml preview
 - brick: eo-checkbox
   properties:
@@ -52,6 +94,8 @@
 
 ### Options
 
+多种选项格式：字符串数组、对象数组和布尔值数组。
+
 ```yaml preview
 - brick: eo-checkbox
   properties:
@@ -87,6 +131,8 @@
 
 ### Disabled
 
+禁用单个选项或整体禁用复选框。
+
 ```yaml preview
 - brick: eo-checkbox
   properties:
@@ -125,6 +171,8 @@
 
 ### Type
 
+展示 default 和 icon 两种类型的复选框样式。
+
 ```yaml preview
 - brick: eo-checkbox
   properties:
@@ -190,8 +238,35 @@
           icon: shell
 ```
 
+### isCustom
+
+启用自定义样式（仅在 type="icon" 时生效），图标尺寸更大。
+
+```yaml preview
+- brick: eo-checkbox
+  properties:
+    label: 自定义图标样式
+    type: icon
+    isCustom: true
+    options:
+      - label: Python
+        value: 0
+        icon:
+          lib: easyops
+          category: colored-common
+          icon: python
+      - label: Javascript
+        value: 1
+        icon:
+          lib: easyops
+          category: program-language
+          icon: javascript
+```
+
 ### checkboxColor
 
+为不同选项设置自定义颜色。
+
 ```yaml preview
 - brick: eo-checkbox
   properties:
@@ -215,6 +290,8 @@
 
 ### optionGroups
 
+启用分组模式，将选项按组展示，支持全选/取消全选操作。
+
 ```yaml preview
 - brick: eo-checkbox
   events:
@@ -242,8 +319,30 @@
       - potato
 ```
 
+### themeVariant
+
+设置主题变体为 elevo 风格。
+
+```yaml preview
+- brick: eo-checkbox
+  properties:
+    themeVariant: elevo
+    label: Elevo 风格
+    options:
+      - label: Beijing
+        value: 0
+      - label: Shanghai
+        value: 1
+      - label: Guangzhou
+        value: 2
+    value:
+      - 0
+```
+
 ### Event
 
+监听 change 和 options.change 事件，通过按钮动态修改选项触发 options.change 事件。
+
 ```yaml preview
 - brick: eo-checkbox
   properties:
@@ -268,7 +367,7 @@
           - <% JSON.stringify(EVENT.detail) %>
 - brick: eo-button
   properties:
-    textContent: Click to Change Radio Option
+    textContent: Click to Change Checkbox Option
   events:
     click:
       - target: "#option-checkbox"
@@ -291,6 +390,8 @@
 
 ### With Form
 
+在表单中使用复选框，支持 required 校验和 message 自定义校验文本。
+
 ```yaml preview
 - brick: eo-form
   events:
@@ -304,6 +405,8 @@
         name: city
         label: 城市
         required: true
+        message:
+          required: 请选择至少一个城市
         options:
           - Beijing
           - Shanghai