@fjyueke/arco-mcp 1.0.0

package/metaData/components/progress/example/index.tsx

@@ -0,0 +1,256 @@
+import { cls } from '@arco-design/mobile-utils';
+import React, { useRef, forwardRef, Ref, useImperativeHandle } from 'react';
+import { ContextLayout } from '../context-provider';
+import { getStyleWithVendor, useProgress } from '../_helpers';
+
+type PercentPosition = 'left' | 'innerLeft' | 'right' | 'follow';
+export type BezierType = [number, number, number, number];
+export interface ProgressProps {
+    /**
+     * 自定义类名
+     * @en Custom classname
+     */
+    className?: string;
+    /**
+     * 自定义样式
+     * @en Custom stylesheet
+     */
+    style?: React.CSSProperties;
+    /**
+     * 文字显示位置
+     * @en Text display position
+     * @default "center"
+     */
+    percentPosition?: PercentPosition;
+    /**
+     * 是否显示进度条内部文字
+     * @en Whether to display the text inside the progress bar
+     * @default true
+     */
+    showPercent?: boolean;
+    /**
+     * 进度环百分比
+     * @en Progress percentage
+     */
+    percentage: number;
+    /**
+     * 进度条内部文字显示（一个函数，返回ReactNode类型，回调参数为当前进度百分比）
+     * @en The text display inside the progress bar (a function that returns the ReactNode type, and the callback parameter is the current progress percentage)
+     */
+    renderPercent?: (percentage: number) => React.ReactNode;
+    /**
+     * 轨道颜色
+     * @en Track color
+     */
+    trackColor?: string;
+    /**
+     * 进度条颜色
+     * @en Progress bar color
+     */
+    progressColor?: string;
+    /**
+     * 是否置灰
+     * @en Whether to be disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 轨道粗细
+     * @en Track thickness
+     * @default 一般默认为4，percentPosition=innerLeft 时为18，mode=nav时为2
+     * @default_en Generally the default is 4, when percentPosition=innerLeft is 18, when mode=nav is 2
+     */
+    trackStroke?: number;
+    /**
+     * 进度条粗细
+     * @en progress bar thickness
+     * @default 继承 trackStroke 值
+     * @default_en Inherit trackStroke value
+     */
+    progressStroke?: number;
+    /**
+     * 每增加step步长所需的毫秒数
+     * @en The number of milliseconds required to increase the step size
+     * @default 300
+     */
+    duration?: number;
+    /**
+     * 步长（增加步长，以step增长）
+     * @en Step size (increase the step size, grow by step)
+     * @default 1
+     */
+    step?: number;
+    /**
+     * 进度条是否两端圆角
+     * @en Whether the progress bar has rounded corners at both ends
+     * @default true
+     */
+    filleted?: boolean;
+    /**
+     * 初始化percentage时是否以动画形式过渡到目的值
+     * @en Whether to animate the transition to the destination value when initializing percentage
+     * @default true
+     */
+    mountedTransition?: boolean;
+    /**
+     * 初始化时动画的贝塞尔曲线
+     * @en Animated bezier curves at initialization
+     * @default [0.34, 0.69, 0.1, 1]
+     */
+    mountedBezier?: BezierType;
+    /**
+     * 模式可选为nav或者base模式
+     * @en The mode can be selected as nav or base mode
+     * @default "base"
+     */
+    mode?: 'nav' | 'base';
+    /**
+     * 距离屏幕顶部的距离（只有当mode为"nav"才有效）
+     * @en The distance from the top of the screen (only valid when mode is "nav")
+     * @default 0
+     */
+    top?: number;
+}
+
+export interface ProgressRef {
+    /**
+     * 最外层元素 DOM
+     * @en The outermost element DOM
+     */
+    dom: HTMLDivElement | null;
+}
+
+/**
+ * 进度条组件，可根据外界传递进来的百分比进行进度展示
+ * @en Progress bar, which can display progress according to the percentage passed in from the outside
+ * @type 反馈
+ * @type_en Feedback
+ * @name 进度条
+ * @name_en Progress
+ */
+const Progress = forwardRef((props: ProgressProps, ref: Ref<ProgressRef>) => {
+    const { mode = 'base' } = props;
+    const percentage = Math.min(100, Math.max(props.percentage, 0));
+    const {
+        top,
+        percentPosition = 'right',
+        className = '',
+        style,
+        showPercent = mode === 'base',
+        renderPercent,
+        trackColor,
+        progressColor,
+        disabled = false,
+        trackStroke,
+        progressStroke,
+        duration = 300,
+        step = 1,
+        filleted = true,
+        mountedTransition = true,
+        mountedBezier = [0.34, 0.69, 0.1, 1],
+    } = props;
+    const domRef = useRef<HTMLDivElement | null>(null);
+    const [currentPercentage, transitionControl] = useProgress(
+        mountedTransition,
+        percentage,
+        duration,
+        mountedBezier,
+        step,
+    );
+    useImperativeHandle(ref, () => ({
+        dom: domRef.current,
+    }));
+    function renderText(position?: PercentPosition) {
+        if (!showPercent) {
+            return null;
+        }
+        if (position === 'follow') {
+            return renderPercent !== void 0 ? (
+                renderPercent(currentPercentage)
+            ) : (
+                <div
+                    className={cls('text-follow', {
+                        'inner-disabled inner-block-disabled': disabled,
+                    })}
+                    style={{ background: progressColor }}
+                >
+                    {currentPercentage}%
+                </div>
+            );
+        }
+        if (position === percentPosition) {
+            return (
+                <div
+                    style={{ color: progressColor }}
+                    className={cls('text', `text-${percentPosition}`, {
+                        'text-disabled':
+                            disabled && (percentPosition === 'left' || percentPosition === 'right'),
+                    })}
+                >
+                    {renderPercent !== void 0
+                        ? renderPercent(currentPercentage)
+                        : `${currentPercentage}%`}
+                </div>
+            );
+        }
+        return null;
+    }
+    function renderBarProgress({ prefixCls }) {
+        return (
+            <div
+                role="progressbar"
+                aria-valuenow={percentage}
+                aria-valuemax={100}
+                aria-valuemin={0}
+                className={cls(
+                    `${prefixCls}-progress`,
+                    { 'progress-fixed': mode === 'nav' },
+                    { 'progress-disabled': disabled },
+                    className,
+                )}
+                style={{
+                    top,
+                    ...style,
+                }}
+                ref={domRef}
+            >
+                <div className="progress-wrapper">
+                    {renderText('left')}
+                    <div
+                        style={{
+                            background: trackColor,
+                            height: trackStroke,
+                        }}
+                        className={cls(
+                            'progress-track',
+                            `position-${percentPosition}`,
+                            { filleted },
+                            { 'nav-mode': mode === 'nav' },
+                        )}
+                    >
+                        <div
+                            style={getStyleWithVendor({
+                                background: progressColor,
+                                width: `${currentPercentage}%`,
+                                height: progressStroke,
+                                transition: transitionControl
+                                    ? `width linear ${duration / 1000}s`
+                                    : '',
+                            })}
+                            className={cls('progress-bar', { 'bar-disabled': disabled, filleted })}
+                        >
+                            {percentPosition === 'follow' ? (
+                                <div className="wrapper">{renderText('follow')}</div>
+                            ) : null}
+                        </div>
+                    </div>
+                    {renderText('right')}
+                    {renderText('innerLeft')}
+                </div>
+            </div>
+        );
+    }
+    return <ContextLayout>{renderBarProgress}</ContextLayout>;
+});
+
+export default Progress;

package/metaData/components/pull-refresh/doc.md

@@ -0,0 +1,37 @@
+### 其他
+
+# 下拉刷新 PullRefresh
+
+下拉刷新数据组件。
+
+======
+
+> 属性/Props
+
+|参数|描述|类型|默认值|
+|----------|-------------|------|------|
+|type|下拉刷新组件不同的实现方式，android \- 常规的外层容器 transform，ios \- 利用 ios scrollTop 负值实现下拉及回弹(性能优于transform)，仅ios可用。指定该属性值后优先级高于 useIosOptimize|"ios" \| "android"|跟随系统|
+|useIosOptimize|在 ios 上是否使用 scrollTop 负值实现下拉及回弹，而不是 transform，关闭后所有机型都使用 transform 的方式|boolean|false|
+|children|子元素|ReactNode|必填|
+|className|样式类名|string|-|
+|style|自定义样式|CSSProperties|-|
+|disabled|是否禁用|boolean|false|
+|finishDelay|加载完成后，展示加载完成的时间(ms)|number|300|
+|loosingText|下拉到可释放时的展示元素（type 为 ios 失效）|ReactNode|-|
+|loadingText|加载中的展示元素|ReactNode|-|
+|pullingText|下拉时的展示元素|ReactNode|-|
+|finishText|加载完成的展示元素|ReactNode|-|
+|initialText|初始状态还未下拉时的展示元素|ReactNode|pullingText属性值|
+|dampRate|阻尼系数（type 为 ios 失效）|number|4|
+|onRefresh|刷新触发事件|() =\> Promise\<void\>|-|
+|useHideAsNestedScroll|惯性滑动时隐藏展示元素|boolean|true|
+|loosingMinHeight|释放可刷线的最小距离(px)|number|loosingText 的高度|
+|allowPullWhenNotTop|未滚到顶部时向下滑动也允许触发下拉刷新，可能影响ios回弹动画效果|boolean|false|
+
+> 引用/Refs
+
+|参数|描述|类型|
+|----------|-------------|------|
+|dom|最外层元素 DOM|HTMLDivElement|
+|refresh|主动触发刷新，执行完成动画后异步返回|() =\> Promise\<void\>|
+|updateIOSHeight|手动更新 IOS 容器自动高度|() =\> void|

package/metaData/components/pull-refresh/example/android-pull-refresh.tsx

@@ -0,0 +1,260 @@
+import React, {
+    useRef,
+    forwardRef,
+    Ref,
+    useCallback,
+    useMemo,
+    useContext,
+    useEffect,
+    useImperativeHandle,
+} from 'react';
+import { cls, nextTick, defaultLocale } from '@arco-design/mobile-utils';
+import { Promise } from 'es6-promise';
+import Loading from '../loading';
+import { GlobalContext } from '../context-provider';
+import { PullRefreshRef, PullRefreshStatus, PullRefreshBasicProps } from './model';
+import { useCommonState, useAddScrollEvents, useCheckAsStart } from './hooks';
+import { setStyleWithVendor } from '../_helpers';
+
+const dampRateCalculate = (val: number, tipsHeight: number, dampRate: number) =>
+    val > tipsHeight ? tipsHeight + (val - tipsHeight) / dampRate : val;
+
+export const PullRefresh = forwardRef((props: PullRefreshBasicProps, ref: Ref<PullRefreshRef>) => {
+    const { prefixCls, locale = defaultLocale } = useContext(GlobalContext);
+
+    const {
+        className,
+        style,
+        children,
+        loosingText = (
+            <div className={cls(`${prefixCls}-pull-refresh-label-text`)}>
+                <span>{locale.PullRefresh.loosingText}</span>
+            </div>
+        ),
+        loadingText = (
+            <div className={cls(`${prefixCls}-pull-refresh-label-text`)}>
+                <Loading type="circle" radius={4} />
+                <span>{locale.PullRefresh.loadingText}</span>
+            </div>
+        ),
+        pullingText = (
+            <div className={cls(`${prefixCls}-pull-refresh-label-text`)}>
+                <span>{locale.PullRefresh.pullingText}</span>
+            </div>
+        ),
+        finishText = (
+            <div className={cls(`${prefixCls}-pull-refresh-label-text`)}>
+                <span>{locale.PullRefresh.finishText}</span>
+            </div>
+        ),
+        initialText,
+        finishDelay = 300,
+        loosingMinHeight,
+        dampRate = 4,
+        disabled = false,
+        useHideAsNestedScroll = true,
+        onRefresh,
+        allowPullWhenNotTop = false,
+    } = props;
+    const placeRef = useRef<HTMLDivElement>(null);
+    const touchRef = useRef<{ start: number; x: number; y: number } | null>(null);
+    const currentTranslateYRef = useRef(0);
+    const onTouching = useRef(false);
+    const {
+        loadingRef,
+        status,
+        setStatus,
+        labelRef,
+        domRef,
+        touching,
+        setTouching,
+        loosingHeight,
+        handleRefresh,
+        tipsHeight,
+    } = useCommonState({ loosingMinHeight, onRefresh });
+
+    const { ifShouldHandle } = useCheckAsStart({ domRef, allowPullWhenNotTop });
+
+    const currentLabelStyle = useMemo(() => {
+        return useHideAsNestedScroll &&
+            !touching &&
+            status === PullRefreshStatus.Pulling &&
+            (domRef?.current?.scrollTop ?? 0) > 0
+            ? { opacity: 0 }
+            : {};
+    }, [useHideAsNestedScroll, touching]);
+
+    const pullTextConfig = {
+        [PullRefreshStatus.Static]: initialText === void 0 ? pullingText : initialText,
+        [PullRefreshStatus.Pulling]: pullingText,
+        [PullRefreshStatus.Loosing]: loosingText || pullingText,
+        [PullRefreshStatus.Loading]: loadingText,
+        [PullRefreshStatus.Finish]: finishText,
+    };
+
+    const scroll = (y: number, ms: number, callback?: () => void) => {
+        if (y < 5) {
+            if (y < 0 || ms === 0) {
+                currentTranslateYRef.current = 0;
+                return;
+            }
+        }
+        const translateY = dampRateCalculate(y, loosingHeight, dampRate);
+        currentTranslateYRef.current = translateY;
+        placeRef.current &&
+            setStyleWithVendor(placeRef.current, {
+                transform: translateY ? `translateY(${translateY}px) translateZ(0)` : '',
+                ...(ms ? { transition: `all ${ms / 1000}s` } : {}),
+            });
+        callback &&
+            setTimeout(() => {
+                callback();
+            }, ms);
+    };
+
+    const reset = (callback = () => {}) => {
+        scroll(0, 300, () => {
+            if (domRef.current && domRef.current.scrollTop < 0) {
+                domRef.current.scrollTop = 0;
+            }
+            loadingRef.current = false;
+            setStatus(PullRefreshStatus.Static);
+            placeRef.current && setStyleWithVendor(placeRef.current, { transition: '' });
+            callback();
+        });
+    };
+
+    const handleTouchStart = useCallback(
+        (e: HTMLElementEventMap['touchstart']) => {
+            if (disabled || touchRef.current || loadingRef.current || !domRef.current) return;
+            if (!ifShouldHandle()) return;
+            setTouching(true);
+            const { pageX, pageY } = e.touches[0];
+            if (pageX && pageY) {
+                touchRef.current = { start: domRef.current?.scrollTop, x: pageX, y: pageY };
+            }
+            setStatus(PullRefreshStatus.Pulling);
+        },
+        [disabled, ifShouldHandle],
+    );
+
+    const refresh = () =>
+        new Promise<void>(resolve => {
+            setStatus(PullRefreshStatus.Loading);
+            nextTick(() => {
+                scroll(tipsHeight, 300);
+                handleRefresh().then(() => {
+                    if (pullTextConfig[PullRefreshStatus.Finish]) {
+                        setStatus(PullRefreshStatus.Finish);
+                        setTimeout(() => {
+                            reset(resolve);
+                        }, finishDelay);
+                    } else {
+                        reset(resolve);
+                    }
+                });
+            });
+        });
+    const handleTouchEnd = useCallback(() => {
+        if (currentTranslateYRef.current === 0 && !ifShouldHandle()) {
+            return;
+        }
+        onTouching.current = false;
+        setTouching(false);
+
+        if (disabled || !touchRef.current || loadingRef.current) return;
+        touchRef.current = null;
+        if (status === PullRefreshStatus.Loosing) {
+            refresh();
+        } else {
+            reset();
+        }
+    }, [disabled, status, tipsHeight, ifShouldHandle]);
+
+    const handleTouchMove = useCallback(
+        (e: HTMLElementEventMap['touchmove']) => {
+            onTouching.current = true;
+
+            if (disabled || loadingRef.current || !domRef.current) return;
+
+            if (!touchRef.current) return;
+            const { pageY } = e.touches[0];
+            const pullY = pageY - touchRef.current.y - touchRef.current.start;
+
+            if (currentTranslateYRef.current === 0 && domRef.current.scrollTop > 0) {
+                return;
+            }
+
+            if (currentTranslateYRef.current === 0 && pullY < 0) {
+                return;
+            }
+            setStatus(() =>
+                pullY > loosingHeight ? PullRefreshStatus.Loosing : PullRefreshStatus.Pulling,
+            );
+            scroll(pullY, 0);
+
+            e.stopPropagation();
+            e.cancelable && e.preventDefault();
+        },
+        [disabled, loosingHeight],
+    );
+
+    useEffect(() => {
+        const onScroll = () => {
+            if (
+                onTouching.current &&
+                domRef.current &&
+                (domRef.current.scrollTop < 0 || currentTranslateYRef.current)
+            ) {
+                // 禁止 ios 负 scrollTop 和双层滚动
+                domRef.current.scrollTop = 0;
+            }
+        };
+        domRef.current?.addEventListener('scroll', onScroll);
+        return () => {
+            domRef.current?.removeEventListener('scroll', onScroll);
+        };
+    }, []);
+
+    useImperativeHandle(ref, () => ({
+        dom: domRef.current,
+        refresh,
+        updateIOSHeight() {
+            console.warn('updateIOSHeight 仅在 type="ios" 时可用');
+        },
+    }));
+
+    useAddScrollEvents({ domRef, handleTouchStart, handleTouchMove, handleTouchEnd });
+
+    return (
+        <div
+            className={cls(`${prefixCls}-pull-refresh all-border-box is-android`, className, {
+                'is-disabled':
+                    (disabled || (!touching && useHideAsNestedScroll)) &&
+                    status !== PullRefreshStatus.Loading,
+            })}
+            style={style}
+            ref={domRef}
+        >
+            <div className={cls(`${prefixCls}-pull-refresh-place`)} ref={placeRef}>
+                <div
+                    className={cls(`${prefixCls}-pull-refresh-label`)}
+                    ref={labelRef}
+                    style={currentLabelStyle}
+                >
+                    {pullTextConfig[status]}
+                </div>
+                <div
+                    className={cls(`${prefixCls}-pull-refresh-content`, {
+                        'is-loading': [
+                            PullRefreshStatus.Loading,
+                            PullRefreshStatus.Finish,
+                        ].includes(status),
+                    })}
+                >
+                    {children}
+                </div>
+            </div>
+        </div>
+    );
+});

package/metaData/components/pull-refresh/example/index.tsx

@@ -0,0 +1,44 @@
+import React, { forwardRef, Ref } from 'react';
+import { PullRefresh as IOSPullRefresh } from './ios-pull-refresh';
+import { PullRefresh as AndroidPullRefresh } from './android-pull-refresh';
+import { PullRefreshBasicProps, PullRefreshRef } from './model';
+import { useSystem } from '../_helpers';
+
+export type { PullRefreshRef } from './model';
+
+export interface PullRefreshProps extends PullRefreshBasicProps {
+    /**
+     * 下拉刷新组件不同的实现方式，android - 常规的外层容器 transform，ios - 利用 ios scrollTop 负值实现下拉及回弹(性能优于transform)，仅ios可用。指定该属性值后优先级高于 useIosOptimize
+     * @en Different implementation methods of PullRefresh, android - conventional outer container transform, ios - use ios scrollTop negative value to achieve pull-down and rebound (performance is better than transform), only available for ios. After specifying value, the priority is higher than useIosOptimize
+     * @default 跟随系统
+     * @default_en Follow the system
+     */
+    type?: 'ios' | 'android';
+    /**
+     * 在 ios 上是否使用 scrollTop 负值实现下拉及回弹，而不是 transform，关闭后所有机型都使用 transform 的方式
+     * @en Whether to use the negative value of scrollTop on ios to achieve pull-down and rebound instead of transform. After closing, all models use transform
+     * @default false
+     */
+    useIosOptimize?: boolean;
+}
+
+/**
+ * 下拉刷新数据组件。
+ * @en PullRefresh component that pulls down to refresh data.
+ * @name 下拉刷新
+ * @name_en PullRefresh
+ * @type 其他
+ * @type_en Others
+ */
+const PullRefresh = forwardRef((props: PullRefreshProps, ref: Ref<PullRefreshRef>) => {
+    const { type, useIosOptimize, children, ...rest } = props;
+    const system = useSystem();
+
+    const Container =
+        type === 'ios' || (useIosOptimize && (type || system) === 'ios')
+            ? IOSPullRefresh
+            : AndroidPullRefresh;
+    return <Container {...{ ...rest, ref }}>{children}</Container>;
+});
+
+export default PullRefresh;