@next-bricks/form 1.21.10 → 1.21.12

package/docs/eo-time-picker.md

@@ -1,56 +1,53 @@
-构件 `eo-time-picker`
+---
+tagName: eo-time-picker
+displayName: WrappedEoTimePicker
+description: 时间选择器
+category: form-input-basic
+source: "@next-bricks/form"
+---
+
+# eo-time-picker
+
+> 时间选择器
+
+## Props
+
+| 属性        | 类型                       | 必填 | 默认值 | 说明                                                                                            |
+| ----------- | -------------------------- | ---- | ------ | ----------------------------------------------------------------------------------------------- |
+| name        | `string`                   | 否   | -      | 时间选择器字段名                                                                                |
+| label       | `string`                   | 否   | -      | 时间选择器说明                                                                                  |
+| value       | `string`                   | 否   | -      | 时间选择器的初始值                                                                              |
+| placeholder | `string`                   | 否   | -      | 时间选择器占位说明                                                                              |
+| message     | `Record<string, string>`   | 否   | -      | 校验文本信息                                                                                    |
+| disabled    | `boolean`                  | 否   | -      | 是否禁用                                                                                        |
+| required    | `boolean`                  | 否   | -      | 是否必填                                                                                        |
+| configProps | `Partial<TimePickerProps>` | 否   | -      | 透传 antd TimePicker 属性，详见 [timePickerProps](https://ant.design/components/time-picker-cn) |
+
+## Events
+
+| 事件   | detail                                  | 说明                           |
+| ------ | --------------------------------------- | ------------------------------ |
+| change | `string` — 格式化后的时间字符串         | 时间变化时触发                 |
+| open   | `string` — 面板打开时的当前时间值字符串 | 面板打开时触发，传出当前时间值 |
+| close  | `string` — 面板关闭时的当前时间值字符串 | 面板关闭时触发，传出当前时间值 |
 
 ## Examples
 
 ### Basic
 
+展示时间选择器的基本用法，包含初始值和占位说明。
+
 ```yaml preview minHeight="400px"
 - brick: eo-time-picker
   properties:
-    label: time
+    label: 时间
     placeholder: 选择时间
     value: "12:30:01"
 ```
 
-### 国际化
-
-```yaml preview minHeight="400px"
-- brick: div
-  properties:
-    style:
-      display: grid
-      gap: 1em
-  children:
-    - brick: eo-time-picker
-    - brick: eo-button
-      properties:
-        textContent: 中文
-      events:
-        click:
-          useProvider: basic.change-language
-          args:
-            - zh
-          callback:
-            success:
-              action: message.success
-              args:
-                - '<% I18N_TEXT({ zh: "你好", "en": "Hello" }) %>'
-    - brick: eo-button
-      properties:
-        textContent: English
-      events:
-        click:
-          useProvider: basic.change-language
-          args:
-            - en
-          callback:
-            success:
-              action: message.success
-              args:
-                - '<% I18N_TEXT({ zh: "你好", "en": "Hello" }) %>'
-```
+### 事件监听
 
-### event
+展示监听 change、open、close 事件的用法。
 
 ```yaml preview minHeight="400px"
 - brick: eo-time-picker
@@ -62,11 +59,40 @@
     close:
       action: console.log
   properties:
-    label: time
+    label: 时间
     placeholder: 选择时间
 ```
 
-### With Form
+### 透传 antd 属性
+
+通过 configProps 透传 antd TimePicker 属性，自定义时间格式等配置。
+
+```yaml preview minHeight="400px"
+- brick: eo-time-picker
+  properties:
+    label: 时间（时分）
+    placeholder: 选择时间
+    configProps:
+      format: "HH:mm"
+      allowClear: true
+```
+
+### 禁用状态
+
+展示禁用状态下时间选择器的效果。
+
+```yaml preview minHeight="400px"
+- brick: eo-time-picker
+  properties:
+    label: 时间
+    disabled: true
+    value: "09:00:00"
+    placeholder: 已禁用
+```
+
+### 表单集成
+
+在表单中使用时间选择器，支持 label、name、required 及自定义校验信息。
 
 ```yaml preview minHeight="400px"
 - brick: eo-form
@@ -81,5 +107,7 @@
         label: 时间
         name: time
         required: true
+        message:
+          required: 请选择时间
     - brick: eo-submit-buttons
 ```

package/docs/eo-time-picker.react.md

@@ -0,0 +1,106 @@
+---
+tagName: eo-time-picker
+displayName: WrappedEoTimePicker
+description: 时间选择器
+category: form-input-basic
+source: "@next-bricks/form"
+---
+
+# WrappedEoTimePicker
+
+> 时间选择器
+
+## 导入
+
+```tsx
+import { WrappedEoTimePicker } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性        | 类型                       | 必填 | 默认值 | 说明                                                                                            |
+| ----------- | -------------------------- | ---- | ------ | ----------------------------------------------------------------------------------------------- |
+| name        | `string`                   | 否   | -      | 时间选择器字段名                                                                                |
+| label       | `string`                   | 否   | -      | 时间选择器说明                                                                                  |
+| value       | `string`                   | 否   | -      | 时间选择器的初始值                                                                              |
+| placeholder | `string`                   | 否   | -      | 时间选择器占位说明                                                                              |
+| message     | `Record<string, string>`   | 否   | -      | 校验文本信息                                                                                    |
+| disabled    | `boolean`                  | 否   | -      | 是否禁用                                                                                        |
+| required    | `boolean`                  | 否   | -      | 是否必填                                                                                        |
+| configProps | `Partial<TimePickerProps>` | 否   | -      | 透传 antd TimePicker 属性，详见 [timePickerProps](https://ant.design/components/time-picker-cn) |
+
+## Events
+
+| 事件     | detail                                  | 说明                           |
+| -------- | --------------------------------------- | ------------------------------ |
+| onChange | `string` — 格式化后的时间字符串         | 时间变化时触发                 |
+| onOpen   | `string` — 面板打开时的当前时间值字符串 | 面板打开时触发，传出当前时间值 |
+| onClose  | `string` — 面板关闭时的当前时间值字符串 | 面板关闭时触发，传出当前时间值 |
+
+## Examples
+
+### Basic
+
+展示时间选择器的基本用法，包含初始值和占位说明。
+
+```tsx
+<WrappedEoTimePicker label="时间" placeholder="选择时间" value="12:30:01" />
+```
+
+### 事件监听
+
+展示监听 change、open、close 事件的用法。
+
+```tsx
+<WrappedEoTimePicker
+  label="时间"
+  placeholder="选择时间"
+  onChange={(e) => console.log(e.detail)}
+  onOpen={(e) => console.log(e.detail)}
+  onClose={(e) => console.log(e.detail)}
+/>
+```
+
+### 透传 antd 属性
+
+通过 configProps 透传 antd TimePicker 属性，自定义时间格式等配置。
+
+```tsx
+<WrappedEoTimePicker
+  label="时间（时分）"
+  placeholder="选择时间"
+  configProps={{ format: "HH:mm", allowClear: true }}
+/>
+```
+
+### 禁用状态
+
+展示禁用状态下时间选择器的效果。
+
+```tsx
+<WrappedEoTimePicker
+  label="时间"
+  disabled={true}
+  value="09:00:00"
+  placeholder="已禁用"
+/>
+```
+
+### 表单集成
+
+在表单中使用时间选择器，支持 label、name、required 及自定义校验信息。
+
+```tsx
+<WrappedEoForm
+  onValidateSuccess={(e) => console.log(e.detail)}
+  onValuesChange={(e) => console.log(e.detail)}
+>
+  <WrappedEoTimePicker
+    label="时间"
+    name="time"
+    required={true}
+    message={{ required: "请选择时间" }}
+  />
+  <WrappedEoSubmitButtons />
+</WrappedEoForm>
+```

package/docs/eo-time-range-picker.md

@@ -1,17 +1,53 @@
-构件 `eo-time-range-picker`
+---
+tagName: eo-time-range-picker
+displayName: WrappedEoTimeRangePicker
+description: 时间区间选择器
+category: form-input-basic
+source: "@next-bricks/form"
+---
+
+# eo-time-range-picker
+
+> 时间区间选择器
+
+## Props
+
+| 属性             | 类型                                    | 必填 | 默认值 | 说明                                                                                                       |
+| ---------------- | --------------------------------------- | ---- | ------ | ---------------------------------------------------------------------------------------------------------- |
+| name             | `string`                                | 否   | -      | 时间段选择器字段名                                                                                         |
+| label            | `string`                                | 否   | -      | 时间段选择器说明                                                                                           |
+| value            | `TimeRange`                             | 否   | -      | 时间段选择器的初始值，格式为 `{ startTime, endTime }`                                                      |
+| required         | `boolean`                               | 否   | -      | 是否必填                                                                                                   |
+| rangeType        | `RangeType`                             | 否   | -      | 时间段类型，可选值：`time` \| `hmTime` \| `date` \| `dateTime` \| `week` \| `month` \| `quarter` \| `year` |
+| placeholder      | `string \| [string, string]`            | 否   | -      | 输入框提示文字，单时间段时为 `string`，范围时间段时为 `[string, string]`                                   |
+| inputStyle       | `React.CSSProperties`                   | 否   | -      | 输入框样式                                                                                                 |
+| selectNearDays   | `number`                                | 否   | -      | 仅在 `rangeType` 为 `date` 或 `dateTime` 时生效，限制只能选择最近 n 天（当前时间向前 n 天）                |
+| emitChangeOnInit | `boolean`                               | 否   | `true` | 是否在初始化完成后额外触发一次 change 事件。默认为 `true` 以兼容历史行为。                                 |
+| presetRanges     | `presetRangeType[]`                     | 否   | -      | 预设时间范围快捷选择。设置了 `selectNearDays` 时不生效；不同 `rangeType` 下可选值有限制。                  |
+| validator        | `(value: any) => MessageBody \| string` | 否   | -      | 自定义校验函数，返回错误信息字符串或 MessageBody 对象，返回空字符串表示校验通过。                          |
+
+## Events
+
+| 事件   | detail                                                               | 说明             |
+| ------ | -------------------------------------------------------------------- | ---------------- |
+| change | `TimeRange` — { startTime: 开始时间字符串, endTime: 结束时间字符串 } | 时间段变化时触发 |
 
 ## Examples
 
 ### Basic
 
+展示时间区间选择器的基本用法。
+
 ```yaml preview minHeight="400px"
 - brick: eo-time-range-picker
   properties:
-    label: hello
+    label: 时间段
     name: time
 ```
 
-### rangeType
+### 区间类型
+
+通过 rangeType 属性切换不同的时间段类型（时间/日期/日期时间/周/月/季度/年）。
 
 ```yaml preview minHeight="400px"
 - brick: eo-radio
@@ -32,18 +68,20 @@
           rangeType: <% EVENT.detail.value %>
 - brick: eo-time-range-picker
   properties:
-    label: hello
+    label: 时间段
     name: time
     id: rangePicker
     rangeType: date
 ```
 
-### presetRanges
+### 预设时间范围
+
+通过 presetRanges 属性设置快捷选择按钮，方便用户快速选择常用时间段。
 
 ```yaml preview minHeight="400px"
 - brick: eo-time-range-picker
   properties:
-    label: hello
+    label: 时间段
     name: time
     rangeType: week
     required: true
@@ -54,13 +92,49 @@
       - 今年
 ```
 
-### validate
+### 最近 N 天
+
+通过 selectNearDays 属性限制只能选择最近 n 天范围内的日期（rangeType 为 date 或 dateTime 时有效）。
+
+```yaml preview minHeight="400px"
+- brick: eo-time-range-picker
+  events:
+    change:
+      action: console.log
+  properties:
+    label: 最近 10 天
+    name: time
+    selectNearDays: 10
+    rangeType: date
+```
+
+### 初始值与输入框样式
+
+通过 value 设置初始时间段，通过 inputStyle 自定义输入框样式。
+
+```yaml preview minHeight="400px"
+- brick: eo-time-range-picker
+  properties:
+    label: 时间段
+    name: time
+    rangeType: date
+    value:
+      startTime: "2024-01-01"
+      endTime: "2024-01-31"
+    inputStyle:
+      width: 300px
+    placeholder:
+      - 开始日期
+      - 结束日期
+```
+
+### 自定义校验
+
+通过 validator 属性自定义校验逻辑，返回错误信息时显示校验失败。
 
 ```yaml preview minHeight="400px"
 - brick: eo-form
   events:
-    values.change:
-      - action: console.log
     validate.success:
       - action: message.success
         args:
@@ -77,37 +151,17 @@
             change:
               action: console.log
           properties:
-            label: hello
+            label: 时间段
             name: time
             required: true
+            emitChangeOnInit: false
+            validator: "<% (value) => value && value.startTime && value.endTime ? '' : '请选择完整的时间段' %>"
         - brick: eo-submit-buttons
 ```
 
-### selectNearDays
-
-```yaml preview minHeight="400px"
-- brick: eo-time-range-picker
-  events:
-    - action: console.log
-  properties:
-    label: hello
-    name: time
-    selectNearDays: 10
-    rangeType: date
-```
-
-### Events
-
-```yaml preview minHeight="400px"
-- brick: eo-time-range-picker
-  events:
-    - action: console.log
-  properties:
-    label: hello
-    name: time
-```
+### 表单集成
 
-### With Form
+在表单中使用时间区间选择器，结合 name、label、required 进行完整的表单提交。
 
 ```yaml preview minHeight="400px"
 - brick: eo-form
@@ -119,7 +173,7 @@
   children:
     - brick: eo-time-range-picker
       properties:
-        label: 时间
+        label: 时间段
         name: time
         required: true
     - brick: eo-submit-buttons

package/docs/eo-time-range-picker.react.md

@@ -0,0 +1,163 @@
+---
+tagName: eo-time-range-picker
+displayName: WrappedEoTimeRangePicker
+description: 时间区间选择器
+category: form-input-basic
+source: "@next-bricks/form"
+---
+
+# WrappedEoTimeRangePicker
+
+> 时间区间选择器
+
+## 导入
+
+```tsx
+import { WrappedEoTimeRangePicker } from "@easyops/wrapped-components";
+```
+
+## Props
+
+| 属性             | 类型                                    | 必填 | 默认值 | 说明                                                                                                       |
+| ---------------- | --------------------------------------- | ---- | ------ | ---------------------------------------------------------------------------------------------------------- |
+| name             | `string`                                | 否   | -      | 时间段选择器字段名                                                                                         |
+| label            | `string`                                | 否   | -      | 时间段选择器说明                                                                                           |
+| value            | `TimeRange`                             | 否   | -      | 时间段选择器的初始值，格式为 `{ startTime, endTime }`                                                      |
+| required         | `boolean`                               | 否   | -      | 是否必填                                                                                                   |
+| rangeType        | `RangeType`                             | 否   | -      | 时间段类型，可选值：`time` \| `hmTime` \| `date` \| `dateTime` \| `week` \| `month` \| `quarter` \| `year` |
+| placeholder      | `string \| [string, string]`            | 否   | -      | 输入框提示文字，单时间段时为 `string`，范围时间段时为 `[string, string]`                                   |
+| inputStyle       | `React.CSSProperties`                   | 否   | -      | 输入框样式                                                                                                 |
+| selectNearDays   | `number`                                | 否   | -      | 仅在 `rangeType` 为 `date` 或 `dateTime` 时生效，限制只能选择最近 n 天（当前时间向前 n 天）                |
+| emitChangeOnInit | `boolean`                               | 否   | `true` | 是否在初始化完成后额外触发一次 change 事件。默认为 `true` 以兼容历史行为。                                 |
+| presetRanges     | `presetRangeType[]`                     | 否   | -      | 预设时间范围快捷选择。设置了 `selectNearDays` 时不生效；不同 `rangeType` 下可选值有限制。                  |
+| validator        | `(value: any) => MessageBody \| string` | 否   | -      | 自定义校验函数，返回错误信息字符串或 MessageBody 对象，返回空字符串表示校验通过。                          |
+
+## Events
+
+| 事件     | detail                                                               | 说明             |
+| -------- | -------------------------------------------------------------------- | ---------------- |
+| onChange | `TimeRange` — { startTime: 开始时间字符串, endTime: 结束时间字符串 } | 时间段变化时触发 |
+
+## Examples
+
+### Basic
+
+展示时间区间选择器的基本用法。
+
+```tsx
+<WrappedEoTimeRangePicker label="时间段" name="time" />
+```
+
+### 区间类型
+
+通过 rangeType 属性切换不同的时间段类型（时间/日期/日期时间/周/月/季度/年）。
+
+```tsx
+import { useState } from "react";
+
+function Demo() {
+  const [rangeType, setRangeType] = useState("date");
+  return (
+    <>
+      <WrappedEoRadio
+        options={[
+          "time",
+          "date",
+          "dateTime",
+          "hmTime",
+          "week",
+          "month",
+          "quarter",
+          "year",
+        ]}
+        onChange={(e) => setRangeType(e.detail.value)}
+      />
+      <WrappedEoTimeRangePicker
+        label="时间段"
+        name="time"
+        rangeType={rangeType}
+      />
+    </>
+  );
+}
+```
+
+### 预设时间范围
+
+通过 presetRanges 属性设置快捷选择按钮，方便用户快速选择常用时间段。
+
+```tsx
+<WrappedEoTimeRangePicker
+  label="时间段"
+  name="time"
+  rangeType="week"
+  required={true}
+  presetRanges={["本周", "本月", "本季度", "今年"]}
+/>
+```
+
+### 最近 N 天
+
+通过 selectNearDays 属性限制只能选择最近 n 天范围内的日期（rangeType 为 date 或 dateTime 时有效）。
+
+```tsx
+<WrappedEoTimeRangePicker
+  label="最近 10 天"
+  name="time"
+  selectNearDays={10}
+  rangeType="date"
+  onChange={(e) => console.log(e.detail)}
+/>
+```
+
+### 初始值与输入框样式
+
+通过 value 设置初始时间段，通过 inputStyle 自定义输入框样式。
+
+```tsx
+<WrappedEoTimeRangePicker
+  label="时间段"
+  name="time"
+  rangeType="date"
+  value={{ startTime: "2024-01-01", endTime: "2024-01-31" }}
+  inputStyle={{ width: 300 }}
+  placeholder={["开始日期", "结束日期"]}
+/>
+```
+
+### 自定义校验
+
+通过 validator 属性自定义校验逻辑，返回错误信息时显示校验失败。
+
+```tsx
+<WrappedEoForm
+  onValidateSuccess={() => alert("表单提交成功")}
+  onValidateError={() => alert("表单校验失败")}
+>
+  <WrappedEoTimeRangePicker
+    label="时间段"
+    name="time"
+    required={true}
+    emitChangeOnInit={false}
+    validator={(value) =>
+      value && value.startTime && value.endTime ? "" : "请选择完整的时间段"
+    }
+    onChange={(e) => console.log(e.detail)}
+  />
+  <WrappedEoSubmitButtons />
+</WrappedEoForm>
+```
+
+### 表单集成
+
+在表单中使用时间区间选择器，结合 name、label、required 进行完整的表单提交。
+
+```tsx
+<WrappedEoForm
+  onValidateSuccess={(e) => console.log(e.detail)}
+  onValuesChange={(e) => console.log(e.detail)}
+>
+  <WrappedEoTimeRangePicker label="时间段" name="time" required={true} />
+  <WrappedEoSubmitButtons />
+</WrappedEoForm>
+```