Card 卡片

乘載標題、內容、底部操作的資訊容器。可整體點選（自帶 button 鍵盤語意），支援載入佔位與 sx 快速版面配置。

基礎用法

基礎用法

雨打芭蕉

隔窗知夜雨，芭蕉先有聲。

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

<template>
  <LhCard title="雨打芭蕉">
    隔窗知夜雨，芭蕉先有声。
  </LhCard>
</template>

<script>
export default {}
</script>

<template>
  <LhCard title="雨打芭蕉">
    隔窗知夜雨，芭蕉先有声。
  </LhCard>
</template>

shadow 控制陰影顯示時機：always（預設）/ hover（懸停時）/ never。

陰影時機

hover 陰影

懸停時出現陰影。

無陰影

始終無陰影。

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

<template>
  <LhCard shadow="hover" title="hover 阴影">悬停时出现阴影。</LhCard>
  <LhCard shadow="never" title="无阴影">始终无阴影。</LhCard>
</template>

<script>
export default {}
</script>

<template>
  <LhCard shadow="hover" title="hover 阴影">悬停时出现阴影。</LhCard>
  <LhCard shadow="never" title="无阴影">始终无阴影。</LhCard>
</template>

標頭插槽與 extra

自訂標頭

自訂標頭操作

透過 header 插槽可完全接管標題區。

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

<template>
  <LhCard>
    <template #header><span>自定义头部</span></template>
    <template #extra>操作</template>
    …
  </LhCard>
</template>

<script>
export default {}
</script>

<template>
  <LhCard>
    <template #header><span>自定义头部</span></template>
    <template #extra>操作</template>
    …
  </LhCard>
</template>

封面與底部

封面與底部

封面區域

正文內容……

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

<template>
  <!-- 封面與底部 -->
  <LhCard>
    <template #cover>…</template>
    …
    <template #footer>
      <LhButton size="small">收藏</LhButton>
    </template>
  </LhCard>
</template>

<script>
export default {}
</script>

<template>
  <!-- 封面與底部 -->
  <LhCard>
    <template #cover>…</template>
    …
    <template #footer>
      <LhButton size="small">收藏</LhButton>
    </template>
  </LhCard>
</template>

整卡可點選

clickable 時整卡承擔 button 語意：可 Tab 聚焦（:focus-visible 焦點環），Enter / Space 觸發 click。

可點選卡片

點選我

整卡可點選。用鍵盤 Tab 聚焦後按 Enter 試試。

<script setup lang="ts">
function onCardClick() {
  console.log('card clicked')
}
</script>

<template>
  <!-- 可點選卡片 -->
  <LhCard clickable title="点击我" @click="onCardClick">…</LhCard>
</template>

<script>
export default {
  methods: {
    onCardClick() {
      console.log('card clicked')
    },
  },
}
</script>

<template>
  <!-- 可點選卡片 -->
  <LhCard clickable title="点击我" @click="onCardClick">…</LhCard>
</template>

載入態

載入態

載入中

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

<template>
  <LhCard title="加载中" loading />
</template>

<script>
export default {}
</script>

<template>
  <LhCard title="加载中" loading />
</template>

Card API

Props

屬性	說明	類型	預設值
title	卡片標題（也可用 header 插槽）	string	—
shadow	陰影顯示時機	"always" | "hover" | "never"	'always'
clickable	整卡可點選（承擔 button 鍵盤語意）	boolean	false
loading	載入態：內容區以骨架佔位	boolean	false
themeVars	元件級主題變數（鍵自動加 --lh- 前綴）	{ [x: string]: string; }	—
bgPattern	花紋背景 URL（如 var(--lh-pattern-willow)），不受全域白名單限制	string	—
sx	sx 快速版面配置屬性	LhSxProps	—

Events

事件	說明	參數
click	可點選卡片被點選（滑鼠或鍵盤 Enter/Space 觸發）	(e: Event) => void

主題變數

以下 CSS 變數在 .lh-card 上定義預設值，可透過 themeVars 全域或元件級覆寫：

變數	說明	預設值
--lh-card-border-radius	圓角	border-radius-base + 2px
--lh-card-bg	背景色	--lh-bg-color
--lh-card-border-color	邊框色	--lh-border-color-light
--lh-card-header-padding / --lh-card-body-padding / --lh-card-footer-padding	三區內邊距	14px 20px / 18px 20px / 12px 20px
--lh-card-shadow / --lh-card-shadow-hover	常態/懸停陰影	暖墨色柔和雙層陰影
--lh-card-loading-bg / --lh-card-loading-highlight	載入佔位底色/流光高光	--lh-border-color-light / 向紙色提亮的混合色

Slots

插槽	說明
header	自訂標題區
extra	標題區右側附加內容
cover	封面
default	主體內容
footer	底部

無障礙

• 可點選卡：role="button" + tabindex="0" + Enter/Space 啟用（APG button pattern）
• 載入態：容器 aria-busy="true"，佔位圖形對螢幕閱讀器隱藏
• 鍵盤焦點環走 :focus-visible，滑鼠點選不顯示

類型定義

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

LhCardProps

export interface LhCardProps {
  /** 卡片標題（也可用 header 插槽） */
  title?: string
  /** 陰影顯示時機 */
  shadow?: LhCardShadow
  /** 整卡可點選（承擔 button 鍵盤語意） */
  clickable?: boolean
  /** 載入態：內容區以骨架佔位 */
  loading?: boolean
  /** 元件級主題變數（鍵自動加 --lh- 前綴） */
  themeVars?: Record<string, string>
  /** 花紋背景 URL（如 var(--lh-pattern-willow)），不受全域白名單限制 */
  bgPattern?: string
  /** sx 快速版面配置屬性 */
  sx?: LhSxProps
}

LhCardShadow _{（來自 @lh-ui/share/core/card）}

/** 卡片陰影顯示時機 */
export type LhCardShadow = 'always' | 'hover' | 'never'