@capgo/capacitor-native-loader

原生渲染路径

将加载器显示为 UIKit 和 Android 覆盖视图，而不是让 WebView 动画化昂贵的半透明效果。

灵活布局

将加载器置于全屏、居中、固定于边缘、顶部 Chrome 风格，或围绕 WebView 并支持安全区域边距。

内置与资源加载器

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

随处可调用

通过公开的原生 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 顶部
圆环
圆点
条形
波浪
轨道
脉冲
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 覆盖整个应用，可选半透明。
• center 在 WebView 上方浮动显示紧凑加载器。
• top, bottom, left，以及 right 将 loader 固定在适配安全区域的边缘。
• chrome style 使用全宽原生顶部栏，与...搭配效果极佳 webView.mode: 'resize'.
• around 在屏幕框架周围渲染 loader 动画。
• custom 为 native-plugin 或分屏工作流使用显式框架。

使用 interactionMode: 'passThrough' 当用户可以继续与 WebView 交互时， block 当加载时应阻止点击，或 loaderOnly 当仅允许 loader 表面接收触摸时。

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

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