Progress 進度條

LhProgress 用於展示任務或容量的完成進度，支援線形與圓形兩種形態，可自訂顏色與文字。

基礎用法

線形進度條

60%

<script setup lang="ts">
</script>

<template>
  <LhProgress :percentage="60" />
</template>

<script>
export default {}
</script>

<template>
  <LhProgress :percentage="60" />
</template>

狀態

normal / success / warning / exception，達到 100 自動 success

100%

80%

40%

<script setup lang="ts">
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <LhProgress :percentage="100" />
    <LhProgress :percentage="80" status="warning" />
    <LhProgress :percentage="40" status="exception" />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <LhProgress :percentage="100" />
    <LhProgress :percentage="80" status="warning" />
    <LhProgress :percentage="40" status="exception" />
  </div>
</template>

自訂顏色與文字

color 支援字串與函式，format 自訂文案

55%

70 分

<script setup lang="ts">
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <LhProgress :percentage="55" color="#B8860B" />
    <LhProgress
      :percentage="70"
      :color="(p: number) => `hsl(${p * 1.2}, 60%, 45%)`"
      :format="(p: number) => `${p} 分`"
    />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <LhProgress :percentage="55" color="#B8860B" />
    <LhProgress
      :percentage="70"
      :color="(p: number) => `hsl(${p * 1.2}, 60%, 45%)`"
      :format="(p: number) => `${p} 分`"
    />
  </div>
</template>

圓形進度

type 設為 circle

75%

100%

<script setup lang="ts">
</script>

<template>
  <div style="display: flex; align-items: center; gap: 24px">
    <LhProgress type="circle" :percentage="75" />
    <LhProgress type="circle" :percentage="100" :width="100" :stroke-width="8" />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <div style="display: flex; align-items: center; gap: 24px">
    <LhProgress type="circle" :percentage="75" />
    <LhProgress type="circle" :percentage="100" :width="100" :stroke-width="8" />
  </div>
</template>

不展示文字

showText 設為 false

<script setup lang="ts">
</script>

<template>
  <LhProgress :percentage="45" :show-text="false" />
</template>

<script>
export default {}
</script>

<template>
  <LhProgress :percentage="45" :show-text="false" />
</template>

API

Props

屬性名	說明	類型	預設值
percentage	進度百分比，超出 [0, 100] 自動鉗制	number	0
type	形態	"line" | "circle"	'line'
status	狀態，normal 時達到 100 自動轉為 success	"normal" | "success" | "warning" | "exception"	'normal'
color	進度條顏色：字串或按百分比回傳顏色的函式	string | ((percentage: number) => string)	—
strokeWidth	線條寬度 px（line 為高度，circle 為描邊寬度）	number	6
width	圓形模式畫布寬度 px	number	126
showText	是否展示文字	boolean	true
format	自訂文字格式化	(percentage: number) => string	—
sx	sx 快速版面配置屬性	LhSxProps	—

Slots

插槽名	說明	作用域
text	自訂文字內容	{ percentage }

無障礙

• 根元素帶 role="progressbar" 與 aria-valuemin / aria-valuemax / aria-valuenow，對齊 WAI-ARIA progressbar 模式
• aria-valuetext 同步可見文案：預設為百分比，傳 format 時播報格式化後的文字（如「42 分」）
• 鉗制後的值同步到 aria-valuenow，不會出現超出範圍的播報

類型定義

本元件對外匯出的 TypeScript 類型結構如下（自動提取自 packages/components/progress/src/types.ts 與 @lh-ui/share/core/* 原始碼，點選各條目展開檢視完整定義；屬性說明見上方 Props 表）：

LhProgressProps

export interface LhProgressProps {
  /** 進度百分比 0-100（超出會自動鉗制） */
  percentage: number
  type?: LhProgressType
  status?: LhProgressStatus
  /** 進度條顏色：字串或按百分比回傳顏色的函式 */
  color?: string | ((percentage: number) => string)
  /** 線條寬度 px（line 為高度，circle 為描邊寬度） */
  strokeWidth?: number
  /** 圓形模式畫布寬度 px */
  width?: number
  showText?: boolean
  /** 自訂文字格式化 */
  format?: (percentage: number) => string
  /** sx 快速版面配置屬性 */
  sx?: LhSxProps
}

LhProgressType _{（來自 @lh-ui/share/core/progress）}

export type LhProgressType = 'line' | 'circle'

LhProgressStatus _{（來自 @lh-ui/share/core/progress）}

export type LhProgressStatus = 'normal' | 'success' | 'warning' | 'exception'