xtf-circle

组件说明

xtf-circle 是环形进度条组件，用于展示进度百分比。支持渐变色、缺口仪表盘样式、动画过渡、自定义端点和中心内容插槽，适用于任务进度、目标完成度和数据占比等场景。

---

基础用法

1. 最简示例

通过 percent 设置进度百分比：

<template>
  <xtf-circle :percent="75" />
</template>

2. 渐变色与自定义样式

通过 color 设置渐变色或纯色，通过 size 控制尺寸，通过 strokeWidth 控制线条宽度：

<template>
  <view style="display: flex; gap: 32rpx; flex-wrap: wrap">
    <xtf-circle :percent="60" :color="{ from: '#3B82F6', to: '#10B981' }" />
    <xtf-circle :percent="80" color="var(--xtf-color-danger)" :size="160" :stroke-width="8" />
    <xtf-circle
      :percent="45"
      color="var(--xtf-color-warning)"
      track-color="var(--xtf-color-surface)"
    />
  </view>
</template>

3. 缺口仪表盘

通过 gapDegree 设置缺口角度，通过 gapPosition 设置缺口位置：

<template>
  <xtf-circle
    :percent="68"
    :color="{ from: '#6366F1', to: '#EC4899' }"
    :gap-degree="60"
    gap-position="bottom"
    stroke-linecap="round"
    :speed="30"
  />
</template>

4. 中心内容插槽

通过默认插槽自定义中心内容：

<template>
  <xtf-circle
    :percent="88"
    :size="220"
    :stroke-width="14"
    :color="{ from: '#3B82F6', to: '#8B5CF6' }"
  >
    <view style="text-align: center">
      <text style="font-size: 40rpx; font-weight: 700; color: var(--xtf-color-text)">88</text>
      <text style="font-size: 22rpx; color: var(--xtf-color-text-secondary)">分</text>
    </view>
  </xtf-circle>
</template>

5. 逆时针与文字格式化

通过 clockwise 切换方向，通过 textFormat 自定义中心文字：

<template>
  <view style="display: flex; gap: 32rpx">
    <xtf-circle :percent="65" :clockwise="false" />
    <xtf-circle :percent="3" :text-format="formatKm" />
  </view>
</template>

<script>
export default {
  methods: {
    formatKm(val) {
      return val + 'km'
    }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
percent	Number | String	0	进度百分比（0~100）	设置进度
size	String | Number	200	圆环直径（rpx）	控制尺寸
strokeWidth	String | Number	12	线条宽度（rpx）	控制线宽
color	String | Object	''	进度颜色，支持渐变 { from, to }	自定义颜色
trackColor	String	''	轨道颜色	自定义轨道色
fill	String	'none'	圆环填充色	填充色
clockwise	Boolean	true	是否顺时针	方向控制
speed	Number | String	60	动画速度（ms），0 无动画	动画控制
strokeLinecap	String	'round'	端点样式：'round' / 'butt' / 'square'	端点样式
gapDegree	Number | String	0	缺口角度（0~360）	仪表盘样式
gapPosition	String	'top'	缺口位置：'top' / 'bottom' / 'left' / 'right'	缺口位置
startAngle	Number | String	null	进度起始角度；0 为右侧，-90 为顶部；设置后优先于 gapPosition	半环与仪表盘
textFormat	Function	null	中心文字格式化函数	自定义文字
customClass	String	''	自定义类名	样式覆盖
customStyle	String | Object	''	自定义样式	动态样式覆盖

---

事件

事件名称	当前实现	回调参数	说明
update:percent	已在 emits 声明，但当前源码未主动触发	(percent: Number)	不应依赖此事件接收动画帧；percent 是单向输入属性。

事件使用示例

<template>
  <view>
    <xtf-button label="增加进度" @click="increase" />
    <xtf-circle :percent="percent" @update:percent="onPercentUpdate" />
  </view>
</template>

<script>
export default {
  data() {
    return { percent: 30 }
  },
  methods: {
    increase() {
      this.percent = Math.min(100, this.percent + 10)
    },
    onPercentUpdate(value) {
      console.log('update:percent：', value)
    }
  }
}
</script>

@update:percent 可按上述方式注册，但当前实现不会主动触发它；请以绑定的 percent 数据作为进度唯一来源。

---

插槽

插槽名	说明
默认插槽	替换圆环中心的百分比文本，可放置 xtf-text 等已有 xtf 组件。

---

主题说明

• 进度颜色默认使用 var(--xtf-color-primary)
• 轨道颜色默认使用 var(--xtf-color-surface-muted)
• 渐变色通过 SVG linearGradient 实现
• 动画使用 setInterval 逐帧递增，速度由 speed 属性控制

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖相关 CSS 变量。