react-native-x-components 0.1.0

package/dist/XSignature/index.js

@@ -0,0 +1,88 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * ============================================================================
+ * XSignature —— 普通签名（单画布连笔，非逐字）
+ * ============================================================================
+ *
+ * 【与 XSignatureSkia 的分工】
+ * - XSignatureSkia：逐字签名（一字一格、可单字重写、结构化 value）；
+ * - XSignature：普通连笔签名（一块白纸写到底），适合"签个名确认"场景；
+ * 两者共用 ./core.tsx 的采集/贝塞尔/渲染内核。
+ *
+ * 【API】
+ *   <XSignature height={200} onExport={base64 => upload(base64)} />
+ * 内置 撤销/清空/完成 三个动作按钮（XButton + theme + i18n）。
+ * ============================================================================
+ */
+import { useCallback, useState } from 'react';
+import { ImageFormat, useCanvasRef } from '@shopify/react-native-skia';
+import { StyleSheet, Text, View } from 'react-native';
+import Svg, { Line } from 'react-native-svg';
+import { XButton } from '../XButton';
+import { useXTheme } from '../theme';
+import { useXLocale } from '../XLocale';
+import { SignatureCanvas } from './core';
+export function XSignature({ height = 200, strokeColor = '#111111', strokeWidth = 4, onExport, onStrokeEnd, disabled = false, style, }) {
+    const t = useXTheme();
+    const { t: i18n } = useXLocale();
+    const canvasRef = useCanvasRef();
+    const [size, setSize] = useState({ width: 0, height: 0 });
+    /** 已提交笔画 */
+    const [strokes, setStrokes] = useState([]);
+    /** 一笔画完 */
+    const handleStrokeComplete = useCallback((points, strokeSize) => {
+        setStrokes(prev => {
+            const next = [
+                ...prev,
+                {
+                    id: `${Date.now()}-${prev.length}`,
+                    color: strokeColor,
+                    width: strokeWidth,
+                    points,
+                    size: strokeSize,
+                },
+            ];
+            onStrokeEnd?.(next.length);
+            return next;
+        });
+    }, [strokeColor, strokeWidth, onStrokeEnd]);
+    /** 撤销最后一笔 */
+    const handleUndo = useCallback(() => setStrokes(prev => prev.slice(0, -1)), []);
+    /** 清空 */
+    const handleClear = useCallback(() => setStrokes([]), []);
+    /** 完成：截图导出（无笔画时不上抛） */
+    const handleDone = useCallback(async () => {
+        if (!strokes.length)
+            return;
+        await new Promise(resolve => setTimeout(resolve, 50));
+        const image = canvasRef.current?.makeImageSnapshot();
+        if (image)
+            onExport?.(image.encodeToBase64(ImageFormat.PNG));
+    }, [strokes.length, canvasRef, onExport]);
+    return (_jsxs(View, { style: [styles.container, style], children: [_jsxs(View, { style: [styles.paper, { height, borderColor: t.colorBorder, borderRadius: t.borderRadiusXL }], children: [_jsx(SignatureCanvas, { strokes: strokes, touchEnabled: !disabled, strokeColor: strokeColor, strokeWidth: strokeWidth, onStrokeComplete: handleStrokeComplete, onLayoutSize: setSize, canvasRef: canvasRef }), size.width > 0 && (_jsxs(Svg, { pointerEvents: 'none', width: size.width, height: size.height, style: styles.grid, children: [_jsx(Line, { x1: '0%', y1: '50%', x2: '100%', y2: '50%', stroke: t.colorSplit, strokeWidth: '1', strokeDasharray: [4, 4] }), _jsx(Line, { x1: '50%', y1: '0%', x2: '50%', y2: '100%', stroke: t.colorSplit, strokeWidth: '1', strokeDasharray: [4, 4] })] })), strokes.length === 0 && (_jsx(Text, { pointerEvents: 'none', style: [styles.placeholder, { color: t.colorTextTertiary }], children: i18n('signHint') }))] }), _jsxs(View, { style: styles.actions, children: [_jsx(XButton, { size: 'small', onPress: handleUndo, disabled: disabled || !strokes.length, children: i18n('undo') }), _jsx(XButton, { size: 'small', danger: true, type: 'text', onPress: handleClear, disabled: disabled || !strokes.length, children: i18n('clear') }), _jsx(XButton, { size: 'small', type: 'primary', onPress: handleDone, disabled: disabled || !strokes.length, children: i18n('done') })] })] }));
+}
+const styles = StyleSheet.create({
+    container: {
+        gap: 8,
+    },
+    paper: {
+        overflow: 'hidden',
+        borderWidth: StyleSheet.hairlineWidth,
+    },
+    grid: {
+        position: 'absolute',
+        top: 0,
+        left: 0,
+    },
+    placeholder: {
+        position: 'absolute',
+        alignSelf: 'center',
+        fontSize: 13,
+    },
+    actions: {
+        flexDirection: 'row',
+        justifyContent: 'flex-end',
+        gap: 8,
+    },
+});
+export default XSignature;

package/dist/XTabs/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * ============================================================================
+ * XTabs —— 选项卡（duxui Tab 的 RN 原生重写版）
+ * ============================================================================
+ *
+ * 【与 duxui Tab 的关系】
+ * 保留 duxui 的核心 API：type('line'|'button') / swiper（内容滑动联动）/
+ * lazyload / scroll / justify / TabPane 子组件声明式用法。
+ * 差异：duxui 的下划线与内容联动跑在 Taro Animated（CSS）上，
+ * 这里用 Reanimated shared value（UI 线程）+ 原生 ScrollView。
+ *
+ * 【用法】
+ *   <XTabs onChange={...}>
+ *     <XTabPane title="标签一" key="a">内容一</XTabPane>
+ *     <XTabPane title="标签二" key="b" badge={3}>内容二</XTabPane>
+ *   </XTabs>
+ *
+ * 【实现要点】
+ * 1. tab 头：项数 > 4 默认横向滚动（scroll 可显式覆盖），每项 onLayout
+ *    记录 x/width，下划线用 withTiming 平移 + 变宽（线型）；
+ * 2. 内容区：swiper 模式 = ScrollView pagingEnabled，滑动结束反向同步
+ *    激活项；非 swiper = 只挂载当前激活页（天然懒加载）；
+ * 3. lazyload 仅对 swiper 模式有意义：激活过才渲染内容，渲染后保持挂载
+ *    （保留滚动位置），未访问的页渲染占位。
+ * ============================================================================
+ */
+import React from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+/** 单个选项卡 */
+export interface XTabPaneProps {
+    /** 标签文字（或任意节点） */
+    title?: React.ReactNode;
+    /** 徽标：数字/文字/true(红点) */
+    badge?: string | number | boolean;
+    /** 是否禁用 */
+    disabled?: boolean;
+    children?: React.ReactNode;
+}
+/** XTabPane 是声明式占位组件：内容由 XTabs 通过 element.props 提取，自身不渲染 */
+export declare function XTabPane(_: XTabPaneProps): null;
+export interface XTabsProps {
+    /** 受控激活 key */
+    value?: string;
+    /** 非受控初始 key（默认第一个 TabPane 的 key） */
+    defaultValue?: string;
+    /** 激活变化回调 */
+    onChange?: (key: string, index: number) => void;
+    /** line=下划线 / button=分段按钮，默认 line */
+    type?: 'line' | 'button';
+    /** 内容区是否可滑动（ScrollView 分页联动），默认 false */
+    swiper?: boolean;
+    /** tab 头是否可横向滚动，默认：项数 > 4 时可滚动 */
+    scroll?: boolean;
+    /** swiper 模式下：激活过才渲染内容（保留已渲染），默认 true */
+    lazyload?: boolean;
+    /** tab 头均分宽度（不可滚动时有效），默认 false */
+    justify?: boolean;
+    /** 激活项右下角文字色跟随主色之外的自定义色（少量场景用） */
+    activeColor?: string;
+    style?: StyleProp<ViewStyle>;
+    tabBarStyle?: StyleProp<ViewStyle>;
+    children?: React.ReactNode;
+}
+export declare function XTabs({ value, defaultValue, onChange, type, swiper, scroll, lazyload, justify, activeColor, style, tabBarStyle, children, }: XTabsProps): React.JSX.Element;
+export default XTabs;

package/dist/XTabs/index.js

@@ -0,0 +1,210 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * ============================================================================
+ * XTabs —— 选项卡（duxui Tab 的 RN 原生重写版）
+ * ============================================================================
+ *
+ * 【与 duxui Tab 的关系】
+ * 保留 duxui 的核心 API：type('line'|'button') / swiper（内容滑动联动）/
+ * lazyload / scroll / justify / TabPane 子组件声明式用法。
+ * 差异：duxui 的下划线与内容联动跑在 Taro Animated（CSS）上，
+ * 这里用 Reanimated shared value（UI 线程）+ 原生 ScrollView。
+ *
+ * 【用法】
+ *   <XTabs onChange={...}>
+ *     <XTabPane title="标签一" key="a">内容一</XTabPane>
+ *     <XTabPane title="标签二" key="b" badge={3}>内容二</XTabPane>
+ *   </XTabs>
+ *
+ * 【实现要点】
+ * 1. tab 头：项数 > 4 默认横向滚动（scroll 可显式覆盖），每项 onLayout
+ *    记录 x/width，下划线用 withTiming 平移 + 变宽（线型）；
+ * 2. 内容区：swiper 模式 = ScrollView pagingEnabled，滑动结束反向同步
+ *    激活项；非 swiper = 只挂载当前激活页（天然懒加载）；
+ * 3. lazyload 仅对 swiper 模式有意义：激活过才渲染内容，渲染后保持挂载
+ *    （保留滚动位置），未访问的页渲染占位。
+ * ============================================================================
+ */
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Pressable, ScrollView, StyleSheet, Text, View, } from 'react-native';
+import Animated, { useAnimatedStyle, useSharedValue, withTiming } from 'react-native-reanimated';
+import { useXTheme } from '../theme';
+/** XTabPane 是声明式占位组件：内容由 XTabs 通过 element.props 提取，自身不渲染 */
+export function XTabPane(_) {
+    return null;
+}
+export function XTabs({ value, defaultValue, onChange, type = 'line', swiper = false, scroll, lazyload = true, justify = false, activeColor, style, tabBarStyle, children, }) {
+    const t = useXTheme();
+    /** 解析 TabPane 子元素 → 数据化 panes（key 取 React key） */
+    const panes = useMemo(() => React.Children.toArray(children)
+        .filter(React.isValidElement)
+        .map(el => {
+        const props = el.props;
+        return {
+            key: String(el.key),
+            title: props.title,
+            badge: props.badge,
+            disabled: props.disabled,
+            content: props.children,
+        };
+    }), [children]);
+    const isControlled = value !== undefined;
+    const [inner, setInner] = useState(() => defaultValue ?? panes[0]?.key);
+    const activeKey = isControlled ? value : inner;
+    const activeIndex = Math.max(0, panes.findIndex(p => p.key === activeKey));
+    const setActive = useCallback((key, index) => {
+        if (!isControlled)
+            setInner(key);
+        onChange?.(key, index);
+    }, [isControlled, onChange]);
+    /** tab 头是否滚动：项数 > 4 默认开 */
+    const scrollable = scroll ?? panes.length > 4;
+    // ---------------------------------------------------------------------------
+    // 下划线（line 类型）：激活项 onLayout 测量 → shared value 平移/变宽
+    // ---------------------------------------------------------------------------
+    const tabLayoutsRef = useRef({});
+    const lineX = useSharedValue(0);
+    const lineW = useSharedValue(0);
+    useEffect(() => {
+        const layout = tabLayoutsRef.current[activeIndex];
+        if (!layout)
+            return;
+        const duration = t.motionDurationMid;
+        lineX.value = withTiming(layout.x, { duration });
+        lineW.value = withTiming(layout.width, { duration });
+    }, [activeIndex, panes.length, lineX, lineW, t.motionDurationMid]);
+    const lineAnimatedStyle = useAnimatedStyle(() => ({
+        transform: [{ translateX: lineX.value }],
+        width: lineW.value,
+    }));
+    // ---------------------------------------------------------------------------
+    // swiper 内容联动：外部激活 → scrollTo；滑动结束 → 反向激活
+    // ---------------------------------------------------------------------------
+    const contentRef = useRef(null);
+    const [contentWidth, setContentWidth] = useState(0);
+    /** 记录"由滑动触发的激活"，避免 scrollTo 循环 */
+    const swipingRef = useRef(false);
+    useEffect(() => {
+        if (!swiper || contentWidth <= 0)
+            return;
+        contentRef.current?.scrollTo({ x: activeIndex * contentWidth, animated: false });
+        // activeIndex 变化统一同步（滑动手势结束 setState 后也会走到这里，
+        // 位置已在松手处，scrollTo 同值无副作用）
+    }, [activeIndex, swiper, contentWidth]);
+    const handleContentMomentumEnd = useCallback((e) => {
+        const index = Math.round(e.nativeEvent.contentOffset.x / contentWidth);
+        const pane = panes[Math.min(Math.max(index, 0), panes.length - 1)];
+        if (pane && pane.key !== activeKey) {
+            swipingRef.current = true;
+            setActive(pane.key, panes.indexOf(pane));
+        }
+    }, [contentWidth, panes, activeKey, setActive]);
+    /** swiper 模式已访问页（lazyload） */
+    const [visited, setVisited] = useState(() => new Set([activeIndex]));
+    useEffect(() => {
+        setVisited(prev => (prev.has(activeIndex) ? prev : new Set(prev).add(activeIndex)));
+    }, [activeIndex]);
+    /** 渲染单个 tab 头 */
+    const renderTab = (pane, index) => {
+        const active = index === activeIndex;
+        const disabled = pane.disabled;
+        const press = () => !disabled && setActive(pane.key, index);
+        if (type === 'button') {
+            // 分段按钮：灰轨道 + 激活白底胶囊（暗黑下轨道黑、胶囊灰，由 token 自适应）
+            return (_jsx(Pressable, { onPress: press, onLayout: e => {
+                    tabLayoutsRef.current[index] = { x: e.nativeEvent.layout.x, width: e.nativeEvent.layout.width };
+                }, style: [styles.buttonTab, justify && !scrollable && styles.flex1], children: _jsx(View, { style: [styles.buttonPill, active && { backgroundColor: t.colorBgContainer }], children: _jsx(TabTitle, { pane: pane, active: active, color: active ? t.colorPrimary : t.colorTextSecondary }) }) }, pane.key));
+        }
+        // line 类型
+        return (_jsx(Pressable, { onPress: press, onLayout: e => {
+                tabLayoutsRef.current[index] = { x: e.nativeEvent.layout.x, width: e.nativeEvent.layout.width };
+            }, style: [styles.lineTab, justify && !scrollable && styles.flex1, disabled && styles.disabled], children: _jsx(TabTitle, { pane: pane, active: active, color: disabled ? t.colorTextQuaternary : active ? activeColor ?? t.colorPrimary : t.colorText }) }, pane.key));
+    };
+    const tabBar = (_jsxs(View, { style: [
+            styles.tabBar,
+            type === 'button' && { backgroundColor: t.colorBgLayout, borderRadius: t.borderRadius, padding: 2 },
+            !scrollable && { flexDirection: 'row' },
+            tabBarStyle,
+        ], children: [scrollable ? (_jsx(ScrollView, { horizontal: true, showsHorizontalScrollIndicator: false, contentContainerStyle: styles.scrollContent, children: panes.map(renderTab) })) : (panes.map(renderTab)), type === 'line' && (_jsx(Animated.View, { style: [styles.lineIndicator, { backgroundColor: activeColor ?? t.colorPrimary }, lineAnimatedStyle], pointerEvents: 'none' }))] }));
+    return (_jsxs(View, { style: style, children: [tabBar, swiper ? (_jsx(View, { onLayout: e => setContentWidth(e.nativeEvent.layout.width), style: styles.content, children: contentWidth > 0 && (_jsx(ScrollView, { ref: contentRef, horizontal: true, pagingEnabled: true, showsHorizontalScrollIndicator: false, scrollEventThrottle: 16, onMomentumScrollEnd: handleContentMomentumEnd, children: panes.map((pane, index) => (_jsx(View, { style: { width: contentWidth }, children: lazyload && !visited.has(index) ? (_jsx(View, { style: styles.lazyPlaceholder })) : (pane.content) }, pane.key))) })) })) : (_jsx(View, { style: styles.content, children: panes[activeIndex]?.content }))] }));
+}
+/** tab 标题 + 徽标 */
+function TabTitle({ pane, active, color }) {
+    const t = useXTheme();
+    return (_jsxs(View, { style: styles.titleRow, children: [typeof pane.title === 'string' ? (_jsx(Text, { style: [styles.titleText, { color }, active && styles.titleActive], numberOfLines: 1, children: pane.title })) : (pane.title), pane.badge != null && pane.badge !== false && (_jsx(View, { style: [
+                    styles.badge,
+                    pane.badge === true
+                        ? { width: 6, height: 6, borderRadius: 3, backgroundColor: t.colorError }
+                        : { backgroundColor: t.colorError },
+                ], children: typeof pane.badge === 'string' || typeof pane.badge === 'number' ? (_jsx(Text, { style: styles.badgeText, allowFontScaling: false, children: pane.badge })) : null }))] }));
+}
+const styles = StyleSheet.create({
+    tabBar: {
+        position: 'relative',
+    },
+    scrollContent: {
+        paddingRight: 8,
+    },
+    lineTab: {
+        paddingHorizontal: 16,
+        height: 44,
+        justifyContent: 'center',
+        alignItems: 'center',
+    },
+    buttonTab: {
+        paddingHorizontal: 4,
+        paddingVertical: 2,
+    },
+    flex1: {
+        flex: 1,
+    },
+    titleRow: {
+        flexDirection: 'row',
+        alignItems: 'center',
+    },
+    titleText: {
+        fontSize: 15,
+    },
+    titleActive: {
+        fontWeight: '600',
+    },
+    badge: {
+        marginLeft: 4,
+        minWidth: 16,
+        height: 16,
+        borderRadius: 8,
+        paddingHorizontal: 4,
+        alignItems: 'center',
+        justifyContent: 'center',
+        overflow: 'hidden',
+    },
+    badgeText: {
+        color: '#fff',
+        fontSize: 10,
+        lineHeight: 12,
+    },
+    lineIndicator: {
+        position: 'absolute',
+        bottom: 0,
+        left: 0,
+        height: 2,
+        borderRadius: 1,
+    },
+    buttonPill: {
+        height: 32,
+        borderRadius: 6,
+        paddingHorizontal: 14,
+        alignItems: 'center',
+        justifyContent: 'center',
+    },
+    content: {
+        overflow: 'hidden',
+    },
+    lazyPlaceholder: {
+        height: 100,
+    },
+    disabled: {
+        opacity: 0.5,
+    },
+});
+export default XTabs;

package/dist/XTag/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * ============================================================================
+ * XTag —— 对标 antd Tag（RN 自实现版），由老 components/Tag 复刻并增强
+ * ============================================================================
+ *
+ * 支持的 antd Tag API：
+ * - color: 预设色名（success/processing/error/warning/default + magenta/red/... 12 种）
+ *          或自定义色值（'#f50' / '#0f0'），自动派生文字/背景/描边
+ * - variant: light（antd 默认浅底彩字）| solid（实底白字，老 Tag 视觉）| outline（描边）
+ * - closable + onClose: 可关闭小叉号（带 hitSlop，方便点按）
+ * - icon: 前置图标节点
+ * - bordered: 描边开关（light/outline 下生效，默认 true）
+ * - onPress: 整体可点（按压有透明度反馈）
+ * - children: 自定义内容（文本外的节点也行）
+ *
+ * 兼容老 Tag API（零成本迁移）：
+ * - text / size(small|medium|large) / type(info|primary|success|warning|error|default)
+ * - 注意：老 Tag 是实底白字，迁移时加 variant='solid' 可保持视觉不变；
+ *   XTag 默认 light 是为了对齐 antd 默认观感
+ *
+ * 与 antd 的差异（RN 环境限制或有意取舍）：
+ * - antd 无 size，RN 下保留老 Tag 的三档尺寸（字号 12/14/16）
+ * - 不支持 'xxx-inverse' 色名写法，反色诉求直接用 variant='solid'
+ * - 无 hover 态，按压反馈统一用透明度变化
+ */
+import React from 'react';
+import { TextStyle, ViewStyle, StyleProp } from 'react-native';
+export type XTagType = 'info' | 'primary' | 'success' | 'warning' | 'error' | 'default';
+export type XTagSize = 'small' | 'medium' | 'large';
+export type XTagVariant = 'light' | 'solid' | 'outline';
+export interface XTagProps {
+    /** 标签文本（兼容老 Tag；与 children 二选一，children 优先级更高） */
+    text?: string;
+    /** 语义类型（兼容老 Tag），会被 color 覆盖 */
+    type?: XTagType;
+    /** 尺寸（老 Tag 三档，antd 没有） */
+    size?: XTagSize;
+    /** 预设色名或自定义色值，优先级高于 type */
+    color?: string;
+    /** 视觉变体：light=浅底彩字（默认，antd 观感）/ solid=实底白字 / outline=描边 */
+    variant?: XTagVariant;
+    /** 是否带描边（light/outline 下生效），默认 true */
+    bordered?: boolean;
+    /** 胶囊圆角（shape='round' 时圆角取高度的一半） */
+    shape?: 'default' | 'round';
+    /** 前置图标节点 */
+    icon?: React.ReactNode;
+    /** 是否显示关闭叉号 */
+    closable?: boolean;
+    /** 关闭回调（e.preventDefault 风格不适用 RN，返回 false 不阻止隐藏，组件本身受控不隐藏） */
+    onClose?: (e: any) => void;
+    /** 整体点击 */
+    onPress?: () => void;
+    /** 自定义内容（优先级高于 text） */
+    children?: React.ReactNode;
+    style?: StyleProp<ViewStyle>;
+    textStyle?: StyleProp<TextStyle>;
+    testID?: string;
+}
+export declare function XTag({ text, type, size, color, variant, bordered, shape, icon, closable, onClose, onPress, children, style, textStyle, testID, }: XTagProps): React.JSX.Element | null;
+export default XTag;

package/dist/XTag/index.js

@@ -0,0 +1,153 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+import AntDesign from '@react-native-vector-icons/ant-design';
+import { useXTheme, xTheme } from '../theme';
+/** antd Tag 十二预设色（文档色板，magenta ~ purple） */
+const PRESET_COLORS = {
+    magenta: '#EB2F96',
+    red: '#F5222D',
+    volcano: '#FA541C',
+    orange: '#FA8C16',
+    gold: '#FAAD14',
+    lime: '#A0D911',
+    green: '#52C41A',
+    cyan: '#13C2C2',
+    blue: '#1677FF',
+    geekblue: '#2F54EB',
+    purple: '#722ED1',
+};
+/** 语义色（状态色名 + type 统一走这张表，值取当前主题 token） */
+function getSemanticColors(t) {
+    return {
+        primary: { solid: t.colorPrimary, lightBg: t.colorPrimaryBg },
+        info: { solid: t.colorPrimary, lightBg: t.colorPrimaryBg },
+        success: { solid: t.colorSuccess, lightBg: t.colorSuccessBg },
+        warning: { solid: t.colorWarning, lightBg: t.colorWarningBg },
+        error: { solid: t.colorError, lightBg: t.colorErrorBg },
+        processing: { solid: t.colorPrimary, lightBg: t.colorPrimaryBg },
+    };
+}
+/** '#f50' / '#0f0' / '#rrggbbaa' -> rgba(alpha)，用于浅底/描边派生色 */
+function withAlpha(color, alpha) {
+    if (!color.startsWith('#')) {
+        return color;
+    }
+    let hex = color.slice(1);
+    if (hex.length === 3) {
+        hex = hex
+            .split('')
+            .map(c => c + c)
+            .join('');
+    }
+    if (hex.length === 8) {
+        hex = hex.slice(0, 6);
+    }
+    const r = parseInt(hex.slice(0, 2), 16);
+    const g = parseInt(hex.slice(2, 4), 16);
+    const b = parseInt(hex.slice(4, 6), 16);
+    return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}
+/** color / type 解析成基准色（solid 色 + 浅底色），default 为灰色系 */
+function resolvePalette(t, color, type = 'default') {
+    const SEMANTIC_COLORS = getSemanticColors(t);
+    // 1. 状态色名（antd 文档的 success/processing/...）
+    const semantic = color ? SEMANTIC_COLORS[color] : undefined;
+    if (semantic) {
+        return { solid: semantic.solid, lightBg: semantic.lightBg, isDefault: false };
+    }
+    // 2. 预设色名（magenta / purple / ...）
+    const preset = color ? PRESET_COLORS[color] : undefined;
+    if (preset) {
+        return { solid: preset, lightBg: withAlpha(preset, 0.12), isDefault: false };
+    }
+    // 3. 自定义色值（# 开头）
+    if (color && color.startsWith('#')) {
+        return { solid: color, lightBg: withAlpha(color, 0.12), isDefault: false };
+    }
+    // 4. type 语义（兼容老 Tag；default 走灰系）
+    const byType = SEMANTIC_COLORS[type];
+    if (byType) {
+        return { solid: byType.solid, lightBg: byType.lightBg, isDefault: false };
+    }
+    return { solid: t.colorTextSecondary, lightBg: t.colorBgContainerDisabled, isDefault: true };
+}
+const SIZE_STYLES = {
+    small: { fontSize: xTheme.fontSizeSM, paddingH: 6, paddingV: 1, radius: xTheme.borderRadiusSM, iconSize: 10 },
+    medium: { fontSize: xTheme.fontSize, paddingH: 8, paddingV: 2, radius: xTheme.borderRadiusSM, iconSize: 12 },
+    large: { fontSize: xTheme.fontSizeLG, paddingH: 10, paddingV: 4, radius: xTheme.borderRadius, iconSize: 14 },
+};
+export function XTag({ text, type = 'default', size = 'medium', color, variant = 'light', bordered = true, shape = 'default', icon, closable = false, onClose, onPress, children, style, textStyle, testID, }) {
+    const t = useXTheme();
+    const sizeStyle = SIZE_STYLES[size];
+    const palette = resolvePalette(t, color, type);
+    const content = children ?? text;
+    // 老组件行为：无文本不渲染（这里放宽为 icon/children 也算内容）
+    if (content === undefined || content === null || content === '') {
+        if (!icon) {
+            return null;
+        }
+    }
+    // --- 按 variant 派生背景 / 文字 / 描边 ---
+    let backgroundColor = 'transparent';
+    let textColor = palette.solid;
+    let borderColor = 'transparent';
+    let borderWidth = 0;
+    if (variant === 'solid') {
+        backgroundColor = palette.solid;
+        textColor = palette.isDefault ? t.colorText : t.colorTextLightSolid;
+    }
+    else if (variant === 'outline') {
+        borderColor = bordered ? palette.solid : 'transparent';
+        borderWidth = bordered ? 1 : 0;
+    }
+    else {
+        // light（默认）
+        backgroundColor = palette.lightBg;
+        borderColor = bordered ? withAlpha(palette.solid, 0.3) : 'transparent';
+        borderWidth = bordered ? 1 : 0;
+    }
+    const borderRadius = shape === 'round'
+        ? sizeStyle.fontSize / 2 + sizeStyle.paddingV + (variant === 'solid' ? 0 : borderWidth) // 近似胶囊
+        : sizeStyle.radius;
+    const containerStyle = [
+        styles.base,
+        {
+            backgroundColor,
+            borderColor,
+            borderWidth,
+            borderRadius,
+            paddingHorizontal: sizeStyle.paddingH,
+            paddingVertical: sizeStyle.paddingV,
+        },
+        style,
+    ];
+    const label = (_jsxs(View, { style: styles.content, children: [icon, _jsx(Text, { style: [{ fontSize: sizeStyle.fontSize, color: textColor, fontWeight: '500' }, textStyle], children: content })] }));
+    const body = closable ? (_jsxs(View, { style: styles.content, children: [label, _jsx(Pressable, { hitSlop: { top: 6, right: 6, bottom: 6, left: 6 }, onPress: e => onClose?.(e), style: ({ pressed }) => [styles.close, pressed && styles.closePressed], children: _jsx(AntDesign, { name: 'close', size: sizeStyle.iconSize, color: textColor }) })] })) : (label);
+    if (onPress) {
+        return (_jsx(Pressable, { testID: testID, onPress: onPress, style: ({ pressed }) => [containerStyle, pressed && styles.pressed], children: body }));
+    }
+    return (_jsx(View, { testID: testID, style: containerStyle, children: body }));
+}
+const styles = StyleSheet.create({
+    base: {
+        alignSelf: 'flex-start',
+        justifyContent: 'center',
+        alignItems: 'center',
+    },
+    content: {
+        flexDirection: 'row',
+        alignItems: 'center',
+        gap: 4,
+    },
+    close: {
+        justifyContent: 'center',
+        alignItems: 'center',
+    },
+    closePressed: {
+        opacity: 0.5,
+    },
+    pressed: {
+        opacity: 0.75,
+    },
+});
+export default XTag;

package/dist/XTopView/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ============================================================================
+ * XTopView —— 全局弹窗宿主渲染器
+ * ============================================================================
+ *
+ * 【它是谁？】
+ * 由 <XPopupProvider /> 挂在应用根部（App.tsx 里），读取 XTopViewStore 中的
+ * items，把每个弹窗渲染成一层"全屏透明的 View"。
+ *
+ * 【层级结构】
+ *   XPopupProvider
+ *   ├── children（整个 App：NavigationContainer 等）
+ *   ├── <XConfirmForm />   （命令式确认框的常驻实例，它内部也是走 XPullView→XTopView）
+ *   └── <XTopView />       ← 所有弹窗最终都画到这里，天然在所有页面之上
+ *
+ * 【关键细节】
+ * 1. StyleSheet.absoluteFill：撑满整个屏幕，配合 box-none 不拦截触摸，
+ *    触摸由弹层内部自己的遮罩/面板处理；
+ * 2. 每个弹窗包一层 View 是为了隔离——后挂载的弹窗盖住先挂载的；
+ * 3. key 用 item.key 而不是 index，保证 update 时 React 能正确复用
+ *    同一个组件实例（否则动画状态会被重置）。
+ * ============================================================================
+ */
+import React from 'react';
+export declare const XTopView: () => React.JSX.Element;

package/dist/XTopView/index.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { StyleSheet, View } from 'react-native';
+import { useXTopViewStore } from '../XTopViewStore';
+export const XTopView = () => {
+    // 订阅 items：store 里 add/update/remove 都会触发这里重渲染
+    const items = useXTopViewStore(state => state.items);
+    return (_jsx(_Fragment, { children: items.map(item => (_jsx(View, { style: StyleSheet.absoluteFill, pointerEvents: 'box-none', children: item.element }, item.key))) }));
+};

package/dist/XTopViewStore/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * ============================================================================
+ * XTopViewStore —— 全局弹窗宿主的状态仓库（zustand）
+ * ============================================================================
+ *
+ * 【为什么需要它？】
+ * 弹窗如果渲染在页面内部（比如 ScrollView 里），会遇到两个问题：
+ *   1. 遮罩的 absoluteFill 只相对最近的定位父级生效，页面后面的兄弟节点
+ *      （比如 Button）会画在遮罩上面 → 遮不住；
+ *   2. 弹窗会跟着页面滚动，也无法覆盖到导航头/TabBar 等页面之外的区域。
+ *
+ * 解决方案（也是 duxui XTopView 的原理）：把弹窗"托管"到一个全局 store，
+ * 再由挂在应用根部的 <XTopView /> 渲染出来。这样弹窗永远在最顶层，
+ * 遮罩天然覆盖整个屏幕，与它在哪个页面里调用无关。
+ *
+ * 【三个 API 的含义】
+ *   add(element)    -> 挂载一个弹窗，返回唯一 key（之后用 key 来操作它）
+ *   update(key, el) -> 替换指定 key 的弹窗元素（用于"关闭时切换成离场态"）
+ *   remove(key)     -> 从宿主中移除（离场动画播完后再调用）
+ *
+ * 【zustand 用法速记】
+ *   create<T>()(set => ({...})) 返回一个 hook：useXTopViewStore(s => s.xxx)
+ *   - 选择器 s => s.add 只在 add 引用变化时才触发组件重渲染；
+ *   - 组件内也能用 useXTopViewStore.getState().add(...) 直接调（不用 hook）。
+ * ============================================================================
+ */
+import React from 'react';
+/** 宿主中的一个弹窗条目：key 唯一标识，element 是要渲染的内容 */
+export interface XTopViewItem {
+    key: number;
+    element: React.ReactNode;
+}
+/** store 的完整状态 + 操作方法定义 */
+interface XTopViewState {
+    /** 当前所有挂载中的弹窗（按挂载顺序排列，后面的绘制在上层） */
+    items: XTopViewItem[];
+    /** 挂载一个弹窗，返回唯一 key */
+    add: (element: React.ReactNode) => number;
+    /** 替换指定 key 的弹窗内容（不改变层级顺序） */
+    update: (key: number, element: React.ReactNode) => void;
+    /** 移除指定 key 的弹窗 */
+    remove: (key: number) => void;
+}
+export declare const useXTopViewStore: import("zustand").UseBoundStore<import("zustand").StoreApi<XTopViewState>>;
+export {};