AgentSkillsCN

capacitor

Capacitor 为 Web 转 Native 移动应用提供插件支持,是混合型移动应用开发的优质选择。

SKILL.md
--- frontmatter
name: capacitor
description: Capacitor for web-to-native mobile apps with plugins. Use for hybrid mobile apps.

Capacitor

Web-native runtime for building cross-platform mobile apps.

When to Use

  • Convert web apps to mobile
  • Access native device features
  • Single codebase for web/mobile
  • Progressive Web App enhancement

Quick Start

bash
# Add to existing web project
npm install @capacitor/core @capacitor/cli
npx cap init

# Add platforms
npm install @capacitor/ios @capacitor/android
npx cap add ios
npx cap add android

Core Concepts

Plugin Usage

typescript
import { Camera, CameraResultType } from "@capacitor/camera";
import { Geolocation } from "@capacitor/geolocation";
import { LocalNotifications } from "@capacitor/local-notifications";

async function takePicture() {
  const image = await Camera.getPhoto({
    resultType: CameraResultType.Uri,
    quality: 90,
  });
  return image.webPath;
}

async function getLocation() {
  const position = await Geolocation.getCurrentPosition();
  return {
    lat: position.coords.latitude,
    lng: position.coords.longitude,
  };
}

async function scheduleNotification() {
  await LocalNotifications.schedule({
    notifications: [
      {
        title: "Reminder",
        body: "Check your tasks!",
        id: 1,
        schedule: { at: new Date(Date.now() + 3600 * 1000) },
      },
    ],
  });
}

Configuration

typescript
// capacitor.config.ts
import type { CapacitorConfig } from "@capacitor/cli";

const config: CapacitorConfig = {
  appId: "com.example.app",
  appName: "My App",
  webDir: "dist",
  server: {
    androidScheme: "https",
  },
  plugins: {
    SplashScreen: {
      launchAutoHide: false,
    },
    Keyboard: {
      resize: "body",
    },
  },
};

export default config;

Common Patterns

Native Bridge

typescript
import { registerPlugin } from "@capacitor/core";

interface MyPluginPlugin {
  echo(options: { value: string }): Promise<{ value: string }>;
}

const MyPlugin = registerPlugin<MyPluginPlugin>("MyPlugin");

// Usage
const result = await MyPlugin.echo({ value: "Hello" });

Build & Deploy

bash
# Sync web code to native
npx cap sync

# Open in IDE
npx cap open ios
npx cap open android

# Live reload during dev
npx cap run ios --livereload --external

Best Practices

Do:

  • Use official Capacitor plugins
  • Run cap sync after web builds
  • Handle permissions gracefully
  • Test on real devices

Don't:

  • Forget to sync after changes
  • Ignore platform differences
  • Skip error handling
  • Use deprecated Cordova plugins

Troubleshooting

IssueCauseSolution
Plugin not foundNot installedInstall and sync
White screenWeb build issueCheck webDir path
Permission deniedNot requestedAdd permission prompts

References