@hsu-react/ui 2.4.9 → 2.5.0

package/es/components/FormItem/FormInput/FormInputNumber/index.d.ts

@@ -2,7 +2,23 @@ import { ItemContainerProps } from "../../ItemContainer";
 import { InputNumberProps } from "../../../Input/Number";
 import React from "react";
 export interface FormInputNumberProps extends ItemContainerProps {
-    componentProps?: InputNumberProps;
+    /**
+     * `onChange` 的签名比基础组件宽：作为**表单字段**，默认交出的是
+     * `number | null`（见 Bridge 的注释）。写这个回调的人拿到的与表单拿到的
+     * 是同一个值。
+     */
+    componentProps?: Omit<InputNumberProps, "onChange"> & {
+        onChange?: (value: string | number | null) => void;
+    };
+    /**
+     * 交给表单的是字符串而不是数字。默认 `false`。
+     *
+     * 只有真的要处理**超出 IEEE754 安全范围的大数**（订单号、雪花 ID）时才打开
+     * —— 那种值转成 number 会丢精度，必须一路以字符串传递。
+     *
+     * 2.5.0 之前没有这个开关，行为固定等同于 `stringMode`（见下方 Bridge 注释）。
+     */
+    stringMode?: boolean;
 }
 declare const FormInputNumber: React.FC<FormInputNumberProps>;
 export default FormInputNumber;

package/es/components/FormItem/FormInput/FormInputNumber/index.js

@@ -1,6 +1,7 @@
 function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
-var _excluded = ["componentProps", "className", "disabled"],
-  _excluded2 = ["placeholder"];
+var _excluded = ["value", "onChange", "componentOnChange", "stringMode"],
+  _excluded2 = ["componentProps", "className", "disabled", "stringMode"],
+  _excluded3 = ["placeholder", "onChange"];
 function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
@@ -11,19 +12,77 @@ function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) r
 import ItemContainer from "../../ItemContainer";
 import Input from "../../../Input";
 import React from "react";
+
+// value / onChange 要重新声明：`InputNumberProps` 上那两个是**基础组件**的
+// 契约（字符串进、字符串出），而这里收的是**表单值**，可以是数字或 null
 import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * 夹在 `Form.Item` 与 `Input.Number` 之间，**把字符串换成数字再交给表单**。
+ *
+ * 为什么需要它：`Input.Number` 内部以字符串保存（底层 `stringMode`，为的是不
+ * 丢大数精度），`onChange` 交出的也是字符串。这对一个**基础输入组件**是合理
+ * 的，但对一个叫 INPUTNUMBER 的**表单字段**不合理 —— 表单收上去的值会直接
+ * 进请求体，而后端字段多半是整数：
+ *
+ * ```
+ * 422  invalid type: string "2", expected i32
+ * ```
+ *
+ * 这个坑平时看不见：没动过的字段，值来自详情接口、本来就是数字，原样发回去
+ * 没事；**只有用户真的改了那一格**才会变成字符串。现象是「我明明只改了个
+ * 数字却保存失败」，而且报错在服务端，前端一行日志都没有。
+ *
+ * 转换只在**往上交**的方向做；`Input.Number` 内部仍然是字符串，所以正在敲的
+ * "1." / "1.50" 不会被改写（配套改动见 `Input/Number` 里的 sameNumber 判断）。
+ */
+var Bridge = function Bridge(props) {
+  var value = props.value,
+    onChange = props.onChange,
+    componentOnChange = props.componentOnChange,
+    stringMode = props.stringMode,
+    rest = _objectWithoutProperties(props, _excluded);
+  var emit = function emit(next) {
+    onChange === null || onChange === void 0 || onChange(next);
+    componentOnChange === null || componentOnChange === void 0 || componentOnChange(next);
+  };
+  return /*#__PURE__*/_jsx(Input.Number, _objectSpread(_objectSpread({}, rest), {}, {
+    value: value,
+    onChange: function onChange(text) {
+      if (stringMode) {
+        emit(text);
+        return;
+      }
+
+      // 空 → null 而不是 ""：语义是「没填」，不是「填了个空字符串」。
+      // 后端 `Option<i32>` 收得下 null，收不下 ""
+      if (text === "" || text === null || text === undefined) {
+        emit(null);
+        return;
+      }
+      var num = Number(text);
+      // 转不动就原样交出去（用户可能正敲到 "-" 或 "1e" 这种中间态）。
+      // 硬转成 NaN 会让表单里躺着一个既非数字也非空的值
+      emit(Number.isFinite(num) ? num : text);
+    }
+  }));
+};
 var FormInputNumber = function FormInputNumber(props) {
   var _inputConfig$disabled;
   var _props$componentProps = props.componentProps,
     componentProps = _props$componentProps === void 0 ? {} : _props$componentProps,
     itemClassName = props.className,
     disabled = props.disabled,
-    formItemProps = _objectWithoutProperties(props, _excluded);
+    stringMode = props.stringMode,
+    formItemProps = _objectWithoutProperties(props, _excluded2);
+  // onChange 必须摘出来，理由见 BridgeProps.componentOnChange
   var placeholder = componentProps.placeholder,
-    inputConfig = _objectWithoutProperties(componentProps, _excluded2);
+    componentOnChange = componentProps.onChange,
+    inputConfig = _objectWithoutProperties(componentProps, _excluded3);
   return /*#__PURE__*/_jsx(ItemContainer, _objectSpread(_objectSpread({}, formItemProps), {}, {
     className: "".concat(itemClassName !== null && itemClassName !== void 0 ? itemClassName : ""),
-    children: /*#__PURE__*/_jsx(Input.Number, _objectSpread(_objectSpread({}, inputConfig), {}, {
+    children: /*#__PURE__*/_jsx(Bridge, _objectSpread(_objectSpread({}, inputConfig), {}, {
+      componentOnChange: componentOnChange,
+      stringMode: stringMode,
       disabled: (_inputConfig$disabled = inputConfig.disabled) !== null && _inputConfig$disabled !== void 0 ? _inputConfig$disabled : disabled,
       placeholder: placeholder !== null && placeholder !== void 0 ? placeholder : "请输入"
     }))

package/es/components/Input/Number/index.d.ts

@@ -3,7 +3,11 @@ import React from "react";
 export interface InputNumberProps extends Omit<AntdInputNumberProps, "ref" | "onChange" | "value"> {
     getRef?: (ref: HTMLInputElement | null) => void;
     onChange?: (value: string) => void;
-    value?: string;
+    /**
+     * 受控值。本组件内部**始终以字符串保存**（底层开了 antd 的 `stringMode`，
+     * 为的是不丢大数精度），但外部传数字进来也接得住。
+     */
+    value?: string | number | null;
     allowClear?: boolean;
     wrapperClassName?: string;
 }

package/es/components/Input/Number/index.js

@@ -64,16 +64,33 @@ var InputNumber = function InputNumber(props) {
     // Update internal state only when the external value prop actually changes
     if (prevValueRef.current !== value) {
       prevValueRef.current = value;
-      if (value !== undefined) {
+
+      // 数值相等就不要回写文本。
+      //
+      // 上游把值转成数字之后（`FormItem` 的 INPUTNUMBER 默认就会转），一个
+      // 回环会打回来：输入 "1." → onChange → 表单存 1 → value={1} 传回来。
+      // 若照单全收地写成 "1"，用户刚敲的小数点当场消失、光标还会跳到末尾，
+      // "1.50" 也会被改写成 "1.5"。
+      //
+      // 判据用**数值相等**而不是字符串相等：这几种写法（"1." / "1.50" / "+1"）
+      // 表示的是同一个数，此时以用户正在敲的那份文本为准。
+      var sameNumber = value !== undefined && value !== null && _value !== "" && Number(value) === Number(_value);
+      if (sameNumber) {
+        // 只同步「已提交值」，不动正在编辑的文本
+        setLastValue(_value);
+      } else if (value !== undefined && value !== null) {
         var newValue = typeof value === "number" ? "".concat(value) : value === null || value === void 0 ? void 0 : value.toString();
         setValue(newValue);
         setLastValue(newValue);
       } else {
-        // Clear only on initialization or when explicitly set to undefined externally
+        // Clear only on initialization or when explicitly set to undefined/null externally
         setValue("");
         setLastValue("");
       }
     }
+    // `_value` 是刻意不进依赖的：这个 effect 只该在**外部** value 变化时跑，
+    // 把它加进来会让每次键入都重跑一遍，等于绕过上面那个 prevValueRef 判断
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [value]);
   useEffect(function () {
     getRef === null || getRef === void 0 || getRef(ref.current);

package/lib/components/FormItem/FormInput/FormInputNumber/index.d.ts

@@ -2,7 +2,23 @@ import { ItemContainerProps } from "../../ItemContainer";
 import { InputNumberProps } from "../../../Input/Number";
 import React from "react";
 export interface FormInputNumberProps extends ItemContainerProps {
-    componentProps?: InputNumberProps;
+    /**
+     * `onChange` 的签名比基础组件宽：作为**表单字段**，默认交出的是
+     * `number | null`（见 Bridge 的注释）。写这个回调的人拿到的与表单拿到的
+     * 是同一个值。
+     */
+    componentProps?: Omit<InputNumberProps, "onChange"> & {
+        onChange?: (value: string | number | null) => void;
+    };
+    /**
+     * 交给表单的是字符串而不是数字。默认 `false`。
+     *
+     * 只有真的要处理**超出 IEEE754 安全范围的大数**（订单号、雪花 ID）时才打开
+     * —— 那种值转成 number 会丢精度，必须一路以字符串传递。
+     *
+     * 2.5.0 之前没有这个开关，行为固定等同于 `stringMode`（见下方 Bridge 注释）。
+     */
+    stringMode?: boolean;
 }
 declare const FormInputNumber: React.FC<FormInputNumberProps>;
 export default FormInputNumber;

package/lib/components/FormItem/FormInput/FormInputNumber/index.js

@@ -9,22 +9,83 @@ var _Input = _interopRequireDefault(require("../../../Input"));
 var _react = _interopRequireDefault(require("react"));
 var _jsxRuntime = require("react/jsx-runtime");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+// value / onChange 要重新声明：`InputNumberProps` 上那两个是**基础组件**的
+// 契约（字符串进、字符串出），而这里收的是**表单值**，可以是数字或 null
+
+/**
+ * 夹在 `Form.Item` 与 `Input.Number` 之间，**把字符串换成数字再交给表单**。
+ *
+ * 为什么需要它：`Input.Number` 内部以字符串保存（底层 `stringMode`，为的是不
+ * 丢大数精度），`onChange` 交出的也是字符串。这对一个**基础输入组件**是合理
+ * 的，但对一个叫 INPUTNUMBER 的**表单字段**不合理 —— 表单收上去的值会直接
+ * 进请求体，而后端字段多半是整数：
+ *
+ * ```
+ * 422  invalid type: string "2", expected i32
+ * ```
+ *
+ * 这个坑平时看不见：没动过的字段，值来自详情接口、本来就是数字，原样发回去
+ * 没事；**只有用户真的改了那一格**才会变成字符串。现象是「我明明只改了个
+ * 数字却保存失败」，而且报错在服务端，前端一行日志都没有。
+ *
+ * 转换只在**往上交**的方向做；`Input.Number` 内部仍然是字符串，所以正在敲的
+ * "1." / "1.50" 不会被改写（配套改动见 `Input/Number` 里的 sameNumber 判断）。
+ */
+const Bridge = props => {
+  const {
+    value,
+    onChange,
+    componentOnChange,
+    stringMode,
+    ...rest
+  } = props;
+  const emit = next => {
+    onChange?.(next);
+    componentOnChange?.(next);
+  };
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_Input.default.Number, {
+    ...rest,
+    value: value,
+    onChange: text => {
+      if (stringMode) {
+        emit(text);
+        return;
+      }
+
+      // 空 → null 而不是 ""：语义是「没填」，不是「填了个空字符串」。
+      // 后端 `Option<i32>` 收得下 null，收不下 ""
+      if (text === "" || text === null || text === undefined) {
+        emit(null);
+        return;
+      }
+      const num = Number(text);
+      // 转不动就原样交出去（用户可能正敲到 "-" 或 "1e" 这种中间态）。
+      // 硬转成 NaN 会让表单里躺着一个既非数字也非空的值
+      emit(Number.isFinite(num) ? num : text);
+    }
+  });
+};
 const FormInputNumber = props => {
   const {
     componentProps = {},
     className: itemClassName,
     disabled,
+    stringMode,
     ...formItemProps
   } = props;
+  // onChange 必须摘出来，理由见 BridgeProps.componentOnChange
   const {
     placeholder,
+    onChange: componentOnChange,
     ...inputConfig
   } = componentProps;
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_ItemContainer.default, {
     ...formItemProps,
     className: `${itemClassName ?? ""}`,
-    children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_Input.default.Number, {
+    children: /*#__PURE__*/(0, _jsxRuntime.jsx)(Bridge, {
       ...inputConfig,
+      componentOnChange: componentOnChange,
+      stringMode: stringMode,
       disabled: inputConfig.disabled ?? disabled,
       placeholder: placeholder ?? "请输入"
     })

package/lib/components/Input/Number/index.d.ts

@@ -3,7 +3,11 @@ import React from "react";
 export interface InputNumberProps extends Omit<AntdInputNumberProps, "ref" | "onChange" | "value"> {
     getRef?: (ref: HTMLInputElement | null) => void;
     onChange?: (value: string) => void;
-    value?: string;
+    /**
+     * 受控值。本组件内部**始终以字符串保存**（底层开了 antd 的 `stringMode`，
+     * 为的是不丢大数精度），但外部传数字进来也接得住。
+     */
+    value?: string | number | null;
     allowClear?: boolean;
     wrapperClassName?: string;
 }

package/lib/components/Input/Number/index.js

@@ -50,16 +50,33 @@ const InputNumber = props => {
     // Update internal state only when the external value prop actually changes
     if (prevValueRef.current !== value) {
       prevValueRef.current = value;
-      if (value !== undefined) {
+
+      // 数值相等就不要回写文本。
+      //
+      // 上游把值转成数字之后（`FormItem` 的 INPUTNUMBER 默认就会转），一个
+      // 回环会打回来：输入 "1." → onChange → 表单存 1 → value={1} 传回来。
+      // 若照单全收地写成 "1"，用户刚敲的小数点当场消失、光标还会跳到末尾，
+      // "1.50" 也会被改写成 "1.5"。
+      //
+      // 判据用**数值相等**而不是字符串相等：这几种写法（"1." / "1.50" / "+1"）
+      // 表示的是同一个数，此时以用户正在敲的那份文本为准。
+      const sameNumber = value !== undefined && value !== null && _value !== "" && Number(value) === Number(_value);
+      if (sameNumber) {
+        // 只同步「已提交值」，不动正在编辑的文本
+        setLastValue(_value);
+      } else if (value !== undefined && value !== null) {
         const newValue = typeof value === "number" ? `${value}` : value?.toString();
         setValue(newValue);
         setLastValue(newValue);
       } else {
-        // Clear only on initialization or when explicitly set to undefined externally
+        // Clear only on initialization or when explicitly set to undefined/null externally
         setValue("");
         setLastValue("");
       }
     }
+    // `_value` 是刻意不进依赖的：这个 effect 只该在**外部** value 变化时跑，
+    // 把它加进来会让每次键入都重跑一遍，等于绕过上面那个 prevValueRef 判断
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [value]);
   (0, _react.useEffect)(() => {
     getRef?.(ref.current);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hsu-react/ui",
-  "version": "2.4.9",
+  "version": "2.5.0",
   "description": "一套基于 React + Ant Design 的中后台业务组件库",
   "license": "MIT",
   "type": "module",

package/src/components/FormItem/FormInput/FormInputNumber/index.tsx

@@ -5,22 +5,114 @@ import { InputNumberProps } from "../../../Input/Number";
 import React from "react";
 
 export interface FormInputNumberProps extends ItemContainerProps {
-  componentProps?: InputNumberProps;
+  /**
+   * `onChange` 的签名比基础组件宽：作为**表单字段**，默认交出的是
+   * `number | null`（见 Bridge 的注释）。写这个回调的人拿到的与表单拿到的
+   * 是同一个值。
+   */
+  componentProps?: Omit<InputNumberProps, "onChange"> & {
+    onChange?: (value: string | number | null) => void;
+  };
+  /**
+   * 交给表单的是字符串而不是数字。默认 `false`。
+   *
+   * 只有真的要处理**超出 IEEE754 安全范围的大数**（订单号、雪花 ID）时才打开
+   * —— 那种值转成 number 会丢精度，必须一路以字符串传递。
+   *
+   * 2.5.0 之前没有这个开关，行为固定等同于 `stringMode`（见下方 Bridge 注释）。
+   */
+  stringMode?: boolean;
 }
 
+// value / onChange 要重新声明：`InputNumberProps` 上那两个是**基础组件**的
+// 契约（字符串进、字符串出），而这里收的是**表单值**，可以是数字或 null
+type BridgeProps = Omit<InputNumberProps, "value" | "onChange"> & {
+  /** antd Form.Item 注入 */
+  value?: string | number | null;
+  /** antd Form.Item 注入 */
+  onChange?: (value: string | number | null) => void;
+  /**
+   * 使用方写在 `componentProps.onChange` 里的那个回调。
+   *
+   * 单独接出来、不跟着 `componentProps` 一起展开：展开的话它会盖掉
+   * Form.Item 注入的那个 onChange，字段值就再也传不到表单里了。
+   * 它拿到的与表单拿到的**是同一个值**（默认已转成数字）。
+   */
+  componentOnChange?: (value: string | number | null) => void;
+  stringMode?: boolean;
+};
+
+/**
+ * 夹在 `Form.Item` 与 `Input.Number` 之间，**把字符串换成数字再交给表单**。
+ *
+ * 为什么需要它：`Input.Number` 内部以字符串保存（底层 `stringMode`，为的是不
+ * 丢大数精度），`onChange` 交出的也是字符串。这对一个**基础输入组件**是合理
+ * 的，但对一个叫 INPUTNUMBER 的**表单字段**不合理 —— 表单收上去的值会直接
+ * 进请求体，而后端字段多半是整数：
+ *
+ * ```
+ * 422  invalid type: string "2", expected i32
+ * ```
+ *
+ * 这个坑平时看不见：没动过的字段，值来自详情接口、本来就是数字，原样发回去
+ * 没事；**只有用户真的改了那一格**才会变成字符串。现象是「我明明只改了个
+ * 数字却保存失败」，而且报错在服务端，前端一行日志都没有。
+ *
+ * 转换只在**往上交**的方向做；`Input.Number` 内部仍然是字符串，所以正在敲的
+ * "1." / "1.50" 不会被改写（配套改动见 `Input/Number` 里的 sameNumber 判断）。
+ */
+const Bridge: React.FC<BridgeProps> = (props) => {
+  const { value, onChange, componentOnChange, stringMode, ...rest } = props;
+
+  const emit = (next: string | number | null) => {
+    onChange?.(next);
+    componentOnChange?.(next);
+  };
+
+  return (
+    <Input.Number
+      {...rest}
+      value={value}
+      onChange={(text) => {
+        if (stringMode) {
+          emit(text);
+          return;
+        }
+
+        // 空 → null 而不是 ""：语义是「没填」，不是「填了个空字符串」。
+        // 后端 `Option<i32>` 收得下 null，收不下 ""
+        if (text === "" || text === null || text === undefined) {
+          emit(null);
+          return;
+        }
+
+        const num = Number(text);
+        // 转不动就原样交出去（用户可能正敲到 "-" 或 "1e" 这种中间态）。
+        // 硬转成 NaN 会让表单里躺着一个既非数字也非空的值
+        emit(Number.isFinite(num) ? num : text);
+      }}
+    />
+  );
+};
+
 const FormInputNumber: React.FC<FormInputNumberProps> = (props) => {
   const {
     componentProps = {},
     className: itemClassName,
     disabled,
+    stringMode,
     ...formItemProps
   } = props;
-  const { placeholder, ...inputConfig } = componentProps;
+  // onChange 必须摘出来，理由见 BridgeProps.componentOnChange
+  const { placeholder, onChange: componentOnChange, ...inputConfig } =
+    componentProps;
 
   return (
     <ItemContainer {...formItemProps} className={`${itemClassName ?? ""}`}>
-      <Input.Number
+      <Bridge
         {...inputConfig}
+        componentOnChange={componentOnChange}
+        stringMode={stringMode}
         disabled={inputConfig.disabled ?? disabled}
         placeholder={placeholder ?? "请输入"}
       />

package/src/components/FormItem/index.md

@@ -93,6 +93,22 @@ export default () => (
 );
 ```
 
+> **`2.5.0` 起，`INPUTNUMBER` 交给表单的是 `number | null`**（此前是字符串）。
+>
+> 表单值往往原样进请求体，而后端字段多半是整数，交字符串上去会被强类型服务端
+> 拒掉（Rust/serde 会回 `invalid type: string "2", expected i32`）。这个问题
+> 平时看不见：**没动过的字段**值来自详情接口、本来就是数字，只有用户真的改了
+> 那一格才会变成字符串 —— 现象是「我只改了个数字却保存失败」。
+>
+> - 空值交出的是 `null`（「没填」），不是 `""`。
+> - 敲到一半的中间态（`-`、`1e`）原样交出，不会变成 `NaN`。
+> - 正在输入的文本不会被回写打断，`1.` / `1.50` 都保得住。
+> - 确实需要字符串（大数不丢精度）时，加 `stringMode`：
+>
+> ```tsx
+> <FormItem type="INPUTNUMBER" name="orderNo" label="订单号" stringMode />
+> ```
+
 ## 范围输入
 
 ```tsx

package/src/components/Input/Number/index.tsx

@@ -17,7 +17,11 @@ export interface InputNumberProps extends Omit<
 > {
   getRef?: (ref: HTMLInputElement | null) => void;
   onChange?: (value: string) => void;
-  value?: string;
+  /**
+   * 受控值。本组件内部**始终以字符串保存**（底层开了 antd 的 `stringMode`，
+   * 为的是不丢大数精度），但外部传数字进来也接得住。
+   */
+  value?: string | number | null;
   allowClear?: boolean;
   wrapperClassName?: string;
 }
@@ -76,17 +80,38 @@ const InputNumber: React.FC<InputNumberProps> = (props) => {
     if (prevValueRef.current !== value) {
       prevValueRef.current = value;
 
-      if (value !== undefined) {
+      // 数值相等就不要回写文本。
+      //
+      // 上游把值转成数字之后（`FormItem` 的 INPUTNUMBER 默认就会转），一个
+      // 回环会打回来：输入 "1." → onChange → 表单存 1 → value={1} 传回来。
+      // 若照单全收地写成 "1"，用户刚敲的小数点当场消失、光标还会跳到末尾，
+      // "1.50" 也会被改写成 "1.5"。
+      //
+      // 判据用**数值相等**而不是字符串相等：这几种写法（"1." / "1.50" / "+1"）
+      // 表示的是同一个数，此时以用户正在敲的那份文本为准。
+      const sameNumber =
+        value !== undefined &&
+        value !== null &&
+        _value !== "" &&
+        Number(value) === Number(_value);
+
+      if (sameNumber) {
+        // 只同步「已提交值」，不动正在编辑的文本
+        setLastValue(_value);
+      } else if (value !== undefined && value !== null) {
         const newValue =
           typeof value === "number" ? `${value}` : value?.toString();
         setValue(newValue);
         setLastValue(newValue);
       } else {
-        // Clear only on initialization or when explicitly set to undefined externally
+        // Clear only on initialization or when explicitly set to undefined/null externally
         setValue("");
         setLastValue("");
       }
     }
+    // `_value` 是刻意不进依赖的：这个 effect 只该在**外部** value 变化时跑，
+    // 把它加进来会让每次键入都重跑一遍，等于绕过上面那个 prevValueRef 判断
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [value]);
 
   useEffect(() => {

package/src/components/Input/index.md

@@ -36,7 +36,15 @@ export default () => {
 
 ## 数字输入框
 
-数字输入框，`onChange` 返回字符串，内置 `allowClear`、`controls={false}` 与 `stringMode`。
+数字输入框，`onChange` 返回**字符串**，内置 `allowClear`、`controls={false}` 与 `stringMode`。
+
+返回字符串是刻意的：`stringMode` 让超出 IEEE754 安全范围的大数（订单号、雪花 ID）
+不丢精度，而转成 `number` 就丢了。
+
+> **注意**：作为**表单字段**用时（`FormItem type="INPUTNUMBER"`）行为不同 ——
+> 自 `2.5.0` 起它交给表单的是 `number | null`。表单值通常会直接进请求体，
+> 而后端字段多半是整数，交字符串上去会被强类型服务端拒掉。
+> 详见 [FormItem 的 INPUTNUMBER](/components/form-item)。
 
 ```tsx
 import React from "react";