JavaScript API 索引

JS API 的 API 文档嵌入在其 JS 文件中。这些页面中的文档在很大程度上是对这些文档的扩展和重新格式化的版本。

但是，在使用这些 API 之一之前，有必要加载和初始化库，这将在本文档的第 2 节 中介绍。

API 稳定性

另请参阅：客户端破坏性 API 更改

加载和初始化 API

sqlite3 JS API 由许多文件组成，其中许多文件通过构建时自动化进行捆绑，组装成 WASM 支持的浏览器可用的形式。这种构建通常是一对名为 sqlite3.js 和 sqlite3.wasm 的文件，但几个名为 sqlite3-<something>.js 的独立文件是特定用例所必需的。sqlite3.js 不仅包含主要 API，还包含加载 WASM 文件并将其插入环境所需的“粘合剂”。

只有加载 sqlite3.js（或等效文件）的 JS 线程才能直接使用该 API。每个加载它的线程都有它自己的独立的 WASM 运行时实例，它们之间不共享任何状态。因此，sqlite3.js 通常只从应用程序选择的任何线程加载一次。正因为如此，并且由于每个 JS 运行时实例都是单线程的，因此在 JS 环境中无法多线程使用单个数据库句柄。同样，由于每个 WASM 运行时实例都有自己的虚拟（模拟）文件系统，因此任何两个 WASM 实例中的相同数据库名称将引用不同的数据库实例。例外情况是，如果数据库存储在持久性存储 中，但对单个数据库的并发访问可能会被文件系统驱动程序禁止。

在客户端代码中，加载和初始化通常看起来像以下几种情况之一...

主线程和工作线程安装

要将完整的 sqlite3 API 加载到与客户端代码相同的线程中，请执行以下操作之一

对于主线程使用，请从 HTML 加载

<script src="sqlite3.js"></script>

或从客户端级别的工作线程加载

importScripts("sqlite3.js");

如果 sqlite3.js 位于客户端应用程序所在的目录之外，请务必阅读此注意事项。

对于这两种方法，请加载 WASM 文件并使用以下方法激活 API

self.sqlite3InitModule().then((sqlite3)=>{
  ... do something with sqlite3 ...
});

sqlite3InitModule() 是由Emscripten 安装的函数，用于加载和初始化模块。它接受一个可选对象作为所谓的 Emscripten 模块，客户端可以使用它来通知加载进度和错误。有关完整详细信息，请参阅有关该主题的 Emscripten 文档。请注意，该项目对这些选项没有任何影响，Emscripten 项目可能会随时更改它们，因此我们既不记录也不支持它们。此外，请注意，该项目可能会尝试在内部覆盖任何特定选项，如果客户端代码也这样做，可能会导致意外的副作用。

另请参阅

专用 sqlite3 工作线程安装（“工作线程 1”）

如果 sqlite3 应完全在其自己的工作线程中运行，与所有客户端级别代码分离，则工作线程 1 API 及其Promise 风格代理 提供开箱即用的功能。

从 ES6 模块加载

sqlite3.js 的规范构建包括 sqlite3.mjs，mjs 是 ES6 模块的首选文件扩展名1。该模块仅导出一个符号：一个函数，它加载关联的 WASM 文件并初始化库（与上面为主线程使用演示的相同函数）。它可以使用类似以下内容从 ES6 模块加载

import {default as sqlite3InitModule} from "./jswasm/sqlite3.mjs";
sqlite3InitModule().then((sqlite3)=>{
  console.log("Loaded sqlite3",sqlite3.version);
});

需要注意的是，截至 2022 年底，并非所有浏览器都支持从工作线程加载 ES6 模块（例如 Firefox）。

或从 HTML 脚本标签加载，例如

<script type="module">
  // same code as above
</script>

使用“捆绑器”工具

发行版压缩包中提供了单独的文件，用于与 JavaScript “捆绑器”工具一起使用，这些工具通常在基于 node.js 的构建环境中使用，同时也要承认我们不使用此类工具，因此按原样发布这些构建，不保证它们能与任何给定的捆绑器一起使用。在这样的环境中，jswasm/*-bundler-friendly.*js 应该替换没有 bundler-friendly 后缀的类似名称的文件。

具体来说

有些文件没有这种变体，在这种情况下，它们可以直接与捆绑器一起使用（例如 sqlite3-opfs-async-proxy.js）。

捆绑器特定构建对于将可配置字符串替换为字符串文字是必要的，以满足捆绑器的静态分析要求。

sqlite3 命名空间

当 sqlite3 模块初始化时，它会创建一个所谓的命名空间对象，其中包含其各种 API。在 JS 表示法中，它看起来像

{
  /* The namespace for the C-style APIs. */
  capi: {...},
  /* WASM-specific utilities, abstracted to be independent of,
     and configurable for use with, arbitrary WASM runtime
     environments. */
  wasm: {...},
  /* Exception class used primarily by the oo1 API. */
  SQLite3Error: ...,
  /* Exception class for reporting WASM-side allocation errors. */
  WasmAllocError: ...,
  /* The OO API #1. */
  oo1: {...},
  /* Utility code for creating virtual table implementations. */
  vtab: {...},
  /* Utility code for creating sqlite3_vfs's. */
  vfs: {...},
  /* The options with which the API was configured. Whether or not
     modifying them after the bootstrapping process will have any
     useful effect is unspecified and may change with any given
     version. Clients must not rely on that capability. */
  config: {...},
  /* The library reserves this property for client-side use and
     promises to never define a property with this name nor to
     ever rely on specific contents of it. It makes no such
     guarantees for other properties. */
  client: undefined
}

该对象中未列出的任何成员不属于公共 API，可能会随时更改或删除。

虽然命名空间对象在技术上是无名的，并且不会被包含的 API 安装到任何范围内，但客户端级别代码通常将其分配给 sqlite3 的名称，这些文档假设它使用该名称。是否保留该符号的范围局部或使其成为全局的，取决于客户端。

  1. ^ 如果您的 Web 服务器无法为 .mjs 文件提供 text/javascript 媒体类型，您可能需要将文件名重命名为 sqlite3.js