n-loading 加载

加载指示器，五种形态（mode）：圆环（默认带轨道）/ 半圆弧 / 花瓣 / 三点脉冲 / 三竖条。两种形态：默认行内局部占位；fixed 开全屏加载层（全屏居中 + 可选遮罩阻断，配函数式 useUi().showLoading() 使用）。旋转与脉冲动画为 JS 帧循环逐帧写行内样式（30ms/帧，全端一致），无 CSS 动画；说明文字走 text，自定义图标走默认插槽（icon-only，n-icon 组件或 image 均可，与文字共存）；loading 为 false 时整体不渲染并停帧，卸载时自动停表，不会空转。

1. 默认圆环不带文字、带主题色轨道——需要"加载中..."提示时传 text；不要轨道传 inactive-color="transparent"，换轨道色传任意 CSS 色值
2. 页面隐藏（跳转下一页、tab 切换、应用切后台）时动画自动暂停，页面回显且仍在加载态时自动恢复；loading=false 与卸载时同样保证停表，不会空转
3. 行内占位用默认形态；请求期间阻断整页交互用 fixed 全屏加载层（函数式开关）；整页品牌化加载（铺满遮罩 + 品牌图）用 n-loading-page

平台兼容性

App	H5	微信小程序	支付宝小程序	百度小程序	头条小程序	QQ小程序
√	√	√	×	×	×	×

如何调用

两种用法打到同一个组件：

函数式（全屏加载层，推荐）：页面挂一个 loading=false 的 fixed 实例（常驻不渲染），任意位置 useUi().showLoading(options) 打开、useUi().hideLoading() 关闭——useUi 从库主入口按页面相对层级导入，按当前页面路由自动命中本页实例，页面栈多页共存互不串扰；与 toast 的 showToast/hideToast 同一入口：

<template>
	<!-- 页面放一个全屏加载层实例 -->
	<n-loading :loading="false" fixed />
</template>

import { useUi } from "../../uni_modules/new-ui";

// 打开：options 逐次覆盖 props 全局默认（text / mode / size / color / duration / vertical 等）
function start() {
	useUi().showLoading({ text: "加载中..." });
}

// 数据到位后关闭；展示中再次 showLoading 即替换内容
function done() {
	useUi().hideLoading();
}

NLoadingOptions 类型从主入口引入。fixed 层默认无遮罩不阻断页面（对齐 uni.showLoading 的 mask 默认关闭语义），要挡操作时逐次传 mask: true（每次调用可各自指定，同一实例可这次带遮罩下次不带）；深色遮罩下说明文字缺省用白色，指示器走主题品牌色。当前页面未挂载 fixed 实例时 showLoading 不做任何事并控制台提示。

ref 直调：页面内多实例分别控制时用；NLoadingComponentPublicInstance 是 uni-app x 编译器为 easycom 组件自动生成的全局类型，无需 import：

<template>
	<n-loading ref="loading" :loading="false" fixed />
</template>

import { ref } from "vue";

const loading = ref<NLoadingComponentPublicInstance | null>(null);

loading.value?.open({ text: "正在同步", mode: "dots" });
loading.value?.close();

声明式（行内指示器）：常规局部占位直接绑 loading 属性：

<n-loading :loading="busy" text="加载中..." />

API

属性

参数	说明	类型	默认值	可选值
mode	指示器形态；非法值按 circle 处理	String	"circle"	circle / semicircle / flower / dots / bars
loading	是否加载中：false 时整体不渲染、动画停止	Boolean	true	-
size	指示器名义尺寸（px）：圆环/半圆弧/花瓣为直径，三点为圆点组总宽基准，三竖条为条组高度	Number	24	-
color	指示器前景色，任意 CSS 色值；空 = 主题品牌色（跟随主题自动适配）	String	""	与 css 相同
inactive-color	圆环轨道色（仅 circle 形态）：空 = 跟随主题弱填充（深浅自动适配）；'transparent' = 关闭轨道	String	""	与 css 相同
duration	一轮动画时长（毫秒）：0 = 各形态调优默认（圆环类 900 / 花瓣 1000 / 三点 1400 / 三竖条 1000）；传正整数统一覆盖	Number	0	-
text	说明文字；空串不渲染文字节点	String	""	-
text-size	说明文字字号（px）	Number	14	-
text-color	说明文字颜色；空 = 主题墨色。深色底调白文字用这里；text-style 最后应用，其中写 color 会覆盖本属性，调色优先用本属性	String	""	与 css 相同
icon-only	插槽图标模式：用默认插槽内容（n-icon / image）替代内置形态指示器，文字仍可同时显示；iconRotate 开启后由组件旋转；动图可保持关闭	Boolean	false	-
iconRotate	旋转默认插槽，仅 iconOnly 开启时生效；duration 控制周期，默认 900ms；关闭时不运行帧循环	Boolean	false	-
vertical	指示器与文字竖排（默认横排），插槽图标路径同样生效	Boolean	false	-
fixed	全屏加载层模式：fixed 全屏居中承载指示器（配 useUi().showLoading 使用），false 为行内指示器	Boolean	false	-
mask	仅 fixed 模式生效：全屏遮罩并阻断下层点击；false 为透明穿透层（下层照常交互，对齐 uni.showLoading 默认关闭语义）；函数式可在 options.mask 逐次指定	Boolean	false	-
mask-color	仅 fixed 且 mask 开启时生效：遮罩色；空 = 主题遮罩色（跟随主题自动适配）	String	""	与 css 相同
text-style	微调说明文字的行内样式，如 "font-weight:600"，最后应用（其中 color 会覆盖 text-color，调色请用 text-color）	String	""	与 css 相同
custom-class	挂到根节点的额外 class（类需定义在组件样式表内）	String	""	-
custom-style	根节点行内样式，如 "margin:20px 0"	String	""	与 css 相同

事件

无事件。

方法（ref 直调）

方法	参数	说明
open	(options?: NLoadingOptions)	打开加载层；options 全部字段可选（mode / size / color / inactive-color / duration / text / text-size / text-color / vertical / mask / mask-color），缺省回落同名 props 默认值；展示中再次调用即替换内容
close	-	关闭加载层，回到 loading 属性驱动的声明式状态

插槽

插槽名	说明
default	插槽图标（icon-only 开启时替代内置形态指示器）：n-icon 组件或 image（远程 / base64）均可，与 text 共存，排列随 vertical

实现说明

• 形态集合：圆环 / 半圆弧 / 花瓣 / 三点脉冲是移动端加载组件的主流形态全集，三竖条为商业组件库常见补充；常见实现用多个属性重复表达形态（mode / type / icon 三套枚举并存），本组件收敛为单一 mode。
• 动画机制：JS 帧循环逐帧写行内样式（30ms/帧≈33fps，与按钮内置加载圈同节奏）——旋转角度/脉冲相位经响应式状态流入各形态样式，全端行为一致。❌ CSS 动画（规范红线）；❌ 官方 Animate API（UniElement.animate）在自定义组件内不可用：动画数据（$eA）写在页面作用域，组件模板读不到，微信端视图层永不应用（像素级实测静止），仅页面级元素可用该 API。
• 页面隐藏停表：帧循环启停收拢为「已挂载 + 加载态 + 页面可见」三条件。页面可见性经组合式 API 的 onPageShow/onPageHide 维护（组件内监听页面 onShow/onHide 的专用钩子，避免与应用级钩子重名）：页面被覆盖（跳转下一页 / tab 切换 / 应用切后台）即停帧，回显且仍在加载态自动恢复；loading=false 与卸载停表同属该不变量。
• 相位错开（dots / bars 各元素错峰呼吸）：不依赖负 delay，用相位时钟——每帧波形函数按 (时钟 + 相位) mod 1 取值，与错峰 delay 等价且全端行为一致。
• 圆环轨道（inactive-color）：旋转弧下层叠一圈静态底环（两层 border 圆），默认跟随主题弱填充色；'transparent' 关闭后即经典的三边实色一边透明缺口环。半圆弧形态不提供轨道（半弧旋转叠底环观感错乱）。
• 花瓣：12 根静态叶片（透明度梯度 1→1/12、按 30° 定角极坐标摆放），仅容器整体旋转——一次动画完成经典花瓣观感，叶片零动画开销。
• 几何参数：三点脉冲周期 1.4s、相位错开 0.3s/0.15s；三竖条固定几何盒 scaleY 中心伸缩 0.1↔1（几何恒定，与文字垂直居中不漂移）、半周期 0.5s、相位错开 0.2s；圆环描边 2px。
• 自定义旋转图标：iconOnly 配合默认插槽提供 n-icon 或 image，iconRotate 控制整体旋转，复用内置指示器的帧循环与页面显隐生命周期；静态插槽不启动帧循环。插槽自行设定尺寸，旋转容器允许内容超出原始边界。
• timingFunction 不开放：旋转必须线性（非线性循环在接缝处跳变），脉冲类缓动由形态内置——开放该参数只会被误用。
• 深色遮罩上使用：color 与 text-color 一起调白；指示器与文字的间距挂在指示器容器上（横排右移 8px / 竖排下移 8px），无文字时不占间距。

新窗口 ↗

演示加载中…

示例代码加载中…