@yoka-ui/ui 1.0.10-test → 1.1.1

package/dist/es/components/YkDateRangePicker/YkDateRangePicker.mdx

@@ -0,0 +1,194 @@
+import { Meta, ArgTypes } from '@storybook/addon-docs/blocks';
+import * as YkDateRangePickerStories from './index.stories';
+
+<Meta of={YkDateRangePickerStories} />
+
+# YkDateRangePicker 事件日期范围选择器
+
+事件类日期范围选择器，支持**紧凑预设标签**与**完整 RangePicker** 双模式切换，提供多项快捷预设与受控逻辑。
+
+## ✨ 核心特性
+
+- 🎯 **双模式交互**：紧凑模式（预设标签）↔ 完整模式（RangePicker）无缝切换
+- ⚡ **智能预设**：内置 8 个常用时间快捷选项，2 列网格布局
+- 🎨 **视觉反馈**：当前激活项高亮显示，蓝色背景标识选中状态
+- 🤖 **智能默认**：无初始值时自动选中「近5分钟」预设
+- 🔄 **受控组件**：精准区分「用户操作」与「外部赋值」，仅用户操作触发 `onChange`
+- 🔒 **日期限制**：仅允许选择近 7 天（含今天）的时间范围
+- 🗑️ **清除支持**：`allowClear` 一键清除，清除后自动重置预设状态
+- 🔧 **ref 控制**：通过 `forwardRef` 暴露 `toggleFirstPreset()` 方法，支持外部强制切换预设
+
+## 📦 依赖
+
+```json
+{
+  "react": "^18.3.1",
+  "antd": "^5.29.2",
+  "dayjs": "^1.x",
+  "classnames": "^2.5.1",
+  "@ant-design/icons": "^5.6.1"
+}
+```
+
+## 🚀 快速开始
+
+### 基础使用
+
+```tsx
+import { useState, useRef } from 'react';
+import { YkDateRangePicker, type DateRangeValue, type YkDateRangePickerRef } from '@yoka-ui/ui';
+import dayjs from 'dayjs';
+
+function App() {
+  const [range, setRange] = useState<DateRangeValue | []>([]);
+  const pickerRef = useRef<YkDateRangePickerRef>(null);
+
+  return (
+    <YkDateRangePicker
+      value={range}
+      onChange={(dates) => setRange(dates ?? [])}
+      ref={pickerRef}
+    />
+  );
+}
+```
+
+### 外部控制
+
+```tsx
+// 强制切换到「近5分钟」预设
+pickerRef.current?.toggleFirstPreset();
+
+// 设置外部值
+setRange([dayjs().subtract(1, 'hour'), dayjs()]);
+
+// 清空选择
+setRange([]);
+```
+
+## 📋 API 文档
+
+<ArgTypes of={YkDateRangePickerStories} />
+
+## 💡 使用场景
+
+### 1. 日志查询
+
+适用于需要快速筛选最近时间段日志的场景，预设的「近5分钟」「近1小时」等选项大幅提升操作效率。
+
+### 2. 数据分析
+
+在数据报表页面中，用户可以通过预设快速切换常用分析周期，或通过自定义范围进行精细化查询。
+
+### 3. 监控告警
+
+结合实时监控需求，预设项帮助用户快速定位异常发生的时间段。
+
+### 4. 自定义样式
+
+通过 `className` 和 `style` 属性可以自定义组件的外观的类名和内联样式：
+
+```tsx
+// 自定义样式示例
+<YkDateRangePicker
+  className="custom-date-picker"
+  style={{ marginTop: 16 }}
+  value={range}
+  onChange={handleChange}
+/>
+```
+
+## 🎯 最佳实践
+
+### 保持受控模式
+
+始终使用受控模式（controlled mode），通过 `value` 和 `onChange` 管理状态，确保组件行为可预测：
+
+```tsx
+// ✅ 推荐：受控模式
+const [value, setValue] = useState<DateRangeValue | []>([]);
+<YkDateRangePicker value={value} onChange={setValue} />
+
+// ❌ 避免：非受控模式可能导致状态不一致
+<YkDateRangePicker defaultValue={initialValue} />
+```
+
+### 合理使用 ref
+
+ref 方法 `toggleFirstPreset()` 适用于特殊场景（如重置查询条件），日常使用中建议通过受控 props 控制组件：
+
+```tsx
+// 在重置按钮的回调中使用
+const handleReset = () => {
+  setValue([]); // 清空值
+  pickerRef.current?.toggleFirstPreset(); // 重置到默认预设
+};
+```
+
+### 处理空值
+
+组件支持空数组 `[]` 作为值，表示未选择任何时间范围。清除后建议重置为 `[]` 而非 `undefined`：
+
+```tsx
+onChange={(val) => {
+  // ✅ 推荐：始终转换为数组
+  setValue(val || []);
+}}
+```
+
+## ⚠️ 注意事项
+
+1. **样式引入**：业务侧使用 `@yoka-ui/ui` 时，需确保引入 Ant Design 全局样式和组件库样式：
+   ```tsx
+   import 'antd/dist/reset.css';
+   import '@yoka-ui/ui/dist/index.less';
+   ```
+
+2. **版本要求**：需要 React 18+ 和 Ant Design 5+，与库的版本保持一致。
+
+3. **日期限制**：组件默认限制只能选择近 7 天（含今天）的时间范围，如需调整需修改源码中的禁用逻辑。
+
+4. **预设范围**：预设项的时长计算基于当前时间，每次展开时会重新计算。
+
+5. **性能优化**：组件内部使用 `useMemo` 和 `useCallback` 优化预设计算和事件处理，避免不必要的重渲染。
+
+## 🎨 预设项说明
+
+| 预设标签 | 时间范围 | 使用场景 |
+| --------- | --------- | --------- |
+| 近5分钟 | 当前时间 - 5分钟 ~ 现在 | 实时监控、日志追踪 |
+| 近15分钟 | 当前时间 - 15分钟 ~ 现在 | 短期数据分析 |
+| 近30分钟 | 当前时间 - 30分钟 ~ 现在 | 中等时长监控 |
+| 近1小时 | 当前时间 - 1小时 ~ 现在 | 小时级数据分析 |
+| 近6小时 | 当前时间 - 6小时 ~ 现在 | 半日数据查看 |
+| 近12小时 | 当前时间 - 12小时 ~ 现在 | 半日对比分析 |
+| 近24小时 | 当前时间 - 24小时 ~ 现在 | 日级数据查询 |
+| 近7天 | 当前时间 - 7天 ~ 现在 | 周级趋势分析 |
+
+## 🔍 交互行为
+
+### 预设选择流程
+
+1. 用户点击紧凑模式的标签区域
+2. 下拉面板展开，显示 8 个预设选项和完整的 RangePicker
+3. 用户点击任意预设项，组件自动计算对应时间范围
+4. 选择后立即触发 `onChange` 回调，并关闭面板
+5. 紧凑模式标签更新为「预设名称 + 格式化时间」或「起止时间」
+
+### 自定义时间选择
+
+1. 用户在展开的面板中点击 RangePicker
+2. 选择自定义开始和结束时间
+3. 点击确定后触发 `onChange` 回调
+4. 紧凑模式标签显示为「开始时间 ~ 结束时间」格式
+
+### 清除行为
+
+- 当设置 `allowClear=true` 时，标签右侧显示清除图标
+- 点击清除图标后，值重置为 `[]`，预设状态被清除
+- 触发 `onChange` 回调，参数为 `[]`
+
+## 📚 相关组件
+
+- [DatePicker](https://ant.design/components/date-picker) - Ant Design 基础日期选择器
+- [RangePicker](https://ant.design/components/date-picker#rangepicker) - Ant Design 日期范围选择器

package/dist/es/components/YkDateRangePicker/index.d.ts

@@ -27,7 +27,7 @@
  * pickerRef.current?.toggleFirstPreset();
  * ```
  */
-import { Dayjs } from 'dayjs';
+import { type Dayjs } from 'dayjs';
 import React from 'react';
 /** 时间范围值 */
 export type DateRangeValue = [Dayjs, Dayjs];
@@ -47,6 +47,14 @@ export interface YkDateRangePickerProps {
      * 默认：「请选择时间范围」
      */
     placeholder?: string;
+    /** 是否禁用选择器 */
+    disabled?: boolean;
+    /** 校验状态 */
+    status?: '' | 'error' | 'warning';
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义内联样式 */
+    style?: React.CSSProperties;
 }
 /** 通过 ref 对父组件暴露的方法 */
 export interface YkDateRangePickerRef {

package/dist/es/components/YkDateRangePicker/index.js

@@ -14,15 +14,23 @@ import React, {
 import styles from "./index.module.less";
 var { RangePicker } = DatePicker;
 function pastTime(n, unit) {
-  const fmt = "YYYY-MM-DD HH:mm:00";
+  const fmt = "YYYY-MM-DD HH:mm:ss";
   return [dayjs(dayjs().subtract(n, unit).format(fmt)), dayjs(dayjs().format(fmt))];
 }
 var DISPLAY_FORMAT = "YYYY-MM-DD HH:mm:ss";
-function toDisplay(d) {
+function formatToKey(d) {
   return dayjs(d).format(DISPLAY_FORMAT);
 }
-function toMatchKey(d) {
-  return dayjs(d).format(DISPLAY_FORMAT);
+function isValueEqual(a, b) {
+  if (a === b)
+    return true;
+  if (!a || !b)
+    return a === b;
+  if (a.length !== b.length)
+    return false;
+  if (a.length < 2 || b.length < 2)
+    return a.length === b.length;
+  return formatToKey(a[0]) === formatToKey(b[0]) && formatToKey(a[1]) === formatToKey(b[1]);
 }
 var RANGE_PRESETS = [
   {
@@ -52,8 +60,8 @@ var RANGE_PRESETS = [
   {
     label: "今天",
     value: () => [
-      dayjs(dayjs().startOf("day").format("YYYY-MM-DD HH:mm:00")),
-      dayjs(dayjs().endOf("day").format("YYYY-MM-DD HH:mm:00"))
+      dayjs(dayjs().startOf("day").format("YYYY-MM-DD HH:mm:ss")),
+      dayjs(dayjs().endOf("day").format("YYYY-MM-DD HH:mm:ss"))
     ],
     // 紧凑模式只展示日期，如「03-25」
     format: (v) => v[0].format("MM-DD")
@@ -61,31 +69,49 @@ var RANGE_PRESETS = [
   {
     label: "昨天",
     value: () => [
-      dayjs(dayjs().subtract(1, "day").startOf("day").format("YYYY-MM-DD HH:mm:00")),
-      dayjs(dayjs().subtract(1, "day").endOf("day").format("YYYY-MM-DD HH:mm:00"))
+      dayjs(dayjs().subtract(1, "day").startOf("day").format("YYYY-MM-DD HH:mm:ss")),
+      dayjs(dayjs().subtract(1, "day").endOf("day").format("YYYY-MM-DD HH:mm:ss"))
     ],
     format: (v) => v[0].format("MM-DD")
   },
   {
     label: "近7天",
     value: () => [
-      dayjs(dayjs().subtract(6, "day").startOf("day").format("YYYY-MM-DD HH:mm:00")),
-      dayjs(dayjs().endOf("day").format("YYYY-MM-DD HH:mm:00"))
+      dayjs(dayjs().subtract(6, "day").startOf("day").format("YYYY-MM-DD HH:mm:ss")),
+      dayjs(dayjs().endOf("day").format("YYYY-MM-DD HH:mm:ss"))
     ],
     // 紧凑模式展示完整日期区间，如「2024-03-19 ~ 2024-03-25」
     format: (v) => [v[0].format("YYYY-MM-DD"), v[1].format("YYYY-MM-DD")]
   }
 ];
-var YkDateRangePicker = forwardRef(function YkDateRangePicker2({ value, onChange, allowClear = false, placeholder = "请选择时间范围" }, ref) {
+var YkDateRangePicker = forwardRef(function YkDateRangePicker2({
+  value,
+  onChange,
+  allowClear = false,
+  placeholder = "请选择时间范围",
+  disabled = false,
+  status = "",
+  className,
+  style
+}, ref) {
   const [showFullPicker, setShowFullPicker] = useState(false);
   const [open, setOpen] = useState(false);
   const [activePreset, setActivePreset] = useState(void 0);
   const [presetFormatText, setPresetFormatText] = useState(void 0);
   const selfChangeRef = useRef(false);
   const isPresetClickRef = useRef(false);
+  const collapseTimerRef = useRef();
   const wrapperRef = useRef(null);
   const pickerRef = useRef(null);
   const prevValueRef = useRef(value);
+  const scheduleCollapse = useCallback((delay) => {
+    clearTimeout(collapseTimerRef.current);
+    collapseTimerRef.current = setTimeout(() => {
+      setOpen(false);
+      setShowFullPicker(false);
+    }, delay != null ? delay : 0);
+  }, []);
+  useEffect(() => () => clearTimeout(collapseTimerRef.current), []);
   useEffect(() => {
     if (value && value.length === 2)
       return;
@@ -98,7 +124,7 @@ var YkDateRangePicker = forwardRef(function YkDateRangePicker2({ value, onChange
     onChange == null ? void 0 : onChange(currentValue);
   }, []);
   useEffect(() => {
-    if (prevValueRef.current === value)
+    if (isValueEqual(prevValueRef.current, value))
       return;
     prevValueRef.current = value;
     if (!selfChangeRef.current) {
@@ -110,16 +136,16 @@ var YkDateRangePicker = forwardRef(function YkDateRangePicker2({ value, onChange
   const showState = useMemo(() => {
     if (!value || value.length < 2)
       return [];
-    return [toDisplay(value[0]), toDisplay(value[1])];
+    return [formatToKey(value[0]), formatToKey(value[1])];
   }, [value]);
   const activePresetIndex = useMemo(() => {
     if (!value || value.length < 2)
       return -1;
     const [v0, v1] = value;
-    const valKeys = [toMatchKey(v0), toMatchKey(v1)];
+    const valKeys = [formatToKey(v0), formatToKey(v1)];
     return RANGE_PRESETS.findIndex((preset) => {
       const presetVal = preset.value();
-      const presetKeys = [toMatchKey(presetVal[0]), toMatchKey(presetVal[1])];
+      const presetKeys = [formatToKey(presetVal[0]), formatToKey(presetVal[1])];
       return valKeys[0] === presetKeys[0] && valKeys[1] === presetKeys[1];
     });
   }, [value, open]);
@@ -138,10 +164,7 @@ var YkDateRangePicker = forwardRef(function YkDateRangePicker2({ value, onChange
       setPresetFormatText(formatText);
       selfChangeRef.current = true;
       onChange == null ? void 0 : onChange(currentValue);
-      setTimeout(() => {
-        setOpen(false);
-        setShowFullPicker(false);
-      }, 0);
+      scheduleCollapse();
     },
     [onChange]
   );
@@ -155,15 +178,12 @@ var YkDateRangePicker = forwardRef(function YkDateRangePicker2({ value, onChange
         onChange == null ? void 0 : onChange(dates);
       } else {
         onChange == null ? void 0 : onChange(null);
-        setTimeout(() => {
-          setOpen(false);
-          setShowFullPicker(false);
-        }, 0);
+        scheduleCollapse();
       }
     },
     [onChange]
   );
-  const handleClickCompactTag = useCallback(() => {
+  const activateCompactTag = useCallback(() => {
     setShowFullPicker(true);
     setTimeout(() => {
       var _a;
@@ -175,14 +195,15 @@ var YkDateRangePicker = forwardRef(function YkDateRangePicker2({ value, onChange
       }
     }, 0);
   }, []);
-  const handleOpenChange = useCallback((isOpen) => {
-    setOpen(isOpen);
-    if (!isOpen) {
-      setTimeout(() => {
-        setShowFullPicker(false);
-      }, 100);
-    }
-  }, []);
+  const handleOpenChange = useCallback(
+    (isOpen) => {
+      setOpen(isOpen);
+      if (!isOpen) {
+        scheduleCollapse(150);
+      }
+    },
+    [scheduleCollapse]
+  );
   const disabledDate = useCallback((current) => {
     return current && (current > dayjs().endOf("day") || current < dayjs().subtract(6, "day").startOf("day"));
   }, []);
@@ -200,9 +221,19 @@ var YkDateRangePicker = forwardRef(function YkDateRangePicker2({ value, onChange
             className: classNames(styles.yokaPresetItem, {
               [styles.yokaPresetItemActive]: isActive
             }),
+            role: "option",
+            tabIndex: 0,
+            "aria-selected": isActive,
             onClick: (e) => {
               e.stopPropagation();
               handlePresetClick(preset);
+            },
+            onKeyDown: (e) => {
+              if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                e.stopPropagation();
+                handlePresetClick(preset);
+              }
             }
           },
           preset.label
@@ -221,37 +252,72 @@ var YkDateRangePicker = forwardRef(function YkDateRangePicker2({ value, onChange
     [handlePresetClick]
   );
   const pickerVisible = showFullPicker || open;
-  return /* @__PURE__ */ React.createElement("div", { className: styles.YkDateRangePicker, ref: wrapperRef }, !showFullPicker && /* @__PURE__ */ React.createElement("span", { className: styles.yokaCompactTag, onClick: handleClickCompactTag }, /* @__PURE__ */ React.createElement("i", { className: classNames("iconfont icon-riqi1", styles.yokaCompactTagIcon) }), /* @__PURE__ */ React.createElement("span", { className: styles.yokaCompactTagContent }, activePreset ? (
-    // 已选预设：「预设名称 (格式化时间)」
-    /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("span", { className: styles.yokaCompactTagPresetLabel }, activePreset.label), /* @__PURE__ */ React.createElement("span", { className: styles.yokaCompactTagPresetFormat }, "(", presetFormatText, ")"))
-  ) : showState.length === 2 ? (
-    // 自定义时间：「起始时间 ~ 结束时间」
-    /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("span", { className: styles.yokaCompactTagDatetime }, showState[0]), /* @__PURE__ */ React.createElement("span", { className: styles.yokaCompactTagSeparator }, "~"), /* @__PURE__ */ React.createElement("span", { className: styles.yokaCompactTagDatetime }, showState[1]))
-  ) : (
-    // 无值/清空：placeholder 居中显示
-    /* @__PURE__ */ React.createElement("span", { className: styles.yokaCompactTagPlaceholder }, placeholder)
-  ))), /* @__PURE__ */ React.createElement("div", { className: styles.yokaPickerWrapper, style: { display: pickerVisible ? "flex" : "none" } }, /* @__PURE__ */ React.createElement("i", { className: classNames("iconfont icon-riqi1", styles.yokaPickerWrapperIcon) }), /* @__PURE__ */ React.createElement(
-    RangePicker,
+  return /* @__PURE__ */ React.createElement(
+    "div",
     {
-      ref: pickerRef,
-      value: value && value.length === 2 ? value : void 0,
-      onChange: handlePickerChange,
-      open,
-      onOpenChange: handleOpenChange,
-      variant: "borderless",
-      allowClear,
-      suffixIcon: null,
-      showTime: {
-        format: "HH:mm:ss",
-        hideDisabledOptions: true,
-        defaultValue: [dayjs("00:00", "HH:mm"), dayjs("23:59", "HH:mm")]
+      className: classNames(styles.YkDateRangePicker, className, {
+        [styles.yokaDisabled]: disabled
+      }),
+      ref: wrapperRef
+    },
+    !showFullPicker && /* @__PURE__ */ React.createElement(
+      "span",
+      {
+        className: styles.yokaCompactTag,
+        style,
+        role: "button",
+        tabIndex: disabled ? -1 : 0,
+        "aria-haspopup": "dialog",
+        "aria-expanded": open,
+        "aria-disabled": disabled,
+        onClick: disabled ? void 0 : activateCompactTag,
+        onKeyDown: (e) => {
+          if (disabled)
+            return;
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            activateCompactTag();
+          }
+        }
       },
-      format: "YYYY-MM-DD HH:mm:ss",
-      disabledDate,
-      presets: presetsNode,
-      getPopupContainer
-    }
-  )));
+      /* @__PURE__ */ React.createElement("i", { className: classNames("iconfont icon-riqi1", styles.yokaCompactTagIcon) }),
+      /* @__PURE__ */ React.createElement("span", { className: styles.yokaCompactTagContent }, activePreset ? (
+        // 已选预设：「预设名称 (格式化时间)」
+        /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("span", { className: styles.yokaCompactTagPresetLabel }, activePreset.label), /* @__PURE__ */ React.createElement("span", { className: styles.yokaCompactTagPresetFormat }, "(", presetFormatText, ")"))
+      ) : showState.length === 2 ? (
+        // 自定义时间：「起始时间 ~ 结束时间」
+        /* @__PURE__ */ React.createElement(React.Fragment, null, /* @__PURE__ */ React.createElement("span", { className: styles.yokaCompactTagDatetime }, showState[0]), /* @__PURE__ */ React.createElement("span", { className: styles.yokaCompactTagSeparator }, "~"), /* @__PURE__ */ React.createElement("span", { className: styles.yokaCompactTagDatetime }, showState[1]))
+      ) : (
+        // 无值/清空：placeholder 居中显示
+        /* @__PURE__ */ React.createElement("span", { className: styles.yokaCompactTagPlaceholder }, placeholder)
+      ))
+    ),
+    /* @__PURE__ */ React.createElement("div", { className: styles.yokaPickerWrapper, style: { display: pickerVisible ? "flex" : "none" } }, /* @__PURE__ */ React.createElement("i", { className: classNames("iconfont icon-riqi1", styles.yokaPickerWrapperIcon) }), /* @__PURE__ */ React.createElement(
+      RangePicker,
+      {
+        ref: pickerRef,
+        value: value && value.length === 2 ? value : void 0,
+        onChange: handlePickerChange,
+        open,
+        onOpenChange: handleOpenChange,
+        variant: "borderless",
+        allowClear,
+        disabled,
+        status: status || void 0,
+        suffixIcon: null,
+        showTime: {
+          format: "HH:mm:ss",
+          hideDisabledOptions: true,
+          defaultValue: [dayjs("00:00", "HH:mm"), dayjs("23:59", "HH:mm")]
+        },
+        format: "YYYY-MM-DD HH:mm:ss",
+        disabledDate,
+        presets: presetsNode,
+        getPopupContainer,
+        classNames: { popup: { root: "yoka-daterangepicker-popup" } }
+      }
+    ))
+  );
 });
 YkDateRangePicker.displayName = "YkDateRangePicker";
 var YkDateRangePicker_default = YkDateRangePicker;