Cara Menggunakan Fitur Paket SPM di Capacitor 8

Untuk menggunakan fitur paket SPM di Capacitor 8, atur experimental.ios.spm.swiftToolsVersion ke "6.1" dan daftar fitur-fitur per plugin di bawah experimental.ios.spm.packageTraits di konfigurasi Capacitor Anda, lalu jalankan bunx cap sync iosThe CLI menulis karakteristik tersebut ke dalam kode yang dihasilkan. CapApp-SPM/Package.swift, and SwiftPM builds the plugin with the matching optional dependencies and code paths. This needs Capacitor CLI 8.3.0 or later and only applies to iOS projects that use Swift Package Manager.

Traits close the last big feature gap between SPM and CocoaPods for plugins: optional native dependencies that used to be podspec subspecs. This guide covers the app side, the plugin author side, and the limits of the current experimental support.

Apa saja sifat paket?

Sifat paket berasal dari usulan Evolusi Swift SE-0450, diimplementasikan dalam Swift 6.1 (Xcode 16.3 dan seterusnya). Paket menyatakan sifat-sifat bernama dalam file Package.swiftKonsumen memilih mana yang diaktifkan ketika mereka bergantung pada paket. Sifat dapat:

• membuat ketergantungan optional (condition: .when(traits: [...]) pada ketergantungan target)
• mengaktifkan jalur code karena setiap sifat yang diaktifkan tersedia sebagai kondisi kompilasi (#if TraitName),
• mengaktifkan pengaturan pembangunan seperti definisi atau flag penggabung
• mengaktifkan sifat lainnya.

Paket juga dapat menandai sifat sebagai default. Mereka aktif kecuali konsumen mengirimkan daftar eksplisit.

Jika Anda tahu subspek CocoaPods atau fitur Cargo di Rust, itu ide yang sama.

Kenapa hal ini penting di Capacitor

Capacitor menghasilkan aplikasi Anda Package.swift untuk Anda, sehingga Anda tidak dapat mengedit secara manual baris ketergantungan untuk memenuhi sifat. Sebelum CLI 8.3, pengembang plugin dengan SDK native opsional memiliki dua pilihan buruk di SPM: selalu menghubungkan SDK, meningkatkan ukuran dan kadang-kadang menambahkan pekerjaan privasi atau kewajiban ekspor, atau menerbitkan plugin kedua. Kasus umum:

• enkripsi vs SQLite biasa (SQLCipher)
• SDK analitik dengan dan tanpa pengumpulan identifikasi pengiklan,
• SDK vendor opsional untuk satu penyedia pembayaran atau login,
• alat pengembangan debug-only.

Aktifkan sifat di aplikasi Anda

1. Periksa versi

bunx cap --version      # 8.3.0 or later
xcodebuild -version     # Xcode 26 (required by Capacitor 8 anyway)

Projek harus menggunakan SPM: ios/App/CapApp-SPM ada. Jika Anda menggunakan CocoaPods, lihat bagaimana untuk memigrasikan aplikasi Capacitor Anda ke SPM.

1. Cari nama fitur plugin

2. Buka plugin’s Package.swift di node_modules dan cari arraynya, atau cek README-nya. Nama fitur case-sensitive. traits: array, atau cek README-nya. Nama trait sensitif terhadap huruf besar-kecil.

3. Configure Capacitor

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example',
  webDir: 'dist',
  experimental: {
    ios: {
      spm: {
        swiftToolsVersion: '6.1',
        packageTraits: {
          '@acme/capacitor-db': ['.defaults', 'SQLCipher'],
        },
      },
    },
  },
};

export default config;

Kunci adalah nama paket plugin npm. Nilai adalah daftar fitur yang diaktifkan.

4. Sinkronkan dan cek hasilnya

bunx cap sync ios

Output yang dihasilkan ios/App/CapApp-SPM/Package.swift sekarang dimulai dengan // swift-tools-version: 6.1 dan garis ketergantungan plugin’s membawa fitur-fitur:

.package(name: "AcmeCapacitorDb", path: "../../../node_modules/@acme/capacitor-db", traits: [.defaults, "SQLCipher"])

Penulis CLI .defaults (atau defaults, .default, default dalam hal apapun) sebagai SwiftPM .defaults Nilai, dan setiap nama lain sebagai string yang diketik.

nilai, dan setiap nama lain sebagai string yang diketik. File > Paket > Reset Cache Paket.

Mengatur aturan yang dijalankan oleh CLI

Konfigurasi Capacitor CLI diverifikasi selama sinkronisasi:

• Jika ada plugin yang memiliki daftar sifat yang tidak kosong dan swiftToolsVersion tidak ada, sinkronisasi berhenti dengan “Paket sifat memerlukan versi alat Swift eksplisit 6.1 atau lebih tinggi.”
• If swiftToolsVersion Versi lebih rendah dari 6.1, sinkronisasi berhenti dan memberitahu Anda bahwa versi terlalu rendah.
• swiftToolsVersion harus terlihat seperti 6.1 atau 6.1.0.
• Plugin dengan array kosong dianggap tidak terdaftar.

Tetapkan atau hapus fitur default

Menampilkan fitur menggantikan default. Bandingkan:

Baca dokumen plugin sebelum menghapus default. Plugin mungkin menempatkan backend standarnya di balik fitur default.

Tambahkan sifat ke plugin Anda sendiri

Jika Anda menjaga plugin dengan opsional SDK, berikut adalah contoh yang lengkap Package.swift. Nama paket harus sesuai dengan nama yang Capacitor CLI mengambil dari nama npm Anda (@acme/capacitor-db menjadi AcmeCapacitorDblihat migrasi plugin Capacitor ke SPM untuk aturan tersebut.

// swift-tools-version: 6.1
import PackageDescription

let package = Package(
    name: "AcmeCapacitorDb",
    platforms: [.iOS(.v15)],
    products: [
        .library(name: "AcmeCapacitorDb", targets: ["DbPlugin"])
    ],
    traits: [
        .trait(name: "SQLCipher", description: "Link SQLCipher and enable encrypted databases."),
        .default(enabledTraits: [])
    ],
    dependencies: [
        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0"),
        .package(url: "https://github.com/sqlcipher/SQLCipher.swift.git", from: "4.10.0")
    ],
    targets: [
        .target(
            name: "DbPlugin",
            dependencies: [
                .product(name: "Capacitor", package: "capacitor-swift-pm"),
                .product(name: "Cordova", package: "capacitor-swift-pm"),
                .product(
                    name: "SQLCipher",
                    package: "SQLCipher.swift",
                    condition: .when(traits: ["SQLCipher"])
                )
            ],
            path: "ios/Sources/DbPlugin"
        )
    ],
    swiftLanguageModes: [.v5]
)

Periksa repositori SDK sendiri untuk URL paket, nama produk, dan versi saat ini sebelum Anda menyalin ini.

Poin-poin yang mudah terlewatkan:

• Versi alat 6.x mengubah mode bahasa default ke Swift 6 untuk target Anda. Capacitor tidak secara resmi mendukung Swift 6, jadi jangan swiftLanguageModes: [.v5] kecuali code Anda sudah siap untuk konkurensi ketat.
• Meningkatkan versi alat plugin Anda ke 6.1 berarti konsumen memerlukan Xcode 16.3+. Capacitor 8 aplikasi sudah memerlukan Xcode 26, jadi itu bukan konstrain baru.

Gunakan fitur ini di code

Fitur-fitur yang diaktifkan adalah kondisi kompilasi di target paket Anda:

#if SQLCipher
import SQLCipher
#endif

@objc func open(_ call: CAPPluginCall) {
    let key = call.getString("encryptionKey")
    #if SQLCipher
    // open with key
    #else
    if key != nil {
        call.unavailable("Encryption requires the SQLCipher trait. Enable it in experimental.ios.spm.packageTraits.")
        return
    }
    #endif
    // open without encryption
}

Kembalikan kesalahan yang jelas dengan nama fitur ketika fitur tertentu dimatikan. Pengembang aplikasi lainnya melihat gagal diam dan menyalahkan plugin.

Anda juga dapat mendefinisikan flag sendiri dengan swiftSettings: [.define("ACME_SQLCIPHER", .when(traits: ["SQLCipher"]))] Jika Anda lebih suka nama yang diprefix.

Desain fitur-fitur untuk menjadi menambahkan

SwiftPM menyatukan fitur-fitur di seluruh grafik dependensi. Jika dua paket bergantung pada plugin Anda dengan fitur-fitur yang berbeda, union yang diaktifkan. Jadi:

• Mengaktifkan fitur harus menambahkan kemampuan, bukan menghilangkan API atau mengubah default.
• Hindari fitur-fitur yang saling eksklusif. Jika Anda tidak bisa, gagal bangun dengan keras:

#if TraitA && TraitB
#error("TraitA and TraitB cannot be enabled together")
#endif

Tes setiap kombinasi

swift build On Mac sendiri membangun untuk, dan plugin yang bergantung pada Capacitor hanya membangun untuk iOS, jadi tes fitur-fitur melalui aplikasi uji Capacitor yang dibangun untuk Simulator iOS. Untuk setiap kombinasi (tidak ada entri untuk fitur-fitur default, dan seterusnya), ubah ['SQLCipher'], ['.defaults', 'SQLCipher'] dan seterusnya), ubah packageTraits Tambahkan setiap kombinasi ke CI sebagai pekerjaan sendiri.

bunx cap sync ios
xcodebuild build \
  -project ios/App/App.xcodeproj \
  -scheme App \
  -destination 'generic/platform=iOS Simulator' \
  CODE_SIGNING_ALLOWED=NO

Tambahkan setiap kombinasi ke CI sebagai pekerjaan sendiri.

Tetapkan Pengguna CocoaPods

Hanya ada di SPM. Jika plugin Anda juga mengirimkan podspec, tawarkan pilihan yang sama seperti subspecs:

s.default_subspec = 'Core'

s.subspec 'Core' do |core|
  core.source_files = 'ios/Sources/DbPlugin/**/*.swift'
  core.dependency 'Capacitor'
end

s.subspec 'SQLCipher' do |sc|
  sc.dependency 'AcmeCapacitorDb/Core'
  sc.dependency 'SQLCipher', '~> 4.10'
  sc.pod_target_xcconfig = { 'SWIFT_ACTIVE_COMPILATION_CONDITIONS' => '$(inherited) SQLCipher' }
end

Mengatur nama kondisi kompilasi yang sama di subspec memungkinkan Anda untuk berbagi #if SQLCipher Rute code. Aplikasi CocoaPods kemudian memilih subspec dalam file Podfile. Pengguna Capacitor CLI menulis satu pod baris per plugin di dalamnya capacitor_podsDokumentasikan baris Podfile tambahan di README Anda. Cara Menggunakan CocoaPods dengan Capacitor 8 menunjukkan di mana baris pod custom pergi.

Keterbatasan

• Experimental. Opsi-opsi ini berada di bawah experimental dan mungkin berpindah ke ios.spm.* di masa depan versi besar. Harapkan perubahan konfigurasi pada suatu titik.
• Swift 6 tidak secara resmi didukung. Dokumen sendiri CLI mengingatkan bahwa pengaturan swiftToolsVersion ke 6.0 atau lebih tinggi mungkin menyebabkan masalah. Uji aplikasi penuh, terutama plugin yang mengirim xcframeworks biner.
• Hanya untuk iOS. Android tidak memiliki setara dengan Capacitor. Plugin mengelola SDK Android opsional dengan variabel Gradle di variables.gradle atau artefak terpisah.
• Plugin harus memilih untuk berpartisipasi. Sebagian besar plugin belum mendefinisikan sifat. Periksa sebelum Anda merencanakan satu.

Troubleshooting

Sync gagal dengan "Sifat paket memerlukan versi alat Swift eksplisit 6.1 atau lebih tinggi." Tambahkan swiftToolsVersion: '6.1' berikutnya packageTraits.

SwiftPM melaporkan sifat yang tidak diketahui. Nama trait sensitif terhadap huruf besar/kecil dan harus ada di plugin tersebut. Package.swift Fungsi masih hilang setelah mengaktifkan sifat.

Fitur masih belum tersedia setelah mengaktifkan sifat tersebut. Hapus cache paket di Xcode, bersihkan folder pembangunan, dan pastikan hasil yang dihasilkan CapApp-SPM/Package.swift memiliki traits: suffix. Mengedit file tersebut dengan tangan tidak berlaku, karena CLI mengubahnya setiap kali sinkronisasi.

Masalah di Swift code setelah meningkatkan versi tools. Swift 6 mode bahasa di dalam paket yang Anda kendalikan. Tambahkan swiftLanguageModes: [.v5].

Konflik nama antara plugin. Sejak CLI 8.4, experimental.ios.spm.packageOptions biarkan Anda menetapkan symlink atau moduleAliases per plugin. Lebih lanjut tentang itu di Capacitor iOS troubleshooting guide.

Untuk gambaran yang lebih besar tentang SPM, baca SPM vs CocoaPods for CapacitorJika Anda ingin membangun di cloud yang sudah menjalankan Xcode terkini untuk proyek SPM, lihat Capgo Bangun.