react-native-x-components 0.1.0 → 0.2.0

package/README.md

@@ -17,12 +17,22 @@ Ant Design 风格的 React Native (Expo) 组件库。对齐 antd v5 设计 token
 npm install react-native-x-components dayjs zustand
 # 必需 peer 依赖（Expo 项目推荐用 expo install 自动匹配版本）
 npx expo install react-native-reanimated react-native-safe-area-context react-native-svg
+# 推荐安装（XImagePreview/XInput 焦点等需要手势处理）：
+npx expo install react-native-gesture-handler
 # 可选（按需装）：
 # 签名: npx expo install @shopify/react-native-skia
 # 录音: npx expo install expo-audio
 # 上传: npx expo install expo-image-picker expo-image-manipulator expo-file-system
 ```
 
+### Android 权限说明（首次录音 / 拍照 / 选媒体时系统会自动弹）
+
+- **录音**：`expo-audio` 在 `npx expo prebuild --clean` 后会自动往 AndroidManifest.xml 注入 `RECORD_AUDIO`、iOS Info.plist 注入 `NSMicrophoneUsageDescription`
+- **拍照**：自动注入 `CAMERA`、iOS NSCameraUsageDescription
+- **选媒体**：自动注入 `READ_MEDIA_IMAGES` / `READ_MEDIA_VIDEO` (Android 13+)、`READ_EXTERNAL_STORAGE` (Android 12-) 及 NSPhotoLibraryUsageDescription (iOS)
+
+如果预编译后系统仍不弹权限框，先执行 `npx expo prebuild --clean && npx expo run:android` 让插件重新注入原生配置。
+
 ## 快速上手
 
 ```tsx

package/dist/XActionSheet/global.d.ts

@@ -0,0 +1,15 @@
+/**
+ * XActionSheet 全局命令式 API：
+ *   XActionSheet.show({title, options}) → Promise<value|null>
+ *
+ * 在 App 根部的 XPopupProvider 下挂载一次 XActionSheetGlobalOverlay 即可。
+ */
+import React from 'react';
+import { XActionSheetOption } from './index';
+/** 命令式调用入口 */
+export declare function showXActionSheet(opts: {
+    title?: string;
+    options: XActionSheetOption[];
+}): Promise<any | null>;
+/** 全局覆盖层：挂一次到 XPopupProvider 内即可 */
+export declare function XActionSheetGlobalOverlay(): React.JSX.Element | null;

package/dist/XActionSheet/global.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { create } from 'zustand';
+import { XActionSheet } from './index';
+const useStore = create(set => ({
+    visible: false,
+    options: [],
+    show: (opts) => {
+        return new Promise(resolve => {
+            set({ visible: true, title: opts.title, options: opts.options, resolve });
+        });
+    },
+    close: (value) => {
+        set(state => {
+            state.resolve?.(value);
+            return { visible: false, options: [], resolve: undefined };
+        });
+    },
+}));
+/** 命令式调用入口 */
+export async function showXActionSheet(opts) {
+    return useStore.getState().show(opts);
+}
+/** 全局覆盖层：挂一次到 XPopupProvider 内即可 */
+export function XActionSheetGlobalOverlay() {
+    const visible = useStore(s => s.visible);
+    const title = useStore(s => s.title);
+    const options = useStore(s => s.options);
+    const close = useStore(s => s.close);
+    if (!visible)
+        return null;
+    return (_jsx(XActionSheet, { visible: visible, onClose: () => close(null), options: options, title: title, onSelect: opt => close(opt.value) }));
+}

package/dist/XActionSheet/index.js

@@ -89,10 +89,11 @@ export function XActionSheet({ visible, onClose, options, title, cancelText, dur
             color: t.colorTextSecondary,
         },
     }), [t]);
-    /** 点选项：先关闭弹层，再通知业务方选中了谁 */
+    /** 点选项：先通知业务方选中了谁，再关弹层（顺序关键：命令式 show() 的
+     * Promise 依赖 onSelect 先 resolve，onClose 后触发时 resolve 已消费） */
     const handleSelect = useCallback((option) => {
-        onClose();
         onSelect?.(option);
+        onClose();
     }, [onClose, onSelect]);
     return (_jsx(XPullView, { visible: visible, onClose: onClose, side: 'bottom', duration: duration, overlayOpacity: 0.4, children: _jsxs(View, { style: [styles.panel, style, { paddingBottom: Math.max(insets.bottom, 10) }], children: [!!title && (_jsx(View, { style: styles.header, children: _jsx(Text, { style: styles.title, children: title }) })), _jsx(View, { style: styles.optionList, children: options.map(option => (_jsx(Pressable, { disabled: option.disabled, onPress: () => handleSelect(option), 
                         // style 可以是函数：pressed 状态时换个底色，模拟按压反馈

package/dist/XCalendar/index.js

@@ -147,24 +147,28 @@ export function XCalendar({ mode = 'day', value, defaultValue, multiple = false,
         setInnerValue(next);
         onChange?.(next);
     }, [mode, multiple, currentValue, onChange, weekStartsOn, pendingStart, isDisabled]);
-    /** 单元格样式计算 */
+    /** 单元格样式计算
+     * 【scope 重新选择规则】已选完一个范围后再点击：pendingStart 存在时
+     * 优先渲染"新一轮起点"，忽略旧范围（否则样式纹丝不动，像卡死）。
+     * 渲染优先级：pendingStart（scope 新起点）> 旧范围 > day 选中 */
     const cellState = useCallback((d) => {
         const key = d.format('YYYY-MM-DD');
         const disabled = isDisabled(d);
         const isToday = d.isSame(dayjs(), 'day');
         let selected = false;
         let inRange = false;
-        if (mode === 'day') {
+        if (mode === 'scope' && pendingStart) {
+            // 新一轮选择中：只高亮起点，旧范围不再显示
+            selected = key === pendingStart.format('YYYY-MM-DD');
+        }
+        else if (mode === 'day') {
             selected = multiple ? selectedSet.has(key) : key === selStart?.format('YYYY-MM-DD');
         }
         else if (selStart && selEnd) {
-            // week/scope：起止实心、中间浅底（week 模式每次选中天然成对）
+            // week/scope：起止实心、中间浅底
             selected = key === selStart.format('YYYY-MM-DD') || key === selEnd.format('YYYY-MM-DD');
             inRange = d.isAfter(selStart, 'day') && d.isBefore(selEnd, 'day');
         }
-        else if (mode === 'scope' && pendingStart) {
-            selected = key === pendingStart.format('YYYY-MM-DD');
-        }
         return { selected, inRange, disabled, isToday };
     }, [mode, multiple, selectedSet, selStart, selEnd, pendingStart, isDisabled]);
     const renderCell = (d, index) => {

package/dist/XDropdownMenu/index.js

@@ -46,42 +46,56 @@ function TriggerTitle({ itemProps, active, onPress, height, }) {
         ? itemProps.options.find(o => o.value === itemProps.value)?.name
         : undefined;
     const label = selectedName ?? itemProps.title;
-    return (_jsxs(Pressable, { onPress: onPress, style: [styles.triggerItem, { height }], disabled: itemProps.disabled || !onPress, children: [_jsx(Text, { style: [styles.triggerText, { color }, active && styles.triggerTextActive], numberOfLines: 1, allowFontScaling: false, children: label }), _jsx(Text, { style: [styles.arrow, { color }, active && styles.arrowOpen], allowFontScaling: false, children: "\u25BE" })] }));
+    return (_jsxs(Pressable, { onPress: onPress, style: [styles.triggerItem, { height }], disabled: itemProps.disabled || !onPress, children: [_jsx(Text, { style: [styles.triggerText, { color }, active && styles.triggerTextActive], numberOfLines: 1, allowFontScaling: false, children: label }), _jsx(Text, { style: [styles.arrow, { color }, active && styles.arrowOpen], allowFontScaling: false, children: "\u25BC" })] }));
 }
 const MenuOverlay = ({ visible, trigger, round, onClose, onExitEnd, snapshot, panel }) => {
     const t = useXTheme();
-    /** 面板内容高度（onLayout 实测 → 决定位移初值） */
+    /** 面板内容高度（onLayout 实测，决定遮罩起点 & 完全收起判断） */
     const [panelHeight, setPanelHeight] = useState(0);
-    const translateY = useSharedValue(0);
+    /** scaleY 展开动画（transformOrigin 顶部 = 触发条下沿），像"从触发条下面抽出/收回" */
+    const scaleY = useSharedValue(0);
     const maskOpacity = useSharedValue(0);
-    /**
-     * 面板位移：隐藏态 = -(panelHeight + 20)（藏在触发条上方），visible 后
-     * 下一帧滑到 0（duxui 的 translateY(-100%) 下拉）。panelHeight 未测得前
-     * 不动画，避免从 0 位置闪现。
-     */
+    /** 展开 scaleY 0→1（顶部锚点），遮罩淡入 */
     useEffect(() => {
-        if (visible && panelHeight > 0) {
+        if (visible) {
             const raf = requestAnimationFrame(() => {
-                translateY.value = withTiming(0, { duration: 200, easing: Easing.out(Easing.ease) });
-                maskOpacity.value = withTiming(1, { duration: 200 });
+                scaleY.value = withTiming(1, { duration: 200, easing: Easing.out(Easing.cubic) });
+                maskOpacity.value = withTiming(0.4, { duration: 200 });
             });
             return () => cancelAnimationFrame(raf);
         }
-    }, [visible, panelHeight, translateY, maskOpacity]);
-    /** 离场：反向动画后通知宿主移除 */
+    }, [visible, scaleY, maskOpacity]);
+    /** 收起 scaleY →0（同锚点收回，不再向上平移），动画后通知宿主移除 */
     useEffect(() => {
         if (!visible) {
-            translateY.value = withTiming(-(panelHeight + 20), { duration: 200, easing: Easing.inOut(Easing.ease) });
-            maskOpacity.value = withTiming(0, { duration: 200 });
-            const timer = setTimeout(onExitEnd, 250);
+            scaleY.value = withTiming(0, { duration: 180, easing: Easing.in(Easing.cubic) });
+            maskOpacity.value = withTiming(0, { duration: 180 });
+            const timer = setTimeout(onExitEnd, 220);
             return () => clearTimeout(timer);
         }
-    }, [visible, panelHeight, translateY, maskOpacity, onExitEnd]);
+    }, [visible, scaleY, maskOpacity, onExitEnd]);
     const panelStyle = useAnimatedStyle(() => ({
-        transform: [{ translateY: translateY.value }],
+        transform: [{ scaleY: scaleY.value }],
     }));
     const maskStyle = useAnimatedStyle(() => ({ opacity: maskOpacity.value }));
-    return (_jsxs(View, { style: StyleSheet.absoluteFill, pointerEvents: 'box-none', children: [_jsx(AnimatedPressable, { style: [StyleSheet.absoluteFill, { backgroundColor: '#000' }, maskStyle], onPress: onClose }), _jsx(View, { pointerEvents: 'none', style: { position: 'absolute', left: trigger.x, top: trigger.y, width: trigger.width, height: trigger.height }, children: snapshot }), _jsx(Animated.View, { style: [
+    return (_jsxs(View, { style: StyleSheet.absoluteFill, pointerEvents: 'box-none', children: [_jsx(AnimatedPressable, { style: [
+                    {
+                        position: 'absolute',
+                        left: 0,
+                        right: 0,
+                        top: trigger.y + trigger.height,
+                        bottom: 0,
+                        backgroundColor: '#000',
+                    },
+                    maskStyle,
+                ], onPress: onClose }), _jsx(View, { pointerEvents: 'none', style: {
+                    position: 'absolute',
+                    left: trigger.x,
+                    top: trigger.y,
+                    width: trigger.width,
+                    height: trigger.height,
+                    backgroundColor: t.colorBgContainer,
+                }, children: snapshot }), _jsx(Animated.View, { style: [
                     styles.panel,
                     {
                         left: trigger.x,
@@ -90,6 +104,7 @@ const MenuOverlay = ({ visible, trigger, round, onClose, onExitEnd, snapshot, pa
                         backgroundColor: t.colorBgContainer,
                         borderBottomLeftRadius: round ? t.borderRadiusXL : 0,
                         borderBottomRightRadius: round ? t.borderRadiusXL : 0,
+                        transformOrigin: '50% 0%',
                     },
                     panelStyle,
                 ], pointerEvents: 'auto', children: _jsx(View, { onLayout: e => {
@@ -192,7 +207,7 @@ export function XDropdownMenu({ round = true, onOpenChange, triggerHeight = 44,
     }, [remove]);
     /** context value：open/close/activeIndex 分发给每个 Item */
     const ctx = useMemo(() => ({ index: -1, activeIndex: activeIndex ?? -1, open, close, triggerHeight }), [activeIndex, open, close, triggerHeight]);
-    return (_jsx(View, { ref: triggerRef, style: [styles.triggerRow, { height: triggerHeight }, style], children: items.map((child, i) => (_jsx(MenuContext.Provider, { value: { ...ctx, index: i }, children: child }, i))) }));
+    return (_jsx(View, { ref: triggerRef, style: [styles.triggerRow, { height: triggerHeight, backgroundColor: t.colorBgContainer }, style], children: items.map((child, i) => (_jsx(MenuContext.Provider, { value: { ...ctx, index: i }, children: child }, i))) }));
 }
 /**
  * 触发条单项（真实渲染）：从 MenuContext 拿到自己的序号与开合动作。
@@ -202,7 +217,7 @@ export function XDropdownMenuItem(props) {
     const ctx = useContext(MenuContext);
     if (!ctx)
         return null;
-    return (_jsx(TriggerTitle, { itemProps: props, active: ctx.activeIndex === ctx.index, onPress: () => !props.disabled && ctx.open(ctx.index), height: 0 }));
+    return (_jsx(TriggerTitle, { itemProps: props, active: ctx.activeIndex === ctx.index, onPress: () => !props.disabled && ctx.open(ctx.index), height: ctx.triggerHeight }));
 }
 const styles = StyleSheet.create({
     triggerRow: {
@@ -224,7 +239,7 @@ const styles = StyleSheet.create({
         fontWeight: '600',
     },
     arrow: {
-        fontSize: 10,
+        fontSize: 9,
         marginLeft: 4,
     },
     arrowOpen: {

package/dist/XInput/index.d.ts

@@ -11,6 +11,7 @@
  * <XInput value={name} onChangeText={setName} placeholder='请输入姓名' />
  * <XInput multiline placeholder='请输入备注' />
  * <XInput disabled value='只读' />
+ * <XInput customKeyboard='numeric' value={amount} onChangeText={setAmount} /> // 自绘数字键盘
  * ```
  *
  * 与 antd Input 的对应：
@@ -18,6 +19,8 @@
  * - disabled：对应 antd disabled（不可编辑 + 禁用样式）
  * - multiline：对应 antd Input.TextArea
  * - allowClear：对应 antd allowClear（非多行时显示清空按钮）
+ * - customKeyboard='numeric'：盖住系统键盘，弹起自绘数字键盘（带"完成"按钮）
+ *   适合金额/数量等场景，外观风格统一；与 XNumberKeyboard 同源渲染
  * - 其余 props（maxLength/keyboardType/secureTextEntry 等）原样透传给 TextInput
  *
  * 注意：value 是完全受控透传，不做任何 trim/transform —— 改写会打断
@@ -33,6 +36,14 @@ export interface XInputProps extends TextInputProps {
     disabled?: boolean;
     /** 有内容时显示清空按钮（antd allowClear；multiline 下不生效） */
     allowClear?: boolean;
+    /**
+     * 自定义键盘：'numeric' 时盖住系统键盘，弹起自绘数字键盘
+     * （带"完成"工具栏，按键直接回写 value；与 XNumberKeyboard 同源）。
+     * 仅单行模式生效；与 multiline 互斥。
+     */
+    customKeyboard?: 'numeric';
+    /** 自定义键盘的小数点（false 隐藏；true 显示，默认 true） */
+    customKeyboardPoint?: boolean;
     style?: StyleProp<TextStyle>;
     /** 外层容器样式（有 allowClear 按钮时想要撑满/贴边用） */
     containerStyle?: StyleProp<ViewStyle>;

package/dist/XInput/index.js

@@ -12,6 +12,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * <XInput value={name} onChangeText={setName} placeholder='请输入姓名' />
  * <XInput multiline placeholder='请输入备注' />
  * <XInput disabled value='只读' />
+ * <XInput customKeyboard='numeric' value={amount} onChangeText={setAmount} /> // 自绘数字键盘
  * ```
  *
  * 与 antd Input 的对应：
@@ -19,17 +20,26 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * - disabled：对应 antd disabled（不可编辑 + 禁用样式）
  * - multiline：对应 antd Input.TextArea
  * - allowClear：对应 antd allowClear（非多行时显示清空按钮）
+ * - customKeyboard='numeric'：盖住系统键盘，弹起自绘数字键盘（带"完成"按钮）
+ *   适合金额/数量等场景，外观风格统一；与 XNumberKeyboard 同源渲染
  * - 其余 props（maxLength/keyboardType/secureTextEntry 等）原样透传给 TextInput
  *
  * 注意：value 是完全受控透传，不做任何 trim/transform —— 改写会打断
  * Android 中文输入法的合成过程（XForm 的同值守卫也依赖原样透传）。
  */
 import { forwardRef, useEffect, useRef, useState } from 'react';
-import { Pressable, StyleSheet, TextInput, View } from 'react-native';
+import { Pressable, StyleSheet, TextInput, View, Text } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { useXTheme } from '../theme';
-export const XInput = forwardRef(function XInput({ value, onChangeText, multiline, disabled, allowClear, style, containerStyle, editable, ...rest }, ref) {
+import { useXLocale } from '../XLocale';
+import { XPullView } from '../XPullView';
+import { XNumberKeyboard } from '../XNumberKeyboard';
+export const XInput = forwardRef(function XInput({ value, onChangeText, multiline, disabled, allowClear, customKeyboard, customKeyboardPoint = true, style, containerStyle, editable, ...rest }, ref) {
     const [focused, setFocused] = useState(false);
     const isDisabled = disabled || editable === false;
+    const useCustomKb = customKeyboard === 'numeric' && !multiline;
+    /** 自定义键盘弹层是否展开 */
+    const [kbVisible, setKbVisible] = useState(false);
     /**
      * Android IME 防回抛镜像（关键）：
      * 受控模式下若把父级 store 的 value 每键原样回写给 TextInput，IME 合成会被
@@ -56,15 +66,58 @@ export const XInput = forwardRef(function XInput({ value, onChangeText, multilin
     // 受控用法显示镜像；非受控（没传 value）不干预，TextInput 自己管
     const displayValue = value !== undefined ? mirror : undefined;
     const t = useXTheme();
+    const { t: i18n } = useXLocale();
+    const insets = useSafeAreaInsets();
     const showClear = !!allowClear && !multiline && !isDisabled && !!displayValue;
     /** 清空后把光标送回输入框，继续输入不用再点一次 */
     const handleClear = () => {
         reportedRef.current = '';
         setMirror('');
         onChangeText?.('');
-        ref && typeof ref === 'object' && ref.current?.focus();
+        if (!useCustomKb) {
+            ref && typeof ref === 'object' && ref.current?.focus();
+        }
+        else {
+            setKbVisible(true);
+        }
+    };
+    /** 自定义键盘：按键 → 回写 value（带 maxLength 校验） */
+    const handleKeyPress = (key) => {
+        const prev = displayValue ?? '';
+        const maxLength = rest.maxLength;
+        if (typeof maxLength === 'number' && prev.length >= maxLength)
+            return;
+        // 小数点只允许一次、不允许开头
+        if (key === '.' && (prev.includes('.') || prev.length === 0))
+            return;
+        handleChange(prev + key);
+    };
+    /** 自定义键盘：退格 */
+    const handleBackspace = () => {
+        const prev = displayValue ?? '';
+        handleChange(prev.slice(0, -1));
     };
-    return (_jsxs(View, { style: [styles.container, containerStyle], children: [_jsx(TextInput, { ...rest, ref: ref, value: displayValue, onChangeText: handleChange, multiline: multiline, editable: !isDisabled, pointerEvents: isDisabled ? 'none' : undefined, style: [
+    // 自定义键盘模式下，"聚焦状态"由弹层是否展开驱动
+    const isFocused = useCustomKb ? kbVisible : focused;
+    return (_jsxs(View, { style: [styles.container, containerStyle], children: [useCustomKb ? (_jsx(Pressable, { onPress: () => !isDisabled && setKbVisible(true), disabled: isDisabled, children: ({ pressed }) => (_jsx(View, { style: [
+                        styles.input,
+                        {
+                            borderColor: isFocused && !isDisabled ? t.colorPrimary : t.colorBorder,
+                            backgroundColor: isDisabled
+                                ? t.colorBgContainerDisabled
+                                : pressed
+                                    ? t.colorBgLayout
+                                    : t.colorBgContainer,
+                        },
+                    ], pointerEvents: 'none', children: _jsx(Text, { style: [
+                            styles.kbText,
+                            {
+                                color: displayValue ? t.colorText : t.colorTextQuaternary,
+                            },
+                            typeof style === 'object' && !Array.isArray(style)
+                                ? style
+                                : undefined,
+                        ], numberOfLines: 1, allowFontScaling: false, children: displayValue || rest.placeholder }) })) })) : (_jsx(TextInput, { ...rest, ref: ref, value: displayValue, onChangeText: handleChange, multiline: multiline, editable: !isDisabled, pointerEvents: isDisabled ? 'none' : undefined, style: [
                     styles.input,
                     {
                         borderColor: focused && !isDisabled ? t.colorPrimary : t.colorBorder,
@@ -83,7 +136,7 @@ export const XInput = forwardRef(function XInput({ value, onChangeText, multilin
                 }, onBlur: e => {
                     setFocused(false);
                     rest.onBlur?.(e);
-                } }), showClear && (_jsx(Pressable, { onPress: handleClear, style: styles.clearBtn, hitSlop: 8, children: _jsxs(View, { style: [styles.clearCircle, { backgroundColor: t.colorTextQuaternary }], children: [_jsx(View, { style: [styles.clearX1, { backgroundColor: t.colorTextLightSolid }] }), _jsx(View, { style: [styles.clearX2, { backgroundColor: t.colorTextLightSolid }] })] }) }))] }));
+                } })), showClear && (_jsx(Pressable, { onPress: handleClear, style: styles.clearBtn, hitSlop: 8, children: _jsxs(View, { style: [styles.clearCircle, { backgroundColor: t.colorTextQuaternary }], children: [_jsx(View, { style: [styles.clearX1, { backgroundColor: t.colorTextLightSolid }] }), _jsx(View, { style: [styles.clearX2, { backgroundColor: t.colorTextLightSolid }] })] }) })), useCustomKb && (_jsx(XPullView, { visible: kbVisible, onClose: () => setKbVisible(false), side: 'bottom', overlayOpacity: 0.4, children: _jsxs(View, { style: [styles.kbPanel, { backgroundColor: t.colorBgContainer, paddingBottom: Math.max(insets.bottom, 10) }], children: [_jsxs(View, { style: [styles.kbToolbar, { borderBottomColor: t.colorSplit }], children: [_jsx(Text, { style: [styles.kbToolbarTitle, { color: t.colorTextSecondary }], numberOfLines: 1, children: rest.placeholder ?? i18n('pleaseInput') }), _jsx(Pressable, { onPress: () => setKbVisible(false), hitSlop: 8, children: _jsx(Text, { style: [styles.kbDone, { color: t.colorPrimary }], children: i18n('done') }) })] }), _jsx(XNumberKeyboard, { onKeyPress: handleKeyPress, onBackspace: handleBackspace, extraKey: customKeyboardPoint ? '.' : null })] }) }))] }));
 });
 /** antd Input.TextArea 的对应形态 */
 export const XTextArea = (props) => _jsx(XInput, { multiline: true, ...props });
@@ -107,6 +160,32 @@ const styles = StyleSheet.create({
         textAlignVertical: 'top',
         paddingVertical: 10,
     },
+    kbText: {
+        fontSize: 15,
+        paddingVertical: 2,
+    },
+    kbPanel: {
+        borderTopLeftRadius: 12,
+        borderTopRightRadius: 12,
+        overflow: 'hidden',
+    },
+    kbToolbar: {
+        flexDirection: 'row',
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        paddingHorizontal: 16,
+        height: 44,
+        borderBottomWidth: StyleSheet.hairlineWidth,
+    },
+    kbToolbarTitle: {
+        fontSize: 13,
+        flex: 1,
+        marginRight: 8,
+    },
+    kbDone: {
+        fontSize: 15,
+        fontWeight: '600',
+    },
     clearBtn: {
         position: 'absolute',
         right: 8,

package/dist/XLicensePlate/index.js

@@ -15,6 +15,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  */
 import { useCallback, useMemo, useState } from 'react';
 import { Pressable, StyleSheet, Text, View } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { XPullView } from '../XPullView';
 import { useXTheme } from '../theme';
 import { useXLocale } from '../XLocale';
@@ -81,6 +82,7 @@ export function XLicensePlateKeyboard({ phase, onInput, onBackspace, allowedKeys
 export function XLicensePlate({ value = '', onChange, length = 7, disabled = false, placeholder, style }) {
     const t = useXTheme();
     const { t: i18n } = useXLocale();
+    const insets = useSafeAreaInsets();
     const [visible, setVisible] = useState(false);
     /** 当前键盘阶段 */
     const phase = value.length === 0 ? 'province' : value.length === 1 ? 'city' : 'alnum';
@@ -112,7 +114,7 @@ export function XLicensePlate({ value = '', onChange, length = 7, disabled = fal
                 isNewEnergyTail && { borderColor: t.colorSuccess, borderWidth: 1.5 },
             ], children: filled && (_jsx(Text, { style: [styles.cellText, { color: t.colorText }], allowFontScaling: false, children: value[i] })) }, i));
     });
-    return (_jsxs(_Fragment, { children: [_jsx(Pressable, { onPress: () => !disabled && setVisible(true), style: [styles.cellRow, style], disabled: disabled, children: cells }), _jsx(XPullView, { visible: visible, onClose: () => setVisible(false), side: 'bottom', overlayOpacity: 0.4, children: _jsxs(View, { style: [styles.panel, { backgroundColor: t.colorBgContainer }], children: [_jsxs(View, { style: [styles.header, { borderBottomColor: t.colorSplit }], children: [_jsx(Text, { style: [styles.headerTitle, { color: t.colorTextSecondary }], allowFontScaling: false, children: length === 8 ? i18n('newEnergyTip') : i18n('platePlaceholder') }), _jsx(Pressable, { onPress: () => setVisible(false), hitSlop: 8, children: _jsx(Text, { style: [styles.doneBtn, { color: t.colorPrimary }], children: i18n('done') }) })] }), _jsx(XLicensePlateKeyboard, { phase: phase, onInput: handleInput, onBackspace: handleBackspace, allowedKeys: allowedKeys, isLast: isLast && length === 7 })] }) })] }));
+    return (_jsxs(_Fragment, { children: [_jsx(Pressable, { onPress: () => !disabled && setVisible(true), style: [styles.cellRow, style], disabled: disabled, children: cells }), _jsx(XPullView, { visible: visible, onClose: () => setVisible(false), side: 'bottom', overlayOpacity: 0.4, children: _jsxs(View, { style: [styles.panel, { backgroundColor: t.colorBgContainer, paddingBottom: Math.max(insets.bottom, 10) }], children: [_jsxs(View, { style: [styles.header, { borderBottomColor: t.colorSplit }], children: [_jsx(Text, { style: [styles.headerTitle, { color: t.colorTextSecondary }], allowFontScaling: false, children: length === 8 ? i18n('newEnergyTip') : i18n('platePlaceholder') }), _jsx(Pressable, { onPress: () => setVisible(false), hitSlop: 8, children: _jsx(Text, { style: [styles.doneBtn, { color: t.colorPrimary }], children: i18n('done') }) })] }), _jsx(XLicensePlateKeyboard, { phase: phase, onInput: handleInput, onBackspace: handleBackspace, allowedKeys: allowedKeys, isLast: isLast && length === 7 })] }) })] }));
 }
 const styles = StyleSheet.create({
     keyboard: {

package/dist/XPopupProvider/index.js

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

package/dist/XSignature/XSignatureSkia.js

@@ -32,7 +32,9 @@ export function XSignatureSkia({ value, onChange, buttonText = '签名', strokeC
     const t = useXTheme();
     const { t: i18n } = useXLocale();
     const insets = useSafeAreaInsets();
-    const signatureValue = value?.characters ? value : emptyValue();
+    /** 非受控兜底：未传 value/onChange 时内部自持状态（示例/轻量场景开箱即用） */
+    const [innerValue, setInnerValue] = useState(null);
+    const signatureValue = value !== undefined ? (value?.characters ? value : emptyValue()) : (innerValue ?? emptyValue());
     /** 预览画布 ref（完成时截图用） */
     const previewCanvasRef = useCanvasRef();
     const [visible, setVisible] = useState(false);
@@ -43,8 +45,14 @@ export function XSignatureSkia({ value, onChange, buttonText = '签名', strokeC
     /** 预览：字符集拼到预览画布 */
     const previewStrokes = useMemo(() => transformCharacters(signatureValue.characters, previewSize), [previewSize, signatureValue.characters]);
     const emitCharacters = useCallback((characters) => {
-        onChange?.(characters.length ? { version: 1, characters } : null);
-    }, [onChange]);
+        const next = characters.length ? { version: 1, characters } : null;
+        if (value !== undefined) {
+            onChange?.(next);
+        }
+        else {
+            setInnerValue(next);
+        }
+    }, [value, onChange]);
     /** 一笔画完 */
     const handleStrokeComplete = useCallback((points, size) => {
         setCurrentStrokes(strokes => [
@@ -105,12 +113,12 @@ export function XSignatureSkia({ value, onChange, buttonText = '签名', strokeC
         setVisible(false);
     }, [signatureValue.characters, currentStrokes, emitCharacters, previewCanvasRef, onExport]);
     /** 签名板内容（XPullView 内） */
-    const board = (_jsxs(View, { style: [styles.board, { backgroundColor: t.colorBgContainer, paddingBottom: Math.max(insets.bottom, 8) }], children: [_jsxs(ScrollView, { horizontal: true, style: [styles.characterStrip, { backgroundColor: t.colorBgLayout }], contentContainerStyle: styles.characterStripContent, children: [_jsx(Text, { style: [styles.savedCount, { color: t.colorTextTertiary }], allowFontScaling: false, children: i18n('savedChars', { n: signatureValue.characters.length }) }), signatureValue.characters.map(character => (_jsx(Pressable, { onLongPress: () => handleRemoveCharacter(character.id), style: [styles.characterChip, { borderColor: t.colorBorder, backgroundColor: t.colorBgContainer }], children: _jsx(CharacterChip, { character: character }) }, character.id)))] }), _jsxs(View, { style: styles.signArea, children: [_jsx(SignatureCanvas, { strokes: currentStrokes, touchEnabled: true, strokeColor: strokeColor, strokeWidth: strokeWidth, onStrokeComplete: handleStrokeComplete, onLayoutSize: setCanvasSize }), canvasSize.width > 0 && canvasSize.height > 0 && (_jsxs(Svg, { pointerEvents: 'none', width: canvasSize.width, height: canvasSize.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] }), _jsx(Line, { x1: '0%', y1: '0%', x2: '100%', y2: '100%', stroke: t.colorSplit, strokeWidth: '1', strokeDasharray: [4, 4] }), _jsx(Line, { x1: '100%', y1: '0%', x2: '0%', y2: '100%', stroke: t.colorSplit, strokeWidth: '1', strokeDasharray: [4, 4] })] }))] }), _jsxs(View, { style: styles.footer, children: [_jsx(XButton, { type: 'text', onPress: () => setVisible(false), children: i18n('close') }), _jsx(XButton, { type: 'text', onPress: handleClearCurrent, children: i18n('rewrite') }), _jsx(XButton, { type: 'default', size: 'small', onPress: handleSaveCharacter, children: i18n('saveChar') }), _jsx(XButton, { type: 'text', danger: true, onPress: handleClearAll, children: i18n('clear') }), _jsx(XButton, { type: 'primary', size: 'small', onPress: handleDone, children: i18n('done') })] })] }));
+    const board = (_jsxs(View, { style: [styles.board, { backgroundColor: t.colorBgContainer, paddingBottom: Math.max(insets.bottom, 8) }], children: [_jsxs(ScrollView, { horizontal: true, style: [styles.characterStrip, { backgroundColor: t.colorBgLayout }], contentContainerStyle: styles.characterStripContent, children: [_jsx(Text, { style: [styles.savedCount, { color: t.colorTextTertiary }], allowFontScaling: false, children: i18n('savedChars', { n: signatureValue.characters.length }) }), signatureValue.characters.map(character => (_jsx(Pressable, { onLongPress: () => handleRemoveCharacter(character.id), style: [styles.characterChip, { borderColor: t.colorBorder, backgroundColor: t.colorBgContainer }], children: _jsx(CharacterChip, { character: character }) }, character.id)))] }), _jsxs(View, { style: [styles.signArea, { height: 320 }], children: [_jsx(SignatureCanvas, { strokes: currentStrokes, touchEnabled: true, strokeColor: strokeColor, strokeWidth: strokeWidth, onStrokeComplete: handleStrokeComplete, onLayoutSize: setCanvasSize }), canvasSize.width > 0 && canvasSize.height > 0 && (_jsxs(Svg, { pointerEvents: 'none', width: canvasSize.width, height: canvasSize.height, style: styles.grid, children: [_jsx(Line, { x1: '0%', y1: '50%', x2: '100%', y2: '50%', stroke: '#DDDDDD', strokeWidth: '1', strokeDasharray: [4, 4] }), _jsx(Line, { x1: '50%', y1: '0%', x2: '50%', y2: '100%', stroke: '#DDDDDD', strokeWidth: '1', strokeDasharray: [4, 4] }), _jsx(Line, { x1: '0%', y1: '0%', x2: '100%', y2: '100%', stroke: '#DDDDDD', strokeWidth: '1', strokeDasharray: [4, 4] }), _jsx(Line, { x1: '100%', y1: '0%', x2: '0%', y2: '100%', stroke: '#DDDDDD', strokeWidth: '1', strokeDasharray: [4, 4] })] }))] }), _jsxs(View, { style: styles.footer, children: [_jsx(XButton, { type: 'text', onPress: () => setVisible(false), children: i18n('close') }), _jsx(XButton, { type: 'text', onPress: handleClearCurrent, children: i18n('rewrite') }), _jsx(XButton, { type: 'default', size: 'small', onPress: handleSaveCharacter, children: i18n('saveChar') }), _jsx(XButton, { type: 'text', danger: true, onPress: handleClearAll, children: i18n('clear') }), _jsx(XButton, { type: 'primary', size: 'small', onPress: handleDone, children: i18n('done') })] })] }));
     // inline 模式：外部自己控制 XPullView（board 由 renderBoard 暴露）——当前版本仅内部用
     if (inline) {
         return board;
     }
-    return (_jsxs(View, { style: styles.container, children: [_jsx(XButton, { type: 'primary', style: styles.openButton, onPress: () => setVisible(true), children: buttonText }), _jsxs(View, { style: [styles.preview, { borderColor: t.colorBorder }], children: [_jsx(SignatureCanvas, { strokes: previewStrokes, strokeColor: strokeColor, strokeWidth: strokeWidth, onLayoutSize: setPreviewSize, canvasRef: previewCanvasRef }), previewStrokes.length === 0 && (_jsx(Text, { style: [styles.placeholder, { color: t.colorTextTertiary }], children: i18n('signHint') }))] }), _jsx(XPullView, { visible: visible, onClose: () => setVisible(false), side: 'bottom', overlayOpacity: 0.5, children: _jsx(View, { style: { height: '88%' }, children: board }) })] }));
+    return (_jsxs(View, { style: styles.container, children: [_jsx(XButton, { type: 'primary', style: styles.openButton, onPress: () => setVisible(true), children: buttonText }), _jsxs(View, { style: [styles.preview, { borderColor: t.colorBorder }], children: [_jsx(SignatureCanvas, { strokes: previewStrokes, strokeColor: strokeColor, strokeWidth: strokeWidth, onLayoutSize: setPreviewSize, canvasRef: previewCanvasRef }), previewStrokes.length === 0 && (_jsx(Text, { style: [styles.placeholder, { color: t.colorTextTertiary }], children: i18n('signHint') }))] }), _jsx(XPullView, { visible: visible, onClose: () => setVisible(false), side: 'bottom', overlayOpacity: 0.5, children: _jsx(View, { style: { height: 520, paddingBottom: 10 }, children: board }) })] }));
 }
 /** 单个已存字的 chip 缩略渲染 */
 function CharacterChip({ character }) {

package/dist/XSignature/index.js

@@ -17,7 +17,6 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 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';
@@ -59,7 +58,7 @@ export function XSignature({ height = 200, strokeColor = '#111111', strokeWidth
         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') })] })] }));
+    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 }), 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: {

package/dist/XTheme/BrandColor.d.ts

@@ -0,0 +1,20 @@
+export interface XBrandPreset {
+    name: string;
+    /** 浅色主色 */
+    primary: string;
+    /** 暗黑主色 */
+    primaryDark: string;
+    /** 弱背景色（antd colorPrimaryBg） */
+    primaryBg: string;
+}
+export declare const X_BRAND_PRESETS: XBrandPreset[];
+interface XBrandState {
+    brand: XBrandPreset;
+    setXBrand: (brand: XBrandPreset) => void;
+    setXBrandByName: (name: string) => void;
+}
+export declare const useXBrandStore: import("zustand").UseBoundStore<import("zustand").StoreApi<XBrandState>>;
+/** 命令式：切换品牌色 */
+export declare function setXBrand(brand: XBrandPreset): void;
+export declare function setXBrandByName(name: string): void;
+export {};

package/dist/XTheme/BrandColor.js

@@ -0,0 +1,33 @@
+/**
+ * ============================================================================
+ * XBrand —— 运行时主题色切换
+ * ============================================================================
+ * 一组预设品牌色 + zustand 全局 store。setXBrand(name) 立即生效：
+ * 浅/深两套 token 里的 colorPrimary / colorPrimaryActive / colorPrimaryBg
+ * 被覆盖。组件统一 useXTheme() 取色，不需要额外订阅。
+ * ============================================================================
+ */
+import { create } from 'zustand';
+export const X_BRAND_PRESETS = [
+    { name: '海洋蓝', primary: '#2080F0', primaryDark: '#3C93F5', primaryBg: 'rgba(32,128,240,0.18)' },
+    { name: '薰衣紫', primary: '#7C3AED', primaryDark: '#A78BFA', primaryBg: 'rgba(124,58,237,0.18)' },
+    { name: '翡翠绿', primary: '#16A34A', primaryDark: '#4ADE80', primaryBg: 'rgba(22,163,74,0.18)' },
+    { name: '暖阳橙', primary: '#F97316', primaryDark: '#FB923C', primaryBg: 'rgba(249,115,22,0.18)' },
+];
+const DEFAULT_BRAND = X_BRAND_PRESETS[0];
+export const useXBrandStore = create(set => ({
+    brand: DEFAULT_BRAND,
+    setXBrand: brand => set({ brand }),
+    setXBrandByName: name => {
+        const found = X_BRAND_PRESETS.find(p => p.name === name);
+        if (found)
+            set({ brand: found });
+    },
+}));
+/** 命令式：切换品牌色 */
+export function setXBrand(brand) {
+    useXBrandStore.getState().setXBrand(brand);
+}
+export function setXBrandByName(name) {
+    useXBrandStore.getState().setXBrandByName(name);
+}

package/dist/XTheme/ThemeControls.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ============================================================================
+ * ThemeControls —— 暗黑/主题色/语言 三个切换按钮组
+ * ============================================================================
+ * 在 3 个位置使用：
+ *   1. 介绍页（app/index.tsx）顶部
+ *   2. 组件页（app/components/index.tsx）Stack headerRight
+ *   3. 我的/关于页（app/mine.tsx）顶部
+ *
+ * props:
+ *   compact?: boolean   true 时紧凑（用于 headerRight 单行）
+ *   inline?: boolean    true 时背景透明、无边框（用于页面顶部）
+ * ============================================================================
+ */
+import React from 'react';
+export interface ThemeControlsProps {
+    compact?: boolean;
+    style?: any;
+}
+/** 三个按钮组合 */
+export declare function ThemeControls({ compact, style }: ThemeControlsProps): React.JSX.Element;
+export default ThemeControls;