X-Next

Appearance

Spin 加载中 ​

用于局部区域或页面等待状态。

何时使用 ​

  • 页面、卡片、表格等区域正在等待异步数据。
  • 操作提交后需要短暂阻止用户继续操作当前区域。
  • 需要用提示文本降低等待过程中的不确定感。

基础用法 ​

加载中
vue
<template>
  <x-spin />
  <x-spin tip="加载中" />
</template>

尺寸 ​

处理中
vue
<template>
  <x-spin :size="16" />
  <x-spin :size="24" />
  <x-spin :size="36" tip="处理中" />
</template>

容器模式 ​

加载中
vue
<template>
  <x-button size="small" @click="loading = !loading">
    {{ loading ? '结束加载' : '开始加载' }}
  </x-button>
  <x-spin :loading="loading" display="block" tip="加载中">
    <div class="panel">
      <strong>内容区域</strong>
      <p>加载时遮罩会覆盖内容，并暂时阻止内部控件聚焦。</p>
      <x-button size="small">区域操作</x-button>
    </div>
  </x-spin>
</template>

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

const loading = ref(true);
</script>

点状动画 ​

同步中
vue
<template>
  <x-spin dot />
  <x-spin dot="color" />
  <x-spin dot="color" :size="10" tip="同步中" />
</template>

隐藏图标 ​

正在连接服务
正在保存
vue
<template>
  <x-spin hide-icon tip="正在连接服务" />
  <x-spin :loading="true" display="block" hide-icon tip="正在保存">
    <div class="panel">表单内容</div>
  </x-spin>
</template>

自定义内容 ​

⌁
自定义图标
自定义元素
请稍候，正在处理
vue
<template>
  <x-spin tip="自定义图标">
    <template #icon>
      <span class="custom-icon">⌁</span>
    </template>
  </x-spin>
  <x-spin tip="自定义元素">
    <template #element>
      <span class="custom-loading" aria-hidden="true"></span>
    </template>
  </x-spin>
  <x-spin>
    <template #tip>
      <span>请稍候，正在处理</span>
    </template>
  </x-spin>
</template>

文案扫光 ​

tipShimmer 让提示文字出现一条横向扫过的光带，比静止文案更醒目。仅对 tip prop 生效（自定义 tip 插槽内容结构未知，不参与扫光）。

加载中
正在同步数据
vue
<template>
  <x-spin tip="加载中" tip-shimmer />
  <x-spin tip="正在同步数据" tip-shimmer :size="32" />
</template>

光带颜色与周期由两个 token 控制，可在主题层或局部覆盖：

css
:root {
  /* 光带色：默认是文案色向白混合，可换成任意颜色 */
  --x-spin-tip-shimmer-color-highlight: var(--x-color-primary-3);
  /* 扫光周期 */
  --x-spin-tip-shimmer-duration: 2s;
}

延迟显示 ​

快速请求往往几十毫秒内就结束。直接切 loading 会让遮罩闪一下又消失，观感比不加加载态更差。delay 让加载态延后出现，这段时间内结束的请求不会有任何闪烁。

快请求遮罩出现 0 次
慢请求遮罩出现 0 次
快速请求

请求早于 delay 结束，遮罩从不出现。

慢速请求

请求超过 delay，遮罩在 300ms 时出现。

vue
<template>
  <x-button @click="runFast">快请求（120ms 结束）</x-button>
  <x-button @click="runSlow">慢请求（1.2s 结束）</x-button>
  <x-spin :loading="loading" :delay="300" display="block" tip="加载中">
    <div class="panel">内容区域</div>
  </x-spin>
</template>

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

const loading = ref(false);

// 120ms 结束：早于 delay，遮罩不出现，不会闪
const runFast = () => {
  loading.value = true;
  window.setTimeout(() => {
    loading.value = false;
  }, 120);
};

// 1.2s 结束：遮罩在 300ms 时出现
const runSlow = () => {
  loading.value = true;
  window.setTimeout(() => {
    loading.value = false;
  }, 1200);
};
</script>

delay 只延迟出现：加载结束时立即收起遮罩，不会让已加载好的内容再被多盖一段时间。因此快请求不闪、慢请求也不拖。

交互说明 ​

  • 容器模式下，loading 为 true 时会显示遮罩，并给内容区域加上不可聚焦状态。不支持 inert 的旧浏览器会退化为给内部可聚焦元素临时加 tabindex="-1"，加载结束后还原。
  • delay 只对容器模式生效；独立形态本身就是加载指示器，loading 与 delay 都不参与。
  • Spin 根节点默认带有加载语义；没有提示文本时会使用默认可访问名称。
  • icon 插槽会向第一个组件注入 spin 属性；若传入普通元素，可自行添加动画样式，或使用 element 插槽完全自定义。
  • 开启系统「减弱动态效果」后，图标旋转、点状动画与文案扫光都会停止；扫光会还原成纯色，避免光带停在文字上留下一块亮斑。
  • 提示文字的行高由组件显式声明（--x-line-height-base），不继承宿主行高，因此在任意项目里高度一致。

按需导入 ​

ts
import { Spin } from 'x-next';

样式按需引入（base.css 为共享基础层，多个组件只需引入一次）：

ts
import 'x-next/style/base.css';
import 'x-next/style/spin.css';

Props ​

参数说明类型默认值
display容器显示方式'block' | 'inline''inline'
size图标或点状动画单点尺寸number-
loading是否为加载中状态，仅容器模式下覆盖内容booleanfalse
delay延迟显示加载态的毫秒数，避免快速请求闪烁；仅容器模式生效，结束时立即收起number0
dot是否使用点状动画boolean | 'default' | 'color'false
tip提示内容string-
hideIcon是否隐藏图标booleanfalse
tipShimmer提示文字是否开启扫光效果，需要同时设置 tipbooleanfalse

Slots ​

插槽名说明
default容器模式下的内容
icon自定义图标，会向第一个组件注入 spin 属性
element自定义加载元素
tip自定义提示内容