@pisell/materials 1.0.1086 → 1.0.1087

package/lib/components/pisellReservationScheduleBand/PisellReservationScheduleBand.stories.d.ts

@@ -0,0 +1,16 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { PisellReservationScheduleBand } from './PisellReservationScheduleBand';
+/**
+ * PisellReservationScheduleBand：营业日条 + 横向时间轴顶栏组合，统一 value `{ date, at }`。
+ * 详见组件目录下 docs/PisellReservationScheduleBand.md。
+ */
+declare const meta: Meta<typeof PisellReservationScheduleBand>;
+export default meta;
+declare type Story = StoryObj<typeof PisellReservationScheduleBand>;
+export declare const Default: Story;
+export declare const CustomTimeNavigator: Story;
+export declare const ScheduleMinMax: Story;
+export declare const Controlled: Story;
+export declare const InitialPastDay: Story;
+/** 日程行左右插槽：左标题 + 中间 PisellReservationSchedule + 右操作区（整条顶栏暗色背景需在业务外层自行包一层，避免压住下方时间轴） */
+export declare const WithScheduleSlots: Story;

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

@@ -0,0 +1,2 @@
+export { PisellReservationScheduleBand } from './PisellReservationScheduleBand';
+export type { PisellReservationScheduleBandProps, ReservationScheduleBandValue, TimeNavigatorPassthroughProps, } from './types';

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

@@ -0,0 +1,57 @@
+import type { CSSProperties, ReactNode } from 'react';
+import type { Dayjs } from 'dayjs';
+import type { PisellTimeNavigatorProps } from '../pisellTimeNavigator/types';
+import type { PisellReservationScheduleProps } from '../pisellReservationSchedule/types';
+/** 组合值：日历日 + 该日上的时刻（与 PisellTimeNavigator 对齐） */
+export interface ReservationScheduleBandValue {
+    date: Dayjs;
+    at: Dayjs;
+}
+export declare type TimeNavigatorPassthroughProps = Omit<PisellTimeNavigatorProps, 'value' | 'onChange' | 'referenceDate' | 'defaultValue'>;
+/**
+ * PisellReservationScheduleBand：营业日条 + 横向时间轴
+ */
+export interface PisellReservationScheduleBandProps {
+    /**
+     * 受控：选中日 + 轴上时刻
+     */
+    value?: ReservationScheduleBandValue;
+    /**
+     * 日历日或时刻任一变化时触发
+     */
+    onChange?: (next: ReservationScheduleBandValue) => void;
+    /**
+     * 非受控初始值（可只传部分字段）
+     */
+    defaultValue?: Partial<ReservationScheduleBandValue>;
+    /**
+     * 透传给 PisellReservationSchedule（如 minDate / maxDate）
+     */
+    scheduleProps?: Omit<PisellReservationScheduleProps, 'value' | 'onChange' | 'defaultValue'>;
+    /**
+     * 透传给 PisellTimeNavigator（不含 value/onChange/referenceDate）
+     */
+    timeNavigatorProps?: TimeNavigatorPassthroughProps;
+    /**
+     * 顶栏日程行：PisellReservationSchedule 左侧自定义内容（如标题）
+     */
+    scheduleStartSlot?: ReactNode;
+    /**
+     * 顶栏日程行：PisellReservationSchedule 右侧自定义内容（如状态、主按钮）
+     */
+    scheduleEndSlot?: ReactNode;
+    /**
+     * 顶栏日程行：紧挨在选日组件之后（如「跟随当前」），与中间列同一 flex 区
+     */
+    scheduleAfterDateSlot?: ReactNode;
+    /**
+     * 为 true 时在整个日程带上叠加载层（如切换营业日后拉预约列表期间）
+     */
+    dataLoading?: boolean;
+    /**
+     * 加载层内文案，由业务侧 {@link locales.getText} 等注入
+     */
+    dataLoadingTip?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}

package/lib/components/pisellSingleLineText/PisellSingleLineText.d.ts

@@ -0,0 +1,40 @@
+import React from 'react';
+import type { PisellSingleLineTextProps } from './types';
+import './PisellSingleLineText.less';
+/**
+ * PisellSingleLineText 单行文本组件
+ *
+ * 通用的单行文本输入/展示组件，支持只读、编辑、禁用三种状态。
+ * 基于 Ant Design Input 组件开发，提供完整的校验框架。
+ *
+ * @param props 组件 Props
+ *
+ * @example
+ * // 受控模式
+ * const [value, setValue] = useState('');
+ * <PisellSingleLineText
+ *   value={value}
+ *   onChange={(v) => setValue(v)}
+ *   placeholder="请输入"
+ * />
+ *
+ * @example
+ * // 非受控模式
+ * <PisellSingleLineText
+ *   defaultValue="初始值"
+ *   required
+ *   minLength={3}
+ * />
+ *
+ * @example
+ * // 只读态
+ * <PisellSingleLineText
+ *   mode="read"
+ *   value="这是一段很长的文本内容"
+ *   ellipsis
+ *   showTooltip
+ * />
+ */
+export declare const PisellSingleLineText: React.FC<PisellSingleLineTextProps>;
+declare const _default: React.NamedExoticComponent<PisellSingleLineTextProps>;
+export default _default;

package/lib/components/pisellSingleSelect/PisellSingleSelect.d.ts

@@ -0,0 +1,9 @@
+/**
+ * PisellSingleSelect - 单选下拉组件
+ * 基于 Ant Design Select 封装，提供符合 Pisell 设计规范的单选功能
+ */
+import React from 'react';
+import type { PisellSingleSelectProps, SingleSelectRef } from './types';
+import './PisellSingleSelect.less';
+declare const PisellSingleSelect: React.ForwardRefExoticComponent<PisellSingleSelectProps<string | number> & React.RefAttributes<SingleSelectRef<string | number>>>;
+export default PisellSingleSelect;

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

@@ -1,4 +1,3 @@
-/// <reference types="react" />
 import { PisellSortProps } from './type';
 declare const PisellSort: (props: PisellSortProps) => JSX.Element;
 export default PisellSort;

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

@@ -0,0 +1,22 @@
+import React from 'react';
+import './index.less';
+export interface PisellStatisticListProps extends React.HTMLAttributes<HTMLDivElement> {
+    isHasBorder?: boolean;
+    backgroundColors?: string[];
+    labelColor?: string;
+    valueColor?: string;
+    data: {
+        label: string;
+        value: string;
+        isLink?: boolean;
+        link?: string;
+        tip?: string;
+        onClick?: () => void;
+        children?: {
+            label: string;
+            value: string;
+        }[];
+    }[];
+}
+declare const PisellStatisticList: (props: PisellStatisticListProps) => JSX.Element;
+export default PisellStatisticList;

package/lib/components/pisellText/components/Amount/index.d.ts

@@ -0,0 +1,20 @@
+import React from 'react';
+import { PisellContextType } from '../../../pisell-config-provider/context';
+export interface AmountProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** 平台 */
+    platform?: PisellContextType['platform'];
+    /** 当前数值  */
+    value?: number | string;
+    /** 小数点后位数 默认是小数点后2位 */
+    precision?: number;
+    /** 显示货币符号 指的是 ¥$ 等货币符号等显隐，默认是展示 */
+    showCurrencySymbol?: boolean;
+    /** 千分位 指的是长金额的千分位逗号隔开，比如“123, 245, 315” 这种展现形式，默认是关闭 */
+    useThousandsSeparator?: boolean;
+    /** 整数位隐藏小数 指的是如果价格为整数，后面的".00" 将被省略以节省页面空间 */
+    hideDecimalForWholeNumbers?: boolean;
+    /** 货币符号 */
+    symbol?: string;
+}
+declare const Amount: (props: AmountProps) => JSX.Element;
+export default Amount;

package/lib/components/pisellTimeNavigator/PisellTimeNavigator.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="react" />
+import type { PisellTimeNavigatorProps } from './types';
+import './PisellTimeNavigator.less';
+/**
+ * PisellTimeNavigator：可拖动的时间导航轴，时间范围内浏览、选择、控制
+ */
+export declare function PisellTimeNavigator(props: PisellTimeNavigatorProps): JSX.Element;
+export declare namespace PisellTimeNavigator {
+    var displayName: string;
+}

package/lib/components/pisellTimeNavigator/PisellTimeNavigator.stories.d.ts

@@ -0,0 +1,79 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { PisellTimeNavigator } from './PisellTimeNavigator';
+/**
+ * PisellTimeNavigator 组件 Storybook
+ * 时间导航轴：时间范围内浏览、选择、控制
+ */
+declare const meta: Meta<typeof PisellTimeNavigator>;
+export default meta;
+declare type Story = StoryObj<typeof PisellTimeNavigator>;
+/**
+ * 默认：横向、轴动、显示 Now
+ */
+export declare const Default: Story;
+/** 默认 - 竖向 */
+export declare const DefaultVertical: Story;
+/**
+ * 受控 + 默认 12:00
+ */
+export declare const Controlled: Story;
+/** 受控 - 竖向 */
+export declare const ControlledVertical: Story;
+/**
+ * 非受控 + 默认 14:30
+ */
+export declare const Uncontrolled: Story;
+/** 非受控 - 竖向 */
+export declare const UncontrolledVertical: Story;
+/**
+ * 竖向
+ */
+export declare const Vertical: Story;
+/**
+ * 指针动模式（cursor-moves）
+ */
+export declare const CursorMoves: Story;
+/** 指针动模式 - 竖向 */
+export declare const CursorMovesVertical: Story;
+/**
+ * 营业时间高亮 10:00–22:00
+ */
+export declare const BusinessHours: Story;
+/** 营业时间高亮 - 竖向 */
+export declare const BusinessHoursVertical: Story;
+/**
+ * 自定义时间范围 08:00–20:00
+ */
+export declare const CustomRange: Story;
+/** 自定义时间范围 - 竖向 */
+export declare const CustomRangeVertical: Story;
+/**
+ * 步长 30 分钟
+ */
+export declare const Step30: Story;
+/** 步长 30 分钟 - 竖向 */
+export declare const Step30Vertical: Story;
+/**
+ * 惯性滚动开启
+ */
+export declare const Inertia: Story;
+/** 惯性滚动 - 竖向 */
+export declare const InertiaVertical: Story;
+/**
+ * 吸附到整点（松手后自动吸附到 0/15/30/45 分刻度）
+ */
+export declare const SnapToStep: Story;
+/** 吸附到整点 - 竖向 */
+export declare const SnapToStepVertical: Story;
+/**
+ * 隐藏 Now 按钮
+ */
+export declare const NoNowButton: Story;
+/** 隐藏 Now 按钮 - 竖向 */
+export declare const NoNowButtonVertical: Story;
+/**
+ * 实时模式（仅演示，实际会跟随系统时间）
+ */
+export declare const Realtime: Story;
+/** 实时模式 - 竖向 */
+export declare const RealtimeVertical: Story;

package/lib/components/pisellTimeNavigator/components/BackgroundLayer.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+export interface BackgroundLayerProps {
+    orientation: 'horizontal' | 'vertical';
+    /** 过去时间淡化色 */
+    pastTimeFade?: string;
+    /** 营业时间区间 [startPx, endPx]，用于视觉高亮 */
+    businessHoursPx?: [number, number];
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * 背景区间层：营业时间高亮、过去时间淡化等（当前时间渐变已拆为独立块，见 axis-wrap 内 .pisell-time-navigator-current-gradient）
+ */
+export declare function BackgroundLayer({ orientation, pastTimeFade, businessHoursPx, className, style, }: BackgroundLayerProps): JSX.Element;

package/lib/components/pisellTimeNavigator/components/CursorLayer.d.ts

@@ -0,0 +1,25 @@
+import React from 'react';
+import type { Dayjs } from 'dayjs';
+export interface CursorLayerProps {
+    orientation: 'horizontal' | 'vertical';
+    value: Dayjs | null;
+    timeFormat: string;
+    locale?: string;
+    isRealtime: boolean;
+    offsetPx: number;
+    /** axis-moves 时固定于视口中央，不应用 offsetPx */
+    fixedCenter?: boolean;
+    style?: React.CSSProperties;
+    className?: string;
+    /** cursor-moves：允许拖指针改时间 */
+    dragInteractive?: boolean;
+    onDragPointerDown?: React.PointerEventHandler<HTMLDivElement>;
+    onDragPointerMove?: React.PointerEventHandler<HTMLDivElement>;
+    onDragPointerUp?: React.PointerEventHandler<HTMLDivElement>;
+    onDragPointerCancel?: React.PointerEventHandler<HTMLDivElement>;
+}
+/**
+ * 时间指示器层：横向为「顶三角 + 竖长方条」SVG，竖向为横线 + 时间气泡
+ * 对齐基准为几何中心。Realtime 态 #FF692E，浏览态 #344054
+ */
+export declare function CursorLayer({ orientation, value, timeFormat, locale, isRealtime, offsetPx, fixedCenter, style, className, dragInteractive, onDragPointerDown, onDragPointerMove, onDragPointerUp, onDragPointerCancel, }: CursorLayerProps): JSX.Element | null;

package/lib/components/pisellTimeNavigator/components/GestureLayer.d.ts

@@ -0,0 +1,33 @@
+import React from 'react';
+import type { Dayjs } from 'dayjs';
+export interface GestureLayerProps {
+    orientation: 'horizontal' | 'vertical';
+    cellSizePx: number;
+    /** 轴在滚动内容中的起始边距（左/上），用于把「滚动内容坐标」转为「轴内偏移」（与 dot 对齐） */
+    axisStartMarginPx: number;
+    offsetToTime: (offset: number) => Dayjs | null;
+    onSelectTime: (t: Dayjs) => void;
+    isInDisabledRanges: (t: Dayjs) => boolean;
+    snapToStep: boolean;
+    stepMinutes: number;
+    snapFn: (t: Dayjs) => Dayjs;
+    scrollPosition: {
+        scrollLeft: number;
+        scrollTop: number;
+    };
+    viewportSize: {
+        w: number;
+        h: number;
+    };
+    onPointerDown?: React.PointerEventHandler;
+    onPointerMove?: React.PointerEventHandler;
+    onPointerUp?: React.PointerEventHandler;
+    onPointerLeave?: React.PointerEventHandler;
+    /** 轴上任意指针按下（含惯性拖轴） */
+    onUserInteraction?: () => void;
+    children: React.ReactNode;
+}
+/**
+ * 交互层：点击刻度跳转、键盘左右/上下 + 回车
+ */
+export declare function GestureLayer({ orientation, cellSizePx, axisStartMarginPx, offsetToTime, onSelectTime, isInDisabledRanges, snapToStep, stepMinutes, snapFn, scrollPosition, viewportSize, onPointerDown, onPointerMove, onPointerUp, onPointerLeave, onUserInteraction, children, }: GestureLayerProps): JSX.Element;

package/lib/components/pisellTimeNavigator/components/NowButton.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import type { CSSProperties } from 'react';
+export interface NowButtonProps {
+    orientation: 'horizontal' | 'vertical';
+    onClick: () => void;
+    style?: CSSProperties;
+    className?: string;
+    renderCustom?: () => React.ReactNode;
+}
+/**
+ * Now 按钮：固定入口，点击跳回当前时间并进入 Realtime
+ * 横向：右侧，左箭头；竖向：底部，上箭头
+ */
+export declare function NowButton({ orientation, onClick, style, className, renderCustom, }: NowButtonProps): JSX.Element;

package/lib/components/pisellTimeNavigator/components/ScaleLayer.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import type { Dayjs } from 'dayjs';
+export interface ScaleLayerProps {
+    orientation: 'horizontal' | 'vertical';
+    ticks: Dayjs[];
+    stepMinutes: number;
+    majorStepMinutes: number;
+    timeFormat: string;
+    locale?: string;
+    style?: React.CSSProperties;
+    className?: string;
+    /**
+     * 横向每格宽度（px），须与 useTimeAxis 的 cellSizePx 一致；
+     * 不传时样式表默认 82（axis-moves）；cursor-moves 压缩比例时必传
+     */
+    horizontalCellSizePx?: number;
+}
+/**
+ * 刻度层：渲染时间刻度与标签
+ * 横向：整点数字 + 小圆点；竖向：整点/半点数字 + 分割线
+ */
+export declare function ScaleLayer({ orientation, ticks, stepMinutes, majorStepMinutes, timeFormat, locale, style, className, horizontalCellSizePx, }: ScaleLayerProps): JSX.Element;

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

@@ -0,0 +1,5 @@
+export { BackgroundLayer } from './BackgroundLayer';
+export { CursorLayer } from './CursorLayer';
+export { GestureLayer } from './GestureLayer';
+export { NowButton } from './NowButton';
+export { ScaleLayer } from './ScaleLayer';

package/lib/components/pisellTimeNavigator/hooks/index.d.ts

@@ -0,0 +1,5 @@
+export { useTimeAxis } from './useTimeAxis';
+export type { UseTimeAxisOptions, TimeAxisState } from './useTimeAxis';
+export { useRealtime } from './useRealtime';
+export { useDragInertia } from './useDragInertia';
+export type { UseDragInertiaOptions } from './useDragInertia';

package/lib/components/pisellTimeNavigator/hooks/useDragInertia.d.ts

@@ -0,0 +1,14 @@
+export interface UseDragInertiaOptions {
+    enabled: boolean;
+    orientation: 'horizontal' | 'vertical';
+    getScrollContainer: () => HTMLElement | null;
+}
+/**
+ * 惯性滚动：根据拖动末段速度在松手后继续滚动并衰减
+ */
+export declare function useDragInertia(options: UseDragInertiaOptions): {
+    onPointerDown: (e: React.PointerEvent) => void;
+    onPointerMove: (e: React.PointerEvent) => void;
+    onPointerUp: (e: React.PointerEvent) => void;
+    stopInertia: () => void;
+};

package/lib/components/pisellTimeNavigator/hooks/useRealtime.d.ts

@@ -0,0 +1,5 @@
+import type { Dayjs } from 'dayjs';
+/**
+ * Realtime 模式：每秒将当前系统时间通过 onTick 回传
+ */
+export declare function useRealtime(enabled: boolean, onTick: (now: Dayjs) => void): void;

package/lib/components/pisellTimeNavigator/hooks/useTimeAxis.d.ts

@@ -0,0 +1,27 @@
+import type { Dayjs } from 'dayjs';
+import type { TimeRangeOption } from '../types';
+export interface UseTimeAxisOptions {
+    range?: TimeRangeOption;
+    stepMinutes: number;
+    referenceDate: Dayjs;
+    orientation: 'horizontal' | 'vertical';
+    /** 横向时每格宽度（px），竖向时每格高度（px） */
+    cellSizePx: number;
+}
+export interface TimeAxisState {
+    rangeStart: Dayjs;
+    rangeEnd: Dayjs;
+    ticks: Dayjs[];
+    /** 时间转主轴偏移（px） */
+    timeToOffset: (t: Dayjs) => number;
+    /** 主轴偏移（px）转时间（最近刻度，用于刻度对齐） */
+    offsetToTime: (offset: number) => Dayjs | null;
+    /** 主轴偏移（px）转时间（连续插值，用于拖动时按分钟步长显示） */
+    offsetToTimeContinuous: (offset: number) => Dayjs | null;
+    /** 主轴总长度（px） */
+    totalLengthPx: number;
+}
+/**
+ * 时间轴刻度与时间↔像素换算
+ */
+export declare function useTimeAxis(options: UseTimeAxisOptions): TimeAxisState;

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

@@ -0,0 +1,5 @@
+export { PisellTimeNavigator } from './PisellTimeNavigator';
+export { getHorizontalAxisSlotCount, getRangeBounds, buildCalendarHourSlotsFromRange, } from './utils';
+export type { PisellTimeNavigatorProps, TimeNavigatorValue, TimeRangeOption, CursorMode, TimeNavigatorOrientation, } from './types';
+/** 多语言文案（en / zh-CN / zh-HK / ja / pt），使用前请在应用内通过 locales.init(pisellTimeNavigatorLocales, lang) 合并 */
+export { default as pisellTimeNavigatorLocales } from './locales';

package/lib/components/pisellTimeNavigator/locales.d.ts

@@ -0,0 +1,22 @@
+/**
+ * PisellTimeNavigator 多语言文案
+ * 使用前请在应用内通过 locales.init() 合并本模块导出的 key
+ */
+declare const _default: {
+    en: {
+        'pisell-time-navigator.now': string;
+    };
+    'zh-CN': {
+        'pisell-time-navigator.now': string;
+    };
+    'zh-HK': {
+        'pisell-time-navigator.now': string;
+    };
+    ja: {
+        'pisell-time-navigator.now': string;
+    };
+    pt: {
+        'pisell-time-navigator.now': string;
+    };
+};
+export default _default;

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

@@ -0,0 +1,160 @@
+import type { CSSProperties, ReactNode } from 'react';
+import type { Dayjs } from 'dayjs';
+/**
+ * value / defaultValue 的 dayjs 兼容类型（组件内部统一为 Dayjs）
+ */
+export declare type TimeNavigatorValue = Dayjs | string | null;
+/**
+ * 时间范围（HH:mm 或 HH:mm:ss，相对 referenceDate 的营业日）
+ * - 同自然日：如 08:00–22:00
+ * - 跨日：结束钟面 ≤ 开始时视为次日结束，如 02:01–02:00 表示至次日 02:00
+ */
+export interface TimeRangeOption {
+    start: string;
+    end: string;
+}
+/**
+ * 拖动/指示器模式
+ * - axis-moves：指示器固定视口中央，刻度移动（默认）
+ * - cursor-moves：刻度固定，指示器在轴上移动
+ */
+export declare type CursorMode = 'axis-moves' | 'cursor-moves';
+/**
+ * 布局方向
+ */
+export declare type TimeNavigatorOrientation = 'horizontal' | 'vertical';
+/**
+ * PisellTimeNavigator 组件 Props
+ */
+export interface PisellTimeNavigatorProps {
+    /**
+     * 当前选中时间（受控）。支持 dayjs 实例或可被 dayjs 解析的字符串
+     */
+    value?: TimeNavigatorValue;
+    /**
+     * 时间变更回调（受控时必传）
+     */
+    onChange?: (value: Dayjs) => void;
+    /**
+     * 默认选中时间（非受控）
+     */
+    defaultValue?: TimeNavigatorValue;
+    /**
+     * 时间轴锚定到的日历日（startOf day）。`range` 的 HH:mm 均相对于该日。
+     * 不传则与历史一致：取「当天」0 点，避免跨天后刻度错位。
+     */
+    referenceDate?: TimeNavigatorValue;
+    /**
+     * 是否 Realtime 模式：value 自动跟随系统当前时间更新
+     * @default false
+     */
+    realtime?: boolean;
+    /**
+     * 时间范围（支持跨日营业，见 {@link TimeRangeOption}）。不传则默认当日 00:00–24:00
+     */
+    range?: TimeRangeOption;
+    /**
+     * 吸附步长（分钟），如 15、30、60
+     * @default 15
+     */
+    stepMinutes?: number;
+    /**
+     * 大刻度间隔（分钟），用于整点刻度；不传则与 stepMinutes 一致或 60
+     * @default 60
+     */
+    majorStepMinutes?: number;
+    /**
+     * 指示器/轴移动模式
+     * @default 'axis-moves'
+     */
+    cursorMode?: CursorMode;
+    /**
+     * 横向或竖向展示
+     * @default 'horizontal'
+     */
+    orientation?: TimeNavigatorOrientation;
+    /**
+     * 营业时间范围（视觉高亮，可选限制选择范围）
+     */
+    businessHours?: TimeRangeOption;
+    /**
+     * 禁用时间段，禁止选中（点击/吸附到该区间无效）
+     */
+    disabledRanges?: TimeRangeOption[];
+    /**
+     * 是否显示 Now 按钮（固定入口）
+     * @default true
+     */
+    showNowButton?: boolean;
+    /**
+     * 为 true 时禁止用户拖动/滚动时间轴、点击刻度改时间（仍随 `value` 程序性对齐视口；用于「跟随当前时刻」等只读轴）
+     * @default false
+     */
+    userInteractionLocked?: boolean;
+    /**
+     * 是否吸附到 step 刻度
+     * @default false
+     */
+    snapToStep?: boolean;
+    /**
+     * 是否开启惯性滚动（拖动松手后减速）
+     * @default false
+     */
+    inertia?: boolean;
+    /**
+     * 过去时间淡化背景色（CSS 颜色值）
+     */
+    pastTimeFade?: string;
+    /**
+     * 容器样式覆盖
+     */
+    containerStyle?: CSSProperties;
+    /**
+     * 刻度层样式覆盖
+     */
+    scaleStyle?: CSSProperties;
+    /**
+     * 时间气泡/竖线样式覆盖（区分 realtime 时由组件内部应用主题色）
+     */
+    cursorStyle?: CSSProperties;
+    /**
+     * Now 按钮样式覆盖
+     */
+    nowButtonStyle?: CSSProperties;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 根节点自定义样式
+     */
+    style?: CSSProperties;
+    /**
+     * dayjs locale
+     */
+    locale?: string;
+    /**
+     * 时间气泡展示格式（dayjs format）
+     * @default 'HH:mm'
+     */
+    timeFormat?: string;
+    /**
+     * 自定义 Now 按钮内容（覆盖默认文案与图标时使用）
+     */
+    renderNowButton?: () => ReactNode;
+    /**
+     * 横向轴上与刻度槽位数一致的密度序列（任意正数，内部按最大值归一化折线高度）
+     */
+    densitySeries?: number[];
+    /**
+     * 未传 `densitySeries` 时按 `referenceDate` 拉取；日历日变更会重新请求，过期响应丢弃
+     */
+    loadDensity?: (params: {
+        referenceDate: Dayjs;
+        stepMinutes: number;
+    }) => Promise<number[]>;
+    /**
+     * 用户开始操作时间轴（拖轴、点刻度、键盘、拖指针等）时回调；用于上层关闭「跟随当前」等。
+     */
+    onUserInteraction?: () => void;
+}