← 返回SQLite 数据库组件参考 · 全部使用指导

SQLite 数据库使用指导

• SQLite 数据库使用指导
  • 快速上手：本地记事本
  • 搭建与测试
  • 案例：异步读取记事本
  • 属性、方法与事件速查
  • 常见问题与验收
  • 鸿蒙连接与备份时序
  • 完整 .aia 源码与操作指导
    • 设备采集记录数据库
  • 按这个顺序验证闭环
    • 工程内素材

不可见组件，内置的迷你本地数据库引擎：兼容主流 SQL 语法，支持事务与异步执行。 现已内置到设计器的「数据存储」分类，无需再导入拓展；积木方法名与原拓展一致， 更详尽的历史图文说明保留在原拓展文档。

快速上手：本地记事本

界面：拖入 文本输入框1、按钮1（文字改为「添加」）、列表显示框1，以及一个 SQLite（默认名 SQLite1）、计时器1（关闭默认启用）和 标签_状态。

代码块：屏幕打开时建表并显示已有记录；点「添加」写入一条并刷新。

各案例独立使用；组合到同一屏幕时，将同名事件的处理合并到一个事件积木中。

global 等待次数 = 0

when Screen1.Initialize() {
  计时器1.TimerEnabled = false
  计时器1.TimerInterval = 200
  SQLite1.OpenDatabase()
  计时器1.TimerEnabled = true
}

when 计时器1.Timer() {
  等待次数 = 等待次数 + 1
  if SQLite1.IsDatabaseOpen() {
    计时器1.TimerEnabled = false
    var 建表成功 = SQLite1.Execute("CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY AUTOINCREMENT, content TEXT)", list())
    if 建表成功 { 刷新列表() }
    else { 标签_状态.Text = "建表失败，请查看SQL错误。" }
  } else if 等待次数 >= 30 {
    计时器1.TimerEnabled = false
    标签_状态.Text = "数据库尚未打开，请检查SQL错误后重新打开。"
  }
}

when 按钮1.Click() {
  if SQLite1.IsDatabaseOpen() and trim(文本输入框1.Text) != "" {
    var 行编号 = SQLite1.Insert("notes", list("content"), list(文本输入框1.Text))
    if 行编号 >= 0 { 文本输入框1.Text = "" 刷新列表() }
  } else { 标签_状态.Text = "先等待数据库打开，并输入内容。" }
}

when SQLite1.SQLError(消息) { 标签_状态.Text = 消息 }

procedure 刷新列表() {
  列表显示框1.Elements = SQLite1.SelectSQL("SELECT content FROM notes ORDER BY id DESC", list())
}

运行效果：输入文字点「添加」，最新一条出现在列表顶部；退出应用再打开，记录仍在。

要点：

• 必须先打开数据库（OpenDatabase），并用 IsDatabaseOpen() 确认已打开再执行 SQL。鸿蒙系统打开是异步过程，不能在调用后立即假定已就绪；上述计时器等待真实状态，不制造完成事件。未打开时执行返回假，并可能触发SQL错误。
• 插入（表名，列列表，值）（Insert）的第 3 个参数是一行的值（与列名一一对应的扁平列表），不要再套一层列表。
• SQL查询（SQL语句，绑定参数）（SelectSQL）返回「行的列表」：只查一列时每行直接就是该列的值（上例可直接设给列表显示框）； 查多列时每行是一个列表，按列序号取值（行[1] 为第一列）。
• 数据量大时改用带「异步」的版本（如 异步SQL查询（标签，SQL语句，绑定参数）（SelectSQLAsync）），结果在对应的「完成时」事件里拿，避免卡界面。

搭建与测试

在设计器拖入本组件和案例涉及的按钮、标签、布局等组件，按案例中的名称重命名。先运行最小案例，确认事件返回，再增加业务逻辑。示例中的素材先上传到项目，服务器地址、令牌、文件路径换成自己的值。

可见组件需要有非零宽高；不可见工具组件必须由属性或方法启动。设计器展示样式不等于运行时已加载数据或绑定目标。联机测试应使用包含本组件的 AI 伴侣；涉及系统入口或权限的行为还要编译安装后验证。

案例：异步读取记事本

在最小记事本案例初始化并建表之后，增加一个查询按钮。绑定参数使用列表，查询结果在 AfterSelect 中读取。

when 按钮_查询.Click() {
  SQLite1.SelectSQLAsync("notes", "SELECT content FROM notes ORDER BY id DESC", list())
}
when SQLite1.AfterSelect(标签, 行数, 行数据) {
  if 标签 == "notes" {
    列表显示框1.Elements = 行数据
  }
}
when SQLite1.SQLError(消息) {
  标签1.Text = 消息
}

先打开数据库再查询；数据库名变化会打开另一个文件。正式业务 SQL 使用绑定参数，不把输入框内容拼进 SQL。

属性、方法与事件速查

完整参数类型、默认值和平台说明见组件参考。下表按调用入口列出用途；有完成事件的方法在事件中读取结果。

常见问题与验收

鸿蒙连接与备份时序

• 先设置数据库名和版本，再打开。组件不在构造阶段偷偷打开默认库。切换名称会释放旧连接；先确认关闭完成，再打开新库。
• 鸿蒙系统关闭也是异步操作。关闭后立即导入、导出可能返回假并提示仍在关闭；稍后重试，只有返回真才表示复制已完成。不把 IsDatabaseOpen() 为假理解成系统文件已经释放。
• 删除数据库会等待当前打开或关闭请求结束后执行；期间拒绝重新打开。删除后通过数据库是否存在确认结果，未出现“删除完成”事件。
• //setup.sql 等素材名在伴侣由实际素材解析器读取，独立HAP从打包的 rawfile/assets 读取。SQL文件每行一条语句；CSV首行列名，不支持完整CSV引号转义语法。

鸿蒙API18及以上按实际列类型返回数字与文本，中文名称和文本编号“001”不会转成0或丢掉前导零。更旧系统没有同步列类型接口时保留字符串；用于计算时先检查并转换数字。

完整 .aia 源码与操作指导

下载 .aia 源码

采集设备温度与电量的本地数据库应用，涵盖全部数据库接口。自带SQL／CSV素材，保存与恢复均操作本案例独立库；先等待实际连接就绪，再显示记录，不用固定延时猜建表完成。

导入 SQLiteAllFeatures.aia，连接最新伴侣，或编译独立安装包。真机／伴侣运行尚未实测。

所有返回值均用于界面反馈，错误由底部错误区展示。设计器采用明确非默认配置，初始化与界面同步。API 覆盖检查按最终 AIA 检查方法、事件、属性读取与设置及设计器配置，不能替代真实设备验证。

设备采集记录数据库

导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 采集设备温度与电量的本地数据库应用，涵盖全部数据库接口。自带SQL／CSV素材，保存与恢复均操作本案例独立库；先等待实际连接就绪，再显示记录，不用固定延时猜建表完成。 覆盖检查 38/38。首次载入及保存重开均0个错误，真实后台导入、安装包编译通过；真机／伴侣／硬件联调尚未实测。全部属性读写、方法与事件的操作入口和预期结果见组件指导。

按这个顺序验证闭环

1. 第一次运行等待上方“已打开”为真，列表应显示温度计001与电量计001；关闭／重新打开后记录保留。
2. 名称填“设备’001”、数值23.5，点击插入。使用参数绑定，名称中的单引号也能保存。新增行的实际编号自动填入编号框；修改数值后更新、查询，再删除该编号。
3. 关闭返回列名后只显示值列表；勾选后每列显示列名和值。分别执行同步、异步查询，检查真实完成事件参数。
4. 提交事务后新记录存在；回滚事务后按插入时ID查询为空。不要把拿到行ID理解为事务已经提交。
5. SQL素材成功数应为2；CSV插入行数2。重复测试只清理该素材的101、102，再插入，其他记录保留。文件每行一条SQL；CSV是简单逗号分隔，不支持引号包裹逗号。
6. 关闭，稍后导出，只有返回真才继续。重新打开插入一个“备份后新增”记录，关闭后导入备份（返回真），再打开，该新增记录应消失，备份时的记录恢复。尚在关闭时返回假属于保护，重试前看错误区；缺失备份返回假。
7. 当前设计器版本2。关闭、改版本3、应用配置、稍后打开；只有真实升级事件才显示2→3。首次创建事件只在新库首次产生。工程拒绝降级，并用独立微数据库保存已应用版本，重启仍按该版本打开，不退回设计器版本2。
8. 测完可勾选永久删除确认，仅删除本案例库；稍后读取不存在，再重新打开。备份留在应用私有目录，不会被删除按钮移除。

工程内素材

• setup.sql：可重复的建表与编号100示例。
• readings.csv：编号101、102，两条真实CSV样本。

安卓与鸿蒙使用相同SQL、参数与素材；鸿蒙系统连接／关闭是异步过程，工程以真实状态和返回值判断。数据库、备份路径来自组件与文件管理器的实际应用私有目录，未填写共享存储固定路径。