@pisell/materials 6.11.5 → 6.11.7

package/es/components/pisellDateTimeDisplay/PisellDateTimeDisplay.js

@@ -5,11 +5,13 @@ function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key i
 function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
 function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
 import React from 'react';
+import dayjs from 'dayjs';
 import 'dayjs/locale/zh-cn';
 import 'dayjs/locale/en';
 import { useCurrentTime } from "./hooks";
-import { getRefreshInterval, isChinese as checkIsChinese } from "./utils";
+import { getRefreshInterval, isChinese as checkIsChinese, getRelativeDay, getRelativeDayLabel, getDayjsLocale } from "./utils";
 import { TimeDisplay, DateDisplay, WeekdayDisplay } from "./components";
+import { DATETIME_DISPLAY_FORMATS } from "./formats/dateTimeDisplayFormats";
 import "./PisellDateTimeDisplay.less";
 
 /**
@@ -40,11 +42,13 @@ import "./PisellDateTimeDisplay.less";
  * />
  */
 export var PisellDateTimeDisplay = function PisellDateTimeDisplay(props) {
+  var _ref, _presetSource$localeK;
   var _props$layout = props.layout,
     layout = _props$layout === void 0 ? 'horizontal' : _props$layout,
     _props$textAlign = props.textAlign,
     textAlign = _props$textAlign === void 0 ? 'center' : _props$textAlign,
     fields = props.fields,
+    formatByLocale = props.formatByLocale,
     timeFormat = props.timeFormat,
     dateFormat = props.dateFormat,
     weekdayFormat = props.weekdayFormat,
@@ -64,8 +68,18 @@ export var PisellDateTimeDisplay = function PisellDateTimeDisplay(props) {
     className = props.className,
     style = props.style;
 
+  // 多语言格式：formatByLocale 优先，否则用内置 DATETIME_DISPLAY_FORMATS；再与单项 props 合并（单项优先）
+  var localeKey = getDayjsLocale(locale);
+  var baseLocale = localeKey.split('-')[0];
+  var presetSource = formatByLocale !== null && formatByLocale !== void 0 ? formatByLocale : DATETIME_DISPLAY_FORMATS;
+  var preset = (_ref = (_presetSource$localeK = presetSource[localeKey]) !== null && _presetSource$localeK !== void 0 ? _presetSource$localeK : presetSource[baseLocale]) !== null && _ref !== void 0 ? _ref : {};
+  var effectiveFields = _objectSpread(_objectSpread({}, preset.fields), fields);
+  var effectiveDateFormat = _objectSpread(_objectSpread({}, preset.dateFormat), dateFormat);
+  var effectiveTimeFormat = _objectSpread(_objectSpread({}, preset.timeFormat), timeFormat);
+  var effectiveWeekdayFormat = _objectSpread(_objectSpread({}, preset.weekdayFormat), weekdayFormat);
+
   // 计算刷新间隔
-  var computedRefreshInterval = refreshInterval !== null && refreshInterval !== void 0 ? refreshInterval : getRefreshInterval(timeFormat);
+  var computedRefreshInterval = refreshInterval !== null && refreshInterval !== void 0 ? refreshInterval : getRefreshInterval(effectiveTimeFormat);
 
   // 使用自定义 hook 管理当前时间
   var currentTime = useCurrentTime({
@@ -93,16 +107,21 @@ export var PisellDateTimeDisplay = function PisellDateTimeDisplay(props) {
     }, /*#__PURE__*/React.createElement("span", null, formattedTime));
   }
 
-  // 获取字段配置
-  var _ref = fields || {},
-    _ref$showTime = _ref.showTime,
-    showTime = _ref$showTime === void 0 ? true : _ref$showTime,
-    _ref$showDate = _ref.showDate,
-    showDate = _ref$showDate === void 0 ? true : _ref$showDate,
-    _ref$showWeekday = _ref.showWeekday,
-    showWeekday = _ref$showWeekday === void 0 ? true : _ref$showWeekday,
-    _ref$fieldOrder = _ref.fieldOrder,
-    fieldOrder = _ref$fieldOrder === void 0 ? ['time', 'date', 'weekday'] : _ref$fieldOrder;
+  // 获取字段配置（已含多语言预设合并）
+  var _ref2 = effectiveFields || {},
+    _ref2$showTime = _ref2.showTime,
+    showTime = _ref2$showTime === void 0 ? true : _ref2$showTime,
+    _ref2$showDate = _ref2.showDate,
+    showDate = _ref2$showDate === void 0 ? true : _ref2$showDate,
+    _ref2$showWeekday = _ref2.showWeekday,
+    showWeekday = _ref2$showWeekday === void 0 ? true : _ref2$showWeekday,
+    _ref2$fieldOrder = _ref2.fieldOrder,
+    fieldOrder = _ref2$fieldOrder === void 0 ? ['time', 'date', 'weekday'] : _ref2$fieldOrder;
+
+  // 日期与星期一体：若日期以相对日（今天/昨天/明天）展示，则不展示星期
+  var referenceDate = dayjs();
+  var relativeDay = effectiveDateFormat !== null && effectiveDateFormat !== void 0 && effectiveDateFormat.showRelativeDay ? getRelativeDay(currentTime, referenceDate) : null;
+  var hideWeekdayWhenDateRelative = showDate && relativeDay !== null;
 
   // 构建容器样式
   var containerInlineStyle = _objectSpread({
@@ -122,21 +141,22 @@ export var PisellDateTimeDisplay = function PisellDateTimeDisplay(props) {
         return showTime ? /*#__PURE__*/React.createElement(TimeDisplay, {
           key: "time",
           time: currentTime,
-          format: timeFormat,
+          format: effectiveTimeFormat,
           style: timeStyle
         }) : null;
       case 'date':
         return showDate ? /*#__PURE__*/React.createElement(DateDisplay, {
           key: "date",
           date: currentTime,
-          format: dateFormat,
+          format: effectiveDateFormat,
+          referenceDate: dayjs(),
           style: dateStyle
         }) : null;
       case 'weekday':
-        return showWeekday ? /*#__PURE__*/React.createElement(WeekdayDisplay, {
+        return showWeekday && !hideWeekdayWhenDateRelative ? /*#__PURE__*/React.createElement(WeekdayDisplay, {
           key: "weekday",
           weekday: currentTime,
-          format: weekdayFormat,
+          format: effectiveWeekdayFormat,
           style: weekdayStyle
         }) : null;
       default:
@@ -144,14 +164,12 @@ export var PisellDateTimeDisplay = function PisellDateTimeDisplay(props) {
     }
   };
 
-  // 单行布局：使用分隔符连接
+  // 单行布局：使用分隔符连接，支持每段不同分隔符（如 2025-12-31 - 2:00 周四）
   if (layout === 'inline') {
-    // 根据 fieldOrder 渲染字段，过滤掉 null
+    var inlineSeparators = effectiveFields === null || effectiveFields === void 0 ? void 0 : effectiveFields.inlineSeparators;
     var _renderedFields = fieldOrder.map(renderField).filter(function (field) {
       return field !== null;
     });
-
-    // 如果没有要显示的字段，返回 null
     if (_renderedFields.length === 0) {
       return null;
     }
@@ -160,11 +178,12 @@ export var PisellDateTimeDisplay = function PisellDateTimeDisplay(props) {
       style: containerInlineStyle,
       onClick: onClick
     }, _renderedFields.map(function (field, index) {
+      var _inlineSeparators$ind;
       return /*#__PURE__*/React.createElement(React.Fragment, {
         key: index
       }, field, index < _renderedFields.length - 1 && /*#__PURE__*/React.createElement("span", {
         className: "pisell-datetime-display-separator"
-      }, inlineSeparator));
+      }, (_inlineSeparators$ind = inlineSeparators === null || inlineSeparators === void 0 ? void 0 : inlineSeparators[index]) !== null && _inlineSeparators$ind !== void 0 ? _inlineSeparators$ind : inlineSeparator));
     }));
   }
 
@@ -187,20 +206,14 @@ export var PisellDateTimeDisplay = function PisellDateTimeDisplay(props) {
     var currentLocale = currentTime.locale();
     var isChinese = checkIsChinese(currentLocale);
 
-    // 当同时显示日期和星期时，使用合并格式
+    // 当同时显示日期和星期时，使用合并格式；有相对日时只展示相对日，不展示具体日期与星期
     if (showDate && showWeekday) {
-      var combinedStr = '';
-      if (isChinese) {
-        // 中文环境：使用格式 "周五 1月30日"
-        var weekdayStr = currentTime.format('ddd'); // 周五
-        var dateStr = currentTime.format('M月D日'); // 1月30日
-        combinedStr = "".concat(weekdayStr, " ").concat(dateStr);
-      } else {
-        // 英文环境：使用格式 "Sat, 21 Mar"
-        var _weekdayStr = currentTime.format('ddd'); // Sat
-        var _dateStr = currentTime.format('D MMM'); // 21 Mar
-        combinedStr = "".concat(_weekdayStr, ", ").concat(_dateStr);
-      }
+      var _labels$relativeDay;
+      var labels = effectiveDateFormat === null || effectiveDateFormat === void 0 ? void 0 : effectiveDateFormat.relativeDayLabels;
+      var dateStr = relativeDay ? (_labels$relativeDay = labels === null || labels === void 0 ? void 0 : labels[relativeDay]) !== null && _labels$relativeDay !== void 0 ? _labels$relativeDay : getRelativeDayLabel(relativeDay, currentTime.locale()) : isChinese ? currentTime.format('M月D日') : currentTime.format('D MMM');
+      var weekdayStr = currentTime.format('ddd');
+      // 相对日替换掉原日期展示：有今天/昨天/明天时只显示相对日，不拼接具体日期或星期
+      var combinedStr = relativeDay ? dateStr : isChinese ? "".concat(weekdayStr, " ").concat(dateStr) : "".concat(weekdayStr, ", ").concat(dateStr);
 
       // 构建日期样式
       var dateInlineStyle = {

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

@@ -26,6 +26,11 @@ export declare const InlineLayout: Story;
  * 单行布局 - 自定义分隔符
  */
 export declare const InlineWithCustomSeparator: Story;
+/**
+ * 中文完整日期格式：2025-12-31 - 2:00 周四
+ * 单行、日期在前、日期与时间之间 " - "、时间与星期之间空格
+ */
+export declare const InlineDateTimeWeekdayZh: Story;
 /**
  * 12小时制
  */
@@ -62,6 +67,20 @@ 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;
 /**
  * 英文完整月份
  */

package/es/components/pisellDateTimeDisplay/PisellDateTimeDisplay.stories.js

@@ -70,6 +70,28 @@ export var InlineWithCustomSeparator = {
   }
 };
 
+/**
+ * 中文完整日期格式：2025-12-31 - 2:00 周四
+ * 单行、日期在前、日期与时间之间 " - "、时间与星期之间空格
+ */
+export var InlineDateTimeWeekdayZh = {
+  args: {
+    layout: 'inline',
+    locale: 'zh-cn',
+    fields: {
+      fieldOrder: ['date', 'time', 'weekday'],
+      inlineSeparators: [' - ', ' ']
+    },
+    dateFormat: {
+      order: 'YMD',
+      showYear: true,
+      separator: '-',
+      showChineseUnit: false,
+      showRelativeDay: false
+    }
+  }
+};
+
 /**
  * 12小时制
  */
@@ -180,6 +202,58 @@ export var DateChinese = {
   }
 };
 
+/**
+ * 相对日：今天/昨天/明天
+ * 与「当前日期」同天显示「今天」，前一天「昨天」，后一天「明天」；其他日期仍按原格式。
+ * 参考日为 dayjs()，随时间变化：例如 2 月 4 日当天，2 月 4 日显示「今天」，2 月 3 日显示「昨天」。
+ */
+export var RelativeDay = {
+  args: {
+    layout: 'horizontal',
+    dateFormat: {
+      showRelativeDay: true,
+      showYear: true,
+      showChineseUnit: true
+    },
+    locale: 'zh-cn'
+  }
+};
+
+/**
+ * 相对日 - 英文
+ */
+export var RelativeDayEn = {
+  args: {
+    layout: 'horizontal',
+    dateFormat: {
+      showRelativeDay: true,
+      order: 'MDY',
+      showYear: true
+    },
+    locale: 'en'
+  }
+};
+
+/**
+ * 相对日 - 自定义文案
+ */
+export var RelativeDayCustomLabels = {
+  args: {
+    layout: 'horizontal',
+    dateFormat: {
+      showRelativeDay: true,
+      relativeDayLabels: {
+        today: '今日',
+        yesterday: '昨日',
+        tomorrow: '翌日'
+      },
+      showYear: true,
+      showChineseUnit: true
+    },
+    locale: 'zh-cn'
+  }
+};
+
 /**
  * 英文完整月份
  */

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

@@ -1,5 +1,5 @@
 import React from 'react';
-import type { Dayjs } from 'dayjs';
+import { type Dayjs } from 'dayjs';
 import type { DateFormatConfig, TextStyleConfig } from '../types';
 /**
  * DateDisplay 组件 Props
@@ -13,6 +13,10 @@ export interface DateDisplayProps {
      * 日期格式配置
      */
     format?: DateFormatConfig;
+    /**
+     * 参考日期（用于「今天/昨天/明天」判定，默认当前时间 dayjs()）
+     */
+    referenceDate?: Dayjs;
     /**
      * 文本样式
      */
@@ -27,6 +31,7 @@ export interface DateDisplayProps {
  *
  * @description
  * - 格式化并展示日期
+ * - 支持 showRelativeDay：今天/昨天/明天时用相对日替换原日期展示，不展示具体日期
  * - 支持不同的日期顺序（YMD/MDY/DMY）
  * - 支持年月日字段显隐
  * - 支持中文单位（年、月、日）

package/es/components/pisellDateTimeDisplay/components/DateDisplay.js

@@ -1,5 +1,6 @@
 import React from 'react';
-import { formatDate } from "../utils";
+import dayjs from 'dayjs';
+import { formatDate, getRelativeDay, getRelativeDayLabel } from "../utils";
 
 /**
  * DateDisplay 组件 Props
@@ -10,6 +11,7 @@ import { formatDate } from "../utils";
  *
  * @description
  * - 格式化并展示日期
+ * - 支持 showRelativeDay：今天/昨天/明天时用相对日替换原日期展示，不展示具体日期
  * - 支持不同的日期顺序（YMD/MDY/DMY）
  * - 支持年月日字段显隐
  * - 支持中文单位（年、月、日）
@@ -23,12 +25,17 @@ import { formatDate } from "../utils";
  * />
  */
 export var DateDisplay = function DateDisplay(_ref) {
+  var _labels$relativeDay;
   var date = _ref.date,
     format = _ref.format,
+    _ref$referenceDate = _ref.referenceDate,
+    referenceDate = _ref$referenceDate === void 0 ? dayjs() : _ref$referenceDate,
     style = _ref.style,
     className = _ref.className;
-  // 格式化日期
-  var formattedDate = formatDate(date, format);
+  var labels = format === null || format === void 0 ? void 0 : format.relativeDayLabels;
+  var relativeDay = format !== null && format !== void 0 && format.showRelativeDay ? getRelativeDay(date, referenceDate) : null;
+  // 相对日替换原日期展示：有今天/昨天/明天时只显示相对日，不展示具体日期
+  var formattedDate = relativeDay ? (_labels$relativeDay = labels === null || labels === void 0 ? void 0 : labels[relativeDay]) !== null && _labels$relativeDay !== void 0 ? _labels$relativeDay : getRelativeDayLabel(relativeDay, date.locale()) : formatDate(date, format);
 
   // 如果没有要显示的内容，返回 null
   if (!formattedDate) {

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

@@ -0,0 +1,7 @@
+import type { DateTimeDisplayFormatPreset } from '../types';
+/**
+ * PisellDateTimeDisplay 按语言预设的格式
+ * - zh-cn：完整日期 - 时间 星期（如 2025-12-31 - 2:00 周四）、相对日今天/昨天/明天
+ * - en：时间 星期, 日期（如 2:00 Sat, 21 Mar, 2026）、相对日 Today/Yesterday/Tomorrow
+ */
+export declare const DATETIME_DISPLAY_FORMATS: Record<string, Partial<DateTimeDisplayFormatPreset>>;

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

@@ -0,0 +1,81 @@
+/**
+ * PisellDateTimeDisplay 按语言预设的格式
+ * - zh-cn：完整日期 - 时间 星期（如 2025-12-31 - 2:00 周四）、相对日今天/昨天/明天
+ * - en：时间 星期, 日期（如 2:00 Sat, 21 Mar, 2026）、相对日 Today/Yesterday/Tomorrow
+ */
+export var DATETIME_DISPLAY_FORMATS = {
+  'zh-cn': {
+    dateFormat: {
+      order: 'YMD',
+      showYear: true,
+      separator: '-',
+      showChineseUnit: false,
+      showRelativeDay: true
+    },
+    timeFormat: {
+      use12Hour: false,
+      showSeconds: false
+    },
+    weekdayFormat: {
+      full: false,
+      singleLetter: false
+    },
+    fields: {
+      showTime: true,
+      showDate: true,
+      showWeekday: true,
+      fieldOrder: ['date', 'time', 'weekday'],
+      inlineSeparators: [' - ', ' ']
+    }
+  },
+  zh: {
+    // 兜底 zh
+    dateFormat: {
+      order: 'YMD',
+      showYear: true,
+      separator: '-',
+      showChineseUnit: false,
+      showRelativeDay: true
+    },
+    timeFormat: {
+      use12Hour: false,
+      showSeconds: false
+    },
+    weekdayFormat: {
+      full: false,
+      singleLetter: false
+    },
+    fields: {
+      showTime: true,
+      showDate: true,
+      showWeekday: true,
+      fieldOrder: ['date', 'time', 'weekday'],
+      inlineSeparators: [' - ', ' ']
+    }
+  },
+  en: {
+    dateFormat: {
+      order: 'DMY',
+      shortMonth: true,
+      showYear: true,
+      showRelativeDay: true,
+      useCommaBeforeYear: true
+    },
+    timeFormat: {
+      use12Hour: false,
+      showSeconds: false
+    },
+    weekdayFormat: {
+      full: false,
+      singleLetter: false,
+      trailingComma: true
+    },
+    fields: {
+      showTime: true,
+      showDate: true,
+      showWeekday: true,
+      fieldOrder: ['time', 'weekday', 'date'],
+      inlineSeparators: [' ', ' ']
+    }
+  }
+};

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

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

package/es/components/pisellDateTimeDisplay/formats/index.js

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

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

@@ -15,7 +15,7 @@ export interface UseCurrentTimeOptions {
     disabled?: boolean;
     /**
      * dayjs locale
-     * @default 优先使用全局配置，其次使用浏览器语言
+     * @default 优先使用全局配置，其次使用 i18n 当前语言（getCurrentLocale）
      * @example 'zh-CN' | 'zh-HK' | 'en' | 'en-US' | 'ja'
      */
     locale?: string;
@@ -30,7 +30,7 @@ export interface UseCurrentTimeOptions {
  * @description
  * - 自动创建定时器刷新时间
  * - 支持自定义刷新间隔
- * - 支持国际化（locale）：优先级为 用户指定 > 全局配置 > 浏览器语言
+ * - 支持国际化（locale）：优先级为 用户指定 > 全局配置 > i18n 当前语言
  * - 组件卸载时自动清除定时器
  *
  * @example

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

@@ -19,7 +19,7 @@ import usePisellConfig from "../../pisell-config-provider/hooks/usePisellConfig"
  * @description
  * - 自动创建定时器刷新时间
  * - 支持自定义刷新间隔
- * - 支持国际化（locale）：优先级为 用户指定 > 全局配置 > 浏览器语言
+ * - 支持国际化（locale）：优先级为 用户指定 > 全局配置 > i18n 当前语言
  * - 组件卸载时自动清除定时器
  *
  * @example
@@ -45,7 +45,7 @@ export function useCurrentTime(options) {
   var globalConfig = usePisellConfig();
   var globalLocale = globalConfig === null || globalConfig === void 0 ? void 0 : globalConfig.locale;
 
-  // 获取实际使用的 locale（优先级：用户指定 > 全局配置 > 浏览器语言）
+  // 获取实际使用的 locale（优先级：用户指定 > 全局配置 > i18n 当前语言）
   var dayjsLocale = getDayjsLocale(userLocale || globalLocale);
 
   // 初始化时间

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

@@ -99,6 +99,26 @@ export interface DateFormatConfig {
      * @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;
+    };
 }
 /**
  * 星期格式配置
@@ -116,6 +136,11 @@ export interface WeekdayFormatConfig {
      * @example true -> "S" / "六" | false -> "Sat" / "周六"
      */
     singleLetter?: boolean;
+    /**
+     * 是否在星期后加逗号（用于与日期拼接如 "Sat, 21 Mar, 2026"）
+     * @default false
+     */
+    trailingComma?: boolean;
 }
 /**
  * 字段配置
@@ -141,6 +166,12 @@ export interface FieldConfig {
      * @default ['time', 'date', 'weekday']
      */
     fieldOrder?: FieldType[];
+    /**
+     * 单行布局时每段之间的分隔符，按顺序对应字段之间
+     * 如 ['date','time','weekday'] 配 inlineSeparators: [' - ', ' '] => "2025-12-31 - 2:00 周四"
+     * 不足时用组件 inlineSeparator 补齐
+     */
+    inlineSeparators?: string[];
 }
 /**
  * 文本样式配置
@@ -202,6 +233,16 @@ export interface ContainerStyleConfig {
      */
     gap?: number | string;
 }
+/**
+ * 多语言格式预设（日期/时间/星期 + 字段顺序与分隔符）
+ * 用于 formatByLocale[locale] 或默认多语言配置
+ */
+export interface DateTimeDisplayFormatPreset {
+    dateFormat?: DateFormatConfig;
+    timeFormat?: TimeFormatConfig;
+    weekdayFormat?: WeekdayFormatConfig;
+    fields?: FieldConfig;
+}
 /**
  * PisellDateTimeDisplay 组件 Props
  */
@@ -220,6 +261,11 @@ export interface PisellDateTimeDisplayProps {
      * 字段显示配置
      */
     fields?: FieldConfig;
+    /**
+     * 多语言格式配置：按 locale 取对应格式预设，再与下方单项配置合并（单项优先）
+     * @example formatByLocale={{ 'zh-cn': { dateFormat: {...}, fields: { fieldOrder: ['date','time','weekday'], inlineSeparators: [' - ', ' '] } }, 'en': {...} }}
+     */
+    formatByLocale?: Record<string, Partial<DateTimeDisplayFormatPreset>>;
     /**
      * 时间格式配置
      */
@@ -274,11 +320,11 @@ export interface PisellDateTimeDisplayProps {
     disableAutoRefresh?: boolean;
     /**
      * dayjs locale（语言代码）
-     * @default 优先使用全局配置（usePisellConfig），其次使用浏览器语言
+     * @default 优先使用全局配置（usePisellConfig），其次使用 i18n 当前语言（getCurrentLocale：全局配置 / umi_locale）
      * @example 'zh-CN' | 'zh-HK' | 'en' | 'en-US' | 'ja'
      * @description
      * - 支持标准 BCP 47 语言代码，会自动标准化为 dayjs 兼容格式
-     * - 优先级：组件 locale 属性 > PisellConfigProvider 全局配置 > 浏览器语言
+     * - 优先级：组件 locale 属性 > PisellConfigProvider 全局配置 > i18n 当前语言
      */
     locale?: string;
     /**

package/es/components/pisellDateTimeDisplay/utils/formatDate.js

@@ -41,7 +41,9 @@ export function formatDate(date, config) {
     _ref$showMonth = _ref.showMonth,
     showMonth = _ref$showMonth === void 0 ? true : _ref$showMonth,
     _ref$showDay = _ref.showDay,
-    showDay = _ref$showDay === void 0 ? true : _ref$showDay;
+    showDay = _ref$showDay === void 0 ? true : _ref$showDay,
+    _ref$useCommaBeforeYe = _ref.useCommaBeforeYear,
+    useCommaBeforeYear = _ref$useCommaBeforeYe === void 0 ? true : _ref$useCommaBeforeYe;
 
   // 判断是否为中文环境
   var locale = date.locale();
@@ -99,13 +101,10 @@ export function formatDate(date, config) {
     return date.format(parts.join(''));
   }
 
-  // MDY 格式特殊处理（英文习惯）
+  // MDY 格式特殊处理（英文习惯）Mar 21, 2026
   if (order === 'MDY' && !isChinese) {
-    // 月日之间用空格，日年之间用逗号+空格
     var formatted = date.format(parts.join(' '));
-    // 如果有年份，在日和年之间加逗号
     if (showYear && showMonth && showDay) {
-      // 例如: "Mar 21 2026" -> "Mar 21, 2026"
       var _formatted$split = formatted.split(' '),
         _formatted$split2 = _slicedToArray(_formatted$split, 3),
         month = _formatted$split2[0],
@@ -114,7 +113,6 @@ export function formatDate(date, config) {
       return "".concat(month, " ").concat(day, ", ").concat(year);
     }
     if (showYear && showDay && !showMonth) {
-      // 例如: "21 2026" -> "21, 2026"
       var _formatted$split3 = formatted.split(' '),
         _formatted$split4 = _slicedToArray(_formatted$split3, 2),
         _day = _formatted$split4[0],
@@ -124,6 +122,27 @@ export function formatDate(date, config) {
     return formatted;
   }
 
+  // DMY 格式英文：21 Mar, 2026 或 22 Jan 2025（useCommaBeforeYear 控制）
+  if (order === 'DMY' && !isChinese) {
+    var _formatted = date.format(parts.join(' '));
+    if (showYear && showMonth && showDay && useCommaBeforeYear) {
+      var _formatted$split5 = _formatted.split(' '),
+        _formatted$split6 = _slicedToArray(_formatted$split5, 3),
+        _day2 = _formatted$split6[0],
+        _month = _formatted$split6[1],
+        _year2 = _formatted$split6[2];
+      return "".concat(_day2, " ").concat(_month, ", ").concat(_year2);
+    }
+    if (showYear && showDay && !showMonth && useCommaBeforeYear) {
+      var _formatted$split7 = _formatted.split(' '),
+        _formatted$split8 = _slicedToArray(_formatted$split7, 2),
+        _day3 = _formatted$split8[0],
+        _year3 = _formatted$split8[1];
+      return "".concat(_day3, ", ").concat(_year3);
+    }
+    return _formatted;
+  }
+
   // 其他情况使用分隔符
   return date.format(parts.join(separator));
 }

package/es/components/pisellDateTimeDisplay/utils/formatDateOrRelative.d.ts

@@ -0,0 +1,17 @@
+import type { Dayjs } from 'dayjs';
+import type { DateFormatConfig, WeekdayFormatConfig } from '../types';
+/**
+ * 获取「日期部分」的展示文案（相对日内置在 datetime）
+ * - 若开启 showRelativeDay 且日期为今天/昨天/明天，返回相对日文案（如「今天」「Yesterday」）
+ * - 否则返回「星期, 日期」格式（用于时间区间跨天等场景）
+ *
+ * 供 PisellDateTimeDisplay、PisellTimeRangeDisplay 等统一使用，相对时间逻辑只在此处维护
+ */
+export declare function getDatePartDisplay(params: {
+    date: Dayjs;
+    dateFormat?: DateFormatConfig;
+    weekdayFormat?: WeekdayFormatConfig;
+    referenceDate: Dayjs;
+    /** 覆盖日期格式（如跨天时的 order: 'DMY', shortMonth: true） */
+    dateFormatOverride?: Partial<DateFormatConfig>;
+}): string;