FxLoading 加载

加载数据时显示动效。不依赖任何 UI 框架，提供 v-loading 指令与 FxLoadingService 命令式两种用法。

基础用法

v-loading 绑定布尔值控制显隐，可附在任意元素上（元素需具备定位，组件会自动为非定位父级补 relative）。

<template>
  <div v-loading="loading" class="demo-loading-box">
    <p class="title">用户列表</p>
    <ul class="rows">
      <li v-for="row in data" :key="row.id">
        <span class="date">{{ row.date }}</span>
        <span class="name">{{ row.name }}</span>
        <span class="address">{{ row.address }}</span>
      </li>
    </ul>
  </div>
  <FxBtn type="primary" class="mt-4" @click="toggle">
    {{ loading ? "关闭加载" : "开始加载" }}
  </FxBtn>
</template>

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

const loading = ref(true)

const data = [
  { id: 1, date: "2016-05-02", name: "王小虎", address: "上海市普陀区金沙江路 1518 弄" },
  { id: 2, date: "2016-05-04", name: "王小虎", address: "上海市普陀区金沙江路 1517 弄" },
  { id: 3, date: "2016-05-01", name: "王小虎", address: "上海市普陀区金沙江路 1519 弄" },
]

function toggle() {
  loading.value = !loading.value
}
</script>

<style scoped>
.demo-loading-box {
  width: 100%;
  border: 1px solid var(--fx-border-color);
  border-radius: var(--fx-border-radius-md);
  overflow: hidden;
}
.title {
  margin: 0;
  padding: 12px 16px;
  font-size: 14px;
  font-weight: 600;
  color: var(--fx-text-color-primary);
  background-color: var(--fx-color-surface-muted);
}
.rows {
  margin: 0;
  padding: 0;
  list-style: none;
  min-height: 168px;
}
.rows li {
  display: flex;
  gap: 24px;
  padding: 12px 16px;
  font-size: 13px;
  color: var(--fx-text-color-secondary);
  border-top: 1px solid var(--fx-border-color);
}
.date {
  width: 120px;
  flex: none;
}
.name {
  width: 96px;
  flex: none;
}
.mt-4 {
  margin-top: 16px;
}
</style>

自定义

可自定义加载文字 text、背景 background、自定义 SVG spinner（spinner / svg + svgViewBox）。

<template>
  <!-- 自定义文字 + 自定义 SVG spinner + 自定义背景 -->
  <div
    v-loading="loading"
    element-loading-text="加载中..."
    :element-loading-spinner="svg"
    element-loading-svg-view-box="-10, -10, 50, 50"
    element-loading-background="rgba(122, 122, 122, 0.8)"
    class="demo-loading-box"
  >
    <p class="placeholder">自定义 SVG spinner</p>
  </div>

  <!-- 仅自定义 SVG 源码（svg 属性） -->
  <div
    v-loading="loading"
    :element-loading-svg="svg"
    element-loading-svg-view-box="-10, -10, 50, 50"
    class="demo-loading-box custom-svg"
  >
    <p class="placeholder">自定义 SVG 源码</p>
  </div>

  <FxBtn type="primary" class="mt-4" @click="toggle">
    {{ loading ? "关闭加载" : "开始加载" }}
  </FxBtn>
</template>

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

const loading = ref(true)

const svg = `
        <path class="path" d="
          M 30 15
          L 28 17
          M 25.61 25.61
          A 15 15, 0, 0, 1, 15 30
          A 15 15, 0, 1, 1, 27.99 7.5
          L 15 15
        " style="stroke-width: 4px; fill: rgba(0, 0, 0, 0)"/>
      `

function toggle() {
  loading.value = !loading.value
}
</script>

<style scoped>
.demo-loading-box {
  width: 100%;
  height: 120px;
  display: flex;
  align-items: center;
  justify-content: center;
  border: 1px solid var(--fx-border-color);
  border-radius: var(--fx-border-radius-md);
}
.demo-loading-box + .demo-loading-box {
  margin-top: 16px;
}
.placeholder {
  margin: 0;
  color: var(--fx-text-color-secondary);
  font-size: 13px;
}
/* 自定义 SVG 描边颜色 */
.custom-svg :deep(.fx-loading__circular .path) {
  stroke: var(--fx-color-danger);
}
.mt-4 {
  margin-top: 16px;
}
</style>

全屏加载

修饰符 .fullscreen.lock 全屏锁定加载；也可用 FxLoadingService 命令式调用，返回实例 .close() 关闭。

<template>
  <FxBtn
    v-loading.fullscreen.lock="fullscreenLoading"
    type="primary"
    @click="openAsDirective"
  >
    指令方式打开
  </FxBtn>
  <FxBtn type="primary" class="ml-2" @click="openAsService">
    命令式方式打开
  </FxBtn>
</template>

<script setup lang="ts">
import { ref } from "vue"
import { FxLoadingService } from "@fx/components"

const fullscreenLoading = ref(false)

function openAsDirective() {
  fullscreenLoading.value = true
  setTimeout(() => {
    fullscreenLoading.value = false
  }, 2000)
}

function openAsService() {
  const loading = FxLoadingService({
    lock: true,
    text: "加载中",
    background: "rgba(0, 0, 0, 0.7)",
  })
  setTimeout(() => {
    loading?.close()
  }, 2000)
}
</script>

<style scoped>
.ml-2 {
  margin-left: 8px;
}
</style>

命令式（service）

FxLoadingService(options) 可在任意时机调用。全屏加载为单例，重复调用复用同一实例。

<template>
  <FxBtn type="primary" @click="open">
    打开全屏加载（2 秒后自动关闭）
  </FxBtn>
</template>

<script setup lang="ts">
import { FxLoadingService } from "@fx/components"

function open() {
  const instance = FxLoadingService({
    fullscreen: true,
    text: "加载中...",
    lock: true,
    background: "rgba(0, 0, 0, 0.7)",
  })
  setTimeout(() => {
    instance?.close()
  }, 2000)
}
</script>

局部引入

import { FxLoadingDirective, FxLoadingService } from "@fx/components"

// 指令需全局注册
app.directive("loading", FxLoadingDirective)

// 命令式调用
const instance = FxLoadingService({ fullscreen: true, text: "加载中" })
instance.close()

API

v-loading 指令

<div v-loading="loading">内容</div>
<div v-loading.fullscreen.lock="loading">全屏锁定</div>
<div v-loading="{ text: '加载中', background: 'rgba(0,0,0,0.7)' }">
  内容
</div>

修饰符	说明
fullscreen	全屏加载
body	挂载到 document.body
lock	锁定滚动（fullscreen 下生效）

指令既可绑定布尔值，也可绑定对象配置。除对象属性外，还支持以 DOM 属性方式配置（命名形如 element-loading-text、element-loading-svg 等），用于不便走绑定值的场景。

Service / Options Attributes

FxLoadingService(options) 与指令对象配置共用同一份 options。

名称	说明	类型	默认值
target	覆盖目标（DOM 节点或选择器）	HTMLElement | string	document.body
fullscreen	是否全屏	boolean	true（target=body）
lock	是否锁定滚动（fullscreen 下生效）	boolean	false
text	spinner 下方显示的加载文字	string | VNode | VNode[]	''
spinner	自定义 spinner（SVG markup，注入 svg 内，优先级高于 svg）	string	''
svg	自定义 SVG 源码（inner SVG markup），优先级低于 spinner	string	''
svgViewBox	自定义 SVG 的 viewBox	string	'0 0 50 50'
background	遮罩背景色	string	''（token 默认遮罩）
customClass	自定义类名（附加到遮罩根节点）	string	''
body	是否挂载到 document.body	boolean	false
beforeClose	关闭前回调，返回 false 取消关闭	() => boolean	—
closed	完全关闭（动画结束）后的回调	() => void	—

Service Instance Exposes

FxLoadingService() 返回的实例方法与属性：

名称	说明	类型
close	关闭并淡出卸载	() => void
setText	动态更新文字	(text: string) => void
visible	当前可见状态（ref）	Ref<boolean>

Slots

名称	说明	作用域参数
text	覆盖默认文字渲染（需设 text）	—

实现说明

• 渲染方式：FxLoading 不依赖具体 UI 框架。FxLoadingService 通过 createVNode + render 渲染 loading.vue 并挂载到目标父节点；指令 v-loading 是对 service 的封装，支持布尔值 / 对象配置 / DOM 属性三种取值来源。
• 渲染结构：spinner 与 svg 均为 SVG markup，二者注入同一个 <svg class="circular">（spinner 优先于 svg），带 class="path" 的子元素（<circle>/<path>）自动获得描边色（--color-on-mask）与 fx-loading-dash 流动动画 —— 这是 spinner/svg 必须落在 svg 上下文内的原因，裸 <path> 放在 HTML 中不会渲染。二者均未提供时，默认渲染 @fx-core/icon 的 ep:loading 图标并施加 2s 线性旋转。spinner 用 position: absolute + top: 50% + 负 margin（spinner 尺寸之半）让 svg 几何中心落在蒙罩 50% 线，文字在下方自然排列、不参与垂直居中（避免「svg + 文字组合居中」把图标挤偏上）；svg 需 vertical-align: top 贴 spinner 内容顶（默认 baseline 会被父级 line-height 推下沉、整体偏上）；<svg> 根元素旋转需显式 transform-box: fill-box + transform-origin: center，否则默认按 viewBox 坐标系解析，遇到带偏移的 viewBox 旋转中心会错位。
• 样式取值：spinner 52px / 全屏 64px / 文字 14px / 旋转 2s；视觉规格全部走 @fx/styles token —— 遮罩背景用 --color-mask（与 fxDialog/fxDrawer 共用的遮罩语义色，明暗自适应），深色蒙罩上 spinner / 文字色统一用 --color-on-mask（遮罩内容语义色，默认派生自 --color-white，可在主题层覆盖）保证对比度，过渡时长用 --duration-normal，不引用任何第三方 UI 库 CSS 变量。
• 全屏单例：全屏加载复用同一实例，避免重复叠加；同一父节点的多个局部 loading 通过 loading-number 属性计数，仅当最后一个关闭时才移除 fx-loading-parent--relative，防止误伤并发 loading。
• 关闭流程：close() 先校验 beforeClose，置 visible=false 触发淡出，待淡出动画结束（400ms 兜底）后 handleAfterLeave 真正卸载 DOM、移除父级类、回退 loading-number 并触发 closed。
• 响应式更新：指令在 updated 时比对配置，配置变化会重建实例，使 text / background / spinner 等即时生效。
• fx 增强：默认 spinner 使用 @fx-core/icon 的 ep:loading 图标；FxIcon 默认 size=16px 会在内联 style 写死宽高、覆盖外部 CSS，故通过 size prop 显式传入 CSS 变量来跟随 spinner 尺寸，避免图标被固定在 16px。