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 實例中，相同的資料庫名稱將指向不同的資料庫實例。唯一的例外是資料庫儲存在永久儲存區中，但檔案系統驅動程式可能會禁止同時存取單個資料庫。

在用戶端程式碼中，載入和初始化通常如下所示…

主線程和 Worker 線程安裝

要將完整的 sqlite3 API 載入到與用戶端程式碼相同的線程中，請執行以下操作之一

對於主線程使用，請從 HTML 載入

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

或者從用戶端層級的 Worker 載入

importScripts("sqlite3.js");

如果 `sqlite3.js` 位於用戶端應用程式所在目錄以外的目錄中，請務必閱讀此注意事項。

對於這兩種方法，請使用以下程式碼載入 WASM 檔案並啟動 API

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

`sqlite3InitModule()` 是由Emscripten 安裝的函式，用於載入和初始化模組。它接受一個可選物件作為所謂的 Emscripten 模組，用戶端可以透過它收到載入進度和錯誤的通知。有關完整詳細資訊，請參閱關於此主題的 Emscripten 文件。請注意，此專案對這些選項沒有影響，Emscripten 專案可能隨時更改它們，因此我們既不記錄也不支援它們。另請注意，此專案可能會嘗試在內部覆寫任何特定選項，如果用戶端程式碼也這樣做，可能會導致不希望的副作用。

另請參閱

專用 sqlite3 Worker 安裝（「Worker1」）

如果 sqlite3 應該完全在其自己的 Worker 線程中運行，與所有用戶端層級程式碼分開，Worker1 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 年底，並非所有瀏覽器都支援從 *Worker* 載入 ES6 模組（例如Firefox）。

或者從 HTML script 標籤載入，例如

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

使用「Bundler」工具

發行版 zip 檔案中提供了單獨的檔案，可與 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. ^ 如果您的網路伺服器無法為 .mjs 檔案提供 text/javascript MIME 類型，您可能需要將檔案重新命名為 sqlite3.js