Loading 加载

在异步数据尚未就绪时覆盖目标区域并显示进度状态。支持组件、v-loading 指令和命令式服务三种用法；短请求可通过 delay 避免加载层闪烁。

区域加载

完整安装 Aurora Plus 后可直接使用 v-loading。指令既接受布尔值，也接受包含 loading 的配置对象。

区域加载与自定义图标

加载层继承页面表面；自定义 SVG 只改变进度图标，不改变目标区域尺寸。

工作区索引已完成

远程分支同步中

扩展状态等待中

vue

<template>
  <div class="loading-basic-demo">
    <div class="au-doc-row">
      <AuButton type="primary" @click="loading = !loading">
        {{ loading ? '结束加载' : '重新加载' }}
      </AuButton>
      <AuButton @click="custom = !custom">
        {{ custom ? '使用默认图标' : '使用自定义 SVG' }}
      </AuButton>
    </div>
    <section
      v-loading="loadingOptions"
      class="loading-basic-demo__region"
      aria-label="同步任务列表"
    >
      <div v-for="task in tasks" :key="task.name" class="loading-basic-demo__row">
        <span>{{ task.name }}</span>
        <span>{{ task.status }}</span>
      </div>
    </section>
  </div>
</template>
<script setup>
import { computed, ref } from 'vue';
import { AuButton } from 'aurora-plus';
const loading = ref(true);
const custom = ref(false);
const customSvg = `
  <path d="M12 3a9 9 0 1 0 9 9" stroke-width="2.2" />
  <path d="M18.4 5.6 21 3v5h-5l2.4-2.4Z" fill="currentColor" stroke="none" />
`;
const loadingOptions = computed(() => ({
  loading: loading.value,
  text: custom.value ? '正在同步更改…' : '加载中…',
  svg: custom.value ? customSvg : '',
  svgViewBox: '0 0 24 24',
  delay: 120,
}));
const tasks = [
  { name: '工作区索引', status: '已完成' },
  { name: '远程分支', status: '同步中' },
  { name: '扩展状态', status: '等待中' },
];
</script>
<style scoped>
.loading-basic-demo {
  display: grid;
  gap: 14px;
}
.loading-basic-demo__region {
  min-height: 168px;
  border: 1px solid var(--au-color-border-subtle);
  border-radius: var(--au-radius-surface);
  overflow: hidden;
}
.loading-basic-demo__row {
  display: flex;
  justify-content: space-between;
  gap: 16px;
  padding: 14px 16px;
  border-bottom: 1px solid var(--au-color-border-muted);
  color: var(--au-color-text-default);
}
.loading-basic-demo__row:last-child {
  border-bottom: 0;
}
</style>

按需注册指令：

import { vLoading } from 'aurora-plus';

app.directive('loading', vLoading);

.body 将区域加载层挂到 document.body 并持续对齐目标元素；.fullscreen 覆盖视口；.lock 在加载层显示期间锁定页面滚动：

<main v-loading.body="loading">...</main>
<AuButton v-loading.fullscreen.lock="saving" @click="save">保存</AuButton>

Loading 服务

服务默认创建全屏加载层；传入 target 后默认只覆盖该元素。返回实例可更新文案、更新视觉配置或主动关闭。

区域与全屏服务

全屏 Loading 是单例；重复打开会返回当前实例。

服务模式可覆盖一个 DOM 节点，也可以直接创建全屏加载层。

vue

<template>
  <div class="loading-service-demo">
    <div class="au-doc-row">
      <AuButton @click="openRegionLoading">区域服务</AuButton>
      <AuButton type="primary" @click="openFullscreenLoading">全屏服务</AuButton>
      <AuButton @click="AuLoading.service.closeAll()">关闭全部</AuButton>
    </div>
    <section ref="regionRef" class="loading-service-demo__region">
      服务模式可覆盖一个 DOM 节点，也可以直接创建全屏加载层。
    </section>
  </div>
</template>
<script setup>
import { onBeforeUnmount, ref } from 'vue';
import { AuButton, AuLoading } from 'aurora-plus';
const regionRef = ref(null);
const timers = new Set();
const instances = new Set();
function scheduleClose(instance, duration) {
  instances.add(instance);
  const timer = globalThis.setTimeout(() => {
    timers.delete(timer);
    instance.close();
    instances.delete(instance);
  }, duration);
  timers.add(timer);
}
function openRegionLoading() {
  if (!regionRef.value) return;
  const instance = AuLoading.service({
    target: regionRef.value,
    fullscreen: false,
    text: '正在读取区域数据…',
    delay: 100,
  });
  scheduleClose(instance, 1600);
}
function openFullscreenLoading() {
  const instance = AuLoading.service({
    lock: true,
    text: '正在同步工作区…',
    background: 'color-mix(in srgb, var(--au-material-background) 82%, transparent)',
  });
  const textTimer = globalThis.setTimeout(() => {
    timers.delete(textTimer);
    instance.setText('即将完成…');
  }, 700);
  timers.add(textTimer);
  scheduleClose(instance, 1700);
}
onBeforeUnmount(() => {
  timers.forEach((timer) => globalThis.clearTimeout(timer));
  instances.forEach((instance) => instance.close());
  timers.clear();
  instances.clear();
});
</script>
<style scoped>
.loading-service-demo {
  display: grid;
  gap: 14px;
}
.loading-service-demo__region {
  min-height: 112px;
  padding: 18px;
  border: 1px solid var(--au-color-border-subtle);
  border-radius: var(--au-radius-surface);
  color: var(--au-color-text-default);
  line-height: 1.6;
}
</style>

import { AuLoading } from 'aurora-plus';

const loading = AuLoading.service({
  lock: true,
  text: '正在保存…',
});

loading.setText('正在刷新列表…');
loading.close();

完整安装后，Options API 中也可以调用 this.$loading(options)；该入口会继承当前应用上下文。

AuLoading 组件

组件用默认插槽包裹内容，通过 loading 控制区域加载；设置 fullscreen 后加载层会传送到 body，默认插槽仍保留原位置。

组件容器与独立 Spinner

切换容器加载层，并对比小型、默认和大型加载图标。

Aurora Editor刚刚更新

Design Tokens5 分钟前

Component Lab昨天

正在载入项目…

小型默认大型

vue

<template>
  <div class="loading-component-demo">
    <div class="au-doc-row">
      <AuButton type="primary" @click="loading = !loading">
        {{ loading ? '隐藏容器加载层' : '显示容器加载层' }}
      </AuButton>
    </div>
    <AuLoading :loading="loading" text="正在载入项目…">
      <section class="loading-component-demo__content" aria-label="最近项目">
        <div v-for="project in projects" :key="project.name" class="loading-component-demo__row">
          <span>{{ project.name }}</span>
          <span>{{ project.updatedAt }}</span>
        </div>
      </section>
    </AuLoading>
    <div class="loading-component-demo__spinners" aria-label="加载图标尺寸">
      <AuLoadingSpinner size="small" text="小型" />
      <AuLoadingSpinner text="默认" />
      <AuLoadingSpinner size="large" text="大型" />
    </div>
  </div>
</template>
<script setup>
import { ref } from 'vue';
import { AuButton, AuLoading, AuLoadingSpinner } from 'aurora-plus';
const loading = ref(true);
const projects = [
  { name: 'Aurora Editor', updatedAt: '刚刚更新' },
  { name: 'Design Tokens', updatedAt: '5 分钟前' },
  { name: 'Component Lab', updatedAt: '昨天' },
];
</script>
<style scoped>
.loading-component-demo {
  display: grid;
  gap: 14px;
}
.loading-component-demo__content {
  min-height: 156px;
  border: 1px solid var(--au-color-border-subtle);
  border-radius: var(--au-radius-surface);
  overflow: hidden;
}
.loading-component-demo__row {
  display: flex;
  justify-content: space-between;
  gap: 16px;
  padding: 13px 16px;
  border-bottom: 1px solid var(--au-color-border-muted);
  color: var(--au-color-text-default);
}
.loading-component-demo__row:last-child {
  border-bottom: 0;
}
.loading-component-demo__row span:last-child {
  color: var(--au-color-text-secondary);
  font-size: var(--au-font-size-small);
}
.loading-component-demo__spinners {
  display: flex;
  align-items: center;
  gap: 22px;
  flex-wrap: wrap;
  padding: 12px 0;
}
</style>

组件内加载状态

按钮、按钮组操作项、输入框、复选框、开关和虚拟表格复用同一个加载图标，并在加载期间阻止重复操作。

控件与数据组件加载态

集中展示所有已接入统一 Loading 的组件。

正在保存选择

任务

负责人

同步设计资源

林晨

更新组件索引

周言

检查无障碍状态

陈夏

正在刷新表格

vue

<template>
  <div class="loading-control-demo">
    <div class="loading-control-demo__row">
      <AuButton loading>提交中</AuButton>
      <AuButton type="primary" loading>保存中</AuButton>
      <AuButtonGroup variant="connected" aria-label="同步操作">
        <AuButtonGroupItem :icon="IconRefresh" loading>同步</AuButtonGroupItem>
        <AuButtonGroupItem :icon="IconSettings">设置</AuButtonGroupItem>
      </AuButtonGroup>
    </div>
    <div class="loading-control-demo__fields">
      <AuInput model-value="正在读取账户信息" loading aria-label="账户信息" />
      <AuCheckbox :model-value="true" loading>正在保存选择</AuCheckbox>
      <AuSwitch :model-value="true" loading active-text="正在应用设置" />
    </div>
    <AuVirtualTable
      :columns="columns"
      :data="rows"
      :height="184"
      loading
      loading-text="正在刷新表格"
      aria-label="加载中的任务表格"
    />
  </div>
</template>
<script setup>
import {
  AuButton,
  AuButtonGroup,
  AuButtonGroupItem,
  AuCheckbox,
  AuInput,
  AuSwitch,
  AuVirtualTable,
  IconRefresh,
  IconSettings,
} from 'aurora-plus';
const columns = [
  { key: 'name', title: '任务', dataKey: 'name', flexGrow: 1, minWidth: 150 },
  { key: 'owner', title: '负责人', dataKey: 'owner', width: 100 },
];
const rows = [
  { id: 1, name: '同步设计资源', owner: '林晨' },
  { id: 2, name: '更新组件索引', owner: '周言' },
  { id: 3, name: '检查无障碍状态', owner: '陈夏' },
];
</script>
<style scoped>
.loading-control-demo,
.loading-control-demo__fields {
  display: grid;
  gap: 14px;
}
.loading-control-demo__row {
  display: flex;
  align-items: center;
  gap: 10px;
  flex-wrap: wrap;
}
.loading-control-demo__fields {
  width: min(100%, 380px);
}
</style>

Options / Attributes

配置	说明	类型	默认值
loading	是否显示加载层；服务调用默认显示	boolean	false（组件）
target	服务需要覆盖的 DOM 节点或选择器	HTMLElement / string	document.body
body	将区域服务挂载到 body 并对齐目标	boolean	false
fullscreen	是否覆盖整个视口；服务未传 target 时默认为 true	boolean	false（组件）
lock	显示期间是否锁定页面滚动	boolean	false
text	加载文案；服务还接受 VNode / VNode[]	string / number / VNode / VNode[]	''
size	图标与文字尺寸，可选 small / default / large	string	default
spinner	自定义 Vue 图标组件；服务中的字符串值按 SVG 标记处理	Component / string	—
svg	自定义 SVG 内部标记	string	''
svgViewBox	自定义 SVG 的 viewBox	string	0 0 24 24
color	加载图标颜色	string	主题主色
background	加载层背景 CSS 值	string	当前材质半透明表面
customClass	加载层自定义类名	string / array / object	''
zIndex	加载层层级	number	1000
ariaLabel	加载状态的无障碍名称	string	加载中
delay	延迟显示时间，单位 ms	number	0
beforeClose	服务关闭前调用；返回 false 可阻止关闭	() => boolean / void	—
closed	服务关闭过渡和 DOM 清理完成后调用	() => void	—

target 与 body 仅用于服务；服务实例创建后不能通过 update() 改变 target、body 或 fullscreen。

指令附加属性

布尔值指令可以通过以下属性配置内容；配置对象中的同名选项优先级更高。

属性	说明
au-loading-text	加载文案
au-loading-svg / au-loading-spinner	自定义 SVG 内部标记
au-loading-svg-view-box	SVG viewBox
au-loading-background	加载层背景
au-loading-custom-class	自定义类名
au-loading-color	加载图标颜色
au-loading-aria-label	无障碍名称

从 Element Plus 迁移时，同名的 element-loading-* 属性仍可使用；新代码建议统一采用 au-loading-*。

安全提示

svg、au-loading-svg、au-loading-spinner 及兼容的 element-loading-spinner / element-loading-svg 会渲染为 SVG 标记。只使用源码内可信内容，不要传入用户提交或未经清理的字符串，以免造成 XSS。

Service API

方法或属性	说明
AuLoading.service(options)	创建加载实例；无 target 时为全屏单例
AuLoading.service.closeAll()	请求关闭全部服务实例；关闭守卫仍会执行
instance.close()	请求关闭当前实例
instance.setText(text)	更新加载文案
instance.update(options)	更新文案、图标、颜色、背景、层级等视觉配置
instance.closed	实例是否已完成清理，只读

Component Slots / Events / Exposes

名称	说明
default	被加载层覆盖的内容
spinner	自定义加载图标，作用域参数为 { size }
opened	加载层进入过渡完成后触发
closed	加载层离开过渡完成后触发
rootRef	组件内容根元素引用

组件和服务均设置 role="status"、aria-live="polite"，目标组件同步 aria-busy。系统启用减少动态、减少透明度、高对比度或强制色彩时会自动采用对应回退。

AuLoadingSpinner

需要在自定义控件中复用同一加载图标时，可按需导入 AuLoadingSpinner。它支持 size、text、color、spinner、svg、svgViewBox 和紧凑图标模式 compact；默认不包含遮罩和滚动锁行为。