欢迎加入开源鸿蒙跨平台社区： https://openharmonycrossplatform.csdn.net

Flutter 三方库 sqflite 鸿蒙化本地数据库实战

摘要

sqflite 是 Flutter 生态中用于实现本地 SQLite 数据库的常用插件，支持创建数据库、表管理、CRUD 操作等核心功能。本文基于 OpenHarmony TPC 仓库的适配版本，详细讲解 sqflite 在鸿蒙项目中的接入流程、数据库创建、核心 API 使用及常见问题排查，并附真实设备运行截图验证。

核心要点：

• 掌握数据库创建与打开
• 实现表的创建与升级
• 熟练使用 CRUD 操作

一、数据库架构

二、参考来源

三、接入步骤

3.1 配置 pubspec.yaml

dependencies:
  flutter:
    sdk: flutter
  
  sqflite:
    git:
      url: https://atomgit.com/openharmony-tpc/flutter_packages.git
      path: packages/sqflite/sqflite
  
  path_provider:
    git:
      url: https://atomgit.com/openharmony-tpc/flutter_packages.git
      path: packages/path_provider/path_provider

3.2 核心代码示例

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

class DatabaseService {
  static Database? _database;
  static const String _dbName = 'demo.db';
  static const int _dbVersion = 1;

  Future<Database> get database async {
    if (_database != null) return _database!;
    _database = await _initDatabase();
    return _database!;
  }

  Future<Database> _initDatabase() async {
    final dbPath = await getDatabasesPath();
    final path = join(dbPath, _dbName);

    return await openDatabase(
      path,
      version: _dbVersion,
      onCreate: _onCreate,
      onUpgrade: _onUpgrade,
    );
  }

  Future<void> _onCreate(Database db, int version) async {
    await db.execute('''
      CREATE TABLE users (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        name TEXT NOT NULL,
        email TEXT NOT NULL,
        age INTEGER
      )
    ''');
  }

  Future<void> _onUpgrade(Database db, int oldVersion, int newVersion) async {
    // 处理数据库升级
  }

  // 插入数据
  Future<int> insert(String table, Map<String, dynamic> data) async {
    final db = await database;
    return await db.insert(table, data);
  }

  // 查询数据
  Future<List<Map<String, dynamic>>> query(
    String table, {
    bool? distinct,
    List<String>? columns,
    String? where,
    List<Object?>? whereArgs,
    String? orderBy,
    int? limit,
  }) async {
    final db = await database;
    return await db.query(
      table,
      distinct: distinct,
      columns: columns,
      where: where,
      whereArgs: whereArgs,
      orderBy: orderBy,
      limit: limit,
    );
  }

  // 更新数据
  Future<int> update(
    String table,
    Map<String, dynamic> data, {
    String? where,
    List<Object?>? whereArgs,
  }) async {
    final db = await database;
    return await db.update(table, data, where: where, whereArgs: whereArgs);
  }

  // 删除数据
  Future<int> delete(
    String table, {
    String? where,
    List<Object?>? whereArgs,
  }) async {
    final db = await database;
    return await db.delete(table, where: where, whereArgs: whereArgs);
  }

  // 执行原始 SQL
  Future<List<Map<String, dynamic>>> rawQuery(String sql) async {
    final db = await database;
    return await db.rawQuery(sql);
  }

  Future<void> close() async {
    final db = await database;
    await db.close();
    _database = null;
  }
}

3.3 完整使用示例

import 'package:flutter/material.dart';

class DatabaseDemo extends StatefulWidget {
  @override
  _DatabaseDemoState createState() => _DatabaseDemoState();
}

class _DatabaseDemoState extends State<DatabaseDemo> {
  final DatabaseService _dbService = DatabaseService();
  List<Map<String, dynamic>> _users = [];
  final _nameController = TextEditingController();
  final _emailController = TextEditingController();
  final _ageController = TextEditingController();

  @override
  void initState() {
    super.initState();
    _loadUsers();
  }

  Future<void> _loadUsers() async {
    final users = await _dbService.query('users', orderBy: 'id DESC');
    if (mounted) {
      setState(() {
        _users = users;
      });
    }
  }

  Future<void> _addUser() async {
    final user = {
      'name': _nameController.text,
      'email': _emailController.text,
      'age': int.tryParse(_ageController.text) ?? 0,
    };
    await _dbService.insert('users', user);
    _nameController.clear();
    _emailController.clear();
    _ageController.clear();
    _loadUsers();
  }

  Future<void> _deleteUser(int id) async {
    await _dbService.delete('users', where: 'id = ?', whereArgs: [id]);
    _loadUsers();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('SQLite Demo'),
      ),
      body: Column(
        children: [
          Padding(
            padding: EdgeInsets.all(16),
            child: Column(
              children: [
                TextField(
                  controller: _nameController,
                  decoration: InputDecoration(labelText: '姓名'),
                ),
                TextField(
                  controller: _emailController,
                  decoration: InputDecoration(labelText: '邮箱'),
                ),
                TextField(
                  controller: _ageController,
                  decoration: InputDecoration(labelText: '年龄'),
                  keyboardType: TextInputType.number,
                ),
                SizedBox(height: 16),
                ElevatedButton(
                  onPressed: _addUser,
                  child: Text('添加用户'),
                ),
              ],
            ),
          ),
          Expanded(
            child: ListView.builder(
              itemCount: _users.length,
              itemBuilder: (context, index) {
                final user = _users[index];
                return ListTile(
                  leading: CircleAvatar(child: Text('${user['id']}')),
                  title: Text(user['name']),
                  subtitle: Text('${user['email']} - ${user['age']}岁'),
                  trailing: IconButton(
                    icon: Icon(Icons.delete, color: Colors.red),
                    onPressed: () => _deleteUser(user['id']),
                  ),
                );
              },
            ),
          ),
        ],
      ),
    );
  }
}

四、验证步骤

五、常见问题排查

六、运行成功截图

未添加数据状态

添加两个测试用户到数据库

七、总结

sqflite 是实现本地数据持久化的核心插件，在 OpenHarmony 平台上的适配完善。通过 SQLite 数据库，可以实现复杂数据的本地存储，是数据管理类应用的必备工具。

附录：Schema.org 结构化数据

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Flutter 三方库 sqflite 鸿蒙化本地数据库实战",
  "description": "基于 OpenHarmony TPC 仓库，详细讲解 sqflite 在鸿蒙项目中的接入流程、数据库创建与 CRUD 操作功能实现。",
  "author": { "@type": "Person", "name": "OpenHarmony 跨平台开发者" },
  "publisher": { "@type": "Organization", "name": "OpenHarmony 跨平台社区", "url": "https://openharmonycrossplatform.csdn.net" },
  "datePublished": "2026-05-07",
  "dateModified": "2026-05-07",
  "mainEntityOfPage": "https://openharmonycrossplatform.csdn.net",
  "keywords": ["开源鸿蒙", "OpenHarmony", "Flutter for OpenHarmony", "sqflite", "本地数据库", "SQLite", "三方库适配"],
  "inLanguage": "zh-CN"
}
</script>