xtf-linkui

Appearance

xtf-loading ​

组件说明 ​

xtf-loading 是加载状态组件，适用于局部等待、全屏提交和跨层级全局加载。它提供 7 种内置动画，并同时支持声明式 show、service 宿主和 loadingManager 命令式控制。

基础用法 ​

1. 内联加载 ​

默认以 inline 模式显示，可用于列表或按钮附近：

vue
<template><xtf-loading type="spinner" text="正在加载" :vertical="false" /></template>
<script>
export default {}
</script>

2. 动画与尺寸 ​

通过 type、theme 和 size 选择符合业务状态的动画：

vue
<template>
  <view><xtf-loading type="ring" theme="success" size="lg" text="数据同步中" /></view>
</template>
<script>
export default {}
</script>

3. 全屏遮罩 ​

用 show 控制声明式全屏加载，并在操作完成后关闭：

vue
<template>
  <view>
    <xtf-button label="提交订单" @click="submit" />
    <xtf-loading :show="submitting" mode="fullscreen" overlay text="正在提交订单" />
  </view>
</template>
<script>
export default {
  data() {
    return { submitting: false }
  },
  methods: {
    submit() {
      this.submitting = true
      setTimeout(() => {
        this.submitting = false
        uni.showToast({ title: '提交成功', icon: 'success' })
      }, 800)
    }
  }
}
</script>

4. 服务模式 ​

页面保留一个 service 宿主后，可从任意业务模块调用 loadingManager：

vue
<template>
  <view>
    <xtf-button label="同步数据" @click="sync" />
    <xtf-loading service />
  </view>
</template>
<script>
import { loadingManager } from '@/uni_modules/xtf-linkui'

export default {
  methods: {
    sync() {
      loadingManager.show({
        text: '正在同步数据',
        type: 'orbit',
        mode: 'fullscreen',
        overlay: true,
        delay: 200
      })
      setTimeout(() => {
        loadingManager.hide()
        console.log('同步完成')
      }, 1000)
    }
  },
  beforeDestroy() {
    loadingManager.hide()
  },
  unmounted() {
    loadingManager.hide()
  }
}
</script>

全部属性 ​

| 属性 | 类型 | 默认值 | 作用描述 | 适用范围 | | --- | --- | --- | --- | | service | Boolean | false | 是否订阅 loadingManager 状态；开启后由管理器配置覆盖其余 props | 全局命令式加载 | | show | Boolean | true | 是否显示声明式加载组件 | 声明式控制 | | text | String | '' | 加载提示文字 | 提示当前任务 | | type | String | 'spinner' | 动画类型：spinner / ring / dots / orbit / pulse / bars / neon；非法值回退为 spinner | 匹配加载场景 | | size | String \| Number | '' | sm / md / lg 或自定义尺寸；数字和纯数字字符串按 rpx 处理 | 调整动画大小 | | theme | String | 'primary' | primary / success / warning / danger / info / secondary / inverse | 匹配业务状态 | | mode | String | 'inline' | 显示模式：inline 或 fullscreen | 局部或全屏等待 | | overlay | Boolean | false | 是否显示遮罩和面板背景 | 阻止当前区域操作 | | vertical | Boolean | true | 是否让动画与文字垂直排列 | 有文字的加载态 | | delay | String \| Number | 0 | 延迟显示毫秒数，负值按 0 处理 | 避免短请求闪烁 | | customClass | String | '' | 根节点自定义类名 | 样式覆盖 | | customStyle | String \| Object | '' | 根节点自定义样式 | 动态样式覆盖 |

方法 ​

1. open(options) — 通过服务宿主显示加载 ​

仅在 service 为 true 时生效，内部调用 loadingManager.show(options)。

参数类型默认值说明
optionsObject{}与 loadingManager.show 相同的配置

返回值：void。

使用示例：

vue
<template><xtf-loading ref="loading" service /></template>
<script>
export default {
  mounted() {
    this.$refs.loading.open({ text: '处理中', mode: 'fullscreen', overlay: true })
  }
}
</script>

2. close() — 通过服务宿主隐藏加载 ​

仅在 service 为 true 时生效，内部调用 loadingManager.hide()。

参数类型默认值说明
---无参数

返回值：void。

使用示例： this.$refs.loading.close()。

3. loadingManager.show(options) — 显示全局加载 ​

需先在页面根部挂载 <xtf-loading service />。

参数类型默认值说明
optionsObject{}覆盖 text、type、size、theme、mode、overlay、vertical、delay、customClass、customStyle

返回值：Object — 更新后的加载状态快照。

使用示例： loadingManager.show({ text: '保存中', mode: 'fullscreen', overlay: true })。

4. loadingManager.hide() — 隐藏并重置全局加载 ​

返回值：Object — 重置后的加载状态快照。

使用示例： loadingManager.hide()。

5. loadingManager.update(options) — 更新当前全局加载配置 ​

参数类型默认值说明
optionsObject{}合并到当前状态的配置

返回值：Object — 更新后的加载状态快照。

使用示例： loadingManager.update({ text: '正在解析第 2 步' })。

6. loadingManager.getState() — 获取当前全局加载状态 ​

返回值：Object — 当前状态副本。

使用示例： console.log(loadingManager.getState())。

7. loadingManager.subscribe(listener) — 订阅全局加载状态 ​

参数类型默认值说明
listener(state: Object) => void-状态改变时调用；非函数时返回空取消函数

返回值：() => void — 取消订阅函数。

使用示例：

js
import { loadingManager } from '@/uni_modules/xtf-linkui'

const unsubscribe = loadingManager.subscribe((state) => console.log('加载状态：', state.show))
unsubscribe()

事件 ​

事件名称触发时机回调参数说明
无--当前组件未声明或触发自定义事件。声明式模式请通过 show 属性控制显示；服务模式请使用 loadingManager 的方法或 subscribe(listener) 订阅状态。

主题说明 ​

  • 加载主色由 --xtf-loading-color 控制，默认映射至对应的 --xtf-color-* 主题变量。
  • 动画尺寸由 --xtf-loading-size 控制，预设 sm、md、lg 分别为 36rpx、48rpx、64rpx。
  • 全屏层级使用 --xtf-loading-z-index，遮罩、面板和玻璃效果分别使用 --xtf-loading-overlay、--xtf-loading-panel-bg、--xtf-loading-panel-border、--xtf-loading-glass-blur。
  • ring、orbit、pulse、bars、neon 还使用 --xtf-loading-ring-border、--xtf-loading-glow、--xtf-loading-pulse-wave、--xtf-loading-bars-cap、--xtf-loading-neon-bg 等变量。

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。

MIT Licensed

Copyright © 2026 xtf-linkui