@arco-design/mobile-react 2.29.6 → 2.30.1

package/dist/index.js

@@ -111,27 +111,151 @@
     }
 
     var opt = Object.prototype.toString;
+    /**
+     * 判断一个对象是否为数组类型
+     * @desc {en} Whether it is an array
+     * @param {any} obj 入参
+     * @param {any} obj {en} Entering
+     * @returns {boolean} 返回是否为数组类型
+     * @returns {boolean} {en} Returns whether it is an array type
+     * @example
+     * ```
+     * import { isArray } from '@arco-design/mobile-utils';
+     *
+     * const test = isArray([]);
+     * ```
+     */
+
     function isArray(obj) {
       return opt.call(obj) === '[object Array]';
     }
+    /**
+     * 判断一个对象是否为对象类型
+     * @desc {en} Whether it is an object
+     * @param {any} obj 入参
+     * @param {any} obj {en} Entering
+     * @returns {boolean} 返回是否为对象类型
+     * @returns {boolean} {en} Returns whether it is an object type
+     * @example
+     * ```
+     * import { isObject } from '@arco-design/mobile-utils';
+     *
+     * const test = isObject({});
+     * ```
+     */
+
     function isObject$2(obj) {
       return opt.call(obj) === '[object Object]';
     }
+    /**
+     * 判断一个对象是否为字符串类型
+     * @desc {en} Whether it is an string
+     * @param {any} obj 入参
+     * @param {any} obj {en} Entering
+     * @returns {boolean} 返回是否为字符串类型
+     * @returns {boolean} {en} Returns whether it is an string type
+     * @example
+     * ```
+     * import { isString } from '@arco-design/mobile-utils';
+     *
+     * const test = isString('');
+     * ```
+     */
+
     function isString(obj) {
       return opt.call(obj) === '[object String]';
     }
+    /**
+     * 检查一个值是否在给定的有效值列表中
+     * @desc {en} Checks whether a value is in the given list of valid values
+     * @param {T} value 检查的值
+     * @param {T} value {en} value to check
+     * @param {T[]} validList 有效值列表
+     * @param {T[]} validList {en} List of valid values
+     * @returns {boolean} 返回要检查的值是否在有效值列表中
+     * @returns {boolean} {en} Returns whether the value to be checked is in the list of valid values
+     * @example
+     * ```
+     * import { isOneOf } from '@arco-design/mobile-utils';
+     *
+     * const test = isOneOf(1, [1, 2, 3]);
+     * ```
+     */
+
     function isOneOf(value, validList) {
       return validList.indexOf(value) !== -1;
     }
+    /**
+     * 检查一个值是否为空值
+     * @desc {en} Check if a value is null
+     * @param {any} obj 入参
+     * @param {any} obj {en} Entering
+     * @returns {boolean} 返回该值是否为空值
+     * @returns {boolean} {en} Returns whether the value is null
+     * @example
+     * ```
+     * import { isEmptyValue } from '@arco-design/mobile-utils';
+     *
+     * const test = isEmptyValue(null);
+     * ```
+     */
+
     function isEmptyValue(obj) {
       return obj === undefined || obj === null || obj === '';
     }
+    /**
+     * 检查一个值是否为函数类型
+     * @desc {en} Check if a value is function
+     * @param {unknown} obj 入参
+     * @param {unknown} obj {en} Entering
+     * @returns {boolean} 返回该值是否为函数
+     * @returns {boolean} {en} Returns whether the value is function
+     * @example
+     * ```
+     * import { isFunction } from '@arco-design/mobile-utils';
+     *
+     * const test = isFunction(() => {});
+     * ```
+     */
+
     function isFunction(obj) {
       return Object.prototype.toString.call(obj).toLowerCase() === '[object function]';
     }
+    /**
+     * 检查一个值是否为空数组
+     * @desc {en} Check if a value is an empty array
+     * @param {Array<unknown>} obj 入参
+     * @param {Array<unknown>} obj {en} Entering
+     * @returns {boolean} 返回该值是否为空数组
+     * @returns {boolean} {en} Returns whether the value is an empty array
+     * @example
+     * ```
+     * import { isEmptyArray } from '@arco-design/mobile-utils';
+     *
+     * const test = isEmptyArray([]);
+     * ```
+     */
+
     function isEmptyArray(obj) {
       return isArray(obj) && !(obj === null || obj === void 0 ? void 0 : obj.length);
     }
+    /**
+     * 深比较两个对象是否相等
+     * @desc {en} Check if a value is an empty array
+     * @param {any} obj 要比较的第一个对象
+     * @param {any} obj {en} the first object to compare
+     * @param {any} obj 要比较的第二个对象
+     * @param {any} obj {en} the second object to be compared
+     * @returns {boolean} 返回两个对象是否相等
+     * @returns {boolean} {en} Returns whether two objects are equal
+     * @example
+     * ```
+     * import { isDeepEqual } from '@arco-design/mobile-utils';
+     *
+     * const test = isDeepEqual({a: 1}, {a: 1});
+     * ```
+     */
+
     function isDeepEqual(obj, sub) {
       if (typeof obj !== 'object' || typeof sub !== 'object' || obj === null || sub === null) {
         return obj === sub;
@@ -152,6 +276,23 @@
       return true;
     }
 
+    /**
+     * @type utils
+     * @name classnames
+     */
+    /**
+     * 将传入的值转为class字符串
+     * @param args 字符串，字符串数组，对象，undefined，null，boolean
+     * @param args {en} string, string[], object, undefined, null, boolean
+     * @returns class字符串
+     * @returns {en} class string
+     * @example
+     * import { cls } from '@arco-design/mobile-utils';
+     *
+     * <div className={cls('a', 'b', { ok: true })} />
+     * // result: <div class="a b ok"></div>
+     */
+
     function cls () {
       var args = [];
 
@@ -263,6 +404,33 @@
     function LinearEasing(x) {
       return x;
     }
+    /**
+     * 获取一个用于计算贝塞尔曲线的函数
+     * @desc {en} Gets a function used to calculate Bezier curves
+     * @param mX1 第一个点的x坐标
+     * @param mX1 {en} The X coordinate of first point
+     * @param mY1 第一个点的y坐标
+     * @param mY1 {en} The Y coordinate of first point
+     * @param mX2 第二个点的x坐标
+     * @param mX2 {en} The X coordinate of second point
+     * @param mY2 第二个点的y坐标
+     * @param mY2 {en} The Y coordinate of second point
+     * @returns 计算贝塞尔曲线的函数
+     * @returns {function} {en} The function of calculating bezier curve
+     * @example
+     * ```
+     * import { bezierEasing } from '@arco-design/mobile-utils';
+     *
+     * const p = (Date.now() - start) / duration;
+     * if (p > 1) {
+     *     scrollTo(targetTop);
+     * } else {
+     *     const newTop = initTop + (targetTop - initTop) * bezierEasing(0.34, 0.69, 0.1, 1)(p);
+     *     scrollTo(newTop);
+     * }
+     * ```
+     */
+
 
     function bezier(mX1, mY1, mX2, mY2) {
       if (!(mX1 >= 0 && mX1 <= 1 && mX2 >= 0 && mX2 <= 1)) {
@@ -316,9 +484,63 @@
       };
     }
 
+    /**
+     * 阻止 TouchEvent 事件的默认行为
+     * @desc {en} Stops the default behavior of a TouchEvent
+     * @param {TouchEvent} e 要阻止的 TouchEvent 事件
+     * @param {TouchEvent} e {en} The TouchEvent to stop
+     * @returns {void}
+     * @example
+     * ```
+     * import { stopTouch } from '@arco-design/mobile-utils';
+     *
+     * // Before calling stopTouch
+     * const touchEvent = new TouchEvent("touchstart", { cancelable: true });
+     * console.log(touchEvent.defaultPrevented); // false
+     *
+     * // Call stopTouch to prevent the default behavior
+     * stopTouch(touchEvent);
+     *
+     * // After calling stopTouch
+     * console.log(touchEvent.defaultPrevented); // true
+     * ```
+     */
+
     function stopTouch(e) {
+      // If the TouchEvent is cancelable, prevent it's default behavior using preventDefault
       e.cancelable && e.preventDefault();
     }
+    /**
+     * 阻止元素滚动
+     * @desc {en} Prevents an element from scrolling
+     * @param scrollContainer 滚动容器的函数，默认为 document.body
+     * @param scrollContainer {en} A function that returns the scroll container, defaults to document.body
+     * @param preventWindow 是否阻止窗口滚动
+     * @param preventWindow {en} Whether to prevent window scrolling
+     * @param customStopTouch 自定义停止触摸事件的函数
+     * @param customStopTouch {en} A custom function to stop touch events
+     * @example
+     * ```
+     * import { preventEleScroll } from '@arco-design/mobile-utils';
+     *
+     * // Example 1: Prevent scrolling in the entire document body
+     * preventEleScroll();
+     *
+     * // Example 2: Prevent scrolling in a specific element
+     * preventEleScroll(() => document.getElementById('myScrollableElement'));
+     *
+     * // Example 3: Prevent scrolling in a specific element with custom touch event handling
+     * preventEleScroll(
+     *   () => document.getElementById('myScrollableElement'),
+     *   false,
+     *   (e) => {
+     *     // Custom touch event handling logic here
+     *     e.preventDefault();
+     *   }
+     * );
+     * ```
+     */
+
     function preventEleScroll(scrollContainer, preventWindow, customStopTouch) {
       if (scrollContainer === void 0) {
         scrollContainer = function scrollContainer() {
@@ -340,6 +562,37 @@
         capture: true
       });
     }
+    /**
+     * 允许元素滚动
+     * @desc {en} Allows an element to scroll
+     * @param scrollContainer 滚动容器的函数，默认为 document.body
+     * @param scrollContainer {en} A function that returns the scroll container, defaults to document.body
+     * @param preventWindow 是否阻止窗口滚动
+     * @param preventWindow {en} Whether to prevent window scrolling
+     * @param customStopTouch 自定义停止触摸事件的函数
+     * @param customStopTouch {en} A custom function to stop touch events
+     * @example
+     * ```
+     * import { freeEleScroll } from '@arco-design/mobile-utils';
+     *
+     * // Example 1: Allow scrolling in the entire document body
+     * freeEleScroll();
+     *
+     * // Example 2: Allow scrolling in a specific element
+     * freeEleScroll(() => document.getElementById('myScrollableElement'));
+     *
+     * // Example 3: Allow scrolling in a specific element with custom touch event handling
+     * freeEleScroll(
+     *   () => document.getElementById('myScrollableElement'),
+     *   false,
+     *   (e) => {
+     *     // Custom touch event handling logic here
+     *     // You can choose to call e.preventDefault() or not based on your needs
+     *   }
+     * );
+     * ```
+     */
+
     function freeEleScroll(scrollContainer, preventWindow, customStopTouch) {
       if (scrollContainer === void 0) {
         scrollContainer = function scrollContainer() {
@@ -362,9 +615,38 @@
     }
     /**
      * 判断父节点是否包含子节点
-     * @desc {en} comfirm parentNode contains children nodes
-     * @param parentEl 父节点
-     * @param childrenEl 子节点
+     * @desc {en} confirm parentNode contains children nodes
+     * @param {HTMLElement | null} parentEl 父节点
+     * @param {HTMLElement | null} parentEl {en} The parent element
+     * @param {HTMLElement | null} childrenEl 子节点
+     * @param {HTMLElement | null} childrenEl {en} The child element
+     * @returns {boolean} 是否包含子节点
+     * @returns {boolean} {en} Whether the parent contains the child
+     * @example
+     * ```
+     * import { isContains } from '@arco-design/mobile-utils';
+     *
+     * // Example 1: When the parent contains the direct child
+     * const parentElement = document.getElementById('parent');
+     * const childElement = document.getElementById('directChild');
+     * const result1 = isContains(parentElement, childElement);
+     * console.log(result1); // Output: true
+     * // Explanation: In this example, the parent element (#parent) contains a direct child element (#directChild).
+     *
+     * // Example 2: When the parent contains an indirect child
+     * const grandparentElement = document.getElementById('grandparent');
+     * const indirectChildElement = document.getElementById('indirectChild');
+     * const result2 = isContains(grandparentElement, indirectChildElement);
+     * console.log(result2); // Output: true
+     * // Explanation: Here, the grandparent element (#grandparent) contains an indirect child element (#indirectChild) nested within other elements.
+     *
+     * // Example 3: When the parent does not contain the child
+     * const unrelatedParent = document.getElementById('unrelatedParent');
+     * const unrelatedChild = document.getElementById('unrelatedChild');
+     * const result3 = isContains(unrelatedParent, unrelatedChild);
+     * console.log(result3); // Output: false
+     * // Explanation: In this case, the unrelated parent element (#unrelatedParent) and unrelated child element (#unrelatedChild) are not related in the DOM structure.
+     * ```
      */
 
     function isContains(parentEl, childrenEl) {
@@ -386,13 +668,79 @@
 
       return false;
     }
+    /**
+     * 使用 requestAnimationFrame 执行函数，如果不支持则使用 setTimeout 作为兜底
+     * @desc {en} Executes a function using requestAnimationFrame, if not supported, falls back to setTimeout
+     * @param {Function} fn 需要执行的函数
+     * @param {Function} fn {en} the function to be executed
+     * @returns {number} 返回 requestAnimationFrame 或 setTimeout 的 ID
+     * @returns {number} {en} returns the ID of requestAnimationFrame or setTimeout
+     * @example
+     * ```
+     * import { execRAF } from '@arco-design/mobile-utils';
+     *
+     * // Example 1: Using requestAnimationFrame
+     * const rafId = execRAF(() => {
+     *   console.log("Using requestAnimationFrame");
+     * });
+     * console.log(rafId); // Output: A numerical ID representing the requestAnimationFrame callback
+     * // Explanation:
+     * // This example demonstrates using `execRAF` with `requestAnimationFrame` to execute a function.
+     * // `requestAnimationFrame` is typically used for animations and smooth updates.
+     * // The ID returned by `requestAnimationFrame` is logged, which can be useful for canceling the animation frame if needed.
+     *
+     * // Example 2: Using setTimeout as a fallback
+     * const setTimeoutId = execRAF(() => {
+     *   console.log("Using setTimeout as a fallback");
+     * });
+     * console.log(setTimeoutId); // Output: A numerical ID representing the setTimeout callback
+     * // Explanation:
+     * // In situations where the browser does not support `requestAnimationFrame`,
+     * // `execRAF` falls back to using `setTimeout` with a delay of approximately 17 milliseconds (equivalent to a frame rate of 60 frames per second).
+     * // The ID returned by `setTimeout` is logged, allowing you to manage the execution of the function, even in browsers without `requestAnimationFrame` support.
+     * ```
+     */
+
     function execRAF(fn) {
       try {
         return requestAnimationFrame(fn);
       } catch (e) {
+        // Note that the delay time for setTimeout is 17 milliseconds, which is approximately equivalent to a frame rate of 60 frames per second.
+        // This is a good fallback option because requestAnimationFrame also typically runs at a rate of about 60 frames per second.
         return setTimeout(fn, 17);
       }
     }
+    /**
+     * 使用动画滚动页面
+     * @desc {en} Scroll the page with animation
+     * @param {number} initTop 初始滚动位置（像素）
+     * @param {number} initTop {en} Initial scroll position (in pixels)
+     * @param {number} target 目标滚动位置（像素）
+     * @param {number} target {en} Target scroll position (in pixels)
+     * @param {function} scrollTo 滚动函数
+     * @param {function} scrollTo {en} Scroll function
+     * @param {number} duration 动画持续时间（毫秒）
+     * @param {number} duration {en} Animation duration (in milliseconds)
+     * @param {Array<number>} bezier 贝塞尔曲线参数
+     * @param {Array<number>} bezier {en} Bezier curve parameters
+     * @param {'by'|'to'} type 滚动类型：'by'表示相对滚动，'to'表示绝对滚动
+     * @param {'by'|'to'} type {en} Scroll type: 'by' for relative scrolling, 'to' for absolute scrolling
+     * @example
+     * ```
+     * import { scrollWithAnimation } from '@arco-design/mobile-utils';
+     *
+     * // Scroll to 500px from the current position over 1 second
+     * scrollWithAnimation(
+     *   window.pageYOffset,
+     *   500,
+     *   (top) => window.scrollTo({ top }),
+     *   1000,
+     *   [0.34, 0.69, 0.1, 1],
+     *   'to'
+     * );
+     * ```
+     */
+
     function scrollWithAnimation(initTop, target, scrollTo, duration, bezier$1, type) {
       if (duration === void 0) {
         duration = 300;
@@ -428,6 +776,26 @@
      * @desc {en} Returns the node's document properties
      * @param {HTMLElement} node dom 节点
      * @param {HTMLElement} node {en} dom Node
+     * @returns {HTMLElement | Document | null} 返回节点的最近可滚动父节点或 document 对象
+     * @returns {HTMLElement | Document | null} {en} Returns the nearest scrollable parent node of the node or the document object
+     * @example
+     * ```
+     * import { scrollParent } from '@arco-design/mobile-utils';
+     *
+     * // Example 1: Finding the scroll parent of a DOM node
+     * const targetNode = document.getElementById('targetElement');
+     * const scrollParentNode = scrollParent(targetNode);
+     * console.log(scrollParentNode); // Output: The nearest scrollable parent element or the document
+     * // Explanation:
+     * // This example demonstrates how to use the `scrollParent` function to find the nearest scrollable parent element of a given DOM node.
+     * // It returns the nearest scrollable parent element, or if none is found, it returns the document.
+     *
+     * // Example 2: Finding the scroll parent of the document body
+     * const bodyNode = document.body;
+     * const scrollParentBody = scrollParent(bodyNode);
+     * console.log(scrollParentBody); // Output: The document's HTML element (document.documentElement)
+     * // Explanation: In this scenario, we use the `scrollParent` function to find the scrollable parent of the document body.
+     * ```
      */
 
     function scrollParent(node) {
@@ -464,6 +832,17 @@
      * @desc {en} Get element offset
      * @param {HTMLElement} node dom 节点
      * @param {HTMLElement} node {en} Dom node
+     * @example
+     * ```
+     * import { getOffset } from '@arco-design/mobile-utils';
+     *
+     * const element = document.getElementById('exampleElement');
+     * const offset = getOffset(element);
+     * console.log('Element Width:', offset.width);
+     * console.log('Element Height:', offset.height);
+     * console.log('Element Top Offset:', offset.top);
+     * console.log('Element Left Offset:', offset.left);
+     * ```
      */
 
     function getOffset(node) {
@@ -492,6 +871,22 @@
         left: left
       };
     }
+    /**
+     * 格式化偏移量
+     * Format the offset
+     * @param {Array|number} offset 输入的偏移量，可以是一个数字或者一个长度为2或4的数组
+     * @param {Array|number} offset {en} The input offset, which can be a number or an array of length 2 or 4
+     * @returns {Array} 返回一个长度为4的数组，表示上、右、下、左四个方向的偏移量
+     * @returns {Array} {en} Returns an array of length 4, representing the offsets in the top, right, bottom, and left directions
+     * @example
+     * ```
+     * import { formatOffset } from '@arco-design/mobile-utils';
+     *
+     * console.log(formatOffset(10)) // output: [10, 10, 10, 10]
+     * console.log(formatOffset([10, 20])) // output: [10, 0, 20, 0]
+     * console.log(formatOffset([10, 20, 30, 40])) // output: [10, 20, 30, 40]
+     * ```
+     */
 
     function formatOffset(offset) {
       var offsets;
@@ -515,6 +910,18 @@
      * @param component {en} Current element node
      * @param parent 当前元素所在容器 dom 节点
      * @param parent {en} The dom node of the container where the current element is located
+     * @example
+     * ```
+     * import { checkOverflowVisible } from '@arco-design/mobile-utils';
+     *
+     * const component = {
+     *   node: document.getElementById('myComponent'),
+     *   offset: 20, // Set the offset value
+     *   threshold: 0.5, // Set the threshold value
+     * }
+     * const myParent = document.getElementById('myParent');
+     * const isVisible = checkOverflowVisible(component, myParent);
+     * ```
      */
 
 
@@ -552,8 +959,30 @@
     /**
      * 检查非局部滚动容器元素是否在视口区域内
      * @desc {en} Check if a non-local scroll container element is inside the viewport area
-     * @param component 当前元素节节点
+     * @param component 当前元素节点
      * @param component {en} Current element node
+     * @returns {boolean} 如果元素可见，则返回 true，否则返回 false。
+     * @returns {boolean} {en} Returns true if the element is visible, otherwise returns false.
+     * @example
+     * ```
+     * import { checkNormalVisible } from '@arco-design/mobile-utils';
+     *
+     * // Example usage:
+     * const element = document.getElementById('myElement');
+     *
+     * // Make sure to set the offset and threshold values to actual values that suit your use case.
+     * const isVisible = checkNormalVisible({
+     *   node: element,
+     *   offset: 20, // Set the offset value
+     *   threshold: 0.5, // Set the threshold value
+     * });
+     *
+     * if (isVisible) {
+     *   console.log('The element is in the viewport area');
+     * } else {
+     *   console.log('The element is not in the viewport area');
+     * }
+     * ```
      */
 
     function checkNormalVisible(component) {
@@ -589,6 +1018,17 @@
      * @param id {en} added dom id
      * @param getContainer 被添加元素的父级
      * @param getContainer {en} The parent of the added element
+     * @example
+     * ```
+     * import { appendElementById } from '@arco-design/mobile-utils';
+     *
+     * // Example 1: Add a div element with the id "myDiv" to the body.
+     * const { child, container } = appendElementById("myDiv");
+     *
+     * // Example 2: Add a div element with the id "customDiv" to a specific container.
+     * const customContainer = document.getElementById("customContainer");
+     * const { child, container } = appendElementById("customDiv", () => customContainer);
+     * ```
      */
 
     function appendElementById(id, getContainer) {
@@ -602,10 +1042,19 @@
       };
     }
     /**
-     * 从父级节点移除元素
+     * 从父级节点移除该元素
      * @desc {en} Remove element from parent node
      * @param ele 待移除元素
      * @param ele {en} Element to be removed
+     * @example
+     * ```
+     * import { removeElement } from '@arco-design/mobile-utils';
+     *
+     * // HTML: <div id="myElement">This is a div</div>
+     * const elementToRemove = document.getElementById('myElement');
+     * // The element with ID 'myElement' will be removed from the DOM
+     * removeElement(elementToRemove);
+     * ```
      */
 
     function removeElement(ele) {
@@ -613,10 +1062,37 @@
         ele.parentNode.removeChild(ele);
       }
     }
+    /**
+     * 获取滚动容器，如果传入 string 则使用 querySelector 选取容器
+     * @desc {en} Get the scrolling container. If a string is passed in, use querySelector to select the container
+     * @param getContainer 指定滚动容器
+     * @param getContainer {en} Specifies the scrolling container.
+     * @example
+     * ```
+     * import { getActualContainer } from '@arco-design/mobile-utils';
+     *
+     * const customContainer = document.getElementById("customContainer");
+     * const actualContainer = getActualContainer(() => customContainer);
+     * ```
+     */
+
     function getActualContainer(getContainer) {
       var container = getContainer ? getContainer() : void 0;
       return typeof container === 'string' ? document.querySelector(container) : container;
     }
+    /**
+     * 获取有效滚动监听容器，默认情况或者监听 body 的滚动时均指定为 window
+     * @desc {en} Get the effective scrolling container, which is specified as window by default or for listening to the scrolling of the body
+     * @param getContainer 指定滚动容器
+     * @param getContainer {en} Specifies the scrolling container.
+     * @example
+     * ```
+     * import { getValidScrollContainer } from '@arco-design/mobile-utils';
+     *
+     * const customContainer = document.getElementById("customContainer");
+     * const validScrollContainer = getValidScrollContainer(() => customContainer);
+     */
+
     function getValidScrollContainer(getContainer) {
       // 默认为window
       // @en Default is window
@@ -625,6 +1101,22 @@
 
       return originContainer === document.body ? window : originContainer;
     }
+    /**
+     * 获取滚动容器的属性。针对 window 和 document 额外进行一些属性兼容处理。
+     * @desc {en} Get properties of the scrolling container. Perform additional attribute compatibility processing for window and document.
+     * @param property 所需属性
+     * @param property {en} Required attributes
+     * @param {() => HTMLElement | Window | Document | null} getContainer 待计算滚动容器
+     * @param getContainer {en} Scrolling container to be calculated.
+     * @example
+     * ```
+     * import { getScrollContainerAttribute } from '@arco-design/mobile-utils';
+     *
+     * const contentRef = useRef<HTMLDivElement>(null);
+     * const scrollTop = getScrollContainerAttribute('scrollTop', () => contentRef.current);
+     * ```
+     */
+
     function getScrollContainerAttribute(property, getContainer) {
       var container = getContainer ? getContainer() : window;
       if (!container) return 0;
@@ -652,6 +1144,20 @@
 
       return container[property];
     }
+    /**
+     * 提供了元素的大小及其相对于视口的位置。
+     * @desc {en} Provide information about the size of an element and its position relative to the viewport.
+     * @param {HTMLElement | Window | null} container 滚动容器
+     * @param container {en} Scroll Container
+     * @example
+     * ```
+     * import { getScrollContainerAttribute } from '@arco-design/mobile-utils';
+     *
+     * const contentRef = useRef<HTMLDivElement>(null);
+     * const scrollTop = getScrollContainerAttribute('scrollTop', () => contentRef.current);
+     * ```
+     */
+
     function getScrollContainerRect(container) {
       var containerRect = {
         top: 0,
@@ -689,6 +1195,19 @@
       };
     }
     var styleDoms = {};
+    /**
+     * 删除自定义 style 标签，配合 addCssStyleDom 函数一起使用
+     * @desc {en} Remove custom style tags and use it in conjunction with the addCssStyleDom function
+     * @param key 标签对应的key
+     * @param key {en} Key corresponding to the tag
+     * @example
+     * ```
+     * import { removeCssStyleDom } from '@arco-design/mobile-utils';
+     *
+     * removeCssStyleDom('arcoTheme');
+     * ```
+     */
+
     function removeCssStyleDom(key) {
       var styleDom = styleDoms[key];
 
@@ -697,6 +1216,21 @@
         delete styleDoms[key];
       }
     }
+    /**
+     * 添加自定义 style 标签，addCssKeyframes 和 addCssRules 的底层方法
+     * @desc {en} Add custom style tags, underlying methods for addCssKeyframes and addCssRules
+     * @param key 标签对应的key
+     * @param key {en} Key corresponding to the tag
+     * @param html 样式内容
+     * @param html {en} style information (CSS)
+     * @example
+     * ```
+     * import { addCssStyleDom } from '@arco-design/mobile-utils';
+     *
+     * addCssStyleDom('arcoTheme', ':root {--base-font-size: 50;}');
+     * ```
+     */
+
     function addCssStyleDom(key, html) {
       removeCssStyleDom(key);
       var style = document.createElement('style');
@@ -704,9 +1238,53 @@
       document.documentElement.appendChild(style);
       styleDoms[key] = style;
     }
+    /**
+     * 增加自定义关键帧动画变量，实现动画函数复用。
+     * @desc {en} Add custom keyframe animation variables to achieve reuse of animation functions
+     * @param key 规则名称
+     * @param key {en} Rule Name
+     * @param rules 动画关键帧
+     * @param rules {en} Animation keyframes
+     * @example
+     * ```
+     * import { addCssKeyframes } from '@arco-design/mobile-utils';
+     *
+     * const maxScaleWithDefault = 2;
+        addCssKeyframes(
+            'animationKey',
+            `{
+                0% {
+                    width: 100%;
+                }
+                50% {
+                    width: ${100 * maxScaleWithDefault}%;
+                }
+                100% {
+                    width: 100%;
+                }
+            }`,
+        );
+     * ```
+     */
+
     function addCssKeyframes(key, rules) {
       addCssStyleDom(key, "@keyframes " + key + " " + rules + "\n@-webkit-keyframes " + key + " " + rules);
     }
+    /**
+     * 增加自定义 CSS 变量规则，使用后将在线替换css变量。需设置less变量 @use-css-vars: 1
+     * @desc {en} Add custom CSS variable rules, which will replace CSS variables online after use.The less variable needs to be set @use-css-vars: 1.
+     * @param key 规则名称
+     * @param key {en} Rule Name
+     * @param rules 规则对象
+     * @param rules {en} Rule Object
+     * @example
+     * ```
+     * import { addCssRules } from '@arco-design/mobile-utils';
+     *
+     * addCssRules('arcoTheme', { 'base-font-size': '50' });
+     * ```
+     */
+
     function addCssRules(key, rules) {
       if (!rules || !Object.keys(rules).length) {
         return;
@@ -716,6 +1294,22 @@
         return "--" + rule + ": " + rules[rule] + ";";
       }).join('\n') + "}");
     }
+    /**
+     * 获取元素的时间属性值，结果统一成毫秒级别
+     * @desc {en} Get the time attribute value of the element, and the results are unified into milliseconds
+     * @param ele 要获取样式的元素
+     * @param ele {en} Element to get the computed style
+     * @param property 与时间相关属性
+     * @param property {en} Property related to time
+     * @example
+     * ```
+     * import { convertCssDuration } from '@arco-design/mobile-utils';
+     *
+     * const contentRef = useRef<HTMLDivElement>(null);
+     * const transTimeout = convertCssDuration(contentRef.current, 'transitionDuration');
+     * ```
+     */
+
     function convertCssDuration(ele, property) {
       var timeout = window.getComputedStyle(ele)[property];
 
@@ -729,6 +1323,20 @@
 
       return 0;
     }
+    /**
+     * 获取指定元素的 CSS 样式，当抛出异常时返回空对象
+     * @desc {en} Get the CSS style of the specified element and return an empty object when an exception is thrown
+     * @param element 要获取样式的元素
+     * @param element {en} Element to get the computed style
+     * @example
+     * ```
+     * import { safeGetComputedStyle } from '@arco-design/mobile-utils';
+     *
+     * const element = document.querySelector("p");
+     * const compStyle =safeGetComputedStyle(element);
+     * ```
+     */
+
     function safeGetComputedStyle(element) {
       try {
         return window.getComputedStyle(element);
@@ -760,6 +1368,10 @@
       return Comp;
     }
 
+    /**
+     * @type utils
+     * @name color
+     */
     var w3cx11 = {
       aliceblue: '#f0f8ff',
       antiquewhite: '#faebd7',
@@ -917,6 +1529,21 @@
       yellow: '#ffff00',
       yellowgreen: '#9acd32'
     };
+    /**
+     * 获取任意颜色的透明色
+     * @desc {en} Get any transparent color
+     * @param color 颜色
+     * @param color {en} color
+     * @returns transparent color
+     * @example
+     * ```
+     * import { fadeColor } from '@arco-design/mobile-utils';
+     *
+     * const transparentColor = fadeColor('#ffffff');
+     * // transparentColor is '#ffffff00'
+     * ```
+     */
+
     function fadeColor(color) {
       if (!color) {
         return '';
@@ -937,6 +1564,27 @@
       return '';
     }
 
+    /**
+     * 获取当前设备的操作系统
+     * @desc {en} Get the operating system of the current device
+     * @returns {string} 返回当前设备的操作系统，可能的值包括 'android'、'ios' 或 'pc'，如果无法获取，则返回空字符串
+     * @returns {string} {en} Returns the operating system of the current device, possible values are 'android', 'ios', or 'pc'. Returns an empty string if it cannot be obtained
+     * @example
+     * ```
+     * import { getSystem } from '@arco-design/mobile-utils';
+     *
+     * const systemInfo = getSystem();
+     * if (systemInfo === 'android') {
+     *     console.log('You are using the Android operating system');
+     * } else if (systemInfo === 'ios') {
+     *     console.log('You are using the iOS operating system');
+     * } else if (systemInfo === 'pc') {
+     *     console.log('You are using a desktop PC operating system');
+     * } else {
+     *     console.log('Unable to detect your operating system');
+     * }
+     * ```
+     */
     function getSystem() {
       try {
         var u = navigator.userAgent;
@@ -949,6 +1597,21 @@
         return '';
       }
     }
+    /**
+     * 检查是否在 SSR 环境
+     * @desc {en} Check if in ssr environment
+     * @example
+     * ```
+     * import { isSSR } from '@arco-design/mobile-utils';
+     *
+     * if (isSSR()) {
+     *     console.log("It is currently in the ssr stage");
+     * } else {
+     *     console.log("It is currently in the csr stage");
+     * }
+     * ```
+     */
+
     function isSSR() {
       return typeof window === 'undefined';
     }
@@ -2974,6 +3637,25 @@
      * @type utils
      * @name utils
      */
+    /**
+     * 基于给定的过滤函数返回一个过滤后的数组
+     * @desc {en} Returns a filtered array based on the given filter function
+     * @param {T[]} data 数据数组
+     * @param {T[]} data {en} data array
+     * @param {Function} filterFn 过滤函数
+     * @param {Function} filterFn {en} filter function
+     * @param {Object} options 可选对象
+     * @param {Object} options {en} Optional object
+     * @return {string} 过滤后的数组
+     * @return {string} filtered array
+     * @example
+     * ```
+     * import { arrayTreeFilter } from '@arco-design/mobile-utils';
+     *
+     * const test = arrayTreeFilter(data, (item: any, level: number) => level <= index && item.value === value[level]);
+     * ```
+     */
+
     function arrayTreeFilter(data, filterFn, options) {
       options = options || {};
       options.childrenKeyName = options.childrenKeyName || 'children';
@@ -3002,8 +3684,16 @@
       return result;
     }
     /**
-     * 历史逻辑问题，轻喷 _(:з」∠)_
-     * @desc {en} Please ignore this weird function _(:з」∠)_
+     * 在下一个事件循环周期执行给定的函数
+     * @desc {en} Execute the given function on the next event loop cycle
+     * @param {Function} func 执行的函数
+     * @param {Function} func {en} function executed
+     * @example
+     * ```
+     * import { nextTick } from '@arco-design/mobile-utils';
+     *
+     * nextTick(() => { updateLayoutData(); });
+     * ```
      */
 
     function nextTick(func) {
@@ -3014,6 +3704,18 @@
      * @desc {en} To simulate the sliding damping effect, use the function x = X/(aX+b), where x is the element displacement, X is the sliding distance, and a and b are custom parameters obtained by setting the corresponding relationship between the two targets
      * 例如目标X=500时x=100, X=200时x=60，可得a,b
      * @desc {en} For example, when the target X=500, x=100, when X=200, x=60, you can get a,b
+     * @param {number} x 元素位移
+     * @param {number} x {en} element displacement
+     * @param {[number, number] | number} damping 阻尼参数
+     * @param {[number, number] | number} damping {en} Damping parameters
+     * @return {number} 返回需要滑动的距离
+     * @return {number} {en} Return the distance required to slide
+     * @example
+     * ```
+     * import { fingerDisToLabelDis } from '@arco-design/mobile-utils';
+     *
+     * const test = fingerDisToLabelDis(1000, 0.01);
+     * ```
      */
 
     function fingerDisToLabelDis(x, damping) {
@@ -3028,11 +3730,12 @@
       return x / (a * x + b);
     }
 
+    var DEFAULT_DARK_MODE_SELECTOR = 'arco-theme-dark';
     var defaultContext = {
       prefixCls: 'arco',
       system: '',
       useDarkMode: false,
-      isDarkMode: false,
+      darkModeSelector: DEFAULT_DARK_MODE_SELECTOR,
       locale: defaultLocale,
       useRtl: false
     };
@@ -3049,25 +3752,63 @@
     function ContextProvider(props) {
       var children = props.children,
           useDarkMode = props.useDarkMode,
-          isDarkMode = props.isDarkMode,
+          userSetIsDarkMode = props.isDarkMode,
+          _a = props.darkModeSelector,
+          darkModeSelector = _a === void 0 ? DEFAULT_DARK_MODE_SELECTOR : _a,
           theme = props.theme,
-          _a = props.locale,
-          locale = _a === void 0 ? defaultLocale : _a,
-          restProps = __rest$1(props, ["children", "useDarkMode", "isDarkMode", "theme", "locale"]);
+          _b = props.locale,
+          locale = _b === void 0 ? defaultLocale : _b,
+          onDarkModeChange = props.onDarkModeChange,
+          restProps = __rest$1(props, ["children", "useDarkMode", "isDarkMode", "darkModeSelector", "theme", "locale", "onDarkModeChange"]);
 
-      var _b = React.useState(),
-          isDarkModeState = _b[0],
-          setIsDarkModeState = _b[1];
+      var _c = React.useState(function () {
+        if (typeof window !== 'undefined' && useDarkMode) {
+          return window.matchMedia('(prefers-color-scheme: dark)').matches;
+        }
 
+        return false;
+      }),
+          isDarkModeState = _c[0],
+          setIsDarkModeState = _c[1];
+
+      var mountedRef = React.useRef(false);
+
+      var setDarkModeState = function setDarkModeState(isDark, needChange) {
+        if (needChange === void 0) {
+          needChange = true;
+        }
+
+        setIsDarkModeState(isDark);
+        needChange && onDarkModeChange && onDarkModeChange(isDark);
+      };
+
+      var isDarkMode = React.useMemo(function () {
+        // 如果未开启暗黑模式则不对body做操作
+        // @en If dark mode is not turned on, no operation will be performed on the body
+        if (userSetIsDarkMode === void 0 && !useDarkMode) {
+          return false;
+        }
+
+        var value = Boolean(userSetIsDarkMode !== void 0 ? userSetIsDarkMode : isDarkModeState);
+        var needUpdateBody = darkModeSelector && typeof document !== 'undefined';
+
+        if (value) {
+          needUpdateBody && document.body.classList.add(darkModeSelector);
+        } else {
+          needUpdateBody && document.body.classList.remove(darkModeSelector);
+        }
+
+        return value;
+      }, [userSetIsDarkMode, isDarkModeState, darkModeSelector, useDarkMode]);
       var changeDarkMode = React.useCallback(function (res) {
-        return setIsDarkModeState(res.matches);
+        return setDarkModeState(res.matches);
       }, []);
       React.useEffect(function () {
         var matchMedia = window.matchMedia('(prefers-color-scheme: dark)');
 
         if (useDarkMode) {
           var dark = matchMedia.matches;
-          setIsDarkModeState(dark);
+          setDarkModeState(dark, mountedRef.current);
 
           if (typeof matchMedia.addEventListener === 'function') {
             matchMedia.addEventListener('change', changeDarkMode);
@@ -3076,6 +3817,7 @@
           }
         }
 
+        mountedRef.current = true;
         return function () {
           if (useDarkMode) {
             if (typeof matchMedia.removeEventListener === 'function') {
@@ -3098,7 +3840,7 @@
       }, [theme]);
       return /*#__PURE__*/React__default["default"].createElement(GlobalContext.Provider, {
         value: __assign$2(__assign$2(__assign$2({}, defaultContext), restProps), {
-          isDarkMode: isDarkMode === void 0 ? isDarkModeState : isDarkMode,
+          isDarkMode: isDarkMode,
           useDarkMode: useDarkMode,
           locale: locale || defaultLocale
         })
@@ -3116,6 +3858,23 @@
       };
     }
 
+    /**
+     * 监听页面resize事件的统一封装
+     * @desc {en} Unified encapsulation for monitoring page resize events
+     * @param resizeHandler resize事件回调
+     * @param resizeHandler {en} Resize event callback
+     * @param deps 触发事件绑定更新的依赖
+     * @param deps {en} Dependencies that trigger event binding updates
+     * @param needListen 是否开启事件监听，默认开启
+     * @param needListen {en} Whether to enable event monitoring
+     * @example
+     * ```
+     * import { useListenResize } from '@arco-design/mobile-react/esm/_helpers/hooks';
+     *
+     * useListenResize(setSize, [], listenResize);
+     * ```
+     */
+
     function useListenResize(resizeHandler, deps, needListen) {
       if (deps === void 0) {
         deps = [];
@@ -3126,15 +3885,16 @@
       }
 
       React.useEffect(function () {
-        if (!needListen) {
-          return function () {};
+        if (needListen) {
+          window.addEventListener('resize', resizeHandler);
+          window.addEventListener('orientationchange', resizeHandler);
         }
 
-        window.addEventListener('resize', resizeHandler);
-        window.addEventListener('orientationchange', resizeHandler);
         return function () {
-          window.removeEventListener('resize', resizeHandler);
-          window.removeEventListener('orientationchange', resizeHandler);
+          if (needListen) {
+            window.removeEventListener('resize', resizeHandler);
+            window.removeEventListener('orientationchange', resizeHandler);
+          }
         };
       }, __spreadArrays$1(deps, [needListen]));
     }
@@ -3145,6 +3905,7 @@
      * @desc {en} Tips: Use in scenarios where asynchronous processing is not completed after unmount. It is not recommended to replace useState without brains
      * @param initialState 初始状态
      * @param initialState {en} Initial State
+     * @returns [state, setState]，同useState返回值
      * @example
      * ```
      * import { useMountedState } from '@arco-design/mobile-react/esm/_helpers/hooks';
@@ -3174,6 +3935,20 @@
       var result = [state, setValidState];
       return result;
     }
+    /**
+     * 用useState管理状态，且在状态更新之前同步至ref，并返回ref
+     * @desc {en} Use useState to manage the state, and synchronize to ref before the state is updated, and return ref
+     * @param initialValue 初始状态
+     * @param initialValue {en} Initial State
+     * @returns [state, stateRef, setState]
+     * @example
+     * ```
+     * import { useSameRefState } from '@arco-design/mobile-react/esm/_helpers/hooks';
+     *
+     * const [opened, openedRef, setOpened] = useSameRefState(false);
+     * ```
+     */
+
     function useSameRefState(initialValue) {
       var _a = React.useState(initialValue),
           state = _a[0],
@@ -3188,6 +3963,20 @@
 
       return [state, stateRef, setStateProxy];
     }
+    /**
+     * 用useState管理状态，且在状态更新后同步至ref，并返回ref
+     * @desc {en} Use useState to manage the state, and synchronize to ref after the state is updated, and return ref
+     * @param initialValue 初始状态
+     * @param initialValue {en} Initial State
+     * @returns [state, stateRef, setState]
+     * @example
+     * ```
+     * import { useRefState } from '@arco-design/mobile-react/esm/_helpers/hooks';
+     *
+     * const [index, indexRef, setIndex] = useRefState(currentIndex);
+     * ```
+     */
+
     function useRefState(initialValue) {
       var _a = React.useState(initialValue),
           state = _a[0],
@@ -3199,6 +3988,23 @@
       }, [state]);
       return [state, stateRef, setState];
     }
+    /**
+     * useEffect特殊封装，仅在非首次依赖更新时触发回调
+     * @desc {en} Special encapsulation of useEffect, which only triggers the callback when the dependency is not updated for the first time
+     * @param effect useEffect回调
+     * @param effect {en} useEffect callback
+     * @param dependencies useEffect依赖
+     * @param dependencies {en} useEffect dependencies
+     * @example
+     * ```
+     * import { useUpdateEffect } from '@arco-design/mobile-react/esm/_helpers/hooks';
+     *
+     * useUpdateEffect(() => {
+     *     handleIndexChange(index);
+     * }, [index]);
+     * ```
+     */
+
     function useUpdateEffect(effect, dependencies) {
       if (dependencies === void 0) {
         dependencies = [];
@@ -3213,6 +4019,21 @@
         }
       }, dependencies);
     }
+    /**
+     * 获取任意变量的最新ref值（用于监听属性、方法等非state变量）
+     * @desc {en} Get the latest ref value of any variable (used to monitor non-state variables such as properties and methods)
+     * @param variable 待获取最新值的变量
+     * @param variable {en} Variable to get latest value
+     * @returns variableRef，变量的最新ref值
+     * @example
+     * ```
+     * import { useLatestRef } from '@arco-design/mobile-react/esm/_helpers/hooks';
+     *
+     * const { wrapSize } = props;
+     * const wrapSizeRef = useLatestRef(wrapSize);
+     * ```
+     */
+
     function useLatestRef(variable) {
       var variableRef = React.useRef(variable);
       React.useEffect(function () {
@@ -3220,6 +4041,18 @@
       }, [variable]);
       return variableRef;
     }
+    /**
+     * 从navigator.userAgent中获取当前操作系统，如果无法获取ua，则从ContextProvider传入的system中获取值
+     * @desc {en} Get the current operating system from navigator.userAgent, if ua cannot be obtained, get the value from the system passed in by ContextProvider
+     * @returns system 操作系统，"" | "pc" | "android" | "ios"
+     * @example
+     * ```
+     * import { useSystem } from '@arco-design/mobile-react/esm/_helpers/hooks';
+     *
+     * const system = useSystem();
+     * ```
+     */
+
     function useSystem() {
       var currentSystem = React.useContext(GlobalContext).system;
 
@@ -3234,12 +4067,26 @@
       }, [currentSystem]);
       return system;
     }
+    /**
+     * 获取页面视口宽高大小，并在页面有resize时更新大小
+     * @desc {en} Get the width and height of the page viewport, and update the size when the page is resized
+     * @param needListen 是否开启resize事件监听
+     * @param needListen {en} Whether to enable resize event monitoring
+     * @returns 页面宽高，{ windowWidth, windowHeight }
+     * @example
+     * ```
+     * import { useWindowSize } from '@arco-design/mobile-react/esm/_helpers/hooks';
+     *
+     * const { windowHeight, windowWidth } = useWindowSize();
+     * ```
+     */
+
     function useWindowSize(listenResize) {
-      var _a = React.useState(0),
+      var _a = React.useState(typeof window !== 'undefined' ? window.innerWidth : 0),
           windowWidth = _a[0],
           setWindowWidth = _a[1];
 
-      var _b = React.useState(0),
+      var _b = React.useState(typeof window !== 'undefined' ? window.innerHeight : 0),
           windowHeight = _b[0],
           setWindowHeight = _b[1];
 
@@ -3257,7 +4104,30 @@
         windowHeight: windowHeight
       };
     }
-    /* eslint-disable max-lines-per-function */
+    /**
+     * 弹窗中滚动统一处理，防止滚动穿透
+     * @desc {en} Unified processing of scrolling in pop-up windows to prevent scrolling penetration
+     * @param visible 弹窗是否被打开
+     * @param visible {en} Whether the popup is opened
+     * @param popupDom 弹窗的dom元素
+     * @param popupDom {en} DOM element of the popup
+     * @param getScrollContainer 弹窗中的滚动容器，可传入多个
+     * @param getScrollContainer {en} The scrolling container in the popup, which can pass in multiple
+     * @param orientationDirection 弹窗内容朝向，默认为top（从上到下），用于实现模拟横屏
+     * @param orientationDirection {en} The content orientation of the popup, the default is top (from top to bottom), which is used to simulate a horizontal screen
+     * @param preventCallback 在滚动穿透被阻止（preventDefault被触发）时的回调
+     * @param preventCallback {en} Callback when scrolling is blocked (preventDefault is triggered)
+     * @param onTouchMove touchmove 自定义事件
+     * @param onTouchMove {en} Touchmove custom event
+     * @param gestureOutOfControl 是否禁用滚动穿透处理
+     * @param gestureOutOfControl {en} Whether to disable scroll through processing
+     * @example
+     * ```
+     * import { usePopupScroll } from '@arco-design/mobile-react/esm/_helpers/hooks';
+     *
+     * usePopupScroll(visible, domRef.current, getScrollContainer, orientationDirection, onPreventTouchMove, onTouchMove, gestureOutOfControl);
+     * ```
+     */
 
     function usePopupScroll(visible, popupDom, getScrollContainer, orientationDirection, preventCallback, onTouchMove, gestureOutOfControl) {
       if (orientationDirection === void 0) {
@@ -3442,6 +4312,19 @@
         };
       }, [visible, popupDom, handleTouchStart, handleTouchMove]);
     }
+    /**
+     * 在滑动类组件中，如果有内部可滚动区域，则在内部滚动区域滚动时禁用滑动事件
+     * @desc {en} In the sliding class component, if there is an inner scrollable area, the sliding event is disabled when the inner scrolling area is scrolled
+     * @param getInnerScrollContainer 内部可滚动区域，可传入多个
+     * @param getInnerScrollContainer {en} Inner scrollable area, can pass in multiple
+     * @example
+     * ```
+     * import { useSwiperInnerScroll } from '@arco-design/mobile-react/esm/_helpers/hooks';
+     *
+     * useSwiperInnerScroll(getInnerScrollContainer);
+     * ```
+     */
+
     function useSwiperInnerScroll(getInnerScrollContainer) {
       var stopFunc = React.useCallback(function (e) {
         return e.stopPropagation();
@@ -3469,6 +4352,26 @@
         };
       }, [getInnerScrollContainer]);
     }
+    /**
+     * 事件绑定统一封装
+     * @desc {en} Unified encapsulation of event binding
+     * @param dom 待绑定事件的dom元素
+     * @param dom {en} The dom element to be bound to the event
+     * @param event 待绑定事件名称
+     * @param event {en} The name of the event to be bound
+     * @param handler 待绑定事件回调
+     * @param handler {en} The callback of the event to be bound
+     * @param options 待绑定事件配置，默认为 { capture: true }
+     * @param options {en} Event configuration to be bound, the default is { capture: true }
+     * @example
+     * ```
+     * import { useAddListener } from '@arco-design/mobile-react/esm/_helpers/hooks';
+     *
+     * useAddListener(domRef.current, 'touchstart', onTouchStart);
+     * useAddListener(domRef.current, 'touchend', onTouchEnd);
+     * ```
+     */
+
     function useAddListener(dom, event, handler, options) {
       if (options === void 0) {
         options = {
@@ -3497,9 +4400,30 @@
 
     var arcoFullScreenCount = 0;
     var arcoFullScreenOriginOverflow = '';
+    /**
+     * 在全屏组件出现时，将body的overflow设置为hidden，防止滚动穿透
+     * @desc {en} When the full screen component appears, set the overflow of the body to hidden to prevent scrolling penetration
+     * @param visible 全屏组件是否被打开
+     * @param visible {en} Whether the full screen component is opened
+     * @param preventBodyScroll 是否启用防滚动穿透，默认启用
+     * @param preventBodyScroll {en} Whether to enable anti-scroll penetration, enabled by default
+     * @param initialBodyOverflow body在初始状态下的overflow值，在全屏组件全部关闭后会还原
+     * @param initialBodyOverflow {en} The overflow value of the body in the initial state, which will be restored after all full-screen components are closed
+     * @example
+     * ```
+     * import { usePreventBodyScroll } from '@arco-design/mobile-react/esm/_helpers/hooks';
+     *
+     * usePreventBodyScroll(visible, preventBodyScroll, initialBodyOverflow);
+     * ```
+     */
+
     function usePreventBodyScroll(visible, preventBodyScroll, initialBodyOverflow) {
-      // 新出现一个全屏组件则计数+1，并设置body hidden样式
+      if (preventBodyScroll === void 0) {
+        preventBodyScroll = true;
+      } // 新出现一个全屏组件则计数+1，并设置body hidden样式
       // @en When a new full-screen component appears, count + 1 and set the body hidden style
+
+
       var addFullScreen = React.useCallback(function () {
         var count = arcoFullScreenCount; // 在当前没有全屏组件出现时，记下body overflow的初始值
         // @en Note the initial value of body overflow when no full-screen components are currently present
@@ -3544,6 +4468,18 @@
         };
       }, [visible]);
     }
+    /**
+     * 进度条计算公共逻辑，根据传入的参数计算出当前百分比和过渡效果开关，进度类组件内部使用
+     * @desc {en} Progress bar calculation common logic, used internally by the progress class component
+     * @returns [当前计算的百分比, 当前是否应有过渡效果]
+     * @example
+     * ```
+     * import { usePreventBodyScroll } from '@arco-design/mobile-react/esm/_helpers/hooks';
+     *
+     * const [currentPercentage, transitionControl] = useProgress(mountedTransition, percentage, duration, mountedBezier, step);
+     * ```
+     */
+
     function useProgress(mountedTransition, percentage, duration, mountedBezier, step) {
       var _a = React.useState(0),
           currentPercentage = _a[0],
@@ -3579,6 +4515,24 @@
       }, [count, percentage, step]);
       return [currentPercentage, transitionControl];
     }
+    /**
+     * 单击和双击事件统一处理
+     * @desc {en} Unified processing of single and double click events
+     * @param onClick 单击事件回调
+     * @param onClick {en} Callback of single click event
+     * @param onDoubleClick 双击事件回调
+     * @param onDoubleClick {en} Callback of double click event
+     * @param delay 两次点击被判定为双击事件的最大间隔时间
+     * @param delay {en} The maximum interval between two clicks is judged as a double-click event
+     * @returns clickHandler，统一后的事件处理方法
+     * @example
+     * ```
+     * import { useSingleAndDoubleClick } from '@arco-design/mobile-react/esm/_helpers/hooks';
+     *
+     * const handleClick = useSingleAndDoubleClick(handleImageClick, handleImageDoubleClick);
+     * ```
+     */
+
     function useSingleAndDoubleClick(onClick, onDoubleClick, delay) {
       if (delay === void 0) {
         delay = 200;
@@ -3607,6 +4561,24 @@
       };
     }
     var arcoSvgKeyCount = 0;
+    /**
+     * 自动生成svg <def>标签的唯一标识，用于区分不同svg的<def>内容
+     * @desc {en} Automatically generate the unique identifier of the svg <def> tag, which is used to distinguish the <def> content of different svg
+     * @param userSetSvgKey 自定义唯一标识，传入则覆盖自动生成的值
+     * @param userSetSvgKey {en} Customize the unique identifier, if passed in, it will override the automatically generated value
+     * @returns 包含svgKey的对象 生成后的唯一标识
+     * @globalVariable
+     * ```
+     * let arcoSvgKeyCount = 0;
+     * ```
+     * @example
+     * ```
+     * import { useGenSvgKey } from '@arco-design/mobile-react/esm/_helpers/hooks';
+     *
+     * const { svgKey } = useGenSvgKey(userSetSvgKey);
+     * ```
+     */
+
     function useGenSvgKey(userSetSvgKey) {
       var _a = React.useState(''),
           innerSvgKey = _a[0],
@@ -3680,6 +4652,38 @@
 
     var render = copyRender;
 
+    /**
+     * 获取带浏览器前缀的样式
+     * @desc {en} Get style with browser vendor prefix
+     * @param {CSSProperties} style 原始样式
+     * @param {CSSProperties} style {en} Original style
+     * @returns {CSSProperties} newStyle 添加了浏览器前缀的新样式
+     * @returns {CSSProperties} newStyle {en} New style with browser vendor prefix
+     * @example
+     * ```
+     * import { getStyleWithVendor } from '@arco-design/mobile-react/esm/_helpers';
+     *
+     * // Example usage:
+     * const originalStyle = {
+     *     transform: 'translateX(50px)',
+     *     transition: 'all 0.3s ease',
+     *     opacity: 0.8,
+     * };
+     *
+     * const styleWithPrefix = getStyleWithVendor(originalStyle);
+     *
+     * // Result:
+     * // styleWithPrefix will be:
+     * // {
+     * //     transform: 'translateX(50px)',
+     * //     WebkitTransform: 'translateX(50px)', // Browser-specific prefix added
+     * //     transition: 'all 0.3s ease',
+     * //     WebkitTransition: 'all 0.3s ease', // Browser-specific prefix added
+     * //     opacity: 0.8,
+     * // }
+     * ```
+     */
+
     function getStyleWithVendor(style) {
       var allowReg = /(transform|transition|animation)/i;
       var newStyle = Object.keys(style).reduce(function (acc, key) {
@@ -3692,6 +4696,37 @@
       }, {});
       return newStyle;
     }
+    /**
+     * 给元素设置带浏览器前缀的样式
+     * @desc {en} Set element style with browser vendor prefix
+     * @param {HTMLElement} dom 需要设置样式的元素
+     * @param {HTMLElement} dom {en} Element to set style
+     * @param {CSSProperties} style Original style
+     * @param {CSSProperties} style {en} Original style
+     * @returns {void}
+     * @example
+     * ```
+     * import { setStyleWithVendor } from '@arco-design/mobile-utils';
+     *
+     * // Example: Setting and displaying styles with the Webkit browser vendor prefix
+     * const element = document.getElementById('myElement');
+     * const originalStyle = {
+     *   transform: 'translateX(100px)',
+     *   transition: 'transform 0.5s ease',
+     *   borderRadius: '5px',
+     * };
+     *
+     * // Set the styles with the Webkit browser vendor prefix
+     * setStyleWithVendor(element, originalStyle);
+     *
+     * // Display the styles with the Webkit browser vendor prefixes applied
+     * const computedStyle = getComputedStyle(element);
+     * console.log(computedStyle.getPropertyValue('-webkit-transform')); // Output: The transformed style with the Webkit browser vendor prefix
+     * console.log(computedStyle.getPropertyValue('-webkit-transition')); // Output: The transition style with the Webkit browser vendor prefix
+     * console.log(computedStyle.getPropertyValue('border-radius')); // Output: The borderRadius style without a vendor prefix
+     * ```
+     */
+
     function setStyleWithVendor(dom, style) {
       var vendorStyle = getStyleWithVendor(style);
 
@@ -3702,6 +4737,22 @@
     /**
      * 计算默认值，仅未定义时使用默认值
      * @desc {en} Calculate the default value, use default value only if undefined
+     * @param {T | undefined} value 输入的值
+     * @param {T | undefined} value {en} The input value
+     * @param {T} defaultValue 默认值
+     * @param {T} defaultValue {en} The default value
+     * @returns {T} 如果输入的值是未定义的，那么返回默认值，否则返回输入的值
+     * @returns {T} {en} Returns the default value if the input is undefined, otherwise returns the input value
+     * @example
+     * ```
+     * import { getDefaultValue } from '@arco-design/mobile-react/esm/_helpers';
+     *
+     * const result = getDefaultValue(42, 0);
+     * console.log(result); // Output: 42
+     *
+     * const result2 = getDefaultValue(undefined, 100);
+     * console.log(result2); // Output: 100
+     * ```
      */
 
     var getDefaultValue = function getDefaultValue(value, defaultValue) {
@@ -4310,7 +5361,7 @@
           fixed: tabBarFixed
         }, {
           'has-divider': hasDivider
-        }),
+        }, system),
         style: typeof tabBarFixed === 'object' ? tabBarFixed : {}
       }, /*#__PURE__*/React__default["default"].createElement("div", {
         className: cls(prefix + "-container", tabDirection, "pos-" + tabBarPosition, "arrange-" + (originArrange || tabBarArrange), "type-" + type, {
@@ -9239,7 +10290,9 @@
         // @en When noLoop is used, the blank space of spaceBetween needs to be exposed at the end, so when sliding to the last one, the transform value moves to the left by the corresponding width
 
         var translateDis = noLoop ? noLoopDis - (total > 1 && index === total - 1 ? spaceBetween : 0) * rtlRatio : dis;
-        var transStr = childSize > 0 ? translateDis + "px" : "-" + index * 100 + "%";
+        var initTranslateDis = -1 * index * 100; // bugfix: prop `style` did not match in ssr
+
+        var transStr = childSize > 0 ? "" + translateDis + (translateDis ? 'px' : '') : "" + initTranslateDis + (initTranslateDis ? '%' : '');
 
         if (vertical) {
           var translateStyle_1 = getStyleWithVendor({
@@ -15101,11 +16154,13 @@
     var getErrorAndWarnings = function getErrorAndWarnings(result) {
       var errors = [];
       var warnings = [];
+      var errorTypes = [];
       result.map(function (_a) {
         var _b = _a.message,
             message = _b === void 0 ? [] : _b,
             _c = _a.validateLevel,
-            validateLevel = _c === void 0 ? 'error' : _c;
+            validateLevel = _c === void 0 ? 'error' : _c,
+            resultErrorTypes = _a.errorTypes;
 
         if (!(message === null || message === void 0 ? void 0 : message.length)) {
           return;
@@ -15115,11 +16170,13 @@
           warnings = __spreadArrays$1(warnings, message);
         } else {
           errors = __spreadArrays$1(errors, message);
+          errorTypes = __spreadArrays$1(errorTypes, resultErrorTypes);
         }
       });
       return {
         warnings: warnings,
-        errors: errors
+        errors: errors,
+        errorTypes: errorTypes
       };
     };
 
@@ -15182,12 +16239,14 @@
               fieldValidator_1.validate((_a = {}, _a[field] = value, _a), function (errorsMap) {
                 var _a = getErrorAndWarnings((errorsMap === null || errorsMap === void 0 ? void 0 : errorsMap[field]) || []),
                     errors = _a.errors,
-                    warnings = _a.warnings;
+                    warnings = _a.warnings,
+                    errorTypes = _a.errorTypes;
 
                 _this._errors = errors;
                 onValidateStatusChange({
                   errors: _this._errors,
-                  warnings: warnings
+                  warnings: warnings,
+                  errorTypes: errorTypes
                 });
                 return resolve({
                   errors: _this._errors,
@@ -15426,16 +16485,22 @@
           errors = _e[0],
           setErrors = _e[1];
 
-      var _f = React.useState([]),
-          warnings = _f[0],
-          setWarnings = _f[1];
+      var _f = React.useState(null),
+          errorTypes = _f[0],
+          setErrorTypes = _f[1];
+
+      var _g = React.useState([]),
+          warnings = _g[0],
+          setWarnings = _g[1];
 
       var formItemRef = React.useRef(null);
 
       var onValidateStatusChange = function onValidateStatusChange(validateResult) {
         var _errors = validateResult.errors,
-            _warnings = validateResult.warnings;
+            _warnings = validateResult.warnings,
+            _errorTypes = validateResult.errorTypes;
         setErrors(_errors.length ? _errors[0] : null);
+        setErrorTypes(_errorTypes.length ? _errorTypes[0] : null);
         setWarnings(_warnings);
       };
 
@@ -15457,7 +16522,7 @@
       return /*#__PURE__*/React__default["default"].createElement("div", {
         className: cls(prefixCls + "-form-item", prefixCls + "-form-item-" + (itemLayout || layout), className, (_a = {
           disabled: fieldDisabled
-        }, _a[prefixCls + "-form-item-error"] = !!errors, _a[prefixCls + "-form-item-warning"] = Boolean(!errors && warnings), _a)),
+        }, _a[prefixCls + "-form-item-error"] = !!errors, _a[prefixCls + "-form-item-warning"] = Boolean(!errors && warnings), _a[prefixCls + "-form-item-error-" + errorTypes] = errorTypes, _a)),
         style: style,
         ref: formItemRef
       }, /*#__PURE__*/React__default["default"].createElement("div", {