@next-bricks/form 1.21.11 → 1.21.13

package/docs/eo-search.md

@@ -1,9 +1,41 @@
-搜索框
+---
+tagName: eo-search
+displayName: WrappedEoSearch
+description: 搜索框
+category: interact-basic
+source: "@next-bricks/form"
+---
+
+# eo-search
+
+> 搜索框
+
+## Props
+
+| 属性         | 类型                   | 必填 | 默认值 | 说明                     |
+| ------------ | ---------------------- | ---- | ------ | ------------------------ |
+| value        | `string`               | 是   | `""`   | 搜索框的值               |
+| placeholder  | `string`               | 否   | -      | 提示语                   |
+| autoFocus    | `boolean`              | 否   | -      | 是否自动聚焦             |
+| clearable    | `boolean`              | 否   | -      | 可以点击清除图标删除内容 |
+| trim         | `boolean`              | 否   | -      | 是否剔除前后空格         |
+| debounceTime | `number`               | 是   | `0`    | 默认延迟时间             |
+| inputStyle   | `CSSProperties`        | 否   | -      | 输入框样式               |
+| themeVariant | `"default" \| "elevo"` | 否   | -      | 主题变体                 |
+
+## Events
+
+| 事件   | detail                | 说明                           |
+| ------ | --------------------- | ------------------------------ |
+| change | `string` — 当前输入值 | 输入的搜索字符，输入变化时触发 |
+| search | `string` — 搜索关键词 | 搜索时触发                     |
 
 ## Examples
 
 ### Basic
 
+展示搜索框的最基本用法，配合 `placeholder`、`clearable` 和 `trim` 属性，并监听 `change` 和 `search` 事件。
+
 ```yaml preview
 - brick: eo-search
   properties:
@@ -20,3 +52,64 @@
       args:
         - "<% EVENT.detail %>"
 ```
+
+### Value
+
+通过 `value` 属性设置搜索框的默认值。
+
+```yaml preview
+- brick: eo-search
+  properties:
+    value: 默认搜索词
+    placeholder: 请输入
+```
+
+### AutoFocus
+
+设置 `autoFocus` 属性使搜索框在页面加载后自动获取焦点。
+
+```yaml preview
+- brick: eo-search
+  properties:
+    autoFocus: true
+    placeholder: 自动聚焦
+```
+
+### Debounce
+
+通过 `debounceTime` 属性设置 `change` 事件的防抖延迟时间（毫秒），减少频繁触发。
+
+```yaml preview
+- brick: eo-search
+  properties:
+    placeholder: 防抖 500ms
+    debounceTime: 500
+  events:
+    change:
+      action: console.log
+      args:
+        - "<% EVENT.detail %>"
+```
+
+### Input Style
+
+通过 `inputStyle` 属性自定义搜索框的内联样式。
+
+```yaml preview
+- brick: eo-search
+  properties:
+    placeholder: 自定义样式
+    inputStyle:
+      width: 300px
+```
+
+### Theme Variant
+
+通过 `themeVariant` 属性切换搜索框的主题变体，支持 `default` 和 `elevo`。
+
+```yaml preview
+- brick: eo-search
+  properties:
+    placeholder: elevo 主题
+    themeVariant: elevo
+```

package/docs/eo-search.react.md

@@ -0,0 +1,122 @@
+---
+tagName: eo-search
+displayName: WrappedEoSearch
+description: 搜索框
+category: interact-basic
+source: "@next-bricks/form"
+---
+
+# WrappedEoSearch
+
+> 搜索框
+
+## 导入
+
+```tsx
+import { WrappedEoSearch } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性         | 类型                   | 必填 | 默认值 | 说明                     |
+| ------------ | ---------------------- | ---- | ------ | ------------------------ |
+| value        | `string`               | 是   | `""`   | 搜索框的值               |
+| placeholder  | `string`               | 否   | -      | 提示语                   |
+| autoFocus    | `boolean`              | 否   | -      | 是否自动聚焦             |
+| clearable    | `boolean`              | 否   | -      | 可以点击清除图标删除内容 |
+| trim         | `boolean`              | 否   | -      | 是否剔除前后空格         |
+| debounceTime | `number`               | 是   | `0`    | 默认延迟时间             |
+| inputStyle   | `React.CSSProperties`  | 否   | -      | 输入框样式               |
+| themeVariant | `"default" \| "elevo"` | 否   | -      | 主题变体                 |
+
+## Events
+
+| 事件     | detail                | 说明                           |
+| -------- | --------------------- | ------------------------------ |
+| onChange | `string` — 当前输入值 | 输入的搜索字符，输入变化时触发 |
+| onSearch | `string` — 搜索关键词 | 搜索时触发                     |
+
+## Examples
+
+### Basic
+
+展示搜索框的最基本用法，配合 `placeholder`、`clearable` 和 `trim` 属性，并监听 `onChange` 和 `onSearch` 事件。
+
+```tsx
+<WrappedEoSearch
+  placeholder="请输入"
+  clearable
+  trim
+  onChange={(e) => console.log(e.detail)}
+  onSearch={(e) => console.log(e.detail)}
+/>
+```
+
+### Value
+
+通过 `value` 属性设置搜索框的默认值。
+
+```tsx
+<WrappedEoSearch value="默认搜索词" placeholder="请输入" />
+```
+
+### AutoFocus
+
+设置 `autoFocus` 属性使搜索框在页面加载后自动获取焦点。
+
+```tsx
+<WrappedEoSearch autoFocus placeholder="自动聚焦" />
+```
+
+### Debounce
+
+通过 `debounceTime` 属性设置 `onChange` 事件的防抖延迟时间（毫秒），减少频繁触发。
+
+```tsx
+<WrappedEoSearch
+  placeholder="防抖 500ms"
+  debounceTime={500}
+  onChange={(e) => console.log(e.detail)}
+/>
+```
+
+### Input Style
+
+通过 `inputStyle` 属性自定义搜索框的内联样式。
+
+```tsx
+<WrappedEoSearch placeholder="自定义样式" inputStyle={{ width: "300px" }} />
+```
+
+### Theme Variant
+
+通过 `themeVariant` 属性切换搜索框的主题变体，支持 `default` 和 `elevo`。
+
+```tsx
+<WrappedEoSearch placeholder="elevo 主题" themeVariant="elevo" />
+```
+
+### Events
+
+使用 `useState` 管理搜索状态，同时监听 `onChange` 实时更新输入值和 `onSearch` 触发搜索。
+
+```tsx
+function SearchExample() {
+  const [searchValue, setSearchValue] = React.useState("");
+  const [result, setResult] = React.useState("");
+
+  return (
+    <div>
+      <WrappedEoSearch
+        value={searchValue}
+        placeholder="请输入搜索内容"
+        clearable
+        trim
+        onChange={(e) => setSearchValue(e.detail)}
+        onSearch={(e) => setResult(e.detail)}
+      />
+      {result && <p>搜索关键词：{result}</p>}
+    </div>
+  );
+}
+```

package/docs/eo-select.md

@@ -1,4 +1,56 @@
-表单下拉选择构件。
+---
+tagName: eo-select
+displayName: WrappedEoSelect
+description: 通用下拉选择构件
+category: form-input-basic
+source: "@next-bricks/form"
+---
+
+# eo-select
+
+> 通用下拉选择构件
+
+## 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 和 search 事件进行防抖。未设置时，useBackend 有默认的 300ms 防抖。 |
+| inputStyle          | `React.CSSProperties`                | -    | -      | 输入框样式                                                                                   |
+| dropdownStyle       | `React.CSSProperties`                | -    | -      | 下拉框样式                                                                                   |
+| dropdownHoist       | `boolean`                            | -    | -      | 下拉框是否使用固定定位防止内容被裁切                                                         |
+| themeVariant        | `"default" \| "elevo"`               | -    | -      | 主题变体                                                                                     |
+
+## Events
+
+| 事件           | detail                                                                   | 说明                              |
+| -------------- | ------------------------------------------------------------------------ | --------------------------------- |
+| change         | `ChangeEventDetail` — { value: 选中的值, options: 对应选项列表 }         | 下拉选择事件                      |
+| change.v2      | `string \| string[]` — 选中的值                                          | 下拉选择事件 v2（仅传递选中的值） |
+| search         | `SearchEventDetail` — { value: 当前输入的搜索词 }                        | 下拉框search事件                  |
+| select.focus   | -                                                                        | 下拉框focus事件                   |
+| options.change | `OptionsChangeEventDetail` — { options: 最新的选项列表, name: 字段名称 } | 选项列表变化事件                  |
+
+## Examples
+
+### Basic
+
+基本用法，展示简单的下拉选择框。
 
 ```yaml preview minHeight="250px"
 - brick: eo-select
@@ -10,10 +62,10 @@
       - Shenzhen
 ```
 
-## Examples
-
 ### Label
 
+设置 label 属性为下拉框添加字段说明。
+
 ```yaml preview minHeight="250px"
 - brick: eo-select
   properties:
@@ -27,6 +79,8 @@
 
 ### Value
 
+设置 value 属性指定默认选中项。
+
 ```yaml preview minHeight="250px"
 - brick: eo-select
   properties:
@@ -41,6 +95,8 @@
 
 ### Options
 
+多种选项格式：字符串数组、对象数组和布尔值数组。
+
 ```yaml preview minHeight="300px"
 - brick: eo-select
   properties:
@@ -82,6 +138,8 @@
 
 ### Disabled
 
+禁用单个选项或整体禁用下拉框。
+
 ```yaml preview minHeight="250px"
 - brick: eo-select
   properties:
@@ -111,6 +169,8 @@
 
 ### Multiple
 
+多选模式，支持同时选择多个选项。
+
 ```yaml preview minHeight="250px"
 - brick: eo-select
   properties:
@@ -128,6 +188,8 @@
 
 ### Tags
 
+标签模式，支持自定义输入新标签、自动分词和最大标签数限制。
+
 ```yaml preview minHeight="250px"
 - brick: eo-select
   properties:
@@ -147,6 +209,8 @@
 
 ### Placeholder
 
+设置 placeholder 占位说明。
+
 ```yaml preview minHeight="250px"
 - brick: eo-select
   properties:
@@ -160,6 +224,8 @@
 
 ### Suffix
 
+使用 suffix 的 useBrick 在选项旁显示额外信息。
+
 ```yaml preview minHeight="250px"
 - brick: eo-select
   properties:
@@ -191,6 +257,8 @@
 
 ### GroupBy
 
+使用 groupBy 属性按指定字段对选项进行分组展示。
+
 ```yaml preview minHeight="300px"
 - brick: eo-select
   properties:
@@ -215,7 +283,9 @@
         tag: 粤
 ```
 
-### caption 展示下拉候选项说明文案
+### Caption
+
+使用 caption 展示下拉候选项说明文案。
 
 ```yaml preview minHeight="300px"
 - brick: eo-select
@@ -238,6 +308,8 @@
 
 ### Fields
 
+使用 fields 属性指定选项列表中哪些字段作为 label 和 value。
+
 ```yaml preview minHeight="300px"
 - brick: eo-select
   properties:
@@ -267,6 +339,8 @@
 
 ### UseBackend
 
+使用后端搜索从远程接口获取选项数据。
+
 ```yaml preview minHeight="300px"
 - brick: eo-select
   properties:
@@ -279,14 +353,14 @@
         <% (data) => data %>
       onValueChangeArgs:
         - |
-          <% 
-            (q) => 
+          <%
+            (q) =>
               `//api.weatherapi.com/v1/search.json?q=${q}&key=${MISC.weather_api_key}`
           %>
       args:
         - |
-          <% 
-            (q) => 
+          <%
+            (q) =>
               `//api.weatherapi.com/v1/search.json?q=${q ? q : "China"}&key=${MISC.weather_api_key}`
           %>
     fields:
@@ -301,6 +375,8 @@
 
 ### Input Style
 
+使用 inputStyle 自定义输入框样式。
+
 ```yaml preview minHeight="250px"
 - brick: eo-select
   properties:
@@ -313,13 +389,69 @@
       - Shenzhen
 ```
 
+### Dropdown Style And Hoist
+
+使用 dropdownStyle 自定义下拉框样式，dropdownHoist 使用固定定位防止内容被裁切。
+
+```yaml preview minHeight="350px"
+- brick: eo-select
+  properties:
+    label: 自定义下拉框样式
+    dropdownStyle:
+      maxHeight: 150px
+    dropdownHoist: true
+    options:
+      - Beijing
+      - Shanghai
+      - Guangzhou
+      - Shenzhen
+      - Hangzhou
+      - Chengdu
+```
+
+### Clearable
+
+设置 clearable 为 false 禁用清除按钮。
+
+```yaml preview minHeight="250px"
+- brick: eo-select
+  properties:
+    label: 不可清除
+    clearable: false
+    value: Beijing
+    options:
+      - Beijing
+      - Shanghai
+      - Guangzhou
+      - Shenzhen
+```
+
+### themeVariant
+
+设置主题变体为 elevo 风格。
+
+```yaml preview minHeight="250px"
+- brick: eo-select
+  properties:
+    themeVariant: elevo
+    label: Elevo 风格
+    options:
+      - Beijing
+      - Shanghai
+      - Guangzhou
+    value: Beijing
+```
+
 ### Event
 
+监听 change、change.v2、search、select.focus 和 options.change 事件。
+
 ```yaml preview minHeight="400px"
 - brick: eo-select
   properties:
     id: options-change-select
     label: Single
+    debounceSearchDelay: 500
     options:
       - Beijing
       - Shanghai
@@ -330,6 +462,18 @@
       - action: message.success
         args:
           - <% JSON.stringify(EVENT.detail) %>
+    change.v2:
+      - action: console.log
+        args:
+          - <% EVENT.detail %>
+    search:
+      - action: console.log
+        args:
+          - <% JSON.stringify(EVENT.detail) %>
+    select.focus:
+      - action: console.log
+        args:
+          - select focused
     options.change:
       - action: message.success
         args:
@@ -337,7 +481,7 @@
 - brick: eo-select
   properties:
     label: Multiple
-    multiple: true
+    mode: multiple
     options:
       - Beijing
       - Shanghai
@@ -369,6 +513,8 @@
 
 ### With Form
 
+在表单中使用下拉选择框，支持 required 校验和 message 自定义校验文本。
+
 ```yaml preview minHeight="250px"
 - brick: eo-form
   events:
@@ -387,5 +533,7 @@
         label: 选择框
         name: select
         required: true
+        message:
+          required: 请选择一个选项
     - brick: eo-submit-buttons
 ```