@capgo/capacitor-native-loader

原生渲染路径

将加载器显示为 UIKit 和 Android 覆盖视图，而非请求 WebView 动画执行高能耗的半透明效果。

灵活的布局方式

支持全屏、居中、固定在边缘、顶部 Chrome 风格，或根据安全区域内边距环绕 WebView 布局。

内置及资源加载器

支持原生 Siri 风格、Siri v2 边缘、Chrome 顶部进度、轨道、圆环、脉冲、圆点、进度条、波浪、光晕、图片或基于 Lottie 的加载器。

随处可调用

可通过公开的 native API，从 JavaScript、Swift、Kotlin 或其他原生插件触发加载器。

平台支持

平台	支持	注意事项
iOS	是	原生
Android	是	原生
Web	否	使用 Capacitor.getPlatform() 做保护

适用场景

@capgo/capacitor-native-loader 适用于 WebView 繁忙、调整大小、页面跳转或被原生界面遮挡时，仍需保持流畅、半透明和原生感的加载状态。

在以下场景中使用：

• Web 内容上方的全屏透明加载层
• Chrome 风格的顶部进度条（可调整 WebView 大小而非遮挡内容）
• 应用顶部、底部、左侧或右侧的边缘加载器
• 原生内容占据部分屏幕时，环绕已调整大小 WebView 的加载器
• 在重度 Web 渲染、路由切换或启动任务期间依然可用的原生兜底加载器
• 在 JavaScript 就绪前，由其他原生插件触发的共享加载器
• 基于 Lottie、内置图片或远程资源的加载动画

注意

对于仅限 Web 的路由动画，请使用 @capgo/capacitor-transitions当加载状态本身需要原生体验，或者在加载过程中需要调整 WebView 大小时，请使用 Native Loader。

演示样式

样式	预览
Siri
Siri v2
Chrome 顶部
Ring
Dots
Bars
Wave
Orbit
Pulse
Halo
Around
Lottie
Image

核心 API

• show(options) 显示加载器并返回其 id.
• update(options) 在不销毁遮罩层的情况下更改现有加载器。
• setProgress(options) 决定更新加载器的进度。
• hide(options) 移除一个加载器。
• hideAll(options) 移除所有加载器。
• setWebViewLayout(options) 调整 WebView/body 的大小或内边距，以便原生加载器可以并排显示。
• resetWebViewLayout(options?) 恢复原始 WebView/body 布局。
• getState() 返回当前可见的加载器 ID。
• configure(options) 设置默认样式、位置、颜色、动画和行为。

放置模式

placement 控制原生层出现的位置：

• fullscreen 覆盖整个 App，可选择半透明。
• center 在 WebView 上方悬浮一个紧凑型加载器。
• top, bottom, left，以及 right 将加载器固定在适配安全区域的边缘。
• chrome 样式采用全宽原生顶部栏，可与以下内容完美搭配： webView.mode: 'resize'.
• around 在屏幕框架周围渲染加载动画。
• custom 为原生插件或分屏工作流提供明确的框架。

使用 interactionMode: 'passThrough' 当用户可以继续与 WebView 进行交互时， block 当加载时需要阻止点击时，或 loaderOnly 当仅允许加载层接收触摸时。

继续阅读 @capgo/capacitor-native-loader

如果你正在使用 @capgo/capacitor-native-loader 若要规划原生媒体和界面行为，请将其与 快速入门 了解实现细节， @capgo/capacitor-native-navigation 关于原生 Chrome 和 WebView 布局， @capgo/capacitor-transitions 关于 Web 路由动画，以及 使用 @capgo/capacitor-native-loader 查看教程。