1. 插件介绍

sqflite 是一个为 Flutter 应用提供 SQLite 数据库支持的插件，允许开发者在 Flutter 应用中轻松进行本地数据存储和管理。本版本基于 sqflite@2.2.8+3 开发，专为鸿蒙系统进行了适配和优化，提供了完整的 SQLite 数据库操作功能。

主要功能特性

• 支持事务和批处理操作
• 自动版本管理
• 提供插入、查询、更新、删除等便捷操作方法
• 数据库操作在后台线程执行，不阻塞 UI
• 支持多种数据类型：String、int、double、bool
• 鸿蒙系统特定的权限配置支持

2. 安装与引入

由于本版本是针对鸿蒙系统的自定义修改版本，需要通过 Git 方式引入依赖。

2.1 添加依赖

在项目的 pubspec.yaml 文件中添加以下依赖配置：

dependencies:
  sqflite:
    git:
      url: "https://gitcode.com/openharmony-sig/flutter_sqflite.git"
      path: ./sqflite

2.2 安装依赖

执行以下命令安装依赖：

flutter pub get

2.3 权限配置

在鸿蒙系统上使用 sqflite 需要配置网络权限。

2.3.1 在 module.json5 中添加权限

打开 entry/src/main/module.json5 文件，添加以下权限配置：

"requestPermissions": [
  {
   "name": "ohos.permission.INTERNET",
    "reason": "$string:network_reason",
    "usedScene": {
      "abilities": [
        "EntryAbility"
      ],
      "when":"inuse"
    }
  },
]

2.3.2 在 string.json 中添加权限原因

打开 entry/src/main/resources/base/element/string.json 文件，添加以下内容：

{
  "string": [
    {
      "name": "network_reason",
      "value": "使用网络"
    },
  ]
}

3. API 调用示例

3.1 数据库初始化与创建

import 'package:sqflite/sqflite.dart';
import 'package:path/path.dart';

// 获取数据库路径
final databasesPath = await getDatabasesPath();
final path = join(databasesPath, 'demo.db');

// 打开数据库
final database = await openDatabase(
  path,
  version: 1,
  onCreate: (Database db, int version) async {
    // 创建表
    await db.execute(
      'CREATE TABLE Test (id INTEGER PRIMARY KEY, name TEXT, value INTEGER, num REAL)'
    );
  }
);

3.2 插入数据

// 插入单条数据
final id = await database.rawInsert(
  'INSERT INTO Test(name, value, num) VALUES(?, ?, ?)',
  ['some name', 1234, 456.789]
);
print('插入的行ID: $id');

// 使用insert方法插入
final id2 = await database.insert('Test', {
  'name': 'another name',
  'value': 5678,
  'num': 123.456
});
print('插入的行ID: $id2');

3.3 查询数据

// 查询所有数据
final List<Map<String, dynamic>> allRows = await database.query('Test');
print('所有数据: $allRows');

// 使用rawQuery查询
final List<Map<String, dynamic>> queryRows = await database.rawQuery('SELECT * FROM Test WHERE value > ?', [2000]);
print('查询结果: $queryRows');

// 按条件查询
final List<Map<String, dynamic>> filteredRows = await database.query(
  'Test',
  columns: ['id', 'name'],
  where: 'value > ?',
  whereArgs: [2000]
);
print('筛选结果: $filteredRows');

3.4 更新数据

// 使用rawUpdate更新
final updatedCount = await database.rawUpdate(
  'UPDATE Test SET name = ?, value = ? WHERE name = ?',
  ['updated name', 9876, 'some name']
);
print('更新的行数: $updatedCount');

// 使用update方法更新
final updatedCount2 = await database.update(
  'Test',
  {'name': 'updated another name', 'value': 8765},
  where: 'name = ?',
  whereArgs: ['another name']
);
print('更新的行数: $updatedCount2');

3.5 删除数据

// 使用rawDelete删除
final deletedCount = await database.rawDelete(
  'DELETE FROM Test WHERE name = ?',
  ['updated name']
);
print('删除的行数: $deletedCount');

// 使用delete方法删除
final deletedCount2 = await database.delete(
  'Test',
  where: 'name = ?',
  whereArgs: ['updated another name']
);
print('删除的行数: $deletedCount2');

3.6 事务操作

await database.transaction((txn) async {
  // 在事务中执行多个操作
  final id1 = await txn.rawInsert(
    'INSERT INTO Test(name, value, num) VALUES(?, ?, ?)',
    ['transaction name 1', 1111, 11.11]
  );
  print('事务中插入的行ID: $id1');

  final id2 = await txn.rawInsert(
    'INSERT INTO Test(name, value, num) VALUES(?, ?, ?)',
    ['transaction name 2', 2222, 22.22]
  );
  print('事务中插入的行ID: $id2');
});

3.7 批处理操作

final batch = database.batch();

// 添加批处理操作
batch.insert('Test', {'name': 'batch name 1', 'value': 3333, 'num': 33.33});
batch.insert('Test', {'name': 'batch name 2', 'value': 4444, 'num': 44.44});
batch.update('Test', {'value': 9999}, where: 'name = ?', whereArgs: ['batch name 1']);
batch.delete('Test', where: 'name = ?', whereArgs: ['batch name 2']);

// 执行批处理
final results = await batch.commit();
print('批处理结果: $results');

3.8 关闭数据库

await database.close();

4. 兼容性与限制

4.1 已测试环境

• Flutter: 3.7.12-ohos-1.0.6
• SDK: 5.0.0(12)
• IDE: DevEco Studio: 5.0.13.200
• ROM: 5.1.0.120 SP3

4.2 注意事项

• 在鸿蒙系统上使用时，需要确保正确配置网络权限
• 当查询返回数据量特别大时，可能会受 taskPool 限制导致序列化失败
• 使用事务可以提高批量操作的性能和数据一致性
• 建议在不需要数据库时及时关闭连接，以释放资源

5. 总结

flutter_sqflite 插件为鸿蒙系统上的 Flutter 应用提供了强大的本地数据库支持，允许开发者轻松实现数据的存储、查询、更新和删除等操作。通过本文的介绍，您应该已经了解了如何：

1. 安装和配置 sqflite 插件
2. 配置鸿蒙系统所需的权限
3. 使用基本的数据库操作 API
4. 实现事务和批处理操作

该插件提供了与原生 SQLite 数据库的完整交互能力，同时保持了 Flutter 应用的跨平台特性，是开发需要本地数据存储的鸿蒙 Flutter 应用的理想选择。