以下示範如何在幾個簡短的步驟內,讓 sqlite3 在瀏覽器中運作1。為了簡潔起見,本教學將示範如何在網頁的主執行緒中載入 sqlite3 JavaScript/WebAssembly (WASM) 模組。從 worker 使用模組只需要多一點點功夫,將在後續的教學中說明,以及如何使用各種持久儲存選項。
在開始之前,請注意以下示範方法的限制
- 此示範使用「原生」JavaScript,無需任何第三方工具。搭配 npm 使用的說明在另一個頁面。
- 資料庫是暫時的 - 重新載入頁面時它們會消失。持久化它們是可行的,但超出本簡短教學的範圍。
- 資料庫大小限制完全取決於瀏覽器和裝置。程式庫沒有可靠的方法來查詢這些限制。
- 強烈建議不要在瀏覽器的主執行緒(也稱為「UI 執行緒」)上執行長時間的操作,因為 JS 程式碼執行時無法渲染 UI。雖然在相對較小的資料庫上執行簡單的資料庫操作應該不會造成可用性問題,但通常建議從 Worker 載入和執行 sqlite3,這樣長時間執行的查詢就不會干擾 UI 渲染。程式庫提供了幾種不同的方法來執行此操作。
步驟 1:建立 HTML
最基本的情況下,我們需要 HTML 框架來載入主要的 sqlite3.js
和使用它的客戶端應用程式。例如:
<!doctype html>
<html lang="en-us">
<head>
<meta charset="utf-8">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Hello, sqlite3</title>
</head>
<body>
<script src="jswasm/sqlite3.js"></script>
<script src="demo-123.js"></script>
</body>
</html>
請參閱 demo-123.html 以取得更豐富的範例。
步驟 2:建立 JS 應用程式
完成 HTML 後,我們需要 JavaScript 應用程式。最基本的部分是載入程式庫的 WASM 編譯形式並初始化其 JavaScript 繫結。這都是透過 sqlite3.js
匯出的例程執行的
window.sqlite3InitModule().then(function(sqlite3){
// The module is now loaded and the sqlite3 namespace
// object was passed to this function.
console.log("sqlite3:", sqlite3);
});
請參閱 demo-123.js 以取得「完整功能」的範例和高階 sqlite3 JS API 的示範。
sqlite3InitModule()
函式是 sqlite3 WASM 模組載入器匯出的唯一全域符號,在任何應用程式中只能呼叫一次。應用程式有責任將 sqlite3
物件儲存在應用程式方便的任何位置。最簡單的情況下
globalThis.sqlite3 = sqlite3;
會將其安裝為全域符號2,但在大多數專案中不建議這樣使用全域範圍。
請注意,在連線速度較慢的情況下,下載 WASM 檔案(由 sqlite3InitModule()
觸發的步驟)可能需要一些時間,在此期間,示範程式碼可能會看起來沒有作用。應用程式可以新增額外的 HTML、CSS 和 JS 部分,以便接收載入狀態的通知,例如,UI 可以顯示「載入中...」動畫或回報任何錯誤。這樣做需要熟悉Emscripten提供的 JS/WASM 框架,並且超出本示範的範圍。在 sqlite3 fiddle 應用程式的底部可以找到一個範例。
步驟 3:Web 伺服器
有了 HTML 和 JS 之後,我們需要一個 Web 伺服器來執行它們。由於安全限制,瀏覽器可能會拒絕從透過 file://
URL 提供的頁面載入 WASM。由於 Web 伺服器很大程度上取決於個人偏好,並且有很多選項可用,因此讓該部分執行不在此討論範圍內。
簡而言之,我們需要以下檔案位於任意 Web 伺服器的同一個目錄中
- demo-123.html
- demo-123.js
sqlite3.js
包含 WASM 模組載入器和 sqlite3 JS API。sqlite3.wasm
是編譯成 WASM 的核心 sqlite3 函式庫。
當網路伺服器啟動並運行後,我們只需要將瀏覽器指向範例檔案的位置即可