react-native-x-components 0.1.0 → 0.2.1

package/AGENTS.md

@@ -0,0 +1,128 @@
+# AGENTS.md — AI 编码工具使用指南
+
+> 本文件供 AI 编码工具（Cursor / Copilot / Claude Code / WorkBuddy 等）在使用
+> react-native-x-components 时参考。人也可以读，但写法面向 AI。
+
+## 0. 安装与前置依赖
+
+```bash
+npm install react-native-x-components dayjs zustand
+# 必需 peer（Expo 项目）：
+npx expo install react-native-reanimated react-native-safe-area-context react-native-svg react-native-gesture-handler
+# 可选 peer（用到哪个装哪个）：
+#   @shopify/react-native-skia   → XSignatureSkia
+#   expo-audio                   → XRecord
+#   expo-image-picker + expo-image-manipulator + expo-file-system → XUpload*
+#   expo-video                   → XVideoPreview
+#   react-native-zoom-toolkit    → XImagePreview 缩放
+```
+
+原生依赖安装后需要 `npx expo prebuild --clean`（裸项目则重新构建原生包），
+否则录音/拍照权限弹窗、Skia、视频编解码不会生效。
+
+## 1. 必须的 App 根部接线（漏掉 = 命令式 API 静默失效）
+
+```tsx
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import { XPopupProvider } from 'react-native-x-components';
+
+export default function App() {
+  return (
+    <GestureHandlerRootView style={{flex: 1}}>
+      <XPopupProvider>
+        {/* 整个 App */}
+      </XPopupProvider>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+XPopupProvider 内部挂载：XTopView（弹层宿主）、XConfirmForm、XActionSheet 全局实例、
+XToast / XLoadingModal / XImagePreview 的 Provider。以下命令式 API 全部依赖它：
+
+- `XToastService.show({ message, type, position })`
+- `confirm({ title, content, danger })` → `Promise<boolean>`
+- `showXActionSheet({ title, options })` → `Promise<value | null>`
+- `XLoadingModalService.show({ message }) / hide()`
+- `XImagePreviewService.show({ images, initialIndex })`
+
+## 2. 常见错误对照表
+
+| 症状 | 原因 | 修复 |
+|---|---|---|
+| Toast / confirm / ActionSheet 无反应 | XPopupProvider 未挂根 | App 根部包 `<XPopupProvider>` |
+| 上传报 adapter 错误 | 未注入上传适配器 | `setXUploadAdapter(createMinioPresignedAdapter({...}))` |
+| 手势 / 滚轮不响应 | 缺 gesture-handler | install + GestureHandlerRootView 包根 |
+| Skia 签名报错 | 未装 skia | `npx expo install @shopify/react-native-skia` |
+| 录音/拍照无权限弹窗 | prebuild 未重跑 | `npx expo prebuild --clean` |
+| 暗黑切换全局不生效 | mode 被手动写死 | `setXThemeMode('system')` 恢复跟随 |
+| 主题色不生效 | 组件硬编码颜色 | 颜色一律取 `useXTheme()` token |
+
+## 3. 最小代码骨架
+
+### 上传（MinIO 预签名直传）
+
+```tsx
+import { setXUploadAdapter, createMinioPresignedAdapter, XUploadImage } from 'react-native-x-components';
+
+setXUploadAdapter(createMinioPresignedAdapter({
+  getUploadUrl: async ({ name }) => {
+    const res = await fetch(API + '/file/getUploadUrl?fileName=' + name);
+    const { data } = await res.json();
+    return { objectKey: data.objectKey, preSignedUrl: data.preSignedUrl };
+  },
+  getPreviewUrl: async objectKey => fetchPreviewUrl(objectKey),
+}));
+
+<XUploadImage value={imgs} onChange={setImgs} max={9} />
+```
+
+### 表单
+
+```tsx
+import { XForm, XInput, XButton } from 'react-native-x-components';
+
+const [form] = XForm.useForm();
+<XForm form={form} onFinish={console.log}>
+  <XForm.Item label="姓名" name="name" trigger="onChangeText"
+    rules={[{ required: true, message: '必填' }]}>
+    <XInput placeholder="请输入姓名" />
+  </XForm.Item>
+  <XButton type="primary" onPress={() => form.submit()}>提交</XButton>
+</XForm>
+```
+
+注意：输入类控件 `trigger="onChangeText"`，选择类 `trigger="onChange"`（默认），写错则值不同步。
+
+### 主题 / 语言
+
+```tsx
+import { useXTheme, setXThemeMode, setXBrandByName, setXLocale } from 'react-native-x-components';
+
+setXThemeMode('dark');        // 'light' | 'dark' | 'system'(默认跟随系统)
+setXBrandByName('薰衣紫');     // 4 套预设品牌色，深浅色各自适配
+setXLocale('en-US');          // 组件文案即时切换
+
+const t = useXTheme();        // 组件内取 token，禁硬编码颜色
+```
+
+## 4. 设计约定（生成代码前遵守）
+
+1. **弹层一律用本库体系**：XPullView（side: bottom/top/left/right/center）+ 全局 XTopView 宿主；**不要用 RN Modal**。
+2. **命令式服务统一 `XxxService.show()` 风格**，不再自己 setState 管 visible（除非用受控形态组件）。
+3. **颜色/圆角一律 `useXTheme()`**：浅深两套 token 自动切换，硬编码颜色是 bug。
+4. **XRadio / XCheckbox 的 onChange 事件对象与 antd 同构**：`e.target.value / e.target.checked`。
+5. XForm.Item 的 trigger：输入类 `onChangeText`，其余 `onChange`。
+6. 上传适配器协议：`upload(file, onProgress) => Promise<XUploadResult>`；`XUploadResult` 至少含 `url`（或 `objectKey`）。
+7. XSignatureSkia 需要 Skia；XRecord 需要 expo-audio；这些可选 peer 没装时不要 import 对应组件。
+
+## 5. 组件速查（36 个）
+
+基础：XButton · XDivider · XInput(customKeyboard 数字键盘) · XTag · XProgress · XRadio · XCheckbox
+表单：XForm · XFormPro · XCascadeSelect · XMultiSelect
+弹层：XPullView · XActionSheet · XPicker · XPickerDate · XModalForm · XConfirmForm · XAnimatedView · XToast · XLoadingModal
+交互：XTabs · XDropdownMenu · XAnimatedSearchPanel · XNumberKeyboard · XLicensePlate
+媒体：XCalendar · XCalendarPopup · XRecord · XSignature · XSignatureSkia · XUploadImage · XUploadVideo · XVideoPreview · XImage · XImagePreview
+数据：XChart
+
+完整用法与 props 表：https://react-native-x-components.dev（AI 可抓取 /llms-full.txt 获取全量文档）。

package/README.md

@@ -1,7 +1,51 @@
 # react-native-x-components
 
+<div align="center">
+
+[![npm version](https://img.shields.io/npm/v/react-native-x-components.svg)](https://www.npmjs.com/package/react-native-x-components)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![GitHub](https://img.shields.io/badge/GitHub-TimSpan%2Frn--x--components-181717?logo=github)](https://github.com/TimSpan/rn-x-components)
+
+</div>
+
 Ant Design 风格的 React Native (Expo) 组件库。对齐 antd v5 设计 token，内置**暗黑模式**与**中英双语**，弹层体系基于自研 TopView（比 RN Modal 更快），覆盖表单、选择器、日历、录音、签名（Skia 逐字签名）、上传（MinIO 预签名适配器）、轻量图表等 40+ 组件。
 
+- 📦 GitHub：https://github.com/TimSpan/rn-x-components
+- 📖 文档：https://react-native-x-components.dev（AI 可抓取 `/llms-full.txt` 全量文档）
+- 💬 微信交流（问题反馈 / 技术交流 / 定制咨询）：
+
+<div align="center">
+<img src="./wechat-qrcode.png" alt="微信添加 Otis 为好友" width="260" />
+</div>
+
+> 🤖 **AI 编码工具（Cursor/Copilot/Claude 等）请先读包内 [AGENTS.md](./AGENTS.md)** ——
+> 前置接线清单、常见错误对照表、最小代码骨架，能避开 90% 的集成坑。
+
+## 30 秒最小骨架
+
+```tsx
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import { XPopupProvider, XButton, XToastService, confirm } from 'react-native-x-components';
+
+export default function App() {
+  return (
+    <GestureHandlerRootView style={{flex: 1}}>
+      <XPopupProvider>   {/* 必挂！否则命令式 API 静默失效 */}
+        <XButton
+          type="primary"
+          onPress={async () => {
+            const ok = await confirm({ title: '确认提交？', danger: true });
+            if (ok) XToastService.show({ message: '已提交', type: 'success' });
+          }}
+        >
+          点我
+        </XButton>
+      </XPopupProvider>
+    </GestureHandlerRootView>
+  );
+}
+```
+
 ## 特性
 
 - 🌗 **暗黑模式**：`useXTheme()` 全组件自适应，`setXThemeMode('light' | 'dark' | 'system')` 一行切换
@@ -17,12 +61,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, {})] }));
 };