Loading 載入

載入中回饋。三種形態：服務式遮罩（LhLoading.show(...)，全螢幕或指定容器）、v-loading 指令、基礎旋轉圖形 LhSpinner。

服務式全螢幕遮罩

全螢幕載入

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

const showFullscreen = () => {
  const handle = LhLoading.show({ fullscreen: true, lock: true })
  setTimeout(() => handle.close(), 2000)
}
</script>

<template>
  <LhButton @click="showFullscreen">全屏加载 2 秒</LhButton>
</template>

<script>
import { LhLoading } from '@lh-ui/vue3'

export default {
  methods: {
    showFullscreen() {
      const handle = LhLoading.show({ fullscreen: true, lock: true })
      setTimeout(() => handle.close(), 2000)
    },
  },
}
</script>

<template>
  <LhButton @click="showFullscreen">全屏加载 2 秒</LhButton>
</template>

指定容器遮罩

不傳 target 為全螢幕；傳入選擇器或元素則在容器內鋪開（absolute 鋪滿最近的定位祖先，static 容器自動補 relative 並在關閉時還原）。

局部載入

<script setup lang="ts">
import { ref } from 'vue'
import { LhLoading } from '@lh-ui/vue3'

const boxRef = ref<HTMLElement>()

const showBox = () => {
  const handle = LhLoading.show({ target: boxRef.value, text: '拼命加载中', lock: true })
  setTimeout(() => handle.close(), 2000)
}
</script>

<template>
  <div
    ref="boxRef"
    class="demo-loading-box"
  >
    <LhButton @click="showBox">容器内加载</LhButton>
  </div>
</template>

<script>
import { LhLoading } from '@lh-ui/vue3'

export default {
  methods: {
    showBox() {
      const handle = LhLoading.show({ target: this.$refs.boxRef, text: '拼命加载中', lock: true })
      setTimeout(() => handle.close(), 2000)
    },
  },
}
</script>

<template>
  <div
    ref="boxRef"
    class="demo-loading-box"
  >
    <LhButton @click="showBox">容器内加载</LhButton>
  </div>
</template>

v-loading 指令

app.use(LhLoading)（或全量引入）後註冊 v-loading 指令，布林值控制顯隱。

<template>
  <div v-loading="busy" class="table-zone">…</div>
  <div v-loading:text="'自定义文案'" :style="busy2 ? 'height:200px' : ''">…</div>
</template>

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

const busy = ref(false)
const busy2 = ref(false)
</script>

<template>
  <div v-loading="busy" class="table-zone">…</div>
  <div v-loading:text="'自定义文案'" :style="busy2 ? 'height:200px' : ''">…</div>
</template>

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

LhSpinner 旋轉圖形

基礎旋轉圖形，可獨立使用（loading 語意遮罩內部同樣由它呈現）。

LhSpinner

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

<template>
  <div class="demo-loading-row">
    <LhSpinner size="small" />
    <LhSpinner size="medium" />
    <LhSpinner size="large" color="#8f9779" />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <div class="demo-loading-row">
    <LhSpinner size="small" />
    <LhSpinner size="medium" />
    <LhSpinner size="large" color="#8f9779" />
  </div>
</template>

自訂外觀

text 自訂提示文字、background 設定遮罩背景、z-index 控制層疊順序、spinner 關閉旋轉圖形。

自訂外觀

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

const showStyled = () => {
  const handle = LhLoading.show({
    text: '正在同步数据…',
    background: 'rgba(42, 37, 32, 0.6)',
    zIndex: 4000,
    spinner: false,
  })
  setTimeout(() => handle.close(), 2000)
}
</script>

<template>
  <LhButton @click="showStyled">自定义外观加载 2 秒</LhButton>
</template>

<script>
import { LhLoading } from '@lh-ui/vue3'

export default {
  methods: {
    showStyled() {
      const handle = LhLoading.show({
        text: '正在同步数据…',
        background: 'rgba(42, 37, 32, 0.6)',
        zIndex: 4000,
        spinner: false,
      })
      setTimeout(() => handle.close(), 2000)
    },
  },
}
</script>

<template>
  <LhButton @click="showStyled">自定义外观加载 2 秒</LhButton>
</template>

API

LhLoadingMask Props

屬性名	說明	類型	預設值
fullscreen	是否全螢幕（目標是 body 時為 true）	boolean	—
text	載入提示文案（未傳時取語言包 loading.text）	string	—
background	遮罩背景色（CSS background 值）	string	—
zIndex	層級	number	—
spinner	是否顯示旋轉圖示	boolean	true
sx	sx 快速版面配置屬性	LhSxProps	—

服務：LhLoading.show({ target?, text?, background?, lock?, spinner?, sx? }) 傳回 { close }；app.use(LhLoading) 註冊 v-loading 指令。

無障礙

• 遮罩為 role="status" + aria-busy="true"，提示文案作為 aria-label 播報
• 指定容器時 inert 可用（漸進增強）則容器對鍵盤與輔助技術不可達，防止操作底層資料
• lock 鎖捲動，關閉後還原；遮罩關閉時還原容器原始定位與捲動狀態
• 旋轉動效尊重 prefers-reduced-motion

類型定義

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

LhLoadingMaskProps

/** 遮罩元件 props（服務/指令內部渲染） */
export interface LhLoadingMaskProps {
  /** 是否全螢幕（目標是 body 時為 true） */
  fullscreen?: boolean
  /** 載入提示文案（未傳時取語言包 loading.text） */
  text?: string
  /** 遮罩背景色（CSS background 值） */
  background?: string
  /** 層級 */
  zIndex?: number
  /** 是否顯示旋轉圖示（預設 true） */
  spinner?: boolean
  sx?: LhSxProps
}

LhLoadingOptions _{（來自 @lh-ui/share/core/loading）}

/** 載入遮罩選項（服務與指令共用） */
export interface LhLoadingOptions {
  /** 掛載目標：選擇器字串 / 元素；不傳為全螢幕 */
  target?: string | HTMLElement
  /** 載入提示文案（未傳時取語言包 loading.text） */
  text?: string
  /** 遮罩背景色（CSS background 值） */
  background?: string
  /** 是否鎖定捲動（全螢幕遮罩鎖 body，指定目標鎖目標自身的捲動） */
  lock?: boolean
  /** 是否顯示旋轉圖示 */
  spinner?: boolean
  sx?: LhSxProps
}

LhLoadingHandle _{（來自 @lh-ui/share/core/loading）}

/** 服務句柄 */
export interface LhLoadingHandle {
  close: () => void
}