UniApp 集成 SQLite 数据库完整教程

一、环境准备

1. 平台支持情况

• ​App端(Android/iOS)​: 完全支持SQLite数据库
• ​H5端​: 不支持，需使用WebSQL或IndexedDB替代
• ​小程序端​: 部分支持，需使用小程序自带的数据库API

2. 插件安装

推荐使用uni-sqlite插件，该插件对原生SQLite进行了封装，提供了统一的API接口：

​​安装步骤​​：

1. 打开HBuilderX，进入项目
2. 点击菜单"工具"→"插件安装"
3. 搜索"sqlite"，安装"uni-sqlite"插件

二、数据库操作封装

1. 创建数据库工具文件

在项目根目录创建common/sqlite.js文件，封装常用数据库操作方法：

const dbName = "myDatabase"; // 数据库名称
const dbPath = "_doc/myDatabase.db"; // 存储路径

// 打开数据库
export function openDatabase() {
  return new Promise((resolve, reject) => {
    plus.sqlite.openDatabase({
      name: dbName,
      path: dbPath,
      success: function(e) {
        console.log('数据库打开成功');
        resolve(e);
      },
      fail: function(e) {
        console.error('数据库打开失败:', JSON.stringify(e));
        reject(e);
      }
    });
  });
}

// 检查数据库是否打开
export function isOpenDatabase() {
  return plus.sqlite.isOpenDatabase({
    name: dbName,
    path: dbPath
  });
}

// 执行SQL语句
export function executeSql(sql, args = []) {
  return new Promise((resolve, reject) => {
    plus.sqlite.executeSql({
      name: dbName,
      sql: sql,
      args: args,
      success: function(e) {
        resolve(e);
      },
      fail: function(e) {
        reject(e);
      }
    });
  });
}

// 查询数据
export function selectSql(sql, args = []) {
  return new Promise((resolve, reject) => {
    plus.sqlite.selectSql({
      name: dbName,
      sql: sql,
      args: args,
      success: function(e) {
        resolve(e);
      },
      fail: function(e) {
        reject(e);
      }
    });
  });
}

// 关闭数据库
export function closeDatabase() {
  return new Promise((resolve, reject) => {
    plus.sqlite.closeDatabase({
      name: dbName,
      success: function(e) {
        resolve(e);
      },
      fail: function(e) {
        reject(e);
      }
    });
  });
}

三、数据库初始化

在应用启动时初始化数据库：

// 在App.vue的onLaunch中初始化
import { openDatabase, executeSql } from '@/common/sqlite.js';

export default {
  onLaunch() {
    this.initDatabase();
  },
  methods: {
    async initDatabase() {
      try {
        // 打开数据库
        await openDatabase();
        
        // 创建用户表
        await executeSql(`
          CREATE TABLE IF NOT EXISTS users (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            name TEXT NOT NULL,
            email TEXT UNIQUE,
            age INTEGER,
            created_at DATETIME DEFAULT CURRENT_TIMESTAMP
          )
        `);
        
        console.log('数据库初始化成功');
      } catch (error) {
        console.error('数据库初始化失败:', error);
      }
    }
  }
}

四、CRUD操作示例

1. 插入数据

async function insertUser(user) {
  try {
    const result = await executeSql(
      'INSERT INTO users (name, email, age) VALUES (?, ?, ?)',
      [user.name, user.email, user.age]
    );
    console.log('插入成功，ID:', result.insertId);
    return result.insertId;
  } catch (error) {
    console.error('插入失败:', error);
    throw error;
  }
}

2. 查询数据

// 查询所有用户
async function getAllUsers() {
  try {
    const result = await selectSql('SELECT * FROM users');
    return result;
  } catch (error) {
    console.error('查询失败:', error);
    throw error;
  }
}

// 条件查询
async function getUserById(id) {
  try {
    const result = await selectSql(
      'SELECT * FROM users WHERE id = ?',
      [id]
    );
    return result.length > 0 ? result[0] : null;
  } catch (error) {
    console.error('查询失败:', error);
    throw error;
  }
}

3. 更新数据

async function updateUser(id, user) {
  try {
    const result = await executeSql(
      'UPDATE users SET name = ?, email = ?, age = ? WHERE id = ?',
      [user.name, user.email, user.age, id]
    );
    console.log('更新成功，影响行数:', result.rowsAffected);
    return result.rowsAffected;
  } catch (error) {
    console.error('更新失败:', error);
    throw error;
  }
}

4. 删除数据

async function deleteUser(id) {
  try {
    const result = await executeSql(
      'DELETE FROM users WHERE id = ?',
      [id]
    );
    console.log('删除成功，影响行数:', result.rowsAffected);
    return result.rowsAffected;
  } catch (error) {
    console.error('删除失败:', error);
    throw error;
  }
}

五、事务处理

async function transferMoney(fromId, toId, amount) {
  try {
    // 开始事务
    await executeSql('BEGIN TRANSACTION');
    
    // 扣款
    await executeSql(
      'UPDATE accounts SET balance = balance - ? WHERE id = ?',
      [amount, fromId]
    );
    
    // 收款
    await executeSql(
      'UPDATE accounts SET balance = balance + ? WHERE id = ?',
      [amount, toId]
    );
    
    // 提交事务
    await executeSql('COMMIT');
    console.log('转账成功');
  } catch (error) {
    // 回滚事务
    await executeSql('ROLLBACK');
    console.error('转账失败:', error);
    throw error;
  }
}

六、页面中使用示例

<template>
  <view>
    <button @click="addUser">添加用户</button>
    <button @click="getUsers">查询用户</button>
    <view v-for="user in userList" :key="user.id">
      {{ user.name }} - {{ user.email }}
    </view>
  </view>
</template>

<script>
import { insertUser, getAllUsers } from '@/common/sqlite.js';

export default {
  data() {
    return {
      userList: []
    };
  },
  methods: {
    async addUser() {
      const user = {
        name: '张三',
        email: 'zhangsan@example.com',
        age: 25
      };
      try {
        await insertUser(user);
        uni.showToast({ title: '添加成功' });
      } catch (error) {
        uni.showToast({ title: '添加失败', icon: 'none' });
      }
    },
    
    async getUsers() {
      try {
        this.userList = await getAllUsers();
      } catch (error) {
        console.error('查询失败:', error);
      }
    }
  }
};
</script>

七、注意事项

1. ​平台兼容性​: 确保只在App端使用SQLite，H5和小程序端需使用其他存储方案
2. ​数据安全​: 对输入数据进行验证和转义，防止SQL注入攻击
3. ​性能优化​: 批量操作时使用事务，避免频繁打开关闭数据库连接
4. ​错误处理​: 所有数据库操作都应添加try-catch块进行错误处理
5. ​资源释放​: 在应用退出或页面销毁时及时关闭数据库连接

通过以上步骤，你可以在UniApp项目中成功集成SQLite数据库，实现本地数据的持久化存储和高效操作。