@cloudtower/eagle 0.35.7 → 0.35.8

package/dist/src/core/Duration/duration.type.d.ts

@@ -0,0 +1,42 @@
+/// <reference types="react" />
+import { IEmptyProps } from "../../core/Empty";
+import { DurationUnitType, FormatDurationItem } from "../../utils/formatDuration";
+import { RawValue } from "../Units/units.type";
+/**
+ * Duration 组件的属性类型
+ */
+export interface DurationProps extends Omit<RawValue, "decimals"> {
+    /**
+     * 最大展示单位数量，默认为 2
+     * @default 2
+     * @example
+     * maxDisplayUnits={3} // 最多展示 3 个单位，如：1 day 1 hour 1 minute
+     */
+    maxDisplayUnits?: number;
+    /**
+     * 最小展示单位，默认为 "second"（秒）
+     * @default "second"
+     * @example
+     * minUnit="minute" // 最小单位为分钟，秒数会被忽略
+     */
+    minUnit?: DurationUnitType;
+    /**
+     * Empty组件的配置属性
+     */
+    emptyProps?: IEmptyProps;
+    /**
+     * 自定义返回结果的渲染
+     * 当提供此函数时，将使用自定义渲染函数来渲染持续时间，而不是使用默认的渲染方式
+     * @param parts 格式化后的持续时间数组，每个元素包含 value 和 unit
+     * @returns 自定义的 React 节点
+     * @example
+     * contentRender={(parts) => (
+     *   <div>
+     *     {parts.map((part, i) => (
+     *       <span key={i}>{part.value} {part.unit}</span>
+     *     ))}
+     *   </div>
+     * )}
+     */
+    contentRender?: (parts: FormatDurationItem[]) => React.ReactNode;
+}

package/dist/src/core/Duration/index.d.ts

@@ -0,0 +1,4 @@
+import React from "react";
+import { DurationProps } from "./duration.type";
+declare const Duration: React.FC<DurationProps>;
+export default Duration;

package/dist/src/core/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 export * from "./AccordionCard";
 export * from "./Alert";
 export * from "./Antd5Anchor";
@@ -28,6 +29,7 @@ export * from "./DeprecatedProgress";
 export * from "./DetailCard";
 export * from "./DonutChart";
 export * from "./DropdownMenu";
+export * from "./Duration";
 export * from "./Empty";
 export * from "./ErrorBoundary";
 export * from "./ExpandableList";
@@ -103,6 +105,7 @@ export declare const units: {
     BitPerSecond: import("./Units").UnitFn;
     Bit: import("./Units").UnitFn;
     Second: import("./Units").UnitFn;
+    Duration: import("react").FC<import("./Duration/duration.type").DurationProps>;
 };
 export { units as Units };
 export { default as AccordionCard } from "./AccordionCard";
@@ -128,6 +131,7 @@ export { default as DeprecatedProgress } from "./DeprecatedProgress";
 export { default as DetailCard } from "./DetailCard";
 export { default as DonutChart } from "./DonutChart";
 export { default as DropdownMenu } from "./DropdownMenu";
+export { default as Duration } from "./Duration";
 export { default as Empty } from "./Empty";
 export { default as Error } from "./Error";
 export { default as ErrorBoundary } from "./ErrorBoundary";

package/dist/src/hooks/__tests__/useFormatDuration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/hooks/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./useCTErrorMsg";
 export { default as useElementResize } from "./useElementResize";
 export { default as useElementsSize } from "./useElementsSize";
+export { useFormatDuration } from "./useFormatDuration";

package/dist/src/hooks/useFormatDuration.d.ts

@@ -0,0 +1,31 @@
+import { DurationUnitType } from "../utils/formatDuration";
+/**
+ * 格式化持续时间的结果项，可用于 ParrotTrans 组件
+ */
+export interface FormatDurationPart {
+    value: number;
+    unit: DurationUnitType;
+    i18nKey: string;
+}
+/**
+ * 格式化持续时间的 Hook
+ * @param milliseconds 毫秒数
+ * @param options 配置选项
+ * @param options.maxDisplayUnits 最大展示单位数量，默认为 2
+ * @param options.useAbbreviation 是否使用简写表述，默认为 false。注意：当仅展示一个单位时，会自动使用全称（忽略此参数）
+ * @param options.minUnit 最小展示单位，默认为 "second"（秒），不满足进位逻辑的剩余时间会被忽略
+ * @returns 格式化后的持续时间数组，每个元素包含可用于 ParrotTrans 的信息
+ * @example
+ * const { parts } = useFormatDuration(3661000);
+ * // parts: [
+ * //   { value: 1, unit: "hour", i18nKey: "unit.hour" },
+ * //   { value: 1, unit: "minute", i18nKey: "unit.minute" }
+ * // ]
+ */
+export declare function useFormatDuration(milliseconds: number, options?: {
+    maxDisplayUnits?: number;
+    useAbbreviation?: boolean;
+    minUnit?: DurationUnitType;
+}): {
+    parts: FormatDurationPart[];
+};

package/dist/src/utils/__test__/formatDuration.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/formatDuration.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 持续时间单位联合类型
+ */
+export type DurationUnitType = "year" | "month" | "week" | "day" | "hour" | "minute" | "second" | "millisecond";
+/**
+ * 格式化持续时间的结果项
+ */
+export interface FormatDurationItem {
+    value: number;
+    unit: DurationUnitType;
+}
+/**
+ * 格式化持续时间
+ * @param milliseconds 毫秒数
+ * @param options 配置选项
+ * @param options.maxDisplayUnits 最大展示单位数量，默认为 2
+ * @param options.minUnit 最小展示单位，默认为 "second"（秒），不满足进位逻辑的剩余时间会被忽略
+ * @returns 格式化后的持续时间数组，每个元素包含数值和单位
+ * @example
+ * formatDuration(3661000) // [{ value: 1, unit: "hour" }, { value: 1, unit: "minute" }]
+ * formatDuration(90061000, { maxDisplayUnits: 3 }) // [{ value: 1, unit: "day" }, { value: 1, unit: "hour" }, { value: 1, unit: "minute" }]
+ * formatDuration(5000) // [{ value: 5, unit: "second" }]
+ * formatDuration(1500, { minUnit: "second" }) // [{ value: 1, unit: "second" }] (500ms 被忽略)
+ */
+export declare function formatDuration(milliseconds: number, options?: {
+    maxDisplayUnits?: number;
+    minUnit?: DurationUnitType;
+}): FormatDurationItem[];

package/dist/src/utils/index.d.ts

@@ -7,3 +7,4 @@ export * from "./icon";
 export * from "./isStringArr";
 export * from "./time";
 export * from "./cterror";
+export * from "./formatDuration";

package/dist/stories/docs/core/Duration.stories.d.ts

@@ -0,0 +1,88 @@
+import Duration from "../../../src/core/Duration";
+import { StoryObj } from "@storybook/react";
+import React from "react";
+/**
+ * * Duration 组件
+ * * 用于展示持续时间（毫秒），支持多个时间单位的组合展示
+ * * 提供标准、缩写和自定义空值展示等功能
+ * * 继承自基础的 Units 系列组件
+ */
+declare const meta: {
+    title: string;
+    component: React.FC<import("../../../src/core/Duration/duration.type").DurationProps>;
+    parameters: {
+        docs: {
+            description: {
+                component: string;
+            };
+        };
+    };
+    tags: string[];
+};
+export default meta;
+type Story = StoryObj<typeof Duration>;
+/**
+ * 基础持续时间展示
+ * 展示最基本的持续时间，默认展示最多 2 个单位
+ */
+export declare const Basic: Story;
+/**
+ * 多单位展示
+ * 展示多个时间单位，如：1天 1小时 1分钟
+ */
+export declare const MultipleUnits: Story;
+/**
+ * 缩写形式展示
+ * 当需要节省空间时，可以使用缩写形式展示持续时间
+ */
+export declare const Abbreviated: Story;
+/**
+ * 指定最小单位
+ * 可以指定最小展示单位，小于该单位的时间会被忽略
+ */
+export declare const WithMinUnit: Story;
+/**
+ * 单单位展示
+ * 只展示一个时间单位
+ */
+export declare const SingleUnit: Story;
+/**
+ * 大数值展示
+ * 展示较大的持续时间，如：1年 1个月
+ */
+export declare const LargeValue: Story;
+/**
+ * 自定义空值展示
+ * 当没有有效值时的自定义展示
+ */
+export declare const CustomEmpty: Story;
+/**
+ * 零值展示
+ * 展示零值的情况
+ */
+export declare const ZeroValue: Story;
+/**
+ * 零值不带单位
+ * 当值为0时，可以选择不显示单位
+ */
+export declare const ZeroWithoutUnit: Story;
+/**
+ * 自定义样式
+ * 可以通过自定义类名来调整展示样式
+ */
+export declare const CustomStyle: Story;
+/**
+ * 自定义渲染
+ * 使用 contentRender 自定义渲染方式
+ */
+export declare const CustomRender: Story;
+/**
+ * 自定义渲染 - 简洁格式
+ * 使用自定义渲染函数展示更简洁的格式
+ */
+export declare const CustomRenderCompact: Story;
+/**
+ * 复杂场景组合
+ * 展示多个配置项的组合使用
+ */
+export declare const Complex: Story;