Button 按鈕

按鈕元件，支援多種類型、尺寸、狀態及國風主題色。

基礎用法

vue

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

<template>
  <!-- 預設 -->
  <LhButton>默认按钮</LhButton>
  <!-- primary -->
  <LhButton type="primary">主要按钮</LhButton>
  <!-- success -->
  <LhButton type="success">成功按钮</LhButton>
  <!-- warning -->
  <LhButton type="warning">警告按钮</LhButton>
  <!-- danger -->
  <LhButton type="danger">危险按钮</LhButton>
  <!-- info -->
  <LhButton type="info">信息按钮</LhButton>
</template>

vue

<script>
export default {}
</script>

<template>
  <!-- 預設 -->
  <LhButton>默认按钮</LhButton>
  <!-- primary -->
  <LhButton type="primary">主要按钮</LhButton>
  <!-- success -->
  <LhButton type="success">成功按钮</LhButton>
  <!-- warning -->
  <LhButton type="warning">警告按钮</LhButton>
  <!-- danger -->
  <LhButton type="danger">危险按钮</LhButton>
  <!-- info -->
  <LhButton type="info">信息按钮</LhButton>
</template>

不同尺寸

vue

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

<template>
  <LhButton size="large">大型按钮</LhButton>
  <LhButton>默认按钮</LhButton>
  <LhButton size="small">小型按钮</LhButton>
  <LhButton size="mini">迷你按钮</LhButton>
</template>

vue

<script>
export default {}
</script>

<template>
  <LhButton size="large">大型按钮</LhButton>
  <LhButton>默认按钮</LhButton>
  <LhButton size="small">小型按钮</LhButton>
  <LhButton size="mini">迷你按钮</LhButton>
</template>

樸素按鈕

vue

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

<template>
  <LhButton plain>朴素按钮</LhButton>
  <LhButton type="primary" plain>主要按钮</LhButton>
  <LhButton type="success" plain>成功按钮</LhButton>
</template>

vue

<script>
export default {}
</script>

<template>
  <LhButton plain>朴素按钮</LhButton>
  <LhButton type="primary" plain>主要按钮</LhButton>
  <LhButton type="success" plain>成功按钮</LhButton>
</template>

圓形按鈕

vue

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

<template>
  <LhButton circle>圆</LhButton>
  <LhButton type="primary" circle>主</LhButton>
  <LhButton type="success" circle>成</LhButton>
</template>

vue

<script>
export default {}
</script>

<template>
  <LhButton circle>圆</LhButton>
  <LhButton type="primary" circle>主</LhButton>
  <LhButton type="success" circle>成</LhButton>
</template>

載入狀態

vue

<script setup lang="ts">
import { ref } from 'vue'

const loading1 = ref(false)
</script>

<template>
  <!-- 點選載入 -->
  <LhButton :loading="loading1" @click="loading1 = true">点击加载</LhButton>
  <!-- 載入中 -->
  <LhButton type="primary" loading>加载中</LhButton>
</template>

vue

<script>
export default {
  data() {
    return { loading1: false }
  },
}
</script>

<template>
  <!-- 點選載入 -->
  <LhButton :loading="loading1" @click="loading1 = true">点击加载</LhButton>
  <!-- 載入中 -->
  <LhButton type="primary" loading>加载中</LhButton>
</template>

停用狀態

vue

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

<template>
  <LhButton disabled>禁用按钮</LhButton>
  <LhButton type="primary" disabled>主要按钮</LhButton>
</template>

vue

<script>
export default {}
</script>

<template>
  <LhButton disabled>禁用按钮</LhButton>
  <LhButton type="primary" disabled>主要按钮</LhButton>
</template>

Block 按鈕

vue

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

<template>
  <!-- 區塊級按鈕 -->
  <LhButton block>块级按钮</LhButton>
  <!-- 主要區塊級 -->
  <LhButton type="primary" block>主要块级</LhButton>
</template>

vue

<script>
export default {}
</script>

<template>
  <!-- 區塊級按鈕 -->
  <LhButton block>块级按钮</LhButton>
  <!-- 主要區塊級 -->
  <LhButton type="primary" block>主要块级</LhButton>
</template>

圓角按鈕

round 提供大圓角膠囊外形（與整圓的 circle 不同）。

vue

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

<template>
  <LhButton round>圆角按钮</LhButton>
  <LhButton type="primary" round>圆角主要</LhButton>
</template>

vue

<script>
export default {}
</script>

<template>
  <LhButton round>圆角按钮</LhButton>
  <LhButton type="primary" round>圆角主要</LhButton>
</template>

圖示按鈕

icon 接受圖示名稱，也可用 #icon 插槽自訂繪製。

vue

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

<template>
  <!-- 搜尋 -->
  <LhButton icon="search">搜索</LhButton>
  <!-- 收藏 -->
  <LhButton type="primary" icon="star">收藏</LhButton>
  <!-- 自訂圖示插槽 -->
  <LhButton circle>
    <template #icon>🔍</template>
  </LhButton>
</template>

vue

<script>
export default {}
</script>

<template>
  <!-- 搜尋 -->
  <LhButton icon="search">搜索</LhButton>
  <!-- 收藏 -->
  <LhButton type="primary" icon="star">收藏</LhButton>
  <!-- 自訂圖示插槽 -->
  <LhButton circle>
    <template #icon>🔍</template>
  </LhButton>
</template>

連結按鈕

設定 href 後繪製為 <a> 標籤，target 控制開啟方式；未設定 href 時 native-type 決定原生 button 類型。

GitHub

vue

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

<template>
  <LhButton href="https://github.com/lhgb-top/lh-ui-plus" target="_blank">GitHub</LhButton>
  <LhButton native-type="submit" type="primary">提交</LhButton>
</template>

vue

<script>
export default {}
</script>

<template>
  <LhButton href="https://github.com/lhgb-top/lh-ui-plus" target="_blank">GitHub</LhButton>
  <LhButton native-type="submit" type="primary">提交</LhButton>
</template>

sx 快速版面配置

透過 sx 屬性快速設定間距與尺寸，無需編寫額外 CSS。

vue

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

<template>
  <LhButton type="primary" :sx="{ mt: 2, mx: 1 }">上方间距 2，水平间距 1</LhButton>
</template>

vue

<script>
export default {}
</script>

<template>
  <LhButton type="primary" :sx="{ mt: 2, mx: 1 }">上方间距 2，水平间距 1</LhButton>
</template>

sx 基於 8px 基準：mt: 2 → marginTop: 16px，mx: 1 → marginLeft: 8px; marginRight: 8px。完整屬性請參考 sx 快速版面配置。

自訂主題

為按鈕應用自訂的主題色，透過 LhConfigProvider 的 themeVars 屬性覆寫 CSS 變數。

vue

<script setup lang="ts">
import { LhConfigProvider, LhButton } from '@lh-ui/vue3'

const cerblueTheme = {
  'primary-color': '#2B4C7C',
  'primary-color-hover': '#3D649E',
  'primary-color-bg': '#E8EDF3',
  'bg-color': '#F0F4F8',
}
</script>

<template>
  <LhConfigProvider :theme-vars="cerblueTheme">
    <!-- 青花瓷按鈕 -->
    <LhButton type="primary">青花瓷按钮</LhButton>
    <!-- 成功 -->
    <LhButton type="success">成功</LhButton>
  </LhConfigProvider>
</template>

vue

<script>
import { LhConfigProvider, LhButton } from '@lh-ui/vue3'

export default {
  components: { LhConfigProvider, LhButton },
  data() {
    return {
      cerblueTheme: {
        'primary-color': '#2B4C7C',
        'primary-color-hover': '#3D649E',
        'primary-color-bg': '#E8EDF3',
        'bg-color': '#F0F4F8',
      },
    }
  },
}
</script>

<template>
  <LhConfigProvider :theme-vars="cerblueTheme">
    <!-- 青花瓷按鈕 -->
    <LhButton type="primary">青花瓷按钮</LhButton>
    <!-- 成功 -->
    <LhButton type="success">成功</LhButton>
  </LhConfigProvider>
</template>

更多主題請參考主題定製。

國際化

按鈕文字可以透過 LhConfigProvider 配合語言包實現國際化切換。

vue

<script setup lang="ts">
import { ref, computed } from 'vue'
import { LhConfigProvider, LhButton, zhCN, enUS } from '@lh-ui/vue3'

const locale = ref('zh-CN')
const messages = computed(() => locale.value === 'zh-CN' ? zhCN : enUS)
</script>

<template>
  <LhConfigProvider :locale="messages">
    <LhButton @click="locale = locale === 'zh-CN' ? 'en-US' : 'zh-CN'">
      {{ locale === 'zh-CN' ? '切换至英文' : 'Switch to Chinese' }}
    </LhButton>
  </LhConfigProvider>
</template>

vue

<script>
import { LhConfigProvider, LhButton, zhCN, enUS } from '@lh-ui/vue3'

export default {
  components: { LhConfigProvider, LhButton },
  data() {
    return { locale: 'zh-CN' }
  },
  computed: {
    messages() {
      return this.locale === 'zh-CN' ? zhCN : enUS
    },
  },
}
</script>

<template>
  <LhConfigProvider :locale="messages">
    <LhButton @click="locale = locale === 'zh-CN' ? 'en-US' : 'zh-CN'">
      {{ locale === 'zh-CN' ? '切换至英文' : 'Switch to Chinese' }}
    </LhButton>
  </LhConfigProvider>
</template>

Button API

Props

屬性名	說明	類型	預設值
type	按鈕類型	`"success" \| "warning" \| "error" \| "info" \| "danger" \| "default" \| "primary"`	`LH_BUTTON_TYPE_CONST.default`
size	按鈕尺寸，未傳時從 ConfigProvider 繼承	`"small" \| "medium" \| "large" \| "mini" \| "x-large"`	—
loading	載入狀態	`boolean`	`false`
disabled	停用狀態	`boolean`	`false`
plain	是否為樸素按鈕	`boolean`	`false`
block	是否區塊級	`boolean`	`false`
round	是否為圓角按鈕	`boolean`	`false`
circle	是否為圓形按鈕	`boolean`	`false`
icon	圖示名稱（內建 LhIcon 圖示，如 `search`；需自訂繪製時用 `icon` 插槽覆寫）	`LhIconName`	—
nativeType	原生 button 類型（僅未傳 `href` 時生效）	`"button" \| "submit" \| "reset"`	`'button'`
href	連結位址（傳入後繪製為 `<a>` 而非 `<button>`）	`string`	`''`
target	連結開啟方式	`string`	`'_self'`
themeVars	元件級主題變數，覆寫 ConfigProvider 設定	`{ [x: string]: string; }`	—
bgPattern	元件級背景花紋，覆寫 ConfigProvider 設定	`string`	—
sx	sx 快速版面配置屬性	`LhSxProps`	—

Events

事件名	說明	回呼參數
click	點選事件	`(event: MouseEvent)`

Slots

插槽名	說明
default	按鈕內容
icon	自訂圖示繪製（覆寫 `icon` 屬性的預設 `LhIcon`）

無障礙

鍵盤焦點環：根元素統一提供 :focus-visible 焦點環（鍵盤導覽時顯示，滑鼠點選不顯示），用 --lh-primary-color 主題變數著色，明暗模式自動跟隨，無需額外設定
圖示按鈕命名：按鈕只有圖示沒有文字時（如圓形圖示按鈕），螢幕閱讀器無法獲知用途，必須傳 aria-label，該屬性會自動透傳到根元素。icon prop 直接傳內建圖示名稱（如 icon="search"）；需要圖示以外的自訂繪製時用 icon 插槽：
vue
```
<LhButton circle aria-label="搜索">
  <template #icon>
    <LhIcon name="search" />
  </template>
</LhButton>
```
動效降級：載入動畫尊重系統 prefers-reduced-motion 設定（減弱動態效果時停用旋轉）

類型定義

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

LhButtonProps

export interface LhButtonProps {
  type?: LhButtonType
  /** 尺寸，可選。若不傳則從 ConfigProvider 繼承 */
  size?: LhButtonSize
  loading?: boolean
  disabled?: boolean
  plain?: boolean
  block?: boolean
  round?: boolean
  circle?: boolean
  /** 圖示名稱（內建 LhIcon 圖示，如 `search`；需自訂繪製時用 `icon` 插槽覆寫） */
  icon?: LhIconName
  nativeType?: 'button' | 'submit' | 'reset'
  href?: string
  target?: string
  /** 元件級主題變數，覆寫 ConfigProvider 的全域 themeVars 和 componentTheme */
  themeVars?: Record<string, string>
  /** 元件級背景花紋，覆寫 ConfigProvider 設定（不受 patternComponents 白名單限制） */
  bgPattern?: string
  /** sx 快速版面配置屬性 */
  sx?: LhSxProps
}

LhButtonType

export type LhButtonType = (typeof LH_BUTTON_TYPE_CONST)[keyof typeof LH_BUTTON_TYPE_CONST]

LhButtonSize

export type LhButtonSize = (typeof LH_BUTTON_SIZE_CONST)[keyof typeof LH_BUTTON_SIZE_CONST]

LhIconName _{（來自 @lh-ui/share/core/icon (svgs.ts)）}

export type LhIconName = keyof typeof LH_ICON_SVGS_CONST

Button 按鈕 ​

基礎用法 ​

不同尺寸 ​

樸素按鈕 ​

圓形按鈕 ​

載入狀態 ​

停用狀態 ​

Block 按鈕 ​

圓角按鈕 ​

圖示按鈕 ​

連結按鈕 ​

sx 快速版面配置 ​

自訂主題 ​

國際化 ​

Button API ​

Props ​

Events ​

Slots ​

無障礙 ​

類型定義 ​