@next-bricks/form 1.21.11 → 1.21.13

package/dist-types/auto-complete/index.d.ts

@@ -34,6 +34,7 @@ export type OptionType = Option | OptionGroup;
  * @author zhendonghuang
  *
  * @category form-input-basic
+ * @slot options-toolbar - 下拉列表底部工具栏
  */
 export declare class AutoComplete extends FormItemElementBase {
     #private;
@@ -61,6 +62,9 @@ export declare class AutoComplete extends FormItemElementBase {
      * 是否必填
      */
     accessor required: boolean | undefined;
+    /**
+     * 输入框当前值
+     */
     accessor value: string | undefined;
     /**
      * 选项列表

package/dist-types/checkbox/index.d.ts

@@ -77,7 +77,7 @@ declare class Checkbox extends FormItemElementBase {
      */
     accessor disabled: boolean | undefined;
     /**
-     * 是否为自定义
+     * 是否为自定义样式，仅在 type="icon" 时生效，启用后图标尺寸更大（52px）
      * @default false
      */
     accessor isCustom: boolean;
@@ -90,7 +90,7 @@ declare class Checkbox extends FormItemElementBase {
      */
     accessor message: Record<string, string> | undefined;
     /**
-     * 是否为复选框，为true时，则可设置分组数据 optionGroups
+     * 是否启用分组模式，为 true 时，则可设置分组数据 optionGroups
      */
     accessor isGroup: boolean | undefined;
     /**

package/dist-types/color-picker/index.d.ts

@@ -15,8 +15,9 @@ export interface EoColorPickerEventsMapping {
     onChange: "change";
 }
 /**
- * 构件 `eo-color-picker`
+ * 颜色选择器
  * @author astrid
+ * @category form-input-basic
  */
 export declare class EoColorPicker extends FormItemElementBase implements EoColorPickerProps {
     #private;

package/dist-types/date-picker/index.d.ts

@@ -19,7 +19,7 @@ interface InternalStateDatePickerProps {
     onChange?: (value: Dayjs | null, dateString: string) => void;
     onOk?: (date: Dayjs) => void;
 }
-interface EoDatePickerProps extends Omit<InternalStateDatePickerProps, "value" | "onChange" | "onOk">, FormItemProps {
+export interface EoDatePickerProps extends Omit<InternalStateDatePickerProps, "value" | "onChange" | "onOk">, FormItemProps {
     shadowRoot: ShadowRoot | null;
     value?: string;
     onChange?: (value: string) => void;

package/dist-types/form/index.d.ts

@@ -44,6 +44,9 @@ declare class Form extends ReactNextElement implements FormProps, AbstractForm {
     get isFormElement(): true;
     set values(value: Record<string, unknown>);
     get values(): Record<string, unknown>;
+    /**
+     * 静态附加值，在表单验证成功时会合并到 validate.success 事件的 detail 中
+     */
     accessor staticValues: Record<string, unknown> | undefined;
     /**
      * 布局方式(默认 vertical 布局)
@@ -62,6 +65,9 @@ declare class Form extends ReactNextElement implements FormProps, AbstractForm {
      * 输入控件列布局样式（仅当 layout="horizontal" 时有效）
      */
     accessor wrapperCol: ColProps;
+    /**
+     * 是否在验证失败时自动滚动到第一个错误字段
+     */
     accessor autoScrollToInvalidFields: boolean | undefined;
     handleValuesChange: (values: Record<string, unknown>) => void;
     /**
@@ -70,6 +76,8 @@ declare class Form extends ReactNextElement implements FormProps, AbstractForm {
     validate(): boolean | Record<string, unknown>;
     /**
      * 表单设置值方法
+     * @param values - 要设置的表单字段值
+     * @param options - 可选配置，支持 runInMicrotask（微任务中执行）和 runInMacrotask（宏任务中执行）
      */
     setInitValue(values: Record<string, unknown>, options?: {
         runInMacrotask?: boolean;
@@ -77,15 +85,22 @@ declare class Form extends ReactNextElement implements FormProps, AbstractForm {
     }): void;
     /**
      * 表单重置值方法
+     * @param name - 要重置的字段名，不传则重置所有字段
      */
     resetFields(name?: string): void;
     /**
      * 获取表单值方法
+     * @param name - 要获取的字段名，不传则获取所有字段的值
+     * @returns 指定字段的值，或所有字段值的对象
+     */
+    getFieldsValue(name?: string): Record<string, unknown> | unknown;
+    /**
+     * 表单自定义样式
      */
-    getFieldsValue(name?: string): unknown;
     accessor formStyle: React.CSSProperties | undefined;
     /**
      * 校验表单字段方法
+     * @param name - 要校验的字段名
      */
     validateField(name: string): void;
     /**

package/dist-types/form-item/index.d.ts

@@ -5,7 +5,7 @@ import type { ComponentSize, Layout } from "../interface.js";
 import type { Form } from "../form/index.js";
 export type { FormItemProps };
 /**
- * 通用输入框构件
+ * 表单项构件
  * @author sailor
  * @slot - 表单项内容
  * @category form-input-basic
@@ -18,11 +18,29 @@ declare class FormItem extends FormItemElementBase implements FormItemProps {
      * 字段名称
      */
     accessor name: string | undefined;
+    /**
+     * 标签文字
+     */
     accessor label: string | undefined;
+    /**
+     * 正则校验规则
+     */
     accessor pattern: string | undefined;
+    /**
+     * 校验失败时的提示信息
+     */
     accessor message: Record<string, string> | undefined;
+    /**
+     * 校验类型
+     */
     accessor type: string | undefined;
+    /**
+     * 表单校验最大值（当 type 为 number 时表示最大数值，否则表示最大长度）
+     */
     accessor max: number | undefined;
+    /**
+     * 表单校验最小值（当 type 为 number 时表示最小数值，否则表示最小长度）
+     */
     accessor min: number | undefined;
     /**
      * 表单项是否为必填
@@ -33,8 +51,18 @@ declare class FormItem extends FormItemElementBase implements FormItemProps {
      * 初始值
      */
     accessor value: string | undefined;
+    /**
+     * 子构件中对应值的属性名
+     * @default "value"
+     */
     accessor valuePropsName: string | undefined;
+    /**
+     * 布局方式
+     */
     accessor layout: Layout | undefined;
+    /**
+     * 尺寸
+     */
     accessor size: ComponentSize | undefined;
     /**
      * 是否自动去除前后的空白字符
@@ -44,6 +72,7 @@ declare class FormItem extends FormItemElementBase implements FormItemProps {
     accessor trim: boolean;
     /**
      * 事件触发方法名
+     * @default "onChange"
      */
     accessor trigger: string;
     /**
@@ -51,7 +80,7 @@ declare class FormItem extends FormItemElementBase implements FormItemProps {
      */
     accessor validator: ((value: any) => MessageBody) | undefined;
     /**
-     * 值变化时是否主动出发校验
+     * 值变化时是否主动触发校验
      */
     accessor needValidate: boolean | undefined;
     disconnectedCallback(): void;

package/dist-types/general-switch/index.d.ts

@@ -62,7 +62,7 @@ export declare class GeneralSwitch extends FormItemElementBase {
      */
     accessor checkedIcon: GeneralIconProps | undefined;
     /**
-     * 非选中时的文本
+     * 非选中时的图标
      */
     accessor unCheckedIcon: GeneralIconProps | undefined;
     /** 主题变体 */

package/dist-types/icon-select/index.d.ts

@@ -49,7 +49,7 @@ export declare class IconSelect extends FormItemElementBase implements IconSelec
      */
     accessor required: boolean | undefined;
     /**
-     * 是否必填
+     * 校验错误提示信息
      */
     accessor message: Record<string, string> | undefined;
     /** 主题变体 */

package/dist-types/input/index.d.ts

@@ -125,11 +125,11 @@ export declare class Input extends FormItemElementBase {
     accessor themeVariant: "default" | "elevo" | undefined;
     handleInputChange: (value: string) => void;
     /**
-     * focus
+     * 使输入框获得焦点
      */
     focusInput(): void | undefined;
     /**
-     * blur
+     * 使输入框失去焦点
      */
     blurInput(): void | undefined;
     /**

package/dist-types/radio/index.d.ts

@@ -27,14 +27,14 @@ export interface RadioProps extends FormItemProps {
 }
 export interface RadioEvents {
     change: CustomEvent<GeneralComplexOption>;
-    optionsChange: CustomEvent<{
+    "options.change": CustomEvent<{
         options: GeneralComplexOption[];
         name: string;
     }>;
 }
 export interface RadioEventsMapping {
     onValueChange: "change";
-    onOptionsChange: "optionsChange";
+    onOptionsChange: "options.change";
 }
 export type { GeneralComplexOption };
 /**
@@ -45,7 +45,7 @@ export type { GeneralComplexOption };
 declare class Radio extends FormItemElementBase {
     #private;
     /**
-     * 下拉框字段名
+     * 字段名称
      */
     accessor name: string | undefined;
     /**
@@ -58,7 +58,7 @@ declare class Radio extends FormItemElementBase {
      */
     accessor options: GeneralOption[] | undefined;
     /**
-     * 单选框当前选中始值
+     * 单选框当前选中值
      */
     accessor value: any | undefined;
     /**

package/dist-types/select/index.d.ts

@@ -140,6 +140,7 @@ declare class Select extends FormItemElementBase {
      */
     accessor groupBy: string | undefined;
     /**
+     * 后缀内容，使用 useBrick 在选项及选中值旁显示额外信息
      */
     accessor suffix: {
         useBrick: UseSingleBrickConf;

package/dist-types/textarea/index.d.ts

@@ -102,7 +102,7 @@ declare class Textarea extends FormItemElementBase implements TextareaProps {
      */
     accessor themeVariant: "default" | "elevo" | undefined;
     /**
-     * focus
+     * 使文本域获得焦点
      */
     focusTextarea(): void | undefined;
     handleInputChange: (value: string) => void;

package/dist-types/time-range-picker/index.d.ts

@@ -75,15 +75,18 @@ export declare class EoTimeRangePicker extends FormItemElementBase {
      */
     accessor selectNearDays: number | undefined;
     /**
-     * @default  true
-     * 是否在初始化完成后额外触发一次`time.range.change`, 这里因为历史原因之前默认行为就是在初始化后会触发该事件，这里为了兼容之前的行为，默认值只能设置为 true。
+     * 是否在初始化完成后额外触发一次 change 事件。因历史原因，默认行为就是在初始化后触发该事件，为了兼容之前的行为，默认值只能设置为 true。
+     * @default true
      */
     accessor emitChangeOnInit: boolean | undefined;
     /**
-     * @default  []
-     * 预设时间范围快捷选择；设置了属性selectNearDays时，属性presetRanges不生效；属性rangeType为week时，presetRanges的值只能为本周、本月、本季度、今年，属性rangeType为month、quarter、year时，以此类推
+     * 预设时间范围快捷选择。设置了 selectNearDays 时，presetRanges 不生效；rangeType 为 week 时只能选本周、本月、本季度、今年，rangeType 为 month、quarter、year 时以此类推。
+     * @default []
      */
     accessor presetRanges: presetRangeType[] | undefined;
+    /**
+     * 自定义校验函数，返回错误信息字符串或 MessageBody 对象，返回空字符串表示校验通过。
+     */
     accessor validator: ((value: any) => MessageBody | string) | undefined;
     handleChange: (value: TimeRange) => void;
     unequal: (value: TimeRange) => string;

package/dist-types/upload/upload-file/index.d.ts

@@ -86,7 +86,7 @@ export declare class EoUploadFile extends FormItemElementBase implements UploadF
      */
     accessor buttonType: ButtonProps["type"] | undefined;
     /**
-     * 上传按钮类型
+     * 上传按钮图标
      */
     accessor buttonIcon: GeneralIconProps;
     /**

package/docs/eo-auto-complete.md

@@ -1,9 +1,50 @@
-构件 `eo-auto-complete`
+---
+tagName: eo-auto-complete
+displayName: WrappedEoAutoComplete
+description: 带候选项的输入框
+category: form-input-basic
+source: "@next-bricks/form"
+---
+
+# eo-auto-complete
+
+> 带候选项的输入框
+
+## 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                    | 说明       |
+| ------ | ------------------------- | ---------- |
+| change | `string` — 当前输入框的值 | 值改变事件 |
+
+## Slots
+
+| 名称            | 说明               |
+| --------------- | ------------------ |
+| options-toolbar | 下拉列表底部工具栏 |
 
 ## Examples
 
 ### Basic
 
+展示带候选项输入框的最基本用法，通过字符串数组提供候选选项。
+
 ```yaml preview minHeight=500px
 - brick: eo-auto-complete
   properties:
@@ -14,7 +55,9 @@
       - Shenzhen
 ```
 
-### caption
+### Caption
+
+通过 `OptionType` 对象格式为每个选项添加 `caption` 附加说明文字。
 
 ```yaml preview
 - brick: eo-auto-complete
@@ -33,6 +76,8 @@
 
 ### 分组
 
+通过 `OptionGroup` 格式对选项进行分组展示，组内每个选项可包含 `label`、`value` 和 `caption`。
+
 ```yaml preview
 - brick: eo-auto-complete
   properties:
@@ -48,13 +93,15 @@
           - label: 选项3-1
             value: 3-1
             caption: 说明3-1
-          - label: 选项3-1
+          - label: 选项3-2
             value: 3-2
             caption: 说明3-2
 ```
 
 ### filterByCaption
 
+设置 `filterByCaption` 为 `true`，搜索时同时匹配选项的 `caption` 字段。
+
 ```yaml preview
 - brick: eo-auto-complete
   properties:
@@ -71,12 +118,60 @@
           - label: 选项3-1
             value: 3-1
             caption: 说明3-1
-          - label: 选项3-1
+          - label: 选项3-2
             value: 3-2
             caption: 说明3-2
 ```
 
-### disabled
+### Value
+
+通过 `value` 属性设置输入框的默认值。
+
+```yaml preview minHeight=300px
+- brick: eo-auto-complete
+  properties:
+    value: Beijing
+    options:
+      - Beijing
+      - Shanghai
+      - Guangzhou
+      - Shenzhen
+```
+
+### Placeholder
+
+通过 `placeholder` 属性设置输入框的占位提示文字。
+
+```yaml preview minHeight=300px
+- brick: eo-auto-complete
+  properties:
+    placeholder: 请输入城市名称
+    options:
+      - Beijing
+      - Shanghai
+      - Guangzhou
+      - Shenzhen
+```
+
+### Input Style
+
+通过 `inputStyle` 属性自定义输入框的内联样式。
+
+```yaml preview minHeight=300px
+- brick: eo-auto-complete
+  properties:
+    inputStyle:
+      width: 300px
+    options:
+      - Beijing
+      - Shanghai
+      - Guangzhou
+      - Shenzhen
+```
+
+### Disabled
+
+设置 `disabled` 属性禁用输入框。
 
 ```yaml preview
 - brick: eo-auto-complete
@@ -89,9 +184,11 @@
       - Shenzhen
 ```
 
-### events
+### Events
 
-```yaml preview
+监听 `change` 事件获取用户输入或选中的实时值。
+
+```yaml preview minHeight=300px
 - brick: eo-auto-complete
   events:
     change:
@@ -106,7 +203,9 @@
 
 ### With Form
 
-```yaml preview minHeight=500px
+在 `eo-form` 中使用，通过 `name`、`label` 属性集成表单功能，并可配合 `required`、`pattern`、`message` 属性实现表单校验。
+
+```yaml preview minHeight=400px
 - brick: eo-form
   events:
     validate.success:
@@ -119,6 +218,10 @@
         name: city
         label: 城市
         required: true
+        pattern: "^[A-Za-z]+"
+        message:
+          required: 请选择城市
+          pattern: 城市名称只能包含字母
         options:
           - Beijing
           - Shanghai
@@ -126,3 +229,50 @@
           - Shenzhen
     - brick: eo-submit-buttons
 ```
+
+### Validator
+
+通过 `validator` 属性自定义表单项的校验逻辑，返回 `null` 表示校验通过，返回包含 `message` 的对象表示校验失败。
+
+```yaml preview minHeight=400px
+- brick: eo-form
+  events:
+    validate.success:
+      - action: console.log
+  children:
+    - brick: eo-auto-complete
+      properties:
+        name: city
+        label: 城市
+        options:
+          - Beijing
+          - Shanghai
+          - Guangzhou
+          - Shenzhen
+        validator: "<% (value) => value && value.length > 10 ? { message: '城市名称不能超过10个字符' } : null %>"
+    - brick: eo-submit-buttons
+```
+
+### Options Toolbar Slot
+
+通过 `options-toolbar` 插槽在下拉列表底部添加自定义工具栏内容。
+
+```yaml preview minHeight=400px
+- brick: eo-auto-complete
+  properties:
+    options:
+      - Beijing
+      - Shanghai
+      - Guangzhou
+      - Shenzhen
+  slots:
+    options-toolbar:
+      bricks:
+        - brick: span
+          properties:
+            textContent: 自定义工具栏
+            style:
+              padding: 4px 8px
+              color: "#999"
+              fontSize: 12px
+```