react-native-x-components 0.1.0

package/dist/XForm/index.js

@@ -0,0 +1,212 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * ============================================================================
+ * XForm / XForm.Item —— 对标 antd Form（RN 自实现版）
+ * ============================================================================
+ *
+ * 用法（和 antd 一致）：
+ * ```tsx
+ * const [form] = XForm.useForm();
+ *
+ * <XForm
+ *   form={form}
+ *   initialValues={{name: '张三'}}
+ *   onFinish={values => console.log('提交', values)}
+ *   onFinishFailed={({errorFields}) => console.log('失败', errorFields)}
+ * >
+ *   <XForm.Item label='姓名' name='name' rules={[{required: true, message: '请输入姓名'}]}>
+ *     <TextInput placeholder='请输入姓名' />
+ *   </XForm.Item>
+ *
+ *   <XForm.Item label='性别' name='sex' rules={[{required: true, message: '请选择性别'}]}>
+ *     <XRadio.Group options={[{label: '男', value: 1}, {label: '女', value: 0}]} />
+ *   </XForm.Item>
+ *
+ *   <XButton type='primary' onPress={() => form.submit()}>提交</XButton>
+ * </XForm>
+ * ```
+ *
+ * Form.Item 支持的 antd API：
+ * - name / label / rules / initialValue
+ * - validateTrigger: 'onChange' | 'onBlur' | 两者数组（默认 onChange）
+ * - valuePropName: 默认 'value'（Checkbox 这类受控属性叫 checked 时改成 'checked'）
+ * - trigger: 值变化回调的 prop 名（默认 'onChange'）
+ * - getValueFromEvent: 自定义从回调参数里取值
+ * - dependencies: 这些字段的值变化会触发本字段重新校验（如二次输入密码）
+ * - help / validateStatus: 手动控制提示文案与状态色（设置后优先生效，help 默认按 error 色显示）
+ * - required: 只控制 * 号显示（校验语义请写在 rules 里，同 antd）
+ * - noStyle: 不渲染 label/错误文案/外层间距，只注入 value/onChange
+ * - shouldUpdate + 函数 children: 渲染函数拿到 form 实例，做联动 UI
+ *
+ * 与 antd 的差异：
+ * - 无 Form.List / Form.Provider（动态列表后续有需要再加）
+ * - store 任何变化会通知所有 Item 重渲染（antd 是精确调度；表单规模下性能足够）
+ * - label 布局提供 vertical（默认）/ horizontal 两种
+ */
+import React, { createContext, useContext, useEffect, useMemo, useReducer, useRef } from 'react';
+import { StyleSheet, View, Text } from 'react-native';
+import { useXTheme, xTheme } from '../theme';
+import { useForm } from './useForm';
+import { defaultGetValueFromEvent } from './utils';
+import { hasRequiredRule } from './validate';
+export { useForm } from './useForm';
+const XFormContext = createContext(null);
+function XForm(props) {
+    const { form, initialValues, onFinish, onFinishFailed, onValuesChange, layout = 'vertical', labelWidth, labelStyle, requiredMark = true, style, children, testID, } = props;
+    const [internalForm] = useForm();
+    const formInstance = form ?? internalForm;
+    const store = formInstance.__getStore();
+    // 每轮渲染都刷新 callbacks 闭包，保证 onFinish 等拿到父组件最新的 state
+    useEffect(() => {
+        store.setCallbacks({ onFinish, onFinishFailed, onValuesChange });
+    });
+    // initialValues 只在 Form 首次挂载时应用一次（antd 同款约定）
+    const initialized = useRef(false);
+    useEffect(() => {
+        if (initialized.current)
+            return;
+        initialized.current = true;
+        store.initValues(initialValues);
+    }, [store, initialValues]);
+    const ctx = useMemo(() => ({ store, formInstance, layout, labelWidth, labelStyle, requiredMark }), [store, formInstance, layout, labelWidth, labelStyle, requiredMark]);
+    return (_jsx(XFormContext.Provider, { value: ctx, children: _jsx(View, { testID: testID, style: [styles.form, style], children: children }) }));
+}
+function XFormItem(props) {
+    const t = useXTheme();
+    const ctx = useContext(XFormContext);
+    // 脱离 <XForm> 使用：按纯布局渲染（hooks 必须无条件调用，所以早退分支放 Inner 外）
+    if (!ctx) {
+        return (_jsxs(View, { testID: props.testID, style: [styles.item, props.style], children: [props.label != null && _jsx(Text, { style: [styles.label, { color: t.colorText }], children: props.label }), typeof props.children === 'function' ? null : props.children] }));
+    }
+    return _jsx(XFormItemInner, { ...props, ctx: ctx });
+}
+/**
+ * 真正的实现拆到 Inner：上面的"无 ctx 早退分支"return 之后不能再有 hooks。
+ */
+function XFormItemInner(props) {
+    const { name, label, rules, initialValue, validateTrigger = 'onChange', valuePropName = 'value', trigger = 'onChange', getValueFromEvent, dependencies, help, validateStatus, required, noStyle, labelWidth, labelStyle, style, children, testID, ctx, } = props;
+    const { store, formInstance, layout, labelWidth: formLabelWidth, labelStyle: formLabelStyle, requiredMark } = ctx;
+    const t = useXTheme();
+    // 订阅 store：任何值/错误变化 bump 一次，本 Item 读自己的最新值
+    const [, forceUpdate] = useReducer(c => c + 1, 0);
+    const nameDefined = name !== undefined && name !== null;
+    const nameKey = nameDefined ? (Array.isArray(name) ? name.map(String).join('.') : String(name)) : '';
+    /**
+     * 字段实体只创建一次；rules/validateTrigger 等每轮渲染原地更新。
+     * 不能按 rules 依赖重建实体 —— 调用方常写内联 rules 数组（每轮新引用），
+     * 重建会导致 register/unregister 反复横跳，错误信息被 unregister 清掉。
+     */
+    const entityRef = useRef(null);
+    if (!entityRef.current) {
+        entityRef.current = { name: name, rules, validateTrigger, dependencies, initialValue, reRender: forceUpdate };
+    }
+    else {
+        entityRef.current.name = name;
+        entityRef.current.rules = rules;
+        entityRef.current.validateTrigger = validateTrigger;
+        entityRef.current.dependencies = dependencies;
+        entityRef.current.initialValue = initialValue;
+    }
+    // 注册/注销只跟随 name 变化（name 变了视为换了字段）
+    useEffect(() => {
+        if (!nameDefined)
+            return;
+        store.registerField(entityRef.current);
+        return () => store.unregisterField(entityRef.current);
+    }, [store, nameKey, nameDefined]);
+    // 无 name 的 Item（shouldUpdate + 函数式 children）：走通用订阅，store 变化即重渲染
+    useEffect(() => {
+        if (nameDefined || typeof children !== 'function')
+            return;
+        return store.subscribe(forceUpdate);
+    }, [store, nameDefined, typeof children === 'function']);
+    const value = nameDefined ? store.getFieldValue(name) : undefined;
+    const autoErrors = nameDefined ? store.getFieldError(name) : [];
+    // ---- help / validateStatus 手动态优先（antd：设置 help 且未设状态时按 error 展示） ----
+    const manualActive = help !== undefined || validateStatus !== undefined;
+    const effectiveStatus = validateStatus ?? (help !== undefined ? 'error' : undefined);
+    const helpText = manualActive ? help : autoErrors.length ? autoErrors.join('，') : null;
+    const helpColorStyle = manualActive
+        ? effectiveStatus === 'warning'
+            ? { color: t.colorWarning }
+            : effectiveStatus === 'error' || effectiveStatus === undefined
+                ? { color: t.colorError }
+                : { color: t.colorTextTertiary }
+        : { color: t.colorError };
+    // ---- children 处理：函数式 or 注入 value/onChange ----
+    let childNode = typeof children === 'function' ? null : children;
+    if (typeof children === 'function') {
+        // shouldUpdate + 函数 children：把 form 实例交给业务自己渲染（联动场景）
+        childNode = children(formInstance);
+    }
+    else if (nameDefined && React.isValidElement(children)) {
+        const child = children;
+        const childProps = {
+            [valuePropName]: value,
+        };
+        // 合并子组件自己的 trigger 回调（不能吞掉别人的 onChange）
+        const childTrigger = child.props?.[trigger];
+        childProps[trigger] = (...args) => {
+            childTrigger?.(...args);
+            const nextValue = getValueFromEvent ? getValueFromEvent(...args) : defaultGetValueFromEvent(valuePropName, args[0]);
+            store.updateValue(name, nextValue, 'onChange');
+        };
+        // validateTrigger 含 onBlur 时注入 onBlur 校验（同样合并子组件自己的 onBlur）
+        const triggers = Array.isArray(validateTrigger) ? validateTrigger : [validateTrigger];
+        if (triggers.includes('onBlur')) {
+            const childBlur = child.props?.onBlur;
+            childProps.onBlur = (...args) => {
+                childBlur?.(...args);
+                store.validateOnBlur(name);
+            };
+        }
+        childNode = React.cloneElement(child, childProps);
+    }
+    // ---- 渲染 ----
+    if (noStyle) {
+        return _jsx(_Fragment, { children: childNode });
+    }
+    const showRequiredMark = requiredMark && (required || hasRequiredRule(rules));
+    const isHorizontal = layout === 'horizontal';
+    const effectiveLabelWidth = labelWidth ?? formLabelWidth;
+    return (_jsxs(View, { testID: testID, style: [styles.item, isHorizontal && styles.itemHorizontal, style], children: [label != null && (_jsxs(View, { style: [styles.labelRow, isHorizontal && { width: effectiveLabelWidth, marginBottom: 0, marginRight: 12 }], children: [showRequiredMark && _jsx(Text, { style: [styles.requiredStar, { color: t.colorError }], children: "*" }), _jsx(Text, { style: [styles.label, { color: t.colorText }, formLabelStyle, labelStyle], allowFontScaling: false, children: label })] })), _jsxs(View, { style: isHorizontal ? styles.controlHorizontal : styles.control, children: [childNode, helpText != null && _jsx(Text, { style: [styles.help, { color: t.colorTextTertiary }, helpColorStyle], children: helpText })] })] }));
+}
+const XFormExported = XForm;
+XFormExported.Item = XFormItem;
+XFormExported.useForm = useForm;
+const styles = StyleSheet.create({
+    form: {
+        width: '100%',
+    },
+    item: {
+        marginBottom: 18,
+    },
+    itemHorizontal: {
+        flexDirection: 'row',
+        alignItems: 'flex-start',
+    },
+    labelRow: {
+        flexDirection: 'row',
+        alignItems: 'center',
+        marginBottom: 8,
+    },
+    label: {
+        fontSize: xTheme.fontSize,
+    },
+    requiredStar: {
+        marginRight: 4,
+        fontSize: xTheme.fontSize,
+    },
+    control: {
+        width: '100%',
+    },
+    controlHorizontal: {
+        flex: 1,
+    },
+    help: {
+        fontSize: xTheme.fontSizeSM,
+        marginTop: 6,
+        lineHeight: 18,
+    },
+});
+export default XFormExported;

package/dist/XForm/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * XForm 类型定义 —— 对标 antd Form / rc-field-form 的类型子集
+ */
+import type React from 'react';
+/** 字段路径：'a' | ['a', 'b'] | ['a', 0, 'b']（数组下标场景） */
+export type XNamePath = string | number | Array<string | number>;
+/** 校验触发时机 */
+export type XValidateTrigger = 'onChange' | 'onBlur';
+/**
+ * 单条校验规则（对标 antd Rule，实现 async-validator 常用子集）
+ */
+export interface XRuleObject {
+    /** 必填 */
+    required?: boolean;
+    /** 报错文案；未填时按规则类型给中文默认文案 */
+    message?: React.ReactNode;
+    /** 值类型校验：string | number | boolean | array | email | url */
+    type?: 'string' | 'number' | 'boolean' | 'array' | 'email' | 'url';
+    /** string：长度下限；number：数值下限；array：长度下限 */
+    min?: number;
+    /** 同上，上限 */
+    max?: number;
+    /** 长度/数值必须等于 */
+    len?: number;
+    /** 正则校验（对 string 值） */
+    pattern?: RegExp;
+    /** 值必须是枚举之一 */
+    enum?: Array<string | number>;
+    /** 空格字符串视为空（配合 required） */
+    whitespace?: boolean;
+    /**
+     * 自定义校验器（对标 antd validator）：
+     * - 返回 Promise，reject / throw 即失败；reject 的值（或 error.message）作为文案
+     * - resolve（包括 reject() 空值 + rule.message 兜底）即通过
+     */
+    validator?: (rule: XRuleObject, value: any) => Promise<void | any>;
+    /** 先转换再校验（不影响 store 里的值，只影响校验输入） */
+    transform?: (value: any) => any;
+}
+export type XRule = XRuleObject;
+/** validateFields 失败时 reject 的对象（对标 antd ValidateErrorEntity） */
+export interface XValidateErrorEntity<Values = any> {
+    values: Values;
+    errorFields: XErrorEntity[];
+    outOfDate: boolean;
+}
+/** 单个字段的错误信息 */
+export interface XErrorEntity {
+    name: XNamePath;
+    errors: string[];
+}
+/** setFields 的入参（对标 antd） */
+export interface XFieldData {
+    name: XNamePath;
+    value?: any;
+    /** 传 [] 清除错误；传 ['xxx'] 设置错误 */
+    errors?: string[];
+    touched?: boolean;
+}
+/**
+ * 表单实例（对标 antd FormInstance）
+ * 所有方法与 antd 同名同义；__getStore 为内部实现细节，业务代码不要调用
+ */
+export interface XFormInstance<Values = any> {
+    getFieldValue: (name: XNamePath) => any;
+    /** nameList 传 true 返回全部（含未注册字段）；传数组只取指定字段；不传返回整个 values */
+    getFieldsValue: (nameList?: XNamePath[] | true) => Values;
+    setFieldValue: (name: XNamePath, value: any) => void;
+    setFieldsValue: (values: Partial<Values>) => void;
+    setFields: (fields: XFieldData[]) => void;
+    resetFields: (nameList?: XNamePath[]) => void;
+    getFieldError: (name: XNamePath) => string[];
+    getFieldsError: (nameList?: XNamePath[]) => XErrorEntity[];
+    /** 校验（不传 name 校验全部）；失败 reject {values, errorFields, outOfDate} */
+    validateFields: (nameList?: XNamePath[]) => Promise<Values>;
+    /** 触发 onFinish / onFinishFailed（对标 antd form.submit()） */
+    submit: () => void;
+    isFieldTouched: (name: XNamePath) => boolean;
+    isFieldsTouched: (nameList?: XNamePath[], allFieldsTouched?: boolean) => boolean;
+    /** 内部：拿到 FormStore（XForm 组件接线用） */
+    __getStore: () => unknown;
+}

package/dist/XForm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/XForm/useForm.d.ts

@@ -0,0 +1,2 @@
+import type { XFormInstance } from './types';
+export declare function useForm<Values extends Record<string, any> = any>(): [XFormInstance<Values>];

package/dist/XForm/useForm.js

@@ -0,0 +1,19 @@
+/**
+ * XForm.useForm —— 对标 antd Form.useForm()
+ *
+ * const [form] = XForm.useForm();
+ * <XForm form={form}>...</XForm>
+ *
+ * 实例对象与 FormStore 绑定（__getStore），XForm 组件拿 form prop 反查 store；
+ * 不传 form 时 XForm 内部自建，一样可用（只是外部拿不到实例方法）。
+ */
+import { useRef } from 'react';
+import { FormStore } from './FormStore';
+export function useForm() {
+    const ref = useRef(undefined);
+    if (!ref.current) {
+        const store = new FormStore();
+        ref.current = store.getForm();
+    }
+    return [ref.current];
+}

package/dist/XForm/utils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * XForm 工具函数：路径读写 / 事件取值 / 空值判断
+ */
+import type { XNamePath } from './types';
+/** namePath 序列化成 map key（['a', 0] -> 'a.0'；'a' -> 'a'） */
+export declare function namePathKey(name: XNamePath): string;
+/** 判断两个 namePath 是否同一个字段 */
+export declare function isSameNamePath(a: XNamePath | undefined, b: XNamePath | undefined): boolean;
+/** 判断 namePath 是否在依赖列表里（依赖支持单路径或路径数组） */
+export declare function matchDependency(dependencies: XNamePath[] | undefined, name: XNamePath): boolean;
+/** 空值：null/undefined/空串/纯空格串/空数组 */
+export declare function isEmptyValue(value: any): boolean;
+/**
+ * 按路径读值（只读，不创建中间对象）
+ * get({a: {b: 1}}, ['a','b']) -> 1
+ */
+export declare function getValueByPath(store: any, name: XNamePath): any;
+/**
+ * 按路径写值（浅拷贝路径上的对象，不 mutate 原 store —— 保证 React 数据流可预测）
+ * set({}, ['a','b'], 1) -> {a: {b: 1}}
+ */
+export declare function setValueByPath<T>(store: T, name: XNamePath, value: any): T;
+/**
+ * 深拷贝（Form values 里可能有 Date 等复杂对象，用 JSON 会丢内容，沿用 lodash cloneDeep 的场景）
+ *
+ * 环安全：一旦值被污染成循环引用（比如事件对象被误存进 store），
+ * 在 revisit 处返回原引用打断递归 —— 宁可数据带环也不能让 App 爆栈崩溃。
+ */
+export declare function deepClone<T>(value: T): T;
+/**
+ * 从事件参数里提取表单值（对标 rc-field-form 的 defaultGetValueFromEvent，做 RN 适配）
+ *
+ * 覆盖四种调用形态：
+ * 1. 直传值：TextInput onChangeText(text) —— text 直接是字符串
+ * 2. RN 原生事件对象：onChange({nativeEvent: {text}}) —— 必须先判这种，
+ *    否则事件对象会被整个存进 store：事件内部（_targetInst.viewConfig 等）全是
+ *    循环引用，后续 deepClone 直接 Maximum call stack size exceeded
+ * 3. 合成事件：XRadio/XCheckbox 的 onChange({value, checked, target})
+ * 4. 兜底：看起来像事件对象（有 nativeEvent/_targetInst/stopPropagation）的一律
+ *    返回 undefined，绝不把事件本身当值存
+ */
+export declare function defaultGetValueFromEvent(valuePropName: string, arg: any): any;

package/dist/XForm/utils.js

@@ -0,0 +1,131 @@
+/** namePath 序列化成 map key（['a', 0] -> 'a.0'；'a' -> 'a'） */
+export function namePathKey(name) {
+    if (typeof name === 'string' || typeof name === 'number')
+        return String(name);
+    return name.map(String).join('.');
+}
+/** 判断两个 namePath 是否同一个字段 */
+export function isSameNamePath(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    return namePathKey(a) === namePathKey(b);
+}
+/** 判断 namePath 是否在依赖列表里（依赖支持单路径或路径数组） */
+export function matchDependency(dependencies, name) {
+    if (!dependencies?.length)
+        return false;
+    const key = namePathKey(name);
+    return dependencies.some(dep => namePathKey(dep) === key);
+}
+/** 空值：null/undefined/空串/纯空格串/空数组 */
+export function isEmptyValue(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value === 'string')
+        return value.trim() === '';
+    if (Array.isArray(value))
+        return value.length === 0;
+    return false;
+}
+/**
+ * 按路径读值（只读，不创建中间对象）
+ * get({a: {b: 1}}, ['a','b']) -> 1
+ */
+export function getValueByPath(store, name) {
+    const path = Array.isArray(name) ? name : [name];
+    let current = store;
+    for (const key of path) {
+        if (current === null || current === undefined)
+            return undefined;
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * 按路径写值（浅拷贝路径上的对象，不 mutate 原 store —— 保证 React 数据流可预测）
+ * set({}, ['a','b'], 1) -> {a: {b: 1}}
+ */
+export function setValueByPath(store, name, value) {
+    const path = Array.isArray(name) ? name : [name];
+    if (path.length === 0)
+        return value;
+    function cloneLevel(node, level) {
+        const key = path[level];
+        if (level === path.length - 1) {
+            // 叶子：数组下标保持数组类型
+            if (Array.isArray(node)) {
+                const copy = [...node];
+                copy[key] = value;
+                return copy;
+            }
+            return { ...node, [key]: value };
+        }
+        const nextNode = node?.[key] ?? (typeof path[level + 1] === 'number' ? [] : {});
+        const clonedNext = cloneLevel(nextNode, level + 1);
+        if (Array.isArray(node)) {
+            const copy = [...node];
+            copy[key] = clonedNext;
+            return copy;
+        }
+        return { ...node, [key]: clonedNext };
+    }
+    return cloneLevel(store, 0);
+}
+/**
+ * 深拷贝（Form values 里可能有 Date 等复杂对象，用 JSON 会丢内容，沿用 lodash cloneDeep 的场景）
+ *
+ * 环安全：一旦值被污染成循环引用（比如事件对象被误存进 store），
+ * 在 revisit 处返回原引用打断递归 —— 宁可数据带环也不能让 App 爆栈崩溃。
+ */
+export function deepClone(value) {
+    return cloneWithCycleGuard(value, new WeakSet());
+}
+function cloneWithCycleGuard(value, seen) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (seen.has(value))
+        return value; // 循环引用：返回原引用打断
+    seen.add(value);
+    if (Array.isArray(value))
+        return value.map(item => cloneWithCycleGuard(item, seen));
+    if (value instanceof Date)
+        return new Date(value.getTime());
+    const out = {};
+    for (const key of Object.keys(value)) {
+        out[key] = cloneWithCycleGuard(value[key], seen);
+    }
+    return out;
+}
+/**
+ * 从事件参数里提取表单值（对标 rc-field-form 的 defaultGetValueFromEvent，做 RN 适配）
+ *
+ * 覆盖四种调用形态：
+ * 1. 直传值：TextInput onChangeText(text) —— text 直接是字符串
+ * 2. RN 原生事件对象：onChange({nativeEvent: {text}}) —— 必须先判这种，
+ *    否则事件对象会被整个存进 store：事件内部（_targetInst.viewConfig 等）全是
+ *    循环引用，后续 deepClone 直接 Maximum call stack size exceeded
+ * 3. 合成事件：XRadio/XCheckbox 的 onChange({value, checked, target})
+ * 4. 兜底：看起来像事件对象（有 nativeEvent/_targetInst/stopPropagation）的一律
+ *    返回 undefined，绝不把事件本身当值存
+ */
+export function defaultGetValueFromEvent(valuePropName, arg) {
+    // RN 原生事件（TextInput 的 onChange/onBlur 等）：值在 nativeEvent.text
+    if (arg && typeof arg === 'object' && arg.nativeEvent != null) {
+        return typeof arg.nativeEvent.text === 'string' ? arg.nativeEvent.text : undefined;
+    }
+    // 自定义合成事件对象（有对象形态的 target）：优先按 valuePropName 取，其次 value
+    if (arg && typeof arg === 'object' && arg.target && typeof arg.target === 'object') {
+        if (valuePropName in arg.target)
+            return arg.target[valuePropName];
+        if ('value' in arg.target)
+            return arg.target.value;
+        return arg.value ?? arg;
+    }
+    // 防御：事件样子的对象（React 合成事件带 _targetInst/stopPropagation）不当值
+    if (arg && typeof arg === 'object' && (arg._targetInst !== undefined || typeof arg.stopPropagation === 'function')) {
+        return undefined;
+    }
+    return arg;
+}

package/dist/XForm/validate.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ============================================================================
+ * XForm 校验引擎 —— 对标 async-validator 的常用子集
+ * ============================================================================
+ *
+ * 支持的规则：required / type / min / max / len / pattern / enum / whitespace /
+ * validator（自定义）/ transform
+ *
+ * 与 async-validator 的差异（有意为之）：
+ * - type='number' 放宽：字符串 '12' 也按数字校验（RN TextInput 只产字符串，
+ *   实际项目里输入框数字校验基本都是字符串形态，严格类型反而难用）
+ * - 未实现的规则字段直接忽略，不报错
+ */
+import type { XRule, XNamePath } from './types';
+/** 规则里声明了 required 吗（Form.Item 的 * 号判断也用它） */
+export declare function hasRequiredRule(rules?: XRule[]): boolean;
+/**
+ * 校验一个字段：按规则顺序执行，收集全部错误（antd 展示所有错误文案，这里保持一致）
+ */
+export declare function validateValue(value: any, rules: XRule[] | undefined, name: XNamePath, label?: string): Promise<string[]>;

package/dist/XForm/validate.js

@@ -0,0 +1,118 @@
+import { isEmptyValue } from './utils';
+/** 文案模板里的 ${label} 占位符替换 */
+function fillTemplate(template, label) {
+    return template.replace(/\$\{label\}/g, label);
+}
+/** 规则里声明了 required 吗（Form.Item 的 * 号判断也用它） */
+export function hasRequiredRule(rules) {
+    return !!rules?.some(rule => rule.required);
+}
+function typeOfValue(value) {
+    if (Array.isArray(value))
+        return 'array';
+    if (value === null)
+        return 'null';
+    if (value instanceof Date)
+        return 'date';
+    return typeof value;
+}
+/** 单条规则单值校验：返回错误文案数组（空数组 = 通过） */
+async function validateRule(rule, rawValue, ctx) {
+    const { label } = ctx;
+    const message = rule.message !== undefined ? String(rule.message) : undefined;
+    const value = rule.transform ? rule.transform(rawValue) : rawValue;
+    const empty = isEmptyValue(value);
+    const errors = [];
+    // ---- required：空值直接失败（whitespace=true 时纯空格串也算空，isEmptyValue 已覆盖）----
+    if (rule.required && empty) {
+        return [message ?? fillTemplate('${label}是必填字段', label)];
+    }
+    // 非必填且值为空：跳过其余检查（async-validator 同款行为）
+    if (empty)
+        return [];
+    // ---- 自定义 validator：reject/throw 即失败 ----
+    if (rule.validator) {
+        try {
+            await rule.validator(rule, value);
+        }
+        catch (err) {
+            // reject() 空值 → 用 rule.message；reject('文案') / throw Error → 用其内容
+            const text = err?.message ?? (typeof err === 'string' ? err : undefined);
+            return [text || message || fillTemplate('${label}校验失败', label)];
+        }
+        return [];
+    }
+    // ---- type ----
+    if (rule.type) {
+        const actual = typeOfValue(value);
+        let typeOk = true;
+        switch (rule.type) {
+            case 'string':
+                typeOk = actual === 'string';
+                break;
+            case 'number':
+                // 放宽：数字字符串也算 number（RN 适配，见文件头注释）
+                typeOk = actual === 'number' || (actual === 'string' && value.trim() !== '' && !isNaN(Number(value)));
+                break;
+            case 'boolean':
+                typeOk = actual === 'boolean';
+                break;
+            case 'array':
+                typeOk = actual === 'array';
+                break;
+            case 'email':
+                typeOk = actual === 'string' && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+                break;
+            case 'url':
+                typeOk = actual === 'string' && /^https?:\/\/\S+$/.test(value);
+                break;
+        }
+        if (!typeOk) {
+            return [message ?? `${label}的类型应为 ${rule.type}`];
+        }
+    }
+    // ---- min / max / len：按实际值类型分派 ----
+    const actual = typeOfValue(value);
+    const asNumber = actual === 'number' ? value : actual === 'string' && !isNaN(Number(value)) ? Number(value) : null;
+    if (rule.len != null) {
+        const lenOk = actual === 'string' || actual === 'array' ? value.length === rule.len : asNumber != null ? asNumber === rule.len : true;
+        if (!lenOk)
+            return [message ?? `${label}应为 ${rule.len} 个字符/项`];
+    }
+    if (rule.min != null) {
+        const minOk = actual === 'string' || actual === 'array' ? value.length >= rule.min : asNumber != null ? asNumber >= rule.min : true;
+        if (!minOk)
+            return [message ?? `${label}不能少于 ${rule.min}${actual === 'string' ? ' 个字符' : actual === 'array' ? ' 项' : ''}`];
+    }
+    if (rule.max != null) {
+        const maxOk = actual === 'string' || actual === 'array' ? value.length <= rule.max : asNumber != null ? asNumber <= rule.max : true;
+        if (!maxOk)
+            return [message ?? `${label}不能超过 ${rule.max}${actual === 'string' ? ' 个字符' : actual === 'array' ? ' 项' : ''}`];
+    }
+    // ---- pattern ----
+    if (rule.pattern && !(actual === 'string' && rule.pattern.test(value))) {
+        return [message ?? fillTemplate('${label}格式不正确', label)];
+    }
+    // ---- enum ----
+    if (rule.enum && !rule.enum.includes(value)) {
+        return [message ?? `${label}必须是 [${rule.enum.join(' / ')}] 中的一个`];
+    }
+    return errors;
+}
+/**
+ * 校验一个字段：按规则顺序执行，收集全部错误（antd 展示所有错误文案，这里保持一致）
+ */
+export async function validateValue(value, rules, name, label) {
+    if (!rules?.length)
+        return [];
+    const displayName = label ?? (typeof name === 'string' || typeof name === 'number' ? String(name) : namePathLabel(name));
+    const allErrors = [];
+    for (const rule of rules) {
+        const errs = await validateRule(rule, value, { label: displayName, required: !!rule.required });
+        allErrors.push(...errs);
+    }
+    return allErrors;
+}
+function namePathLabel(name) {
+    return Array.isArray(name) ? name.map(String).join('.') : String(name);
+}

package/dist/XFormPro/components/FieldTrigger.d.ts

@@ -0,0 +1,14 @@
+/**
+ * XFormPro 内部字段触发器：select / datePicker 这类"弹层控件"的触发区。
+ *
+ * 与 XInput 同视觉（浅灰底、发丝边框、右侧 ›），点击由外部接管打开弹层。
+ */
+import React from 'react';
+export interface FieldTriggerProps {
+    /** 展示文本（已选值/已选 label；空串或 undefined 显示 placeholder） */
+    text?: string;
+    placeholder?: string;
+    onPress: () => void;
+    disabled?: boolean;
+}
+export declare function FieldTrigger({ text, placeholder, onPress, disabled }: FieldTriggerProps): React.JSX.Element;