xiaoye-components

Appearance

Loading 加载 ​

Loading 在当前库里不是公开的 <xy-loading /> 标签，而是一组插件式能力：v-loading 指令、XyLoadingService() / XyLoading.service()，以及全量安装后的 this.$loading()。指令配套属性统一使用 xy-loading-* 前缀。

容器内加载 ​

最常见的场景是卡片、表格、分区面板内的局部加载。默认遮罩会直接挂到使用 directive 的元素上。

基础用法容器遮罩

加载状态用于容器级别的加载提示，适合表格、卡片和分区面板。

容器加载中
运营日报

这个示例展示最常见的容器内遮罩用法，适合表格、卡片和分区面板。

自定义文案、背景和 SVG ​

xy-loading-text、xy-loading-background、xy-loading-svg 和 xy-loading-custom-class 可以组合出更贴近业务语境的加载态。

审批配置

这里演示文案、自定义 SVG 和遮罩背景色的组合方式。

Fullscreen 与锁滚动 ​

v-loading.fullscreen.lock 适合全页初始化、批量导入和短暂的阻断式流程。

全屏加载Fullscreen

全屏加载配合锁定滚动，适合全页切换和必须阻断操作的流程。

Service 调用 ​

XyLoadingService() 默认会创建 fullscreen loading，并返回一个可更新文案、可关闭的实例。

默认会以 fullscreen 形态挂到 body

延迟显示与最短展示时长 ​

delay 可以避免请求太快时的遮罩闪烁，minDuration 会从“真正显示出来”的时刻开始计时，保证可见时长稳定。

等待触发
版本差异面板

`delay` 可以避免请求太快时的闪烁，`minDuration` 可以保证真的展示出来后不会一闪而过。

groupKey 复用与 closeAll ​

同一个 groupKey 会复用现有 service 实例，并只合并可更新字段；closeAll() 可以一次性关闭当前所有 service loading。

未触发

service.with() 包装异步任务 ​

XyLoadingService.with() 适合直接包裹 Promise 或异步函数，任务完成或抛错后都会自动关闭 loading。

空闲

ConfigProvider 默认项 ​

ConfigProvider.loading 可以统一独立 Loading 的默认文案、背景、spinner 和时序参数；Dialog / Table / Select 只会复用其中的视觉默认项。

同时会影响 Dialog / Table / Select 的默认 loading 视觉
全局默认项

通过 `ConfigProvider.loading` 可以统一 loading 文案、背景色和时序默认值，减少页面层重复传参。

target 与 body 跟随目标区域 ​

target 可以让 service 覆盖指定元素；body: true 会把遮罩挂到 document.body，并在滚动、缩放和目标尺寸变化时持续跟随目标区域。

图表面板

一个适合演示 target 与 body 差异的局部区域。

使用建议 ​

  • 页面中只需要局部遮罩时，优先使用 v-loading，模板最直观。
  • 需要在组合函数、异步请求链路或 store 里随处触发时，优先使用 XyLoadingService()。
  • 需要把 loading 生命周期和异步任务严格绑定时，优先使用 XyLoadingService.with()，避免漏关。
  • 默认 fullscreen service 是单例；局部 target service 不做全局去重。
  • groupKey 只做 service 级复用，同 key 下不会改写既有实例的 target / body / fullscreen / lock 作用域。
  • 如果只是静态占位而不是交互阻断，优先考虑 xy-skeleton。

无障碍说明 ​

  • 独立 Loading 遮罩的状态节点会带 role="status" 与 aria-live="polite"。
  • directive 作用元素和 service 的目标元素在 loading 期间会自动加上 aria-busy="true"，关闭后移除。
  • Dialog / Table / Select 的内建 loading 也会同步标记 aria-busy，但各自仍保留原本的 DOM 语义。

安全提示 ​

XSS 风险

xy-loading-svg 和 svg 选项会把传入字符串作为 SVG 片段渲染。不要把用户提交的原始内容直接塞进这些字段，否则可能引入 XSS 风险。

命名对照 ​

  • v-loading 的附加属性统一使用 xy-loading-* 前缀，例如 xy-loading-text、xy-loading-background、xy-loading-custom-class。
  • XyLoadingService() / $loading() 的 options 和 LoadingInstance.update() 使用 customClass、svgViewBox、groupKey 这类 camelCase 字段。
  • LoadingInstance 暴露的状态字段同样是 camelCase，例如 customClass、svgViewBox、zIndex。
  • 如果你是在模板上写局部加载，不要把 customClass 直接写成模板属性；如果你是在 service 里调 loading，也不要反过来传 xy-loading-custom-class。

用法 ​

指令 ​

vue
<template>
  <div
    v-loading="loading"
    xy-loading-text="正在同步数据..."
    xy-loading-background="rgba(255, 255, 255, 0.82)"
  />
</template>

Service ​

ts
import { XyLoadingService } from "xiaoye-components";

const loading = XyLoadingService({
  text: "正在发布版本...",
  lock: true
});

loading.setText("正在刷新缓存...");
loading.close();

全量安装后的 $loading ​

ts
app.use(XiaoyeComponents);

app.config.globalProperties.$loading({
  text: "正在初始化工作台..."
});

API ​

Loading Options ​

字段说明类型默认值
target要覆盖的目标元素，支持 CSS 选择器或 HTMLElementstring | HTMLElementdocument.body
body是否把遮罩挂到 document.bodybooleanfalse
fullscreen是否使用 fullscreen 形态booleantrue
lockfullscreen 时是否锁定 body 滚动booleanfalse
text加载文案LoadingText''
spinner自定义 spinner classstring''
background自定义遮罩背景色string''
customClass遮罩自定义 classstring''
svg自定义 SVG 片段string''
svgViewBox自定义 SVG 的 viewBoxstring'0 0 50 50'
visible当前可见状态；创建时默认显示，也可通过 instance.update({ visible }) 在运行时切换booleantrue
delay延迟显示时长，单位毫秒number0
minDuration实际显示后的最短可见时长，单位毫秒number0
groupKeyservice 复用键；相同 key 会复用已有实例stringundefined
beforeClose关闭前拦截；返回 false 会阻止关闭LoadingOptions["beforeClose"]undefined
closed完全关闭并卸载后触发LoadingOptions["closed"]undefined

Directive ​

项说明
v-loading绑定 boolean 或 LoadingOptions，控制加载遮罩显示
.body把遮罩挂到 document.body
.fullscreen使用 fullscreen 加载
.lockfullscreen 时锁定 body 滚动

Directive Attributes ​

属性说明类型
xy-loading-text加载文案string
xy-loading-spinner自定义 spinner classstring
xy-loading-svg自定义 SVG 片段string
xy-loading-svg-view-box自定义 SVG 的 viewBoxstring
xy-loading-background遮罩背景色string
xy-loading-custom-class遮罩自定义 classstring

Loading Instance ​

方法说明签名
close关闭并卸载 loadingLoadingInstance["close"]
setText更新加载文案LoadingInstance["setText"]
update更新运行中的 loading 配置LoadingInstance["update"]

Loading Instance State ​

字段说明类型
visible当前 loading 是否可见LoadingInstance["visible"]
text当前加载文案LoadingInstance["text"]
background当前遮罩背景色LoadingInstance["background"]
spinner当前 spinner classLoadingInstance["spinner"]
svg当前 SVG 片段LoadingInstance["svg"]
svgViewBox当前 SVG viewBoxLoadingInstance["svgViewBox"]
fullscreen当前是否为 fullscreen 形态LoadingInstance["fullscreen"]
lock当前是否锁滚动LoadingInstance["lock"]
customClass当前自定义 classLoadingInstance["customClass"]
zIndex当前遮罩层级LoadingInstance["zIndex"]
$el当前遮罩根元素LoadingInstance["$el"]

Loading Service ​

方法说明签名
XyLoadingService(...)创建一个 loading 实例LoadingService
XyLoadingService.closeAll()关闭当前所有 service loadingLoadingService["closeAll"]
XyLoadingService.with(...)包裹异步任务并在结束后自动关闭LoadingService["with"]

Loading Global Config ​

ConfigProvider.loading 的类型为 LoadingGlobalConfig：

ts
type LoadingGlobalConfig = ConfigProviderProps["loading"];
  • 独立 v-loading 与 XyLoadingService() 会完整读取这组默认值。
  • Dialog / Table / Select 只消费视觉类默认项：text / spinner / svg / svgViewBox / background。
  • 局部 options 优先级始终高于 ConfigProvider.loading。

全量安装导出 ​

ts
import {
  XyLoading,
  XyLoadingDirective,
  XyLoadingService,
  vLoading,
  type LoadingBinding,
  type LoadingGlobalConfig,
  type LoadingInstance,
  type LoadingOptions
} from "xiaoye-components";