@pisell/materials 1.8.12 → 1.8.13

package/lib/components/pisellDateTimeDisplay/PisellDateTimeDisplay.stories.d.ts

@@ -0,0 +1,195 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import PisellDateTimeDisplay from './PisellDateTimeDisplay';
+/**
+ * PisellDateTimeDisplay 组件 Storybook
+ */
+declare const meta: Meta<typeof PisellDateTimeDisplay>;
+export default meta;
+declare type Story = StoryObj<typeof PisellDateTimeDisplay>;
+/**
+ * 基础示例
+ */
+export declare const Basic: Story;
+/**
+ * 水平布局（默认）
+ */
+export declare const HorizontalLayout: Story;
+/**
+ * 垂直布局
+ */
+export declare const VerticalLayout: Story;
+/**
+ * 单行布局
+ */
+export declare const InlineLayout: Story;
+/**
+ * 单行布局 - 自定义分隔符
+ */
+export declare const InlineWithCustomSeparator: Story;
+/**
+ * 中文完整日期格式：2025-12-31 - 2:00 周四
+ * 单行、日期在前、日期与时间之间 " - "、时间与星期之间空格
+ */
+export declare const InlineDateTimeWeekdayZh: Story;
+/**
+ * 12小时制
+ */
+export declare const Time12Hour: Story;
+/**
+ * 显示秒
+ */
+export declare const TimeWithSeconds: Story;
+/**
+ * 12小时制 + 显示秒
+ */
+export declare const Time12HourWithSeconds: Story;
+/**
+ * 小时补零
+ */
+export declare const TimePadHour: Story;
+/**
+ * 只显示小时
+ */
+export declare const TimeOnlyHour: Story;
+/**
+ * 完整日期（Y-M-D）
+ */
+export declare const DateFullYMD: Story;
+/**
+ * 月-日-年 格式
+ */
+export declare const DateMDY: Story;
+/**
+ * 日-月-年 格式
+ */
+export declare const DateDMY: Story;
+/**
+ * 中文日期带单位
+ */
+export declare const DateChinese: Story;
+/**
+ * 相对日：今天/昨天/明天
+ * 与「当前日期」同天显示「今天」，前一天「昨天」，后一天「明天」；其他日期仍按原格式。
+ * 参考日为 dayjs()，随时间变化：例如 2 月 4 日当天，2 月 4 日显示「今天」，2 月 3 日显示「昨天」。
+ */
+export declare const RelativeDay: Story;
+/**
+ * 相对日 - 英文
+ */
+export declare const RelativeDayEn: Story;
+/**
+ * 相对日 - 自定义文案
+ */
+export declare const RelativeDayCustomLabels: Story;
+/**
+ * 英文完整月份
+ */
+export declare const DateFullMonth: Story;
+/**
+ * 自定义分隔符
+ */
+export declare const DateCustomSeparator: Story;
+/**
+ * 星期完整展示（英文）
+ */
+export declare const WeekdayFull: Story;
+/**
+ * 星期完整展示（中文）
+ */
+export declare const WeekdayFullChinese: Story;
+/**
+ * 星期单字母展示
+ */
+export declare const WeekdaySingleLetter: Story;
+/**
+ * 只显示时间
+ */
+export declare const OnlyTime: Story;
+/**
+ * 只显示日期
+ */
+export declare const OnlyDate: Story;
+/**
+ * 自定义字段顺序
+ */
+export declare const CustomFieldOrder: Story;
+/**
+ * 自定义格式化 - ISO 格式
+ */
+export declare const CustomFormatISO: Story;
+/**
+ * 自定义格式化 - 中文格式
+ */
+export declare const CustomFormatChinese: Story;
+/**
+ * 自定义格式化 - 包含星期
+ */
+export declare const CustomFormatWithWeekday: Story;
+/**
+ * 中文环境
+ */
+export declare const LocaleChinese: Story;
+/**
+ * 英文环境
+ */
+export declare const LocaleEnglish: Story;
+/**
+ * 自定义容器样式
+ */
+export declare const CustomContainerStyle: Story;
+/**
+ * 自定义文本样式
+ */
+export declare const CustomTextStyle: Story;
+/**
+ * 居中对齐
+ */
+export declare const CenterAlign: Story;
+/**
+ * 禁用自动刷新
+ */
+export declare const DisableRefresh: Story;
+/**
+ * 自定义刷新间隔（5秒）
+ */
+export declare const CustomRefreshInterval: Story;
+/**
+ * 应用场景 - 后台首页
+ */
+export declare const ScenarioDashboard: Story;
+/**
+ * 应用场景 - 状态栏
+ */
+export declare const ScenarioStatusBar: Story;
+/**
+ * 应用场景 - 欢迎页
+ */
+export declare const ScenarioWelcome: Story;
+/**
+ * 应用场景 - 大屏展示
+ */
+export declare const ScenarioLargeScreen: Story;
+/**
+ * 多语言对比
+ */
+export declare const MultiLanguage: Story;
+/**
+ * 时间格式对比
+ */
+export declare const TimeFormats: Story;
+/**
+ * 日期格式对比
+ */
+export declare const DateFormats: Story;
+/**
+ * 星期格式对比
+ */
+export declare const WeekdayFormats: Story;
+/**
+ * 所有布局对比
+ */
+export declare const AllLayouts: Story;
+/**
+ * 深色主题
+ */
+export declare const DarkTheme: Story;

package/lib/components/pisellDateTimeDisplay/components/DateDisplay.d.ts

@@ -0,0 +1,48 @@
+import React from 'react';
+import { type Dayjs } from 'dayjs';
+import type { DateFormatConfig, TextStyleConfig } from '../types';
+/**
+ * DateDisplay 组件 Props
+ */
+export interface DateDisplayProps {
+    /**
+     * 日期对象
+     */
+    date: Dayjs;
+    /**
+     * 日期格式配置
+     */
+    format?: DateFormatConfig;
+    /**
+     * 参考日期（用于「今天/昨天/明天」判定，默认当前时间 dayjs()）
+     */
+    referenceDate?: Dayjs;
+    /**
+     * 文本样式
+     */
+    style?: TextStyleConfig;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+}
+/**
+ * 日期展示组件
+ *
+ * @description
+ * - 格式化并展示日期
+ * - 支持 showRelativeDay：今天/昨天/明天时用相对日替换原日期展示，不展示具体日期
+ * - 支持不同的日期顺序（YMD/MDY/DMY）
+ * - 支持年月日字段显隐
+ * - 支持中文单位（年、月、日）
+ * - 支持英文月份格式（简写/完整/数字）
+ *
+ * @example
+ * <DateDisplay
+ *   date={dayjs()}
+ *   format={{ order: 'YMD', showYear: true, showChineseUnit: true }}
+ *   style={{ fontSize: 18, fontWeight: 400, color: '#666' }}
+ * />
+ */
+export declare const DateDisplay: React.FC<DateDisplayProps>;
+export default DateDisplay;

package/lib/components/pisellDateTimeDisplay/formats/dateTimeDisplayFormats.d.ts

@@ -0,0 +1,7 @@
+import type { DateTimeDisplayFormatPreset } from '../types';
+/**
+ * PisellDateTimeDisplay 按语言预设的格式
+ * - zh-cn：完整日期 - 时间 星期（如 2025-12-31 - 2:00 周四）；默认不展示相对日，可传 dateFormat.showRelativeDay: true 开启
+ * - en：时间 星期, 日期（如 2:00 Sat, 21 Mar, 2026）；默认不展示相对日，可传 dateFormat.showRelativeDay: true 开启
+ */
+export declare const DATETIME_DISPLAY_FORMATS: Record<string, Partial<DateTimeDisplayFormatPreset>>;

package/lib/components/pisellDateTimeDisplay/formats/dateTimeDisplayFormats.js

@@ -29,7 +29,7 @@ var DATETIME_DISPLAY_FORMATS = {
       showYear: true,
       separator: "-",
       showChineseUnit: false,
-      showRelativeDay: true
+      showRelativeDay: false
     },
     timeFormat: {
       use12Hour: false,
@@ -54,7 +54,7 @@ var DATETIME_DISPLAY_FORMATS = {
       showYear: true,
       separator: "-",
       showChineseUnit: false,
-      showRelativeDay: true
+      showRelativeDay: false
     },
     timeFormat: { use12Hour: false, showSeconds: false },
     weekdayFormat: { full: false, singleLetter: false },
@@ -71,7 +71,7 @@ var DATETIME_DISPLAY_FORMATS = {
       order: "DMY",
       shortMonth: true,
       showYear: true,
-      showRelativeDay: true,
+      showRelativeDay: false,
       useCommaBeforeYear: true
     },
     timeFormat: {

package/lib/components/pisellDateTimeDisplay/formats/index.d.ts

@@ -0,0 +1 @@
+export { DATETIME_DISPLAY_FORMATS } from './dateTimeDisplayFormats';

package/lib/components/pisellDateTimeDisplay/hooks/useCurrentTime.d.ts

@@ -0,0 +1,46 @@
+import { Dayjs } from 'dayjs';
+/**
+ * useCurrentTime Hook 配置项
+ */
+export interface UseCurrentTimeOptions {
+    /**
+     * 刷新间隔（毫秒）
+     * @default 60000
+     */
+    refreshInterval?: number;
+    /**
+     * 是否禁用自动刷新
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * dayjs locale
+     * @default 优先使用全局配置，其次使用 i18n 当前语言（getCurrentLocale）
+     * @example 'zh-CN' | 'zh-HK' | 'en' | 'en-US' | 'ja'
+     */
+    locale?: string;
+    /**
+     * 时间更新回调
+     */
+    onUpdate?: (time: Dayjs) => void;
+}
+/**
+ * 管理当前时间状态的自定义 Hook
+ *
+ * @description
+ * - 自动创建定时器刷新时间
+ * - 支持自定义刷新间隔
+ * - 支持国际化（locale）：优先级为 用户指定 > 全局配置 > i18n 当前语言
+ * - 组件卸载时自动清除定时器
+ *
+ * @example
+ * const currentTime = useCurrentTime({
+ *   refreshInterval: 1000,
+ *   locale: 'zh-CN',
+ *   onUpdate: (time) => console.log(time.format())
+ * });
+ *
+ * @param options 配置项
+ * @returns 当前时间（Dayjs 对象）
+ */
+export declare function useCurrentTime(options?: UseCurrentTimeOptions): Dayjs;

package/lib/components/pisellDateTimeDisplay/hooks/useCurrentTime.js

@@ -36,7 +36,9 @@ var import_react = require("react");
 var import_dayjs = __toESM(require("dayjs"));
 var import_localeUtils = require("../utils/localeUtils");
 var import_usePisellConfig = __toESM(require("../../pisell-config-provider/hooks/usePisellConfig"));
+var import_useEngineContext = __toESM(require("../../../hooks/useEngineContext"));
 function useCurrentTime(options) {
+  var _a, _b;
   const {
     refreshInterval = 6e4,
     disabled = false,
@@ -44,8 +46,12 @@ function useCurrentTime(options) {
     onUpdate
   } = options || {};
   const globalConfig = (0, import_usePisellConfig.default)();
+  const context = (0, import_useEngineContext.default)();
   const globalLocale = globalConfig == null ? void 0 : globalConfig.locale;
-  const dayjsLocale = (0, import_localeUtils.getDayjsLocale)(userLocale || globalLocale);
+  const engineLocale = (_b = (_a = context == null ? void 0 : context.engine) == null ? void 0 : _a.props) == null ? void 0 : _b.locale;
+  const dayjsLocale = (0, import_localeUtils.getDayjsLocale)(
+    userLocale || globalLocale || engineLocale || "en"
+  );
   const [currentTime, setCurrentTime] = (0, import_react.useState)(() => {
     const time = (0, import_dayjs.default)();
     return time.locale(dayjsLocale);

package/lib/components/pisellDateTimeDisplay/index.d.ts

@@ -0,0 +1,3 @@
+export { default as PisellDateTimeDisplay } from './PisellDateTimeDisplay';
+export type { PisellDateTimeDisplayProps, LayoutDirection, DateOrder, TextAlign, FieldType, TimeFormatConfig, DateFormatConfig, WeekdayFormatConfig, FieldConfig, TextStyleConfig, ContainerStyleConfig, } from './types';
+export { default } from './PisellDateTimeDisplay';

package/lib/components/pisellDateTimeDisplay/types.d.ts

@@ -0,0 +1,352 @@
+import type { CSSProperties } from 'react';
+import type { Dayjs } from 'dayjs';
+/**
+ * 布局方向
+ * - horizontal: 水平布局（默认）- 时间在上，日期+星期在下
+ * - vertical: 垂直布局 - 时间、日期、星期分别独立成行
+ * - inline: 单行布局 - 所有信息横向排列，用分隔符连接
+ */
+export declare type LayoutDirection = 'horizontal' | 'vertical' | 'inline';
+/**
+ * 日期顺序
+ * - YMD: 年-月-日（如：2026-03-21）
+ * - MDY: 月-日-年（如：Mar 21, 2026）
+ * - DMY: 日-月-年（如：21 Mar 2026）
+ */
+export declare type DateOrder = 'YMD' | 'MDY' | 'DMY';
+/**
+ * 对齐方式
+ */
+export declare type TextAlign = 'left' | 'center' | 'right';
+/**
+ * 字段类型
+ */
+export declare type FieldType = 'time' | 'date' | 'weekday';
+/**
+ * 时间格式配置
+ */
+export interface TimeFormatConfig {
+    /**
+     * 是否使用12小时制
+     * @default false
+     * @example true -> "1:45 PM" | false -> "13:45"
+     */
+    use12Hour?: boolean;
+    /**
+     * 是否显示秒
+     * @default false
+     * @example true -> "13:45:30" | false -> "13:45"
+     */
+    showSeconds?: boolean;
+    /**
+     * 小时是否补零
+     * @default false
+     * @example true -> "01:45 PM" | false -> "1:45 PM"
+     */
+    padHour?: boolean;
+    /**
+     * 是否只显示小时
+     * @default false
+     * @example true -> "13" | false -> "13:45"
+     */
+    onlyShowHour?: boolean;
+}
+/**
+ * 日期格式配置
+ */
+export interface DateFormatConfig {
+    /**
+     * 日期顺序
+     * @default 'YMD'
+     */
+    order?: DateOrder;
+    /**
+     * 英文月份是否简写
+     * @default true
+     * @example true -> "Mar" | false -> "March"
+     */
+    shortMonth?: boolean;
+    /**
+     * 英文月份是否数字展示
+     * @default false
+     * @example true -> "03" | false -> "Mar"
+     */
+    numericMonth?: boolean;
+    /**
+     * 中文是否显示"年月日"汉字
+     * @default false
+     * @example true -> "2026年3月21日" | false -> "2026-03-21"
+     */
+    showChineseUnit?: boolean;
+    /**
+     * 分隔符
+     * @default '-'
+     * @example '-' -> "2026-03-21" | '/' -> "2026/03/21"
+     */
+    separator?: string;
+    /**
+     * 是否显示年
+     * @default false
+     */
+    showYear?: boolean;
+    /**
+     * 是否显示月
+     * @default true
+     */
+    showMonth?: boolean;
+    /**
+     * 是否显示日
+     * @default true
+     */
+    showDay?: boolean;
+    /**
+     * 英文 DMY 时年月之间是否加逗号（如 21 Mar, 2026；false 时为 22 Jan 2025）
+     * @default true
+     */
+    useCommaBeforeYear?: boolean;
+    /**
+     * 是否在「今天/昨天/明天」时用相对日替换具体日期
+     * 开启后：与参考日同天显示「今天」，前一天「昨天」，后一天「明天」；其他日期仍按原格式
+     * @default false
+     */
+    showRelativeDay?: boolean;
+    /**
+     * 相对日文案覆盖（用于 i18n 或自定义）
+     * 不传时按 locale 使用默认：zh 今天/昨天/明天，en Today/Yesterday/Tomorrow
+     */
+    relativeDayLabels?: {
+        today?: string;
+        yesterday?: string;
+        tomorrow?: string;
+    };
+}
+/**
+ * 星期格式配置
+ */
+export interface WeekdayFormatConfig {
+    /**
+     * 是否完整展示
+     * @default false
+     * @example true -> "Saturday" / "星期六" | false -> "Sat" / "周六"
+     */
+    full?: boolean;
+    /**
+     * 是否单字母展示
+     * @default false
+     * @example true -> "S" / "六" | false -> "Sat" / "周六"
+     */
+    singleLetter?: boolean;
+    /**
+     * 是否在星期后加逗号（用于与日期拼接如 "Sat, 21 Mar, 2026"）
+     * @default false
+     */
+    trailingComma?: boolean;
+}
+/**
+ * 字段配置
+ */
+export interface FieldConfig {
+    /**
+     * 是否显示时间字段
+     * @default true
+     */
+    showTime?: boolean;
+    /**
+     * 是否显示日期字段
+     * @default true
+     */
+    showDate?: boolean;
+    /**
+     * 是否显示星期字段
+     * @default true
+     */
+    showWeekday?: boolean;
+    /**
+     * 字段顺序
+     * @default ['time', 'date', 'weekday']
+     */
+    fieldOrder?: FieldType[];
+    /**
+     * 单行布局时每段之间的分隔符，按顺序对应字段之间
+     * 如 ['date','time','weekday'] 配 inlineSeparators: [' - ', ' '] => "2025-12-31 - 2:00 周四"
+     * 不足时用组件 inlineSeparator 补齐
+     */
+    inlineSeparators?: string[];
+}
+/**
+ * 文本样式配置
+ */
+export interface TextStyleConfig {
+    /**
+     * 字体大小
+     * @example 14 | '14px' | '1rem'
+     */
+    fontSize?: number | string;
+    /**
+     * 字体粗细
+     * @example 400 | '400' | 'bold'
+     */
+    fontWeight?: number | string;
+    /**
+     * 字体颜色
+     * @example '#000' | 'rgba(0, 0, 0, 0.85)'
+     */
+    color?: string;
+    /**
+     * 行高
+     * @example 1.5 | '1.5' | '24px'
+     */
+    lineHeight?: number | string;
+}
+/**
+ * 容器样式配置
+ */
+export interface ContainerStyleConfig {
+    /**
+     * 背景色
+     * @example '#fff' | 'transparent'
+     */
+    background?: string;
+    /**
+     * 圆角
+     * @example 8 | '8px'
+     */
+    borderRadius?: number | string;
+    /**
+     * 边框
+     * @example '1px solid #ddd'
+     */
+    border?: string;
+    /**
+     * 阴影
+     * @example '0 2px 8px rgba(0, 0, 0, 0.1)'
+     */
+    boxShadow?: string;
+    /**
+     * 内边距
+     * @example 16 | '16px' | '16px 24px'
+     */
+    padding?: number | string;
+    /**
+     * 间距（子元素之间的间距）
+     * @example 8 | '8px'
+     */
+    gap?: number | string;
+}
+/**
+ * 多语言格式预设（日期/时间/星期 + 字段顺序与分隔符）
+ * 用于 formatByLocale[locale] 或默认多语言配置
+ */
+export interface DateTimeDisplayFormatPreset {
+    dateFormat?: DateFormatConfig;
+    timeFormat?: TimeFormatConfig;
+    weekdayFormat?: WeekdayFormatConfig;
+    fields?: FieldConfig;
+}
+/**
+ * PisellDateTimeDisplay 组件 Props
+ */
+export interface PisellDateTimeDisplayProps {
+    /**
+     * 传入时展示该时间，不传则展示当前时间（并可按 refreshInterval 刷新）
+     * @description 用于表格列、详情等展示给定时间；支持 dayjs、时间戳、ISO 字符串
+     */
+    value?: Dayjs | string | number;
+    /**
+     * 布局方向
+     * @default 'horizontal'
+     */
+    layout?: LayoutDirection;
+    /**
+     * 文本对齐方式
+     * @default 'center'
+     */
+    textAlign?: TextAlign;
+    /**
+     * 字段显示配置
+     */
+    fields?: FieldConfig;
+    /**
+     * 多语言格式配置：按 locale 取对应格式预设，再与下方单项配置合并（单项优先）
+     * @example formatByLocale={{ 'zh-cn': { dateFormat: {...}, fields: { fieldOrder: ['date','time','weekday'], inlineSeparators: [' - ', ' '] } }, 'en': {...} }}
+     */
+    formatByLocale?: Record<string, Partial<DateTimeDisplayFormatPreset>>;
+    /**
+     * 时间格式配置
+     */
+    timeFormat?: TimeFormatConfig;
+    /**
+     * 日期格式配置
+     */
+    dateFormat?: DateFormatConfig;
+    /**
+     * 星期格式配置
+     */
+    weekdayFormat?: WeekdayFormatConfig;
+    /**
+     * 自定义格式化字符串（优先级最高，类似 dayjs().format()）
+     * @example 'YYYY-MM-DD HH:mm:ss' | 'MM/DD/YYYY'
+     * @description 当设置此属性时，其他格式化配置将被忽略
+     */
+    customFormat?: string;
+    /**
+     * 单行模式分隔符
+     * @default ' · '
+     * @example ' | ' | ' - '
+     */
+    inlineSeparator?: string;
+    /**
+     * 容器样式
+     */
+    containerStyle?: ContainerStyleConfig;
+    /**
+     * 时间文本样式
+     */
+    timeStyle?: TextStyleConfig;
+    /**
+     * 日期文本样式
+     */
+    dateStyle?: TextStyleConfig;
+    /**
+     * 星期文本样式
+     */
+    weekdayStyle?: TextStyleConfig;
+    /**
+     * 自定义刷新间隔（毫秒）
+     * @description 不设置则根据 showSeconds 自动判断（显示秒=1000ms，否则=60000ms）
+     * @example 1000 | 5000 | 60000
+     */
+    refreshInterval?: number;
+    /**
+     * 是否禁用自动刷新
+     * @default false
+     * @description 设置为 true 时，组件只显示初始时间，不会自动更新
+     */
+    disableAutoRefresh?: boolean;
+    /**
+     * dayjs locale（语言代码）
+     * @default 优先使用全局配置（usePisellConfig），其次使用 i18n 当前语言（getCurrentLocale：全局配置 / umi_locale）
+     * @example 'zh-CN' | 'zh-HK' | 'en' | 'en-US' | 'ja'
+     * @description
+     * - 支持标准 BCP 47 语言代码，会自动标准化为 dayjs 兼容格式
+     * - 优先级：组件 locale 属性 > PisellConfigProvider 全局配置 > i18n 当前语言
+     */
+    locale?: string;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 自定义样式
+     */
+    style?: CSSProperties;
+    /**
+     * 时间更新回调
+     * @param currentTime 当前时间（Dayjs 对象）
+     */
+    onTimeUpdate?: (currentTime: Dayjs) => void;
+    /**
+     * 点击回调
+     */
+    onClick?: () => void;
+}