HumanBreak/docs/api/user-client-modules/组件 Progress.md

Progress 组件 API 文档

本文档由 DeepSeek R1 模型生成并微调。

---

核心特性

• 动态进度显示：支持 0.0~1.0 范围的进度可视化
• 双色样式分离：可分别定制已完成/未完成部分样式
• 精准定位：支持像素级坐标控制
• 平滑过渡：数值变化自动触发重绘

---

Props 属性说明

属性名	类型	默认值	描述
loc	ElementLocator	必填	进度条容器坐标
progress	number	必填	当前进度值（0.0~1.0）
success	CanvasStyle	green	已完成部分填充样式
background	CanvasStyle	gray	未完成部分填充样式
lineWidth	number	2	进度条线宽（像素）

---

使用示例

基础用法

import { defineComponent, ref } from 'vue';
import { Progress } from '@user/client-modules';
import { onTick } from '@motajs/render';

export const MyCom = defineComponent(() => {
    // 创建响应式进度值
    const loadingProgress = ref(0);

    // 模拟进度更新
    onTick(() => {
        if (loadingProgress.value < 1) {
            loadingProgress.value += 0.002;
        }
    });

    return () => (
        <Progress
            loc={[20, 20, 200, 8]} // x=20, y=20, 宽200px, 高8px
            progress={loadingProgress.value}
        />
    );
});

自定义样式

// 自定义进度条的已完成和未完成部分的样式
<Progress
    loc={[50, 100, 300, 12]}
    progress={0.65}
    success="rgb(54, 255, 201)"
    background="rgba(255,255,255,0.2)"
    lineWidth={6}
/>

垂直进度条

// 通过旋转容器实现垂直效果，注意锚点的使用
<container rotation={-Math.PI / 2} loc={[100, 200, 150, 8, 0.5, 0.5]}>
    <Progress loc={[0, 0, 150, 8]} progress={0.8} success="#FF5722" />
</container>

---

动画效果实现

平滑过渡示例

import { transitioned } from '@user/client-modules';
import { pow } from 'mutate-animate';

const progressValue = transitioned(0, 2000, pow(2, 'out'));
progressValue.set(1); // 2秒内完成二次曲线平滑过渡

return () => (
    <Progress loc={[0, 0, 400, 10]} progress={progressValue.ref.value} />
);

---

注意事项

1. 坐标系统
   实际渲染高度由 loc[3] 参数控制，会自动上下居中：

   // 情况1：显式指定高度为8px
   <Progress loc={[0, 0, 200, 8]} />