@next-bricks/form 1.21.11 → 1.21.13

package/docs/eo-select.react.md

@@ -0,0 +1,411 @@
+---
+tagName: eo-select
+displayName: WrappedEoSelect
+description: 通用下拉选择构件
+category: form-input-basic
+source: "@next-bricks/form"
+---
+
+# WrappedEoSelect
+
+> 通用下拉选择构件
+
+## 导入
+
+```tsx
+import { WrappedEoSelect } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性                | 类型                                 | 必填 | 默认值 | 说明                                                                                           |
+| ------------------- | ------------------------------------ | ---- | ------ | ---------------------------------------------------------------------------------------------- |
+| name                | `string`                             | -    | -      | 字段名称                                                                                       |
+| placeholder         | `string`                             | -    | -      | 占位说明                                                                                       |
+| label               | `string`                             | -    | -      | 字段文本                                                                                       |
+| options             | `GeneralComplexOption[]`             | 是   | -      | 选项列表                                                                                       |
+| value               | `any`                                | -    | -      | 值                                                                                             |
+| required            | `boolean`                            | -    | -      | 是否必填                                                                                       |
+| message             | `Record<string, string>`             | -    | -      | 校验文本信息                                                                                   |
+| disabled            | `boolean`                            | -    | -      | 是否禁用                                                                                       |
+| mode                | `"tags" \| "multiple"`               | -    | -      | 类型                                                                                           |
+| tokenSeparators     | `string[]`                           | -    | -      | 自动分词的分隔符，仅在 mode="tags" 时生效                                                      |
+| maxTagCount         | `number`                             | -    | -      | 最多显示多少个 tag, 剩余的 tag 将被隐藏                                                        |
+| groupBy             | `string`                             | -    | -      | 分组字段                                                                                       |
+| suffix              | `{ useBrick: UseSingleBrickConf }`   | -    | -      | 后缀内容，使用 useBrick 在选项及选中值旁显示额外信息                                           |
+| clearable           | `boolean`                            | -    | `true` | 是否支持清除                                                                                   |
+| fields              | `{ label?: string; value?: string }` | -    | -      | 列表指定字段作为 label 和 value                                                                |
+| useBackend          | `UseBackendConf`                     | -    | -      | 后端搜索                                                                                       |
+| debounceSearchDelay | `number`                             | -    | -      | 设置时，同时对 useBackend 和 onSearch 事件进行防抖。未设置时，useBackend 有默认的 300ms 防抖。 |
+| inputStyle          | `React.CSSProperties`                | -    | -      | 输入框样式                                                                                     |
+| dropdownStyle       | `React.CSSProperties`                | -    | -      | 下拉框样式                                                                                     |
+| dropdownHoist       | `boolean`                            | -    | -      | 下拉框是否使用固定定位防止内容被裁切                                                           |
+| themeVariant        | `"default" \| "elevo"`               | -    | -      | 主题变体                                                                                       |
+
+## Events
+
+| 事件            | detail                                                                   | 说明                              |
+| --------------- | ------------------------------------------------------------------------ | --------------------------------- |
+| onChange        | `ChangeEventDetail` — { value: 选中的值, options: 对应选项列表 }         | 下拉选择事件                      |
+| onChangeV2      | `string \| string[]` — 选中的值                                          | 下拉选择事件 v2（仅传递选中的值） |
+| onSearch        | `SearchEventDetail` — { value: 当前输入的搜索词 }                        | 下拉框search事件                  |
+| onSelectFocus   | -                                                                        | 下拉框focus事件                   |
+| onOptionsChange | `OptionsChangeEventDetail` — { options: 最新的选项列表, name: 字段名称 } | 选项列表变化事件                  |
+
+## Examples
+
+### Basic
+
+基本用法，展示简单的下拉选择框。
+
+```tsx
+<WrappedEoSelect options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]} />
+```
+
+### Label
+
+设置 label 属性为下拉框添加字段说明。
+
+```tsx
+<WrappedEoSelect
+  label="city"
+  options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+/>
+```
+
+### Value
+
+设置 value 属性指定默认选中项。
+
+```tsx
+<WrappedEoSelect
+  label="city"
+  value="Shanghai"
+  options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+/>
+```
+
+### Options
+
+多种选项格式：字符串数组、对象数组和布尔值数组。
+
+```tsx
+<>
+  <WrappedEoSelect
+    label="string"
+    options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+    value="Guangzhou"
+  />
+  <div style={{ height: "20px" }} />
+  <WrappedEoSelect
+    label="Array<object>"
+    options={[
+      { label: "Beijing", value: 0 },
+      { label: "Shanghai", value: 1 },
+      { label: "Guangzhou", value: 2 },
+      { label: "Shenzhen", value: 3 },
+    ]}
+    value={2}
+  />
+  <div style={{ height: "20px" }} />
+  <WrappedEoSelect label="boolean" options={[true, false]} />
+</>
+```
+
+### Disabled
+
+禁用单个选项或整体禁用下拉框。
+
+```tsx
+<>
+  <WrappedEoSelect
+    options={[
+      { label: "Beijing", value: 0, disabled: true },
+      { label: "Shanghai", value: 1 },
+      { label: "Guangzhou", value: 2 },
+      { label: "Shenzhen", value: 3 },
+    ]}
+  />
+  <WrappedEoSelect
+    disabled={true}
+    options={[
+      { label: "Beijing", value: 0 },
+      { label: "Shanghai", value: 1 },
+      { label: "Guangzhou", value: 2 },
+      { label: "Shenzhen", value: 3 },
+    ]}
+  />
+</>
+```
+
+### Multiple
+
+多选模式，支持同时选择多个选项。
+
+```tsx
+<WrappedEoSelect
+  label="multiple"
+  mode="multiple"
+  value={["Beijing", "Guangzhou"]}
+  options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+/>
+```
+
+### Tags
+
+标签模式，支持自定义输入新标签、自动分词和最大标签数限制。
+
+```tsx
+<WrappedEoSelect
+  label="tags"
+  mode="tags"
+  tokenSeparators={[" ", ";", "；"]}
+  maxTagCount={3}
+  options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+/>
+```
+
+### Placeholder
+
+设置 placeholder 占位说明。
+
+```tsx
+<WrappedEoSelect
+  placeholder="This is placeholder..."
+  options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+/>
+```
+
+### Suffix
+
+使用 suffix 的 useBrick 在选项旁显示额外信息。
+
+```tsx
+<WrappedEoSelect
+  placeholder="This is placeholder..."
+  options={[
+    { label: "Beijing", value: 1, color: "red", tag: "京" },
+    { label: "Shanghai", value: 2, color: "green", tag: "沪" },
+    { label: "Guangzhou", value: 3, color: "blue", tag: "粤" },
+    { label: "Shenzhen", value: 4, color: "yellow", tag: "粤" },
+  ]}
+  suffix={{
+    useBrick: {
+      brick: "eo-tag",
+      properties: {
+        textContent: "<% DATA.tag %>",
+        color: "<% DATA.color %>",
+      },
+    },
+  }}
+/>
+```
+
+### GroupBy
+
+使用 groupBy 属性按指定字段对选项进行分组展示。
+
+```tsx
+<WrappedEoSelect
+  placeholder="This is placeholder..."
+  groupBy="tag"
+  options={[
+    { label: "Beijing", value: 1, color: "red", tag: "京" },
+    { label: "Shanghai", value: 2, color: "green", tag: "沪" },
+    { label: "Guangzhou", value: 3, color: "blue", tag: "粤" },
+    { label: "Shenzhen", value: 4, color: "yellow", tag: "粤" },
+  ]}
+/>
+```
+
+### Caption
+
+使用 caption 展示下拉候选项说明文案。
+
+```tsx
+<WrappedEoSelect
+  placeholder="This is placeholder..."
+  options={[
+    { caption: "如nginx、api_gateway等", label: "接入层", value: "接入层" },
+    { caption: "如DB等", label: "数据层", value: "数据层" },
+    { caption: "如业务逻辑组件", label: "业务层", value: "业务层" },
+    { caption: "如平台通用组件", label: "中台层", value: "中台层" },
+  ]}
+/>
+```
+
+### Fields
+
+使用 fields 属性指定选项列表中哪些字段作为 label 和 value。
+
+```tsx
+<WrappedEoSelect
+  placeholder="This is placeholder..."
+  fields={{ label: "name", value: "city" }}
+  value={3}
+  options={[
+    { name: "Beijing", city: 1, color: "red", tag: "京" },
+    { name: "Shanghai", city: 2, color: "green", tag: "沪" },
+    { name: "Guangzhou", city: 3, color: "blue", tag: "粤" },
+    { name: "Shenzhen", city: 4, color: "yellow", tag: "粤" },
+  ]}
+/>
+```
+
+### UseBackend
+
+使用后端搜索从远程接口获取选项数据。
+
+```tsx
+<WrappedEoSelect
+  label="useBackend"
+  placeholder="后端搜索"
+  value="Shenzhen"
+  useBackend={{
+    provider: "basic.http-request",
+    transform: (data: any) => data,
+    onValueChangeArgs: [
+      (q: string) => `//api.weatherapi.com/v1/search.json?q=${q}&key=YOUR_KEY`,
+    ],
+    args: [
+      (q: string) =>
+        `//api.weatherapi.com/v1/search.json?q=${q ? q : "China"}&key=YOUR_KEY`,
+    ],
+  }}
+  fields={{ label: "name", value: "name" }}
+  suffix={{
+    useBrick: {
+      brick: "eo-tag",
+      properties: {
+        textContent: "<% DATA.country %>",
+      },
+    },
+  }}
+/>
+```
+
+### Input Style
+
+使用 inputStyle 自定义输入框样式。
+
+```tsx
+<WrappedEoSelect
+  inputStyle={{ width: "180px" }}
+  options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+/>
+```
+
+### Dropdown Style And Hoist
+
+使用 dropdownStyle 自定义下拉框样式，dropdownHoist 使用固定定位防止内容被裁切。
+
+```tsx
+<WrappedEoSelect
+  label="自定义下拉框样式"
+  dropdownStyle={{ maxHeight: "150px" }}
+  dropdownHoist={true}
+  options={[
+    "Beijing",
+    "Shanghai",
+    "Guangzhou",
+    "Shenzhen",
+    "Hangzhou",
+    "Chengdu",
+  ]}
+/>
+```
+
+### Clearable
+
+设置 clearable 为 false 禁用清除按钮。
+
+```tsx
+<WrappedEoSelect
+  label="不可清除"
+  clearable={false}
+  value="Beijing"
+  options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+/>
+```
+
+### themeVariant
+
+设置主题变体为 elevo 风格。
+
+```tsx
+<WrappedEoSelect
+  themeVariant="elevo"
+  label="Elevo 风格"
+  options={["Beijing", "Shanghai", "Guangzhou"]}
+  value="Beijing"
+/>
+```
+
+### Event
+
+监听 onChange、onChangeV2、onSearch、onSelectFocus 和 onOptionsChange 事件。
+
+```tsx
+function SelectEventDemo() {
+  const [options, setOptions] = useState([
+    "Beijing",
+    "Shanghai",
+    "Guangzhou",
+    "Shenzhen",
+  ]);
+
+  return (
+    <>
+      <WrappedEoSelect
+        label="Single"
+        debounceSearchDelay={500}
+        options={options}
+        onChange={(e) => console.log("change:", e.detail)}
+        onChangeV2={(e) => console.log("change.v2:", e.detail)}
+        onSearch={(e) => console.log("search:", e.detail)}
+        onSelectFocus={() => console.log("select focused")}
+        onOptionsChange={(e) => console.log("options.change:", e.detail)}
+      />
+      <WrappedEoSelect
+        label="Multiple"
+        mode="multiple"
+        options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+        onChange={(e) => console.log("change:", e.detail)}
+      />
+      <WrappedEoButton
+        textContent="Click to change options"
+        onClick={() =>
+          setOptions([
+            "Beijing",
+            "Shanghai",
+            "Guangzhou",
+            "Shenzhen",
+            "Hangzhou",
+          ])
+        }
+      />
+      <div style={{ height: "20px" }} />
+    </>
+  );
+}
+```
+
+### With Form
+
+在表单中使用下拉选择框，支持 required 校验和 message 自定义校验文本。
+
+```tsx
+<WrappedEoForm
+  onValidateSuccess={(e) => console.log(e.detail)}
+  onValuesChange={(e) => console.log(e.detail)}
+>
+  <WrappedEoSelect
+    options={["Beijing", "Shanghai", "Guangzhou", "Shenzhen"]}
+    label="选择框"
+    name="select"
+    required={true}
+    message={{ required: "请选择一个选项" }}
+  />
+  <WrappedEoSubmitButtons />
+</WrappedEoForm>
+```

package/docs/eo-submit-buttons.md

@@ -1,14 +1,40 @@
-表单提交按钮。
-(tips: 通常在于 eo-form 构件搭配使用)
+---
+tagName: eo-submit-buttons
+displayName: WrappedEoSubmitButtons
+description: 表单提交按钮
+category: form-input-basic
+source: "@next-bricks/form"
+---
 
-```yaml preview
-- brick: eo-submit-buttons
-```
+# eo-submit-buttons
+
+> 表单提交按钮
+
+## Props
+
+| 属性              | 类型                   | 必填 | 默认值   | 说明                                   |
+| ----------------- | ---------------------- | ---- | -------- | -------------------------------------- |
+| submitText        | `string`               | 是   | `"提交"` | 提交按钮的文字                         |
+| cancelText        | `string`               | 否   | -        | 取消按钮的文字，不设置则不显示取消按钮 |
+| disableAfterClick | `boolean`              | 否   | -        | 点击确定按钮后自动禁用                 |
+| submitDisabled    | `boolean`              | 否   | -        | 禁用提交按钮                           |
+| submitType        | `ButtonType`           | 否   | -        | 提交按钮类型                           |
+| cancelType        | `ButtonType`           | 否   | -        | 取消按钮类型                           |
+| themeVariant      | `"default" \| "elevo"` | 否   | -        | 主题变体                               |
+
+## Events
+
+| 事件   | detail | 说明                   |
+| ------ | ------ | ---------------------- |
+| submit | `void` | 点击提交按钮触发的事件 |
+| cancel | `void` | 点击取消按钮触发的事件 |
 
 ## Examples
 
 ### Basic
 
+展示提交按钮与取消按钮的基本用法，并监听点击事件。
+
 ```yaml preview
 - brick: eo-submit-buttons
   properties:
@@ -25,7 +51,9 @@
           - Cancel
 ```
 
-### Button types
+### Button Types
+
+通过 submitType 和 cancelType 自定义按钮的样式类型。
 
 ```yaml preview
 - brick: eo-submit-buttons
@@ -36,7 +64,9 @@
     cancelType: default
 ```
 
-### Disable submit button
+### Disable Submit Button
+
+展示 submitDisabled 禁用提交按钮的效果。
 
 ```yaml preview
 - brick: eo-submit-buttons
@@ -45,3 +75,86 @@
     cancelText: Cancel
     submitDisabled: true
 ```
+
+### Disable After Click
+
+演示 disableAfterClick 在点击提交后自动禁用按钮，防止重复提交。
+
+```yaml preview
+- brick: eo-submit-buttons
+  properties:
+    submitText: 提交
+    cancelText: 取消
+    disableAfterClick: true
+  events:
+    submit:
+      - action: message.success
+        args:
+          - 已提交，按钮已禁用
+    cancel:
+      - action: message.info
+        args:
+          - 已取消
+```
+
+### Theme Variant Elevo
+
+展示 Elevo 主题变体下提交按钮的样式。
+
+```yaml preview
+- brick: eo-submit-buttons
+  properties:
+    submitText: 提交
+    cancelText: 取消
+    themeVariant: elevo
+    submitType: primary
+    cancelType: default
+  events:
+    submit:
+      - action: message.success
+        args:
+          - 提交成功
+    cancel:
+      - action: message.info
+        args:
+          - 已取消
+```
+
+### In Form
+
+与 eo-form 搭配使用，演示完整的表单提交流程。
+
+```yaml preview
+- brick: eo-form
+  events:
+    validate.success:
+      - action: message.success
+        args:
+          - 表单提交成功
+    validate.error:
+      - action: message.error
+        args:
+          - 表单校验失败
+  slots:
+    "":
+      bricks:
+        - brick: eo-input
+          properties:
+            required: true
+            name: name
+            label: 姓名
+        - brick: eo-select
+          properties:
+            required: true
+            name: city
+            label: 城市
+            options:
+              - label: 北京
+                value: beijing
+              - label: 上海
+                value: shanghai
+        - brick: eo-submit-buttons
+          properties:
+            submitText: 提交
+            cancelText: 取消
+```

package/docs/eo-submit-buttons.react.md

@@ -0,0 +1,129 @@
+---
+tagName: eo-submit-buttons
+displayName: WrappedEoSubmitButtons
+description: 表单提交按钮
+category: form-input-basic
+source: "@next-bricks/form"
+---
+
+# WrappedEoSubmitButtons
+
+> 表单提交按钮
+
+## 导入
+
+```tsx
+import { WrappedEoSubmitButtons } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性              | 类型                   | 必填 | 默认值   | 说明                                   |
+| ----------------- | ---------------------- | ---- | -------- | -------------------------------------- |
+| submitText        | `string`               | 是   | `"提交"` | 提交按钮的文字                         |
+| cancelText        | `string`               | 否   | -        | 取消按钮的文字，不设置则不显示取消按钮 |
+| disableAfterClick | `boolean`              | 否   | -        | 点击确定按钮后自动禁用                 |
+| submitDisabled    | `boolean`              | 否   | -        | 禁用提交按钮                           |
+| submitType        | `ButtonType`           | 否   | -        | 提交按钮类型                           |
+| cancelType        | `ButtonType`           | 否   | -        | 取消按钮类型                           |
+| themeVariant      | `"default" \| "elevo"` | 否   | -        | 主题变体                               |
+
+## Events
+
+| 事件     | detail | 说明                   |
+| -------- | ------ | ---------------------- |
+| onSubmit | `void` | 点击提交按钮触发的事件 |
+| onCancel | `void` | 点击取消按钮触发的事件 |
+
+## Examples
+
+### Basic
+
+展示提交按钮与取消按钮的基本用法，并监听点击事件。
+
+```tsx
+<WrappedEoSubmitButtons
+  submitText="Submit"
+  cancelText="Cancel"
+  onSubmit={() => console.log("Submit")}
+  onCancel={() => console.log("Cancel")}
+/>
+```
+
+### Button Types
+
+通过 submitType 和 cancelType 自定义按钮的样式类型。
+
+```tsx
+<WrappedEoSubmitButtons
+  submitText="Submit"
+  cancelText="Cancel"
+  submitType="primary"
+  cancelType="default"
+/>
+```
+
+### Disable Submit Button
+
+展示 submitDisabled 禁用提交按钮的效果。
+
+```tsx
+<WrappedEoSubmitButtons
+  submitText="Submit"
+  cancelText="Cancel"
+  submitDisabled
+/>
+```
+
+### Disable After Click
+
+演示 disableAfterClick 在点击提交后自动禁用按钮，防止重复提交。
+
+```tsx
+<WrappedEoSubmitButtons
+  submitText="提交"
+  cancelText="取消"
+  disableAfterClick
+  onSubmit={() => console.log("已提交，按钮已禁用")}
+  onCancel={() => console.log("已取消")}
+/>
+```
+
+### Theme Variant Elevo
+
+展示 Elevo 主题变体下提交按钮的样式。
+
+```tsx
+<WrappedEoSubmitButtons
+  submitText="提交"
+  cancelText="取消"
+  themeVariant="elevo"
+  submitType="primary"
+  cancelType="default"
+  onSubmit={() => console.log("提交成功")}
+  onCancel={() => console.log("已取消")}
+/>
+```
+
+### In Form
+
+与 WrappedEoForm 搭配使用，演示完整的表单提交流程。
+
+```tsx
+<WrappedEoForm
+  onValidateSuccess={(e) => console.log("表单提交成功", e.detail)}
+  onValidateError={(e) => console.log("表单校验失败", e.detail)}
+>
+  <WrappedEoInput required name="name" label="姓名" />
+  <WrappedEoSelect
+    required
+    name="city"
+    label="城市"
+    options={[
+      { label: "北京", value: "beijing" },
+      { label: "上海", value: "shanghai" },
+    ]}
+  />
+  <WrappedEoSubmitButtons submitText="提交" cancelText="取消" />
+</WrappedEoForm>
+```