react-native-x-components 0.1.0

package/dist/XPickerDate/index.js

@@ -0,0 +1,234 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * ============================================================================
+ * XPickerDate -- 日期时间滚轮选择器（antd-mobile DatePicker 架构移植）
+ * ============================================================================
+ *
+ * 【format 决定列】出现哪些单位 token 就显示哪些列，顺序固定为
+ *   年 → 月 → 日 → 时 → 分 → 秒
+ * （与 antd-mobile precision 模型一致：antd 用 precision 指定末列，
+ *  format 是它的超集 -- antd 只能选"到某单位为止的前缀"，format 可以
+ *  任意组合，如 'YYYY-MM' 或 'HH:mm'）。
+ *
+ *   format='YYYY-MM-DD'          年 | 月 | 日（默认）
+ *   format='YYYY-MM-DD HH:mm:ss' 年 | 月 | 日 | 时 | 分 | 秒
+ *   format='HH:mm:ss'            时 | 分 | 秒
+ *   format='YYYY-MM'             年 | 月
+ *
+ * 输入解析与输出格式化都使用同一个 format：
+ *   value 传入组件输出过的同格式字符串可精确回读（dayjs customParseFormat），
+ *   传 Date 直接取各字段，解析失败取当前时间。
+ *
+ * 【对标 antd-mobile DatePicker 的逐条核对结论】
+ * 1. 列顺序/子集模型（precision）          -> format 超集实现        ✅
+ * 2. 时/分/秒两位补零，年/月/日不补
+ *    （antd 默认 renderLabel: ('0'+n).slice(-2)）                    ✅
+ * 3. 日列随年月联动（antd getMonthDays）    -> dayjs daysInMonth      ✅
+ * 4. 滚轮手势/弹簧/橡皮筋/松手立即上报
+ *    （antd picker-view wheel.tsx）        -> 通用 XWheel 组件         ✅
+ * 5. min/max 逐列收窄（antd 全量支持）      -> 仅 minYear/maxYear     ⚠️ 差异，
+ *    维持现状：本项目只需要年份范围，无整段 Date 边界需求。
+ *
+ * 滚轮本体见 ./XWheel.tsx（与 XPicker 单列选择器共用）。
+ * ============================================================================
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Pressable, StyleSheet, View, Text } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import dayjs from 'dayjs';
+import customParseFormat from 'dayjs/plugin/customParseFormat';
+import { XPullView } from '../XPullView';
+import { XWheel } from '../XWheel';
+import { useXTheme } from '../theme';
+import { useXLocale } from '../XLocale';
+// 按格式解析字符串值需要 customParseFormat 插件（antd 同款方案）
+dayjs.extend(customParseFormat);
+/** 默认 format：年月日 */
+const DEFAULT_FORMAT = 'YYYY-MM-DD';
+const UNIT_ORDER = ['year', 'month', 'day', 'hour', 'minute', 'second'];
+/** 生成 [start, end] 的整数数组 */
+const range = (start, end) => {
+    const list = [];
+    for (let i = start; i <= end; i++) {
+        list.push(i);
+    }
+    return list;
+};
+/** 两位补零（时/分/秒的展示，与 antd 默认 renderLabel 一致） */
+const pad2 = (n) => String(n).padStart(2, '0');
+/** 数值 → 滚轮选项（时分秒补零，年月日不补） */
+const toOption = (v, pad) => ({ label: pad ? pad2(v) : String(v), value: v });
+/** 静态列（无联动，模块级只生成一次） */
+const MONTH_OPTIONS = range(1, 12).map(v => toOption(v, false));
+const HOUR_OPTIONS = range(0, 23).map(v => toOption(v, true));
+const MINUTE_OPTIONS = range(0, 59).map(v => toOption(v, true));
+const SECOND_OPTIONS = range(0, 59).map(v => toOption(v, true));
+/**
+ * 解析 format：出现哪些单位 token 就有哪些列（顺序固定为 UNIT_ORDER 的子序列）。
+ * 支持的 token：YYYY / MM / DD / HH / mm / ss（dayjs 标准写法，大小写敏感）。
+ * 一个单位都没有（传了不认识的格式）时退回默认年月日。
+ */
+const parseUnits = (format) => {
+    const tokens = {
+        year: format.includes('YYYY'),
+        month: format.includes('MM'),
+        day: format.includes('DD'),
+        hour: format.includes('HH'),
+        minute: format.includes('mm'),
+        second: format.includes('ss'),
+    };
+    const units = UNIT_ORDER.filter(unit => tokens[unit]);
+    return units.length ? units : ['year', 'month', 'day'];
+};
+/** dayjs 对象 → 六单位草稿（dayjs.month() 是 0~11，所以要 +1） */
+const splitDraft = (d) => ({
+    year: d.year(),
+    month: d.month() + 1,
+    day: d.date(),
+    hour: d.hour(),
+    minute: d.minute(),
+    second: d.second(),
+});
+/**
+ * 外部 value → 草稿。
+ * 字符串先按 format 解析（组件输出值的回读路径，精确匹配），
+ * 失败再宽松兜底（如值 '2026-08-19' 配 format 'YYYY-MM-DD HH:mm:ss'，
+ * 日期部分正确、时间归零），仍失败取当前时间；Date 直接取各字段。
+ */
+const parseValue = (format, value) => {
+    let d = null;
+    if (value instanceof Date) {
+        d = dayjs(value);
+    }
+    else if (typeof value === 'string' && value.trim()) {
+        d = dayjs(value, format);
+        if (!d.isValid()) {
+            d = dayjs(value);
+        }
+    }
+    return splitDraft(d && d.isValid() ? d : dayjs());
+};
+export function XPickerDate({ visible, onClose, value, onChange, title, duration = 200, format, mode = 'date', minYear = 1970, maxYear = 2100, }) {
+    const t = useXTheme();
+    const { t: i18n } = useXLocale();
+    const insets = useSafeAreaInsets();
+    const styles = useMemo(() => StyleSheet.create({
+        panel: {
+            backgroundColor: t.colorBgContainer,
+            borderTopLeftRadius: 12,
+            borderTopRightRadius: 12,
+            overflow: 'hidden',
+        },
+        toolbar: {
+            flexDirection: 'row',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            paddingHorizontal: 16,
+            height: 48,
+            borderBottomWidth: StyleSheet.hairlineWidth,
+            borderBottomColor: t.colorSplit,
+        },
+        cancelBtn: {
+            fontSize: 15,
+        },
+        title: {
+            fontSize: 16,
+            fontWeight: '600',
+            flex: 1,
+            textAlign: 'center',
+            marginHorizontal: 8,
+        },
+        confirmBtn: {
+            fontSize: 15,
+            fontWeight: '600',
+        },
+        /** 各列平分（antd: column flex:1） */
+        columns: {
+            flexDirection: 'row',
+        },
+    }), [t]);
+    /** format 优先；未传时按旧 mode 兜底，保持向后兼容 */
+    const resolvedFormat = format ?? (mode === 'time' ? 'HH:mm:ss' : DEFAULT_FORMAT);
+    /** format 决定的列集合（固定顺序） */
+    const units = useMemo(() => parseUnits(resolvedFormat), [resolvedFormat]);
+    const hasDate = units.some(unit => unit === 'year' || unit === 'month' || unit === 'day');
+    const hasTime = units.some(unit => unit === 'hour' || unit === 'minute' || unit === 'second');
+    const [draft, setDraft] = useState(() => parseValue(resolvedFormat, value));
+    /** 上一次的 visible，用于识别"本次渲染刚被打开" */
+    const prevVisibleRef = useRef(visible);
+    /** 各列滚轮的 flush 句柄：确定时强制按当前视觉位置结算 */
+    const wheelRefs = useRef({});
+    /**
+     * 打开瞬间同步重置草稿为当前 value（渲染期修正派生状态）。
+     * 不用 useEffect：effect 要等这一帧提交后才跑，弹层会先以上次的旧值挂载。
+     */
+    if (visible !== prevVisibleRef.current) {
+        prevVisibleRef.current = visible;
+        if (visible) {
+            setDraft(parseValue(resolvedFormat, value));
+        }
+    }
+    /** 年列数据源（useMemo 缓存，避免每次渲染重新生成数组） */
+    const yearOptions = useMemo(() => range(minYear, maxYear).map(v => toOption(v, false)), [minYear, maxYear]);
+    /** 打开期间外部 value / format 变化（比如上层异步回填）也跟着同步 */
+    useEffect(() => {
+        if (visible) {
+            setDraft(parseValue(resolvedFormat, value));
+        }
+    }, [visible, value, resolvedFormat]);
+    /** 当月实际天数（2月28/29、小月30）。antd: getMonthDays(selectedYear, selectedMonth) */
+    const daysInMonth = useMemo(() => dayjs(`${draft.year}-${draft.month}-01`).daysInMonth(), [draft.year, draft.month]);
+    /** 日列数据源：跟随当月天数变化 */
+    const dayOptions = useMemo(() => range(1, daysInMonth).map(v => toOption(v, false)), [daysInMonth]);
+    /** 各列的选项表与显示值（静态列用模块级常量，引用稳定不触发滚轮重建手势） */
+    const columns = useMemo(() => units.map(unit => ({
+        unit,
+        options: unit === 'year'
+            ? yearOptions
+            : unit === 'day'
+                ? dayOptions
+                : unit === 'month'
+                    ? MONTH_OPTIONS
+                    : unit === 'hour'
+                        ? HOUR_OPTIONS
+                        : unit === 'minute'
+                            ? MINUTE_OPTIONS
+                            : SECOND_OPTIONS,
+        /** 日列：草稿天数可能超过当月天数（如切到2月还停着31），夹回来 */
+        value: unit === 'day' ? Math.min(draft.day, daysInMonth) : draft[unit],
+    })), [units, yearOptions, dayOptions, draft, daysInMonth]);
+    /** 某列选中：更新草稿单位。年/月变化可能改变当月天数，顺手把日夹回来（antd 日列 upper 联动） */
+    const handleChange = useCallback((unit, v) => {
+        setDraft(prev => {
+            if (prev[unit] === v) {
+                return prev;
+            }
+            const next = { ...prev, [unit]: v };
+            if ((unit === 'year' || unit === 'month') && units.includes('day')) {
+                next.day = Math.min(prev.day, dayjs(`${next.year}-${next.month}-01`).daysInMonth());
+            }
+            return next;
+        });
+    }, [units]);
+    /**
+     * 确定：先逐列 flush（拖拽/spring 进行中也按当前视觉位置结算），
+     * 再按 format 格式化输出。
+     */
+    const handleConfirm = useCallback(() => {
+        const final = { ...draft };
+        for (const unit of units) {
+            const flushed = wheelRefs.current[unit]?.flush();
+            if (flushed !== undefined) {
+                final[unit] = flushed.value;
+            }
+        }
+        // 日再按当月天数保险收窄：防 2月31日 被 Date 构造器滚动成 3月3日
+        const safeDay = Math.min(final.day, dayjs(`${final.year}-${final.month}-01`).daysInMonth());
+        const result = dayjs(new Date(final.year, final.month - 1, safeDay, final.hour, final.minute, final.second)).format(resolvedFormat);
+        onChange?.(result);
+        onClose();
+    }, [units, draft, resolvedFormat, onChange, onClose]);
+    return (_jsx(XPullView, { visible: visible, onClose: onClose, side: 'bottom', duration: duration, overlayOpacity: 0.4, children: _jsxs(View, { style: [styles.panel, { paddingBottom: Math.max(insets.bottom, 10) }], children: [_jsxs(View, { style: styles.toolbar, children: [_jsx(Pressable, { onPress: onClose, hitSlop: 8, children: _jsx(Text, { style: [styles.cancelBtn, { color: t.colorTextSecondary }], children: i18n('cancel') }) }), _jsx(Text, { style: [styles.title, { color: t.colorText }], numberOfLines: 1, children: title ?? (hasDate && hasTime ? i18n('selectDateTime') : hasTime ? i18n('selectTime') : i18n('selectDate')) }), _jsx(Pressable, { onPress: handleConfirm, hitSlop: 8, children: _jsx(Text, { style: [styles.confirmBtn, { color: t.colorPrimary }], children: i18n('confirm') }) })] }), _jsx(View, { style: styles.columns, children: columns.map(({ unit, options, value: columnValue }) => (_jsx(XWheel, { ref: el => {
+                            wheelRefs.current[unit] = el;
+                        }, items: options, value: columnValue, onSelect: v => handleChange(unit, v) }, unit))) })] }) }));
+}

package/dist/XPopupProvider/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ============================================================================
+ * XPopupProvider —— 弹窗体系的"根部挂载点"
+ * ============================================================================
+ *
+ * 【为什么需要它？】
+ * 命令式弹窗（XConfirmForm/confirm）和 XTopView 宿主都需要一个"永远在场"
+ * 的渲染位置。RN 没有 React 官方的 Portal，所以用 Provider 组件把这两样
+ * 东西常驻挂载在应用根部（App.tsx 里已经接好）。
+ *
+ * 【渲染顺序 = 层级顺序】
+ *   {children}     ← 整个 App
+ *   <XConfirmForm/> ← 命令式确认框实例（内部弹层会进 XTopView）
+ *   <XTopView />    ← 所有 XPullView 弹层的最终渲染层（最后渲染 = 最上层）
+ *
+ * 注意必须放在 GestureHandlerRootView 之内（App.tsx 里就是这样），
+ * 否则手势库的触摸拦截会影响弹层内部的手势。
+ * ============================================================================
+ */
+import React from 'react';
+export declare const XPopupProvider: ({ children }: {
+    children: React.ReactNode;
+}) => React.JSX.Element;

package/dist/XPopupProvider/index.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { XConfirmForm } from '../XConfirmForm';
+import { XTopView } from '../XTopView';
+export const XPopupProvider = ({ children }) => {
+    return (_jsxs(_Fragment, { children: [children, _jsx(XConfirmForm, {}), _jsx(XTopView, {})] }));
+};

package/dist/XProgress/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ============================================================================
+ * XProgress —— 对标 antd Progress（RN 自实现版）
+ * ============================================================================
+ *
+ * 支持的 antd API：
+ * - type: 'line' | 'circle' | 'dashboard'
+ * - percent / showInfo / format(percent) 自定义文案
+ * - status: 'success' | 'exception' | 'normal' | 'active'
+ * - strokeColor: 纯色 或 {from, to} 渐变（line 用 LinearGradient，circle 用 SVG 渐变）
+ * - trailColor / strokeWidth
+ * - success: {percent, strokeColor} —— line 形态下的已完成成功段（绿色前置段）
+ * - size: circle/dashboard 的直径（antd 老 API 叫 width，这里 size 即 width）
+ *
+ * 与 antd 的差异：
+ * - status='active' 的流光动画未实现（颜色按 normal 处理），其余行为一致
+ * - percent 超过 100：进度条封顶 100%，文案显示真实值（同 antd）
+ * - circle 满进度/成功态的 ✓、异常态的 ✕ 用 SVG Path 画（几何居中），不依赖图标字体
+ */
+import React from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+export interface XProgressProps {
+    type?: 'line' | 'circle' | 'dashboard';
+    /** 0-100；超出封顶显示 */
+    percent?: number;
+    showInfo?: boolean;
+    status?: 'success' | 'exception' | 'normal' | 'active';
+    /** 纯色或渐变 {from, to} */
+    strokeColor?: string | {
+        from: string;
+        to: string;
+    };
+    trailColor?: string;
+    /** line 默认 8，circle 默认 6 */
+    strokeWidth?: number;
+    /** circle/dashboard 直径，默认 120 */
+    size?: number;
+    /** line 形态的成功段 */
+    success?: {
+        percent?: number;
+        strokeColor?: string;
+    };
+    /** 自定义文案，返回 null 可隐藏（配合 showInfo） */
+    format?: (percent?: number) => React.ReactNode;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+export declare function XProgress({ type, percent, showInfo, status, strokeColor, trailColor, strokeWidth, success, format, size, style, testID, }: XProgressProps): React.JSX.Element;
+export default XProgress;

package/dist/XProgress/index.js

@@ -0,0 +1,196 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * ============================================================================
+ * XProgress —— 对标 antd Progress（RN 自实现版）
+ * ============================================================================
+ *
+ * 支持的 antd API：
+ * - type: 'line' | 'circle' | 'dashboard'
+ * - percent / showInfo / format(percent) 自定义文案
+ * - status: 'success' | 'exception' | 'normal' | 'active'
+ * - strokeColor: 纯色 或 {from, to} 渐变（line 用 LinearGradient，circle 用 SVG 渐变）
+ * - trailColor / strokeWidth
+ * - success: {percent, strokeColor} —— line 形态下的已完成成功段（绿色前置段）
+ * - size: circle/dashboard 的直径（antd 老 API 叫 width，这里 size 即 width）
+ *
+ * 与 antd 的差异：
+ * - status='active' 的流光动画未实现（颜色按 normal 处理），其余行为一致
+ * - percent 超过 100：进度条封顶 100%，文案显示真实值（同 antd）
+ * - circle 满进度/成功态的 ✓、异常态的 ✕ 用 SVG Path 画（几何居中），不依赖图标字体
+ */
+import { useEffect, useId, useRef, useState } from 'react';
+import { Animated, StyleSheet, View, Text } from 'react-native';
+import LinearGradient from 'react-native-linear-gradient';
+import Svg, { Circle, Circle as SvgCircle, Defs, LinearGradient as SvgLinearGradient, Path, Stop } from 'react-native-svg';
+import { useXTheme, xTheme } from '../theme';
+/** 把 strokeColor 归一化成 {from, to} */
+function normalizeGradient(color) {
+    if (!color)
+        return null;
+    if (typeof color === 'string')
+        return null; // 字符串走纯色逻辑
+    return color;
+}
+/**
+ * 数字过渡动画 hook：percent 变化时从当前值平滑过渡到目标值，
+ * 每帧 setState 驱动重渲染（circle 的 strokeDashoffset 需要 JS 侧值）。
+ */
+function useAnimatedPercent(percent, animate = true) {
+    const [display, setDisplay] = useState(animate ? 0 : percent);
+    const current = useRef(display);
+    useEffect(() => {
+        if (!animate) {
+            current.current = percent;
+            setDisplay(percent);
+            return;
+        }
+        const value = new Animated.Value(current.current);
+        const listener = value.addListener(({ value: v }) => {
+            current.current = v;
+            setDisplay(v);
+        });
+        const timing = Animated.timing(value, {
+            toValue: percent,
+            duration: xTheme.motionDurationMid * 3,
+            useNativeDriver: false, // 要驱动 setState，不能走 native
+        });
+        timing.start(({ finished }) => {
+            if (finished)
+                value.removeListener(listener);
+        });
+        // 卸载时停掉动画，避免 setState after unmount
+        return () => {
+            timing.stop();
+            value.removeListener(listener);
+        };
+    }, [percent, animate]);
+    return display;
+}
+export function XProgress({ type = 'line', percent = 0, showInfo = true, status = 'normal', strokeColor, trailColor, strokeWidth, success, format, size = 120, style, testID, }) {
+    const t = useXTheme();
+    // 状态色：exception 红 / success 绿 / 其余主色（active 视同 normal）
+    const semanticColor = status === 'exception' ? t.colorError : status === 'success' ? t.colorSuccess : t.colorPrimary;
+    const gradient = normalizeGradient(strokeColor);
+    // antd 规则：渐变模式下状态色不覆盖（strokeColor 优先级高于 status）
+    const solidColor = typeof strokeColor === 'string' ? strokeColor : semanticColor;
+    const finalColor = gradient ? gradient.from : solidColor;
+    // 视觉封顶 100（文案仍显示真实值）
+    const clamped = Math.min(Math.max(percent, 0), 100);
+    const successPercent = success?.percent ? Math.min(Math.max(success.percent, 0), 100) : 0;
+    const successColor = success?.strokeColor ?? t.colorSuccess;
+    if (type === 'line') {
+        return (_jsx(XLineProgress, { percent: clamped, successPercent: successPercent, successColor: successColor, color: finalColor, gradient: gradient, trailColor: trailColor, strokeWidth: strokeWidth ?? 8, showInfo: showInfo, format: format, percentRaw: percent, status: status, style: style, testID: testID }));
+    }
+    return (_jsx(XCircleProgress, { variant: type, percent: clamped, percentRaw: percent, color: finalColor, gradient: gradient, trailColor: trailColor, strokeWidth: strokeWidth ?? 6, size: size, showInfo: showInfo, format: format, status: status, style: style, testID: testID }));
+}
+// ============================================================================
+// line 形态
+// ============================================================================
+/**
+ * 信息文案渲染：format 返回的可能是纯字符串 —— RN 里 View 的字符串子节点不渲染，
+ * 必须包一层 Text（antd 网页端没这个约束，这是 RN 适配点）。
+ */
+function renderInfo(showInfo, format, percentRaw, textStyle) {
+    if (!showInfo)
+        return null;
+    const node = format ? format(percentRaw) : `${percentRaw}%`;
+    if (node === null || node === undefined)
+        return null;
+    if (typeof node === 'string' || typeof node === 'number') {
+        return (_jsx(Text, { style: textStyle, allowFontScaling: false, children: node }));
+    }
+    return node;
+}
+function XLineProgress(props) {
+    const t = useXTheme();
+    const { percent, percentRaw, successPercent, successColor, color, gradient, trailColor, strokeWidth, showInfo, format, status, style, testID } = props;
+    const animated = useAnimatedPercent(percent);
+    /**
+     * 填充宽度 = 进度百分比。不能用 flex：轨道是 column 方向，flex 控制的是
+     * 主轴（竖向）尺寸，横向会被 stretch 撑满 —— 表现为进度条永远全宽。
+     */
+    const barStyle = { width: `${Math.max(animated, 0)}%` };
+    const info = renderInfo(showInfo, format, percentRaw, [
+        styles.lineInfo,
+        { color: t.colorTextSecondary },
+        status === 'exception' && { color: t.colorError },
+    ]);
+    return (_jsxs(View, { testID: testID, style: [styles.lineRow, style], children: [_jsx(View, { style: [
+                    styles.track,
+                    {
+                        height: strokeWidth,
+                        borderRadius: strokeWidth / 2,
+                        backgroundColor: trailColor ?? t.colorProgressTrack,
+                    },
+                ], children: _jsxs(View, { style: [styles.lineFill, { flexDirection: 'row' }, barStyle], children: [successPercent > 0 && _jsx(View, { style: { flex: successPercent, backgroundColor: successColor } }), gradient ? (_jsx(LinearGradient, { colors: [gradient.from, gradient.to], start: { x: 0, y: 0 }, end: { x: 1, y: 0 }, style: { flex: Math.max(animated - successPercent, 0) } })) : (_jsx(View, { style: { flex: Math.max(animated - successPercent, 0), backgroundColor: color } }))] }) }), info] }));
+}
+function XCircleProgress(props) {
+    const t = useXTheme();
+    const { variant, percent, percentRaw, color, gradient, trailColor, strokeWidth, size, showInfo, format, status, style, testID } = props;
+    const animated = useAnimatedPercent(percent);
+    const gradientId = `xprog-${useId().replace(/[^a-zA-Z0-9-]/g, '')}`;
+    // dashboard：上下各留 45° 缺口（antd gapDegree=75 的视觉近似值，取 45° 更圆润）
+    const totalAngle = variant === 'dashboard' ? 270 : 360;
+    const r = (size - strokeWidth) / 2;
+    const c = 2 * Math.PI * r;
+    // 参与弧长的周长比例（dashboard 只画 270°）
+    const arcLength = (c * totalAngle) / 360;
+    /**
+     * 进度弧 = 可见弧长 + 空白补齐。不能用"全长 dash + offset 回退"的画法：
+     * 360° 圆的 gap 为 0，图案退化为连续线，offset 失效 —— 表现为圆环永远满圈。
+     */
+    const visibleArc = arcLength * (Math.min(Math.max(animated, 0), 100) / 100);
+    const strokeDasharray = `${visibleArc} ${c - visibleArc}`;
+    // SVG Circle 的 dash 起点在 3 点钟；circle：-90° 把起点挪到 12 点；dashboard：135° 起点在 7:30
+    // 注意：react-native-svg 的 transform 用字符串形式（对象形式支持不完整）
+    const transform = `rotate(${variant === 'dashboard' ? 135 : -90}, ${size / 2}, ${size / 2})`;
+    // 满圈/成功 → ✓；异常 → ✕（antd 同款行为；SVG Path 绘制，几何上绝对居中）
+    const showDone = status === 'success' || (percent >= 100 && status !== 'exception');
+    const showException = status === 'exception';
+    const badgeColor = showDone ? t.colorSuccess : t.colorError;
+    return (_jsxs(View, { testID: testID, style: [{ width: size, height: size, alignItems: 'center', justifyContent: 'center' }, style], children: [_jsxs(Svg, { width: size, height: size, children: [_jsx(Defs, { children: gradient && (_jsxs(SvgLinearGradient, { id: gradientId, x1: '0%', y1: '0%', x2: '100%', y2: '100%', children: [_jsx(Stop, { offset: '0%', stopColor: gradient.from }), _jsx(Stop, { offset: '100%', stopColor: gradient.to })] })) }), _jsx(Circle, { cx: size / 2, cy: size / 2, r: r, stroke: trailColor ?? t.colorProgressTrack, strokeWidth: strokeWidth, fill: 'none', strokeDasharray: `${arcLength} ${c - arcLength}`, transform: transform }), _jsx(Circle, { cx: size / 2, cy: size / 2, r: r, stroke: gradient ? `url(#${gradientId})` : color, strokeWidth: strokeWidth, fill: 'none', strokeLinecap: 'round', strokeDasharray: strokeDasharray, transform: transform })] }), showInfo && (_jsx(View, { style: styles.infoOverlay, pointerEvents: 'none', children: showDone ? (_jsxs(Svg, { width: 40, height: 40, viewBox: '0 0 40 40', children: [_jsx(SvgCircle, { cx: 20, cy: 20, r: 17.5, stroke: badgeColor, strokeWidth: 2.5, fill: 'none' }), _jsx(Path, { d: 'M12.5 20.5 L17.5 25.5 L27 13.5', stroke: badgeColor, strokeWidth: 3, fill: 'none', strokeLinecap: 'round', strokeLinejoin: 'round' })] })) : showException ? (_jsxs(Svg, { width: 40, height: 40, viewBox: '0 0 40 40', children: [_jsx(SvgCircle, { cx: 20, cy: 20, r: 17.5, stroke: badgeColor, strokeWidth: 2.5, fill: 'none' }), _jsx(Path, { d: 'M14.5 14.5 L25.5 25.5 M25.5 14.5 L14.5 25.5', stroke: badgeColor, strokeWidth: 3, fill: 'none', strokeLinecap: 'round' })] })) : (_jsx(View, { style: styles.circleInfo, children: renderInfo(true, format, percentRaw, [styles.circleInfoText, { color: t.colorText }]) })) }))] }));
+}
+const styles = StyleSheet.create({
+    lineRow: {
+        flexDirection: 'row',
+        alignItems: 'center',
+        width: '100%',
+    },
+    track: {
+        flex: 1,
+        overflow: 'hidden',
+        flexDirection: 'row',
+    },
+    lineFill: {
+        flexDirection: 'row',
+        borderRadius: 999,
+        overflow: 'hidden',
+    },
+    lineInfo: {
+        fontSize: xTheme.fontSize,
+        marginLeft: 8,
+        minWidth: 40,
+        textAlign: 'right',
+    },
+    /**
+     * 信息浮层：absoluteFillObject 定位到圆心区域 + 双轴居中。
+     * 注意不能只用 StyleSheet.absoluteFill：绝对定位的子元素不参与父级
+     * alignItems/justifyContent 布局（Yoga 行为），必须自己声明居中，
+     * 否则 SVG 图标会缩在左上角。
+     */
+    infoOverlay: {
+        ...{ position: "absolute", top: 0, left: 0, right: 0, bottom: 0 },
+        alignItems: 'center',
+        justifyContent: 'center',
+    },
+    circleInfo: {
+        flex: 1,
+        alignItems: 'center',
+        justifyContent: 'center',
+    },
+    circleInfoText: {
+        fontSize: xTheme.fontSizeLG,
+        fontWeight: '600',
+    },
+});
+export default XProgress;

package/dist/XProviders/XImagePreview/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ============================================================================
+ * XImagePreview —— 命令式图片预览（X 系列，复刻自 components/ImagePreview）
+ * ============================================================================
+ *
+ * 由四部分组成（单文件聚合，避免目录过碎）：
+ * - XGalleryImage          单图渲染（fitContainer 适配屏幕）
+ * - XImagePreview          预览 UI（Gallery 翻页 + 页码 + 关闭按钮）
+ * - XImagePreviewProvider  状态宿主，App 根部挂载一次
+ * - XImagePreviewService   命令式入口，任意地方调用
+ *
+ * 用法：
+ *   XImagePreviewService.show({images: urls, initialIndex: 0});
+ *   XImagePreviewService.hide();
+ *
+ * 实现要点：
+ * - 全局句柄 useEffect 注册/清理（无 render 副作用）；
+ * - 关闭时清空 images，及时释放大图列表引用；
+ * - DEV 环境未挂载时给出 console.warn；
+ * - Modal 使用 transparent + fade，浮在原页面上（系统相册同款观感）；
+ * - GestureHandlerRootView 是 react-native-zoom-toolkit 手势正常工作的必要包裹。
+ */
+import React, { type ReactNode } from 'react';
+export interface XImagePreviewParams {
+    images: string[];
+    initialIndex?: number;
+}
+interface XImagePreviewProps {
+    initialIndex?: number;
+    imageList: string[];
+    onClose?: () => void;
+}
+export declare const XImagePreview: ({ initialIndex, imageList, onClose }: XImagePreviewProps) => React.JSX.Element;
+export declare const XImagePreviewProvider: ({ children }: {
+    children: ReactNode;
+}) => React.JSX.Element;
+/**
+ * XImagePreviewService —— 命令式调用入口（可在组件外使用）
+ */
+export declare const XImagePreviewService: {
+    show: (params: XImagePreviewParams) => void;
+    hide: () => void;
+};
+export {};