开始使用

安装

您可以使用我们的 AI 助手设置来安装插件。使用以下命令将 Capgo 技能添加到您的 AI 工具中：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下提示：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-native-loader` plugin in my project.

如果您更喜欢手动设置，请运行以下命令安装插件，并按照以下平台特定的说明进行操作：

1. 安装包

   npm install @capgo/capacitor-native-loader
   npx cap sync

2. 从 JavaScript 中显示一个原生加载器

   import { NativeLoader } from '@capgo/capacitor-native-loader';
   
   const { id } = await NativeLoader.show({
     style: 'siri',
     placement: 'fullscreen',
     message: 'Preparing workspace',
     colors: ['#71f6ff', '#8b5cf6', '#ff4ecd', '#fff7ad'],
     scrimColor: 'rgba(3, 7, 18, 0.42)',
     interactionMode: 'block',
   });
   
   await doExpensiveWork();
   
   await NativeLoader.hide({ id });

配置默认值

await NativeLoader.configure({
  defaults: {
    style: 'orbit',
    placement: 'center',
    size: 96,
    colors: ['#38bdf8', '#a78bfa'],
    reducedMotion: 'system',
    interactionMode: 'passThrough',
  },
});

Chrome 风格顶部加载器

使用 style: 'chrome' 当您希望熟悉的浏览器顶部进度条和 WebView 应该保持可用时。

const { id } = await NativeLoader.show({
  style: 'chrome',
  placement: 'top',
  colors: ['#4285f4', '#34a853', '#fbbc05', '#ea4335'],
  thickness: 4,
  interactionMode: 'passThrough',
  webView: {
    mode: 'resize',
    insets: { top: 12 },
    restoreOnHide: true,
  },
});

await NativeLoader.hide({ id, restoreWebView: true });

Siri V2 Edge Loader

使用 style: 'siri-v2' 当加载状态应该是原生全屏色彩动画环绕应用边缘而不是居中的卡片时。

const { id } = await NativeLoader.show({
  style: 'siri-v2',
  placement: 'fullscreen',
  colors: ['#71f6ff', '#8b5cf6', '#ff4ecd', '#fff7ad'],
  thickness: 10,
  scrimColor: 'rgba(3, 7, 18, 0.10)',
  interactionMode: 'passThrough',
});

await NativeLoader.hide({ id });

更新进度

const { id } = await NativeLoader.show({
  style: 'ring',
  message: 'Uploading',
  progress: 0,
});

for await (const progress of uploadFile(file)) {
  await NativeLoader.setProgress({ id, progress });
}

await NativeLoader.hide({ id });

调整WebView大小

使用 setWebViewLayout 当原生加载器应该占据屏幕的一部分，而网页内容仍然可用和可用时。

await NativeLoader.setWebViewLayout({
  mode: 'inset',
  insets: { top: 96, bottom: 24 },
  animated: true,
});

await NativeLoader.show({
  style: 'wave',
  placement: 'top',
  size: 72,
  message: 'Syncing',
  interactionMode: 'passThrough',
});

原生表面消失时恢复原始布局：

await NativeLoader.hideAll({ restoreWebView: true });

Lottie 和图像加载器

将 Lottie JSON 或图像资产打包到原生应用中，并从 JavaScript 中引用它们。

await NativeLoader.show({
  style: 'lottie',
  placement: 'center',
  asset: {
    type: 'lottie',
    source: 'rocket-loader.json',
    loop: true,
  },
});

await NativeLoader.show({
  style: 'image',
  placement: 'bottom',
  asset: {
    type: 'image',
    source: 'loader-frame',
  },
});

注意

注意

远程资产支持，但打包的原生资产对于启动加载器更好，因为它们在网络和 JavaScript 初始化完成之前就可用。

其他 iOS 插件可以直接调用共享加载器。

import CapgoCapacitorNativeLoader

let id = NativeLoader.shared.show(options: [
  "style": "siri",
  "placement": "fullscreen",
  "message": "Opening secure session",
  "interactionMode": "block"
])

NativeLoader.shared.setProgress(id: id, progress: 0.6)
NativeLoader.shared.hide(id: id)

Native Kotlin Calls

复制到剪贴板

import app.capgo.nativeloader.NativeLoader

val id = NativeLoader.show(
  activity = activity,
  options = mapOf(
    "style" to "orbit",
    "placement" to "fullscreen",
    "message" to "Loading profile",
    "interactionMode" to "block",
  ),
  webView = bridge.webView,
)

NativeLoader.setProgress(id, 0.6)
NativeLoader.hide(id)

Section titled “Common Options”

类型	描述']} The translations are based on the Simplified Chinese language. The translation is natural and adapted to the user's cultural context. The idioms, grammar, tone, and phrasing are adjusted accordingly. The brand names, product names, developer terms, URLs, code identifiers, file paths, package names, language codes, numbers, punctuation, and whitespace meaning are preserved. The literal tokens are not translated. The placeholders are copied exactly as written. The translations are in the same order as the input. The result is a JSON object with exactly one key named	translations
style	'siri' | 'siri-v2' | 'chrome' | 'orbit' | 'ring' | 'pulse' | 'dots' | 'bars' | 'wave' | 'halo' | 'lottie' | 'image'	Loader 渲染器
placement	'center' | 'top' | 'bottom' | 'left' | 'right' | 'fullscreen' | 'around' | 'custom'	原生表面位置
interactionMode	'passThrough' | 'block' | 'loaderOnly'	触摸处理
backgroundColor	string	遮罩颜色，包括 alpha
scrimColor	string	全屏幕或周围屏幕遮罩颜色
colors	string[]	Loader 渐变颜色
progress	number	确定值从 0 到 1
autoHide	number	自动隐藏前毫秒数
asset	object	Lottie 或图像资产来源

使用 reducedMotion: 'system' 以尊重用户的平台运动设置。