Erste Schritte

1. Paket installieren

   npm

   npm i @capgo/capacitor-data-storage-sqlite

   pnpm

   pnpm add @capgo/capacitor-data-storage-sqlite

   yarn

   yarn add @capgo/capacitor-data-storage-sqlite

   bun

   bun add @capgo/capacitor-data-storage-sqlite

2. Mit nativen Projekten synchronisieren

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Plugin konfigurieren

   Grundlegendes Speicherbeispiel:

   import { CapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';
   
   // Eine Speicherdatenbank öffnen
   await CapacitorDataStorageSqlite.openStore({
     database: 'myapp_storage'
   });
   
   // Daten speichern
   await CapacitorDataStorageSqlite.set({
     key: 'user_preferences',
     value: JSON.stringify({ theme: 'dark' })
   });

   Verschlüsseltes Speicherbeispiel:

   // Verschlüsselten Speicher öffnen
   await CapacitorDataStorageSqlite.openStore({
     database: 'secure_storage',
     encrypted: true,
     mode: 'encryption'
   });
   
   // Sensible Daten speichern
   await CapacitorDataStorageSqlite.set({
     key: 'api_token',
     value: 'secret_token_value'
   });

   iOS

   Keine zusätzliche Einrichtung für iOS erforderlich.

   Android

   Keine zusätzliche Einrichtung für Android erforderlich.

4. Grundlegende Operationen

   import { CapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';
   
   // Einen Wert setzen
   await CapacitorDataStorageSqlite.set({
     key: 'username',
     value: 'john_doe'
   });
   
   // Einen Wert abrufen
   const { value } = await CapacitorDataStorageSqlite.get({
     key: 'username'
   });
   console.log('Benutzername:', value); // "john_doe"
   
   // Einen Wert entfernen
   await CapacitorDataStorageSqlite.remove({
     key: 'username'
   });
   
   // Alle Daten löschen
   await CapacitorDataStorageSqlite.clear();
   
   // Prüfen, ob Schlüssel existiert
   const { result } = await CapacitorDataStorageSqlite.iskey({
     key: 'username'
   });
   console.log('Schlüssel existiert:', result); // true oder false
   
   // Alle Schlüssel abrufen
   const { keys } = await CapacitorDataStorageSqlite.keys();
   console.log('Alle Schlüssel:', keys);
   
   // Alle Werte abrufen
   const { values } = await CapacitorDataStorageSqlite.values();
   console.log('Alle Werte:', values);

5. Erweiterte Verwendung

   import { CapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';
   
   export class StorageService {
     private dbName = 'app_storage';
     private isEncrypted = false;
   
     async initialize(encrypted = false) {
       this.isEncrypted = encrypted;
   
       // Speicher mit Optionen öffnen
       await CapacitorDataStorageSqlite.openStore({
         database: this.dbName,
         encrypted: encrypted,
         mode: encrypted ? 'encryption' : 'no-encryption',
         version: 1
       });
     }
   
     // Generische Speichermethoden
     async setObject<T>(key: string, data: T): Promise<void> {
       const value = JSON.stringify(data);
       await CapacitorDataStorageSqlite.set({ key, value });
     }
   
     async getObject<T>(key: string): Promise<T | null> {
       try {
         const { value } = await CapacitorDataStorageSqlite.get({ key });
         return value ? JSON.parse(value) : null;
       } catch (error) {
         console.error('Fehler beim Abrufen des Objekts:', error);
         return null;
       }
     }
   
     // Batch-Operationen
     async setMultiple(items: Record<string, any>): Promise<void> {
       for (const [key, value] of Object.entries(items)) {
         await CapacitorDataStorageSqlite.set({
           key,
           value: typeof value === 'string' ? value : JSON.stringify(value)
         });
       }
     }
   
     async getMultiple(keys: string[]): Promise<Record<string, any>> {
       const results: Record<string, any> = {};
   
       for (const key of keys) {
         try {
           const { value } = await CapacitorDataStorageSqlite.get({ key });
           results[key] = value;
         } catch (error) {
           results[key] = null;
         }
       }
   
       return results;
     }
   
     // Tabellenverwaltung
     async getTables(): Promise<string[]> {
       const { tables } = await CapacitorDataStorageSqlite.tables();
       return tables;
     }
   
     async deleteTable(table: string): Promise<void> {
       await CapacitorDataStorageSqlite.deleteTable({ table });
     }
   
     // Import/Export-Funktionalität
     async exportToJson(): Promise<any[]> {
       const { keys } = await CapacitorDataStorageSqlite.keys();
       const { values } = await CapacitorDataStorageSqlite.values();
   
       return keys.map((key, index) => ({
         key,
         value: values[index]
       }));
     }
   
     async importFromJson(data: Array<{ key: string; value: string }>): Promise<void> {
       // Vorhandene Daten löschen
       await CapacitorDataStorageSqlite.clear();
   
       // Neue Daten importieren
       for (const item of data) {
         await CapacitorDataStorageSqlite.set({
           key: item.key,
           value: item.value
         });
       }
     }
   
     // Filtern und Suchen
     async keysStartingWith(prefix: string): Promise<string[]> {
       const { keys } = await CapacitorDataStorageSqlite.keys();
       return keys.filter(key => key.startsWith(prefix));
     }
   
     async filterByPrefix(prefix: string): Promise<Array<{ key: string; value: string }>> {
       const { keys } = await CapacitorDataStorageSqlite.keys();
       const { values } = await CapacitorDataStorageSqlite.values();
   
       const filtered: Array<{ key: string; value: string }> = [];
   
       keys.forEach((key, index) => {
         if (key.startsWith(prefix)) {
           filtered.push({ key, value: values[index] });
         }
       });
   
       return filtered;
     }
   
     // Datenbank schließen, wenn fertig
     async close(): Promise<void> {
       await CapacitorDataStorageSqlite.closeStore({
         database: this.dbName
       });
     }
   }
   
   // Verwendungsbeispiel
   const storage = new StorageService();
   await storage.initialize(true); // Verschlüsselung verwenden
   
   // Benutzerdaten speichern
   await storage.setObject('user_profile', {
     id: 123,
     name: 'John Doe',
     email: 'john@example.com'
   });
   
   // Benutzerdaten abrufen
   const profile = await storage.getObject<any>('user_profile');
   console.log('Benutzerprofil:', profile);

API-Referenz

Methoden

openStore(options: OpenStoreOptions)

Eine Speicherdatenbank öffnen.

Parameter:

• options.database: string - Datenbankname
• options.encrypted: boolean - Verschlüsselung aktivieren
• options.mode: string - ‘encryption’ oder ‘no-encryption’
• options.version: number - Datenbankversion

closeStore(options: CloseStoreOptions)

Die Speicherdatenbank schließen.

set(options: SetOptions)

Ein Schlüssel-Wert-Paar speichern.

Parameter:

• options.key: string - Speicherschlüssel
• options.value: string - Zu speichernder Wert

get(options: GetOptions)

Einen Wert nach Schlüssel abrufen.

Rückgabe: Promise<{ value: string }>

remove(options: RemoveOptions)

Ein Schlüssel-Wert-Paar entfernen.

clear()

Alle Daten aus dem Speicher löschen.

iskey(options: IskeyOptions)

Prüfen, ob ein Schlüssel existiert.

Rückgabe: Promise<{ result: boolean }>

keys()

Alle Speicherschlüssel abrufen.

Rückgabe: Promise<{ keys: string[] }>

values()

Alle Speicherwerte abrufen.

Rückgabe: Promise<{ values: string[] }>

tables()

Alle Tabellennamen abrufen.

Rückgabe: Promise<{ tables: string[] }>

deleteTable(options: DeleteTableOptions)

Eine bestimmte Tabelle löschen.

Schnittstellen

interface OpenStoreOptions {
  database: string;
  encrypted?: boolean;
  mode?: string;
  version?: number;
}

interface SetOptions {
  key: string;
  value: string;
}

interface GetOptions {
  key: string;
}

interface RemoveOptions {
  key: string;
}

Plattform-Hinweise

iOS

• Verwendet SQLite3 mit optionalem SQLCipher für Verschlüsselung
• Daten bleiben über App-Updates hinweg erhalten
• Unterstützt iOS 11.0+

Android

• Verwendet SQLite mit optionalem SQLCipher
• Daten bleiben über App-Updates hinweg erhalten
• Unterstützt Android 5.0 (API 21)+

Häufige Anwendungsfälle

1. Benutzereinstellungen: App-Einstellungen und Präferenzen speichern
2. Cache-Verwaltung: API-Antworten und Daten zwischenspeichern
3. Offline-Speicher: Daten für Offline-Zugriff speichern
4. Sitzungsverwaltung: Benutzersitzungen sicher verwalten
5. Token-Speicher: Authentifizierungs-Token sicher speichern

Best Practices

1. Verschlüsselung für sensible Daten verwenden

   // Für sensible Daten wie Token
   await openStore({
     database: 'secure_db',
     encrypted: true,
     mode: 'encryption'
   });

2. Schlüssel mit Präfixen organisieren

   // Präfixe zur Organisation verwenden
   await set({ key: 'user:123:profile', value: userData });
   await set({ key: 'cache:api:users', value: apiData });

3. Große Daten vorsichtig behandeln

   // Für große Objekte Kompression in Betracht ziehen
   const compressed = compress(largeData);
   await set({ key: 'large_data', value: compressed });

4. Regelmäßige Bereinigung

   // Abgelaufene Cache-Einträge entfernen
   const keys = await keys();
   for (const key of keys.keys) {
     if (key.startsWith('cache:') && isExpired(key)) {
       await remove({ key });
     }
   }

Fehlerbehebung

Datenbank wird nicht geöffnet:

• Prüfen Sie, ob der Datenbankname gültig ist (alphanumerisch, Unterstriche)
• Stellen Sie sicher, dass keine Sonderzeichen im Datenbanknamen enthalten sind
• Überprüfen Sie, ob der Verschlüsselungsmodus mit der vorhandenen Datenbank übereinstimmt

Daten werden nicht gespeichert:

• Stellen Sie sicher, dass openStore vor Operationen aufgerufen wird
• Überprüfen Sie auf Fehler in der Konsole
• Überprüfen Sie, ob Schlüsselnamen Strings sind

Leistungsprobleme:

• Vermeiden Sie das Speichern sehr großer Werte
• Verwenden Sie Batch-Operationen, wenn möglich
• Erwägen Sie die Verwendung mehrerer Datenbanken für verschiedene Datentypen