快速入门

安装

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

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

然后使用以下 prompt：

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

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

bun add @capgo/capacitor-data-storage-sqlite
bunx cap sync

导入

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

快速入门

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

await CapgoCapacitorDataStorageSqlite.openStore({ database: 'app', encrypted: true });
await CapgoCapacitorDataStorageSqlite.set({ key: 'session', value: JSON.stringify(session) });
const { value } = await CapgoCapacitorDataStorageSqlite.get({ key: 'session' });

示例：命名空间表

await CapgoCapacitorDataStorageSqlite.setTable({ table: 'drafts' });
await CapgoCapacitorDataStorageSqlite.set({ key: 'invoice-42', value: draftJson });

常见坑点

• 使用前先打开：每次读写都需要一个已打开的 store 句柄。
• 加密范围：加密仅适用于 iOS 和 Android 原生 store，不适用于 Web 端 IndexedDB 路径。
• 退出登录时关闭: clear() 加 closeStore() 可防止共享设备上出现过期数据。

API 概览

openStore

打开 Store

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

await CapgoCapacitorDataStorageSqlite.openStore({
  database: 'database',
  table: 'table',
  encrypted: false,
  mode: 'encryption',
  autoVacuum: 'none',
});

closeStore

关闭 Store

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

await CapgoCapacitorDataStorageSqlite.closeStore({ database: 'database' });

isStoreOpen

检查 Store 是否已打开

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

const result = await CapgoCapacitorDataStorageSqlite.isStoreOpen({ database: 'database' });
console.log(result);

isStoreExists

检查 Store 是否存在

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

const result = await CapgoCapacitorDataStorageSqlite.isStoreExists({ database: 'database' });
console.log(result);

deleteStore

删除存储库

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

await CapgoCapacitorDataStorageSqlite.deleteStore({
  database: 'database',
  table: 'table',
  encrypted: false,
  mode: 'encryption',
  autoVacuum: 'none',
});

setTable

为现有存储库设置或添加表

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

await CapgoCapacitorDataStorageSqlite.setTable({ table: 'table' });

set

使用指定的键值对存储数据

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

await CapgoCapacitorDataStorageSqlite.set({ key: 'key-123' });

get

根据指定的键获取数据值

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

const result = await CapgoCapacitorDataStorageSqlite.get({ key: 'key-123' });
console.log(result);

remove

根据指定的 key 删除数据

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

await CapgoCapacitorDataStorageSqlite.remove({ key: 'key-123' });

clear

清空数据存储（删除所有 key）

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

await CapgoCapacitorDataStorageSqlite.clear();

iskey

检查是否存在指定的 data key

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

const result = await CapgoCapacitorDataStorageSqlite.iskey({ key: 'key-123' });
console.log(result);

keys

获取 data key 列表

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

const result = await CapgoCapacitorDataStorageSqlite.keys();
console.log(result);

values

获取数据值列表

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

const result = await CapgoCapacitorDataStorageSqlite.values();
console.log(result);

filtervalues

获取 filter 键的数据值列表

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

const result = await CapgoCapacitorDataStorageSqlite.filtervalues({ filter: 'filter' });
console.log(result);

keysvalues

获取数据键值对列表

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

const result = await CapgoCapacitorDataStorageSqlite.keysvalues();
console.log(result);

isTable

检查表是否存在

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

const result = await CapgoCapacitorDataStorageSqlite.isTable({ table: 'table' });
console.log(result);

tables

获取当前 store 的表列表

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

const result = await CapgoCapacitorDataStorageSqlite.tables();
console.log(result);

deleteTable

删除表

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

await CapgoCapacitorDataStorageSqlite.deleteTable({ table: 'table' });

importFromJson

从 JSON 导入数据库

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

const result = await CapgoCapacitorDataStorageSqlite.importFromJson({ jsonstring: 'jsonstring' });
console.log(result);

isJsonValid

校验 JSON 对象是否有效

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

const result = await CapgoCapacitorDataStorageSqlite.isJsonValid({ jsonstring: 'jsonstring' });
console.log(result);

exportToJson

将给定数据库导出为 JSON 对象

import { CapgoCapacitorDataStorageSqlite } from '@capgo/capacitor-data-storage-sqlite';

const result = await CapgoCapacitorDataStorageSqlite.exportToJson();
console.log(result);

类型参考

capOpenStorageOptions

export interface capOpenStorageOptions {
  /**
   * The storage database name
   */
  database?: string; // default:
  //  ios, android: storageSQLite
  //  web : storageIDB
  /**
   * The storage table name
   */
  table?: string; // default:
  //  ios, android: storage_table
  //  web: storage_store
  /**
   * Set to true for database encryption
   */
  encrypted?: boolean; // only for ios and android
  /***
   * Set the mode for database encryption
   * ["encryption", "secret","newsecret"]
   */
  mode?: string; // only for ios and android
}

capStorageOptions

export interface capStorageOptions {
  /**
   * The storage name
   */
  database: string;
}

capDataStorageResult

export interface capDataStorageResult {
  /**
   * result set to true when successful else false
   */
  result?: boolean;
  /**
   * a returned message
   */
  message?: string;
}

capTableStorageOptions

export interface capTableStorageOptions {
  /**
   * The storage table name
   */
  table: string;
}

capDataStorageOptions

export interface capDataStorageOptions {
  /**
   * The data name
   */
  key: string;
  /**
   * The data value when required
   */
  value?: string;
}

capValueResult

export interface capValueResult {
  /**
   * the data value for a given data key
   */
  value: string;
}

capKeysResult

export interface capKeysResult {
  /**
   * the data key list as an Array
   */
  keys: string[];
}

capValuesResult

export interface capValuesResult {
  /**
   * the data values list as an Array
   */
  values: string[];
}

capFilterStorageOptions

export interface capFilterStorageOptions {
  /**
   * The filter data for filtering keys
   *
   * ['%filter', 'filter', 'filter%'] for
   * [starts with filter, contains filter, ends with filter]
   */
  filter: string;
}

capKeysValuesResult

export interface capKeysValuesResult {
  /**
   * the data keys/values list as an Array of {key:string,value:string}
   */
  keysvalues: any[];
}

capTablesResult

export interface capTablesResult {
  /**
   * the tables list as an Array
   */
  tables: string[];
}

capStoreImportOptions

export interface capStoreImportOptions {
  /**
   * Set the JSON object to import
   *
   */
  jsonstring?: string;
}

单一事实来源

本页面由插件的 src/definitions.ts生成。当上游的公共 API 发生变化时，请重新运行 sync。

从入门指南继续

如果你正在使用 快速入门 要规划存储和文件处理，请将其与 使用 @capgo/capacitor-data-storage-sqlite 关于使用 @capgo/capacitor-data-storage-sqlite 的原生能力， @capgo/capacitor-data-storage-sqlite 关于 @capgo/capacitor-data-storage-sqlite 中的实现细节， @capgo/capacitor-file 关于 @capgo/capacitor-file 中的实现细节， 使用 @capgo/capacitor-file 用于“使用 @capgo/capacitor-file”中的原生能力，以及 @capgo/capacitor-uploader 了解 @capgo/capacitor-uploader. 的实现细节