插件概述 #

┌─────────────────────────────────────────────────────────────┐
│                      JavaScript API                          │
│                    (统一的调用接口)                           │
├─────────────────────────────────────────────────────────────┤
│                       Plugin Layer                           │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐   │
│  │  iOS Plugin   │  │Android Plugin │  │   Web Plugin  │   │
│  │   (Swift)     │  │    (Java)     │  │ (TypeScript)  │   │
│  └───────────────┘  └───────────────┘  └───────────────┘   │
├─────────────────────────────────────────────────────────────┤
│                    Native Platform APIs                      │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐   │
│  │   iOS SDK     │  │ Android SDK   │  │  Web APIs     │   │
│  └───────────────┘  └───────────────┘  └───────────────┘   │
└─────────────────────────────────────────────────────────────┘

@capacitor/plugin-name/
├── dist/                    # 编译输出
│   ├── esm/                 # ES模块
│   ├── cjs/                 # CommonJS模块
│   └── definitions.d.ts     # 类型定义
│
├── src/
│   ├── definitions.ts       # 接口定义
│   ├── index.ts             # 入口文件
│   ├── web.ts               # Web实现
│   └── index.ts             # 导出
│
├── ios/
│   ├── Sources/
│   │   └── PluginName/
│   │       ├── PluginName.h
│   │       └── PluginName.m
│   └── PluginName.podspec   # CocoaPods配置
│
├── android/
│   └── src/
│       └── main/
│           ├── java/com/example/plugin/
│           │   └── PluginName.java
│           └── AndroidManifest.xml
│
├── package.json
├── tsconfig.json
└── README.md

// src/definitions.ts
export interface MyPlugin {
    // 方法定义
    doSomething(options: DoSomethingOptions): Promise<DoSomethingResult>;
    
    // 事件监听
    addListener(eventName: 'myEvent', listener: (data: MyEventData) => void): Promise<void>;
    
    // 移除监听
    removeAllListeners(): Promise<void>;
}

// 选项接口
export interface DoSomethingOptions {
    param1: string;
    param2?: number;
}

// 结果接口
export interface DoSomethingResult {
    success: boolean;
    data?: any;
}

// 事件数据接口
export interface MyEventData {
    message: string;
    timestamp: number;
}

// src/index.ts
import { registerPlugin } from '@capacitor/core';
import type { MyPlugin } from './definitions';
import { MyPluginWeb } from './web';

// 注册插件
const MyPlugin = registerPlugin<MyPlugin>('MyPlugin', {
    web: () => import('./web').then(m => new m.MyPluginWeb())
});

export * from './definitions';
export { MyPlugin };

# 安装相机插件
npm install @capacitor/camera

# 安装地理位置插件
npm install @capacitor/geolocation

# 安装存储插件
npm install @capacitor/preferences

# 同步原生项目
npx cap sync

// 相机插件
import { Camera, CameraResultType } from '@capacitor/camera';

async function takePhoto() {
    const photo = await Camera.getPhoto({
        quality: 90,
        allowEditing: true,
        resultType: CameraResultType.Uri
    });
    
    return photo.webPath;
}

// 地理位置插件
import { Geolocation } from '@capacitor/geolocation';

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

// 存储插件
import { Preferences } from '@capacitor/preferences';

async function saveData(key: string, value: string) {
    await Preferences.set({ key, value });
}

async function getData(key: string) {
    const { value } = await Preferences.get({ key });
    return value;
}

# 安装Firebase分析
npm install @capacitor-community/firebase-analytics

# 安装SQLite
npm install @capacitor-community/sqlite

# 同步
npx cap sync

# 安装Cordova插件
npm install cordova-plugin-device-name

# 同步
npx cap sync

// 声明全局变量
declare global {
    interface Window {
        device: any;
    }
}

// 使用
if (window.device) {
    console.log('Device name:', window.device.name);
}

# 检查插件兼容性
npx cap plugin:check

# 使用Capacitor CLI创建插件
npm init @capacitor/plugin my-plugin

# 按提示输入信息
# ? Plugin NPM name: @mycompany/my-plugin
# ? Plugin id: my-plugin
# ? Plugin description: My custom Capacitor plugin
# ? Plugin git repository: 
# ? Plugin author: 
# ? Plugin license: MIT
# ? Package type: npm

my-plugin/
├── src/
│   ├── definitions.ts       # 接口定义
│   ├── index.ts             # 入口
│   └── web.ts               # Web实现
│
├── ios/
│   ├── Sources/
│   │   └── MyPlugin/
│   │       ├── MyPlugin.swift
│   │       └── MyPlugin.m
│   └── MyPlugin.podspec
│
├── android/
│   └── src/main/
│       └── java/com/mycompany/myplugin/
│           └── MyPlugin.java
│
├── package.json
├── tsconfig.json
├── rollup.config.js
└── README.md

// src/definitions.ts
import type { PluginListenerHandle } from '@capacitor/core';

export interface MyPlugin {
    // 基本方法
    echo(options: { value: string }): Promise<{ value: string }>;
    
    // 带选项的方法
    doSomething(options: DoSomethingOptions): Promise<DoSomethingResult>;
    
    // 事件监听
    addListener(
        eventName: 'myEvent',
        listener: (data: MyEventData) => void
    ): Promise<PluginListenerHandle>;
    
    // 移除所有监听器
    removeAllListeners(): Promise<void>;
}

export interface DoSomethingOptions {
    param1: string;
    param2?: number;
    flag?: boolean;
}

export interface DoSomethingResult {
    success: boolean;
    message: string;
    data?: any;
}

export interface MyEventData {
    type: string;
    payload: any;
}

// src/web.ts
import { WebPlugin } from '@capacitor/core';
import type { MyPlugin, DoSomethingOptions, DoSomethingResult, MyEventData } from './definitions';

export class MyPluginWeb extends WebPlugin implements MyPlugin {
    async echo(options: { value: string }): Promise<{ value: string }> {
        return { value: options.value };
    }
    
    async doSomething(options: DoSomethingOptions): Promise<DoSomethingResult> {
        console.log('doSomething called with:', options);
        
        // Web实现逻辑
        return {
            success: true,
            message: 'Operation completed',
            data: { input: options }
        };
    }
    
    // 触发事件示例
    notifyEvent(data: MyEventData) {
        this.notifyListeners('myEvent', data);
    }
}

// src/index.ts
import { registerPlugin } from '@capacitor/core';
import type { MyPlugin } from './definitions';

const MyPlugin = registerPlugin<MyPlugin>('MyPlugin', {
    web: () => import('./web').then(m => new m.MyPluginWeb())
});

export * from './definitions';
export { MyPlugin };

// 最常用的异步调用模式
const result = await MyPlugin.doSomething({
    param1: 'value',
    param2: 123
});

console.log(result.success);

// 添加监听器
const listener = await MyPlugin.addListener('myEvent', (data) => {
    console.log('Event received:', data);
});

// 移除监听器
await listener.remove();

// 移除所有监听器
await MyPlugin.removeAllListeners();

// 某些插件支持回调
MyPlugin.watchPosition({}, (position) => {
    console.log('Position:', position);
});

// 清除监听
await MyPlugin.clearWatch();

<!-- ios/App/App/Info.plist -->
<key>NSCameraUsageDescription</key>
<string>需要访问相机来拍照</string>

<key>NSPhotoLibraryUsageDescription</key>
<string>需要访问相册来选择照片</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>需要获取您的位置信息</string>

<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

import { Camera } from '@capacitor/camera';

// 请求权限
async function requestCameraPermission() {
    const permission = await Camera.requestPermissions();
    
    if (permission.camera === 'granted') {
        // 权限已授予
        const photo = await Camera.getPhoto();
    } else {
        // 权限被拒绝
        console.log('Camera permission denied');
    }
}

// 在插件中添加日志
export class MyPluginWeb extends WebPlugin implements MyPlugin {
    async doSomething(options: DoSomethingOptions): Promise<DoSomethingResult> {
        console.log('[MyPlugin] doSomething called:', options);
        
        // ... 实现逻辑
        
        console.log('[MyPlugin] doSomething result:', result);
        return result;
    }
}

// Swift日志
print("[MyPlugin] doSomething called with: \(options)")

// Java日志
Log.d("MyPlugin", "doSomething called with: " + options.toString());

// 开发模式下启用详细日志
if (import.meta.env.DEV) {
    const originalCall = MyPlugin.doSomething;
    MyPlugin.doSomething = async (options) => {
        console.time('doSomething');
        const result = await originalCall(options);
        console.timeEnd('doSomething');
        return result;
    };
}

// 定义错误类型
export class MyPluginError extends Error {
    constructor(
        message: string,
        public code: string,
        public data?: any
    ) {
        super(message);
        this.name = 'MyPluginError';
    }
}

// 使用
async doSomething(options: DoSomethingOptions): Promise<DoSomethingResult> {
    if (!options.param1) {
        throw new MyPluginError('param1 is required', 'INVALID_ARGUMENT');
    }
    
    try {
        // 执行操作
        return { success: true, message: 'OK' };
    } catch (error) {
        throw new MyPluginError(
            error.message,
            'OPERATION_FAILED',
            { originalError: error }
        );
    }
}

// 检查API可用性
async checkAvailability(): Promise<boolean> {
    try {
        await MyPlugin.echo({ value: 'test' });
        return true;
    } catch {
        return false;
    }
}