Loading 加载

提供包裹式的 Loading 组件和便捷的 v-loading 自定义指令，在耗时任务进行时锁定用户交互，显示加粗硬边框的加载标识和黄色底色文本。

预览

Preview

声明式容器加载 Loading

订单支付明细

应付金额：¥ 199.00

支付状态：待付

指令式加载 v-loading

安装

pnpm dlx brutx-vue@latest add loading

用法

声明式容器用法

包裹在需要展示加载遮罩的块级元素外部。通过 loading 属性控制加载状态的切换，并通过 text 属性自定义加载文案。

<script setup>
import { ref } from 'vue'
import { Loading } from 'brutx-ui-vue'

const loading = ref(true)
</script>

<template>
    <Loading :loading="loading" text="正在读取核心数据...">
        <div class="card">
            <h4>账户明细</h4>
            <p>可提现余额：¥ 1500.00</p>
        </div>
    </Loading>
</template>

自定义指令用法

在普通的 HTML 元素或第三方组件上挂载 v-loading 指令。可以使用 v-loading-text 提供定制的加载文案。

<script setup>
import { ref } from 'vue'

const isDataLoading = ref(true)
</script>

<template>
    <!-- 指令内部会自动计算宿主定位，并在加载结束后完美还原 -->
    <div v-loading="isDataLoading" v-loading-text="'云端解析中...'">
        <p>今日订单量：1,250单</p>
        <p>成功发货率：98.5%</p>
    </div>
</template>

API 参考

Loading — 属性

名称	类型	默认值	说明
loading	boolean | undefined	false	控制加载状态；仅在为 true 时显示局部遮罩或页面级加载内容。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/loading/Loading.vue 解析值 false 来源 Loading.vue:9 packages/ui/src/components/loading/Loading.vue
text	string | undefined	undefined	设置局部加载遮罩中的自定义短文案；为空时不渲染该文案区域。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/loading/Loading.vue 解析值 undefined 来源 Loading.vue:10 packages/ui/src/components/loading/Loading.vue
background	string | undefined	undefined	设置局部加载遮罩的背景色；未提供时使用组件默认的半透明主题背景。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/loading/Loading.vue 解析值 undefined 来源 Loading.vue:11 packages/ui/src/components/loading/Loading.vue
customClass	string | undefined	undefined	追加到局部加载遮罩层的 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/loading/Loading.vue 解析值 undefined 来源 Loading.vue:12 packages/ui/src/components/loading/Loading.vue
page	boolean | undefined	false	切换到页面级加载布局；加载时渲染至少占满视口高度的页面内容。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/loading/Loading.vue 解析值 false 来源 Loading.vue:13 packages/ui/src/components/loading/Loading.vue
fullscreen	boolean | undefined	false	显示固定定位的全屏加载视图，即使组件位于普通容器内也覆盖整个视口。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/loading/Loading.vue 解析值 false 来源 Loading.vue:14 packages/ui/src/components/loading/Loading.vue
title	string | undefined	undefined	设置页面级加载卡片的标题。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/loading/Loading.vue 解析值 undefined 来源 Loading.vue:15 packages/ui/src/components/loading/Loading.vue
description	string | undefined	undefined	设置页面级加载卡片的说明文本。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/loading/Loading.vue 解析值 undefined 来源 Loading.vue:16 packages/ui/src/components/loading/Loading.vue
progress	number | undefined	undefined	提供 0 到 100 的加载进度；仅在有值时显示进度条，超出范围会钳制到边界。
详情 声明类型 number | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/loading/Loading.vue 解析值 undefined 来源 Loading.vue:17 packages/ui/src/components/loading/Loading.vue
class	string | undefined	undefined	追加到页面级根容器或局部加载容器的 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/loading/Loading.vue 解析值 undefined 来源 Loading.vue:18 packages/ui/src/components/loading/Loading.vue

Loading — 插槽

名称	签名或类型	说明
#header	{}	页面级加载布局中标题卡片之前的自定义头部内容。
详情 声明类型 {} 来源 Loading.vue packages/ui/src/components/loading/Loading.vue
#default	{}	页面级加载卡片的主体内容。
详情 声明类型 {} 来源 Loading.vue packages/ui/src/components/loading/Loading.vue
#footer	{}	页面级加载卡片底部的自定义内容，进度条之后渲染。
详情 声明类型 {} 来源 Loading.vue packages/ui/src/components/loading/Loading.vue

可访问性

• 交互锁定：加载遮罩展示时会附带 pointer-events-none 限制容器子元素交互，避免二次提交
• 宿主保护：指令内部会自动劫持宿主定位为 relative（并在卸载时精准还原），防范加载遮罩产生视觉溢出