@arco-design/mobile-react 2.29.5 → 2.30.0

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 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 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,57 @@
     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 setDarkModeState = function setDarkModeState(isDark) {
+        setIsDarkModeState(isDark);
+        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);
 
           if (typeof matchMedia.addEventListener === 'function') {
             matchMedia.addEventListener('change', changeDarkMode);
@@ -3098,7 +3833,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 +3851,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 +3878,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 +3898,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 +3928,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 +3956,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 +3981,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 +4012,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 +4034,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 +4060,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 +4097,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 +4305,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 +4345,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 +4393,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 +4461,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 +4508,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 +4554,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 +4645,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 +4689,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 +4730,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 +5354,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, {
@@ -5311,7 +6355,10 @@
         // 利用受控手动更改index时，给cell line加上动画
         // @en Animate the cell line when changeing the index
         setCellTrans(true);
-        changeFromRef.current = 'manual';
+
+        if (!changeFromRef.current) {
+          changeFromRef.current = 'manual';
+        }
       }, [activeTab]);
       useUpdateEffect(function () {
         onDistanceChange && onDistanceChange(distance, wrapWidth, activeIndex);
@@ -7306,9 +8353,7 @@
         }, normalize(config)), {
           visible: false,
           close: function close() {}
-        });
-
-        var dynamicProps = __assign$2({}, baseProps); // 不同的key用不同的容器挂载
+        }); // 不同的key用不同的容器挂载
 
 
         var id = "_" + (containerId || 'ARCO_MASKING') + "_DIV_" + (config.key || '') + "_";
@@ -7316,6 +8361,12 @@
         var leaving = false;
         var render = new ReactDOMRender(Component, div, context).render;
 
+        var dynamicProps = __assign$2(__assign$2({}, baseProps), {
+          getContainer: function getContainer() {
+            return div;
+          }
+        });
+
         function update(newConfig) {
           dynamicProps = __assign$2(__assign$2({}, dynamicProps), normalize(newConfig));
           render(dynamicProps);
@@ -7736,69 +8787,69 @@
      */
 
     var BaseImage = /*#__PURE__*/React.forwardRef(function (props, ref) {
-      var system = useSystem();
-
-      var _a = useWindowSize(),
-          windowWidth = _a.windowWidth,
-          windowHeight = _a.windowHeight;
-
-      var _b = useMountedState('init'),
-          imageStatus = _b[0],
-          setImageStatus = _b[1];
-
-      var _c = useMountedState(''),
-          wrapClass = _c[0],
-          setWrapClass = _c[1];
-
-      var _d = useMountedState(false),
-          staticRetrying = _d[0],
-          setStaticRetrying = _d[1];
-
-      var imageRef = React.useRef(null);
-      var imageDomRef = React.useRef(null);
-      var wrapRef = React.useRef(null);
-      var retryCountRef = React.useRef(0);
-      var loadingImageRef = React.useRef(null);
-      var hasLoadedRef = React.useRef(false);
       var style = props.style,
           className = props.className,
           status = props.status,
           src = props.src,
           width = props.width,
           height = props.height,
-          _e = props.alt,
-          alt = _e === void 0 ? '' : _e,
-          _f = props.fit,
-          fit = _f === void 0 ? 'cover' : _f,
-          _g = props.position,
-          position = _g === void 0 ? 'center' : _g,
+          _a = props.alt,
+          alt = _a === void 0 ? '' : _a,
+          _b = props.fit,
+          fit = _b === void 0 ? 'cover' : _b,
+          _c = props.position,
+          position = _c === void 0 ? 'center' : _c,
           radius = props.radius,
           bordered = props.bordered,
           loadingArea = props.loadingArea,
           errorArea = props.errorArea,
           showLoading = props.showLoading,
           showError = props.showError,
-          _h = props.animateDuration,
-          animateDuration = _h === void 0 ? 200 : _h,
-          _j = props.retryTime,
-          retryTime = _j === void 0 ? 0 : _j,
+          _d = props.animateDuration,
+          animateDuration = _d === void 0 ? 200 : _d,
+          _e = props.retryTime,
+          retryTime = _e === void 0 ? 0 : _e,
           forceHttps = props.forceHttps,
-          _k = props.boxWidth,
-          boxWidth = _k === void 0 ? 0 : _k,
-          _l = props.boxHeight,
-          boxHeight = _l === void 0 ? 0 : _l,
+          _f = props.boxWidth,
+          boxWidth = _f === void 0 ? 0 : _f,
+          _g = props.boxHeight,
+          boxHeight = _g === void 0 ? 0 : _g,
           topOverlap = props.topOverlap,
           bottomOverlap = props.bottomOverlap,
-          _m = props.showImage,
-          showImage = _m === void 0 ? true : _m,
+          _h = props.showImage,
+          showImage = _h === void 0 ? true : _h,
           staticLabel = props.staticLabel,
-          _o = props.nativeProps,
-          nativeProps = _o === void 0 ? {} : _o,
+          _j = props.nativeProps,
+          nativeProps = _j === void 0 ? {} : _j,
           onChange = props.onChange,
           onClick = props.onClick,
-          _onLoad = props.onLoad,
+          onLoad = props.onLoad,
           onError = props.onError,
           onAutoRetry = props.onAutoRetry;
+      var system = useSystem();
+
+      var _k = useWindowSize(),
+          windowWidth = _k.windowWidth,
+          windowHeight = _k.windowHeight;
+
+      var _l = useMountedState(staticLabel && showLoading ? 'loading' : 'init'),
+          imageStatus = _l[0],
+          setImageStatus = _l[1];
+
+      var _m = useMountedState(''),
+          wrapClass = _m[0],
+          setWrapClass = _m[1];
+
+      var _o = useMountedState(false),
+          staticRetrying = _o[0],
+          setStaticRetrying = _o[1];
+
+      var imageRef = React.useRef(null);
+      var imageDomRef = React.useRef(null);
+      var wrapRef = React.useRef(null);
+      var retryCountRef = React.useRef(0);
+      var loadingImageRef = React.useRef(null);
+      var hasLoadedRef = React.useRef(false);
       var isPreview = Boolean(fit.indexOf('preview') >= 0);
       var actualBoxWidth = boxWidth || windowWidth;
       var actualBoxHeight = boxHeight || windowHeight;
@@ -7834,6 +8885,21 @@
         retryCountRef.current = 0;
         loadImage();
       }, [attrs, width, height, showImage, staticLabel]);
+      React.useEffect(function () {
+        var _a; // 当使用img标签时，onLoad可能加载完成前已经执行完，此时手动触发一次
+        // @en When using the img tag, onLoad may have been executed before loading is complete, and it needs to be triggered manually
+
+
+        if (staticLabel && !hasLoadedRef.current && ((_a = imageDomRef.current) === null || _a === void 0 ? void 0 : _a.complete)) {
+          // 图片有宽高认为正常加载，否则认为加载错误
+          // @en If the image has width and height, it is considered to be loaded normally, otherwise it is considered to be a loading error
+          if (imageDomRef.current.naturalWidth || imageDomRef.current.naturalHeight) {
+            handleImageLoaded(null, imageDomRef.current);
+          } else {
+            handleStaticImageError(null);
+          }
+        }
+      }, [staticLabel]);
 
       function changeStatus(newStatus) {
         setImageStatus(newStatus);
@@ -7854,6 +8920,43 @@
         }
       }
 
+      function handleImageLoaded(evt, image) {
+        hasLoadedRef.current = true;
+        changeStatus('loaded');
+        var _a = image.width,
+            imageWidth = _a === void 0 ? 0 : _a,
+            _b = image.height,
+            imageHeight = _b === void 0 ? 0 : _b;
+        var extraClass = '';
+
+        if (isPreview) {
+          var scale = imageWidth / imageHeight;
+          var windowScale = actualBoxWidth / actualBoxHeight;
+
+          if (fit === 'preview-y') {
+            if (scale < windowScale) {
+              image.style.width = actualBoxWidth + "px";
+              image.style.height = actualBoxWidth / scale + "px";
+              extraClass = 'preview-overflow-y';
+            } else {
+              extraClass = 'preview-fit-contain-y';
+            }
+          } else if (fit === 'preview-x') {
+            if (scale > windowScale) {
+              image.style.width = actualBoxHeight * scale + "px";
+              image.style.height = actualBoxHeight + "px";
+              extraClass = 'preview-overflow-x';
+            } else {
+              extraClass = 'preview-fit-contain-x';
+            }
+          }
+        }
+
+        extraClass && image.classList.add(extraClass);
+        setWrapClass(extraClass ? extraClass + "-container" : '');
+        onLoad && onLoad(evt, image);
+      }
+
       function loadImage(isFromRetry) {
         // 如果在加载图片前发现上一个图片还没加载完，则抛弃上一个图片的加载
         // @en Abort last image before starting loading new image
@@ -7879,41 +8982,8 @@
         image.onload = function (evt) {
           loadingImageRef.current = null;
           imageDomRef.current = image;
-          hasLoadedRef.current = true;
-          changeStatus('loaded');
-          var _a = image.width,
-              imageWidth = _a === void 0 ? 0 : _a,
-              _b = image.height,
-              imageHeight = _b === void 0 ? 0 : _b;
-          var extraClass = '';
-
-          if (isPreview) {
-            var scale = imageWidth / imageHeight;
-            var windowScale = actualBoxWidth / actualBoxHeight;
-
-            if (fit === 'preview-y') {
-              if (scale < windowScale) {
-                image.style.width = actualBoxWidth + "px";
-                image.style.height = actualBoxWidth / scale + "px";
-                extraClass = 'preview-overflow-y';
-              } else {
-                extraClass = 'preview-fit-contain-y';
-              }
-            } else if (fit === 'preview-x') {
-              if (scale > windowScale) {
-                image.style.width = actualBoxHeight * scale + "px";
-                image.style.height = actualBoxHeight + "px";
-                extraClass = 'preview-overflow-x';
-              } else {
-                extraClass = 'preview-fit-contain-x';
-              }
-            }
-          }
-
-          extraClass && image.classList.add(extraClass);
-          setWrapClass(extraClass ? extraClass + "-container" : '');
+          handleImageLoaded(evt, image);
           replaceChild(image);
-          _onLoad && _onLoad(evt, image);
         };
 
         image.onerror = function (evt) {
@@ -7939,9 +9009,10 @@
       }
 
       function handleStaticImageError(e) {
-        var evt = e.nativeEvent;
+        var evt = e ? e.nativeEvent : null;
 
         if (retryCountRef.current >= retryTime) {
+          changeStatus('error');
           onError && onError(evt);
         } else {
           retryCountRef.current += 1;
@@ -8006,7 +9077,7 @@
         }, staticLabel && showImage && !staticRetrying ? /*#__PURE__*/React__default["default"].createElement("img", __assign$2({}, nativeProps, attrs, {
           ref: imageDomRef,
           onLoad: function onLoad(e) {
-            return _onLoad && _onLoad(e.nativeEvent, imageDomRef.current);
+            return handleImageLoaded(e.nativeEvent, imageDomRef.current);
           },
           onError: handleStaticImageError
         })) : null), showLoading && validStatus === 'loading' ? /*#__PURE__*/React__default["default"].createElement("div", {
@@ -19596,9 +20667,7 @@
           unmountOnExit: true
         }, config || {}), {
           close: function close() {}
-        });
-
-        var dynamicProps = __assign$2({}, baseProps); // 不同的key用不同的容器挂载
+        }); // 不同的key用不同的容器挂载
         // @en Different keys are mounted in different containers
 
 
@@ -19607,6 +20676,12 @@
         var leaving = false;
         var render = new ReactDOMRender(Component, div, context).render;
 
+        var dynamicProps = __assign$2(__assign$2({}, baseProps), {
+          getContainer: function getContainer() {
+            return div;
+          }
+        });
+
         function update(newConfig) {
           dynamicProps = __assign$2(__assign$2({}, dynamicProps), newConfig || {});
           render(dynamicProps);
@@ -20444,7 +21519,9 @@
           return renderIndicator(currentIndex, total, lastIndex);
         }
 
-        return openLoaded ? /*#__PURE__*/React__default["default"].createElement(Portal, null, /*#__PURE__*/React__default["default"].createElement("div", {
+        return openLoaded ? /*#__PURE__*/React__default["default"].createElement(Portal, {
+          getContainer: getContainer
+        }, /*#__PURE__*/React__default["default"].createElement("div", {
           className: "image-preview-indicator"
         }, currentIndex + 1, "/", total)) : null;
       } // ios在重设style时图片会消失一下造成闪动，因此在底下垫一张图
@@ -20482,7 +21559,9 @@
       function renderLoadingArea(index) {
         // loadingArea提出来，放到过渡图上层
         // @en The loadingArea is extracted and placed on the upper layer of the transition image
-        return index === openIndex ? /*#__PURE__*/React__default["default"].createElement(Portal, null, /*#__PURE__*/React__default["default"].createElement("div", {
+        return index === openIndex ? /*#__PURE__*/React__default["default"].createElement(Portal, {
+          getContainer: getContainer
+        }, /*#__PURE__*/React__default["default"].createElement("div", {
           className: "image-preview-loading-area"
         }, loadingArea || /*#__PURE__*/React__default["default"].createElement(Loading, {
           type: "circle",