Dexie.js

[![NPM 版本][npm-image]][npm-url] 构建状态

Dexie.js 是一个 indexedDB 的封装库 - indexedDB 是浏览器中的标准数据库。https://dexie.org。

为什么选择 Dexie.js？

IndexedDB 是所有浏览器引擎的通用数据库。Dexie.js 让使用它变得有趣且简单。

此外：

Dexie.js 被广泛用于 10 万个网站、应用程序和其他项目，支持所有浏览器、用于桌面应用的 Electron、用于 iOS / Android 应用的 Capacitor，当然还有纯 PWA。
Dexie.js 解决了 IndexedDB 实现中的一些 bug，提供更稳定的用户体验。
它可以轻松实现同步。

Hello World

<!DOCTYPE html>
<html>
  <head>
    <script src="https://unpkg.com/dexie/dist/dexie.js"></script>
    <script>

      //
      // 声明数据库
      //
      const db = new Dexie('FriendDatabase');
      db.version(1).stores({
        friends: '++id, age'
      });

      //
      // 使用示例
      //
      db.friends.add({ name: 'Alice', age: 21 }).then(() => {
        return db.friends
          .where('age')
          .below(30)
          .toArray();
      }).then(youngFriends => {
        alert (`我的年轻朋友：${JSON.stringify(youngFriends)}`);
      }).catch (e => {
        alert(`出错了：${e}`);
      });

    </script>
  </head>
</html>

是的，就是这么简单。阅读文档以了解详情。

Hello World（适用于现代浏览器）

所有现代浏览器都支持 ES 模块和顶级 await。无需转译器。以下是上一个示例的现代版本：

<!DOCTYPE html>
<html>
  <head>
    <script type="module">
      // 导入 Dexie
      import { Dexie } from 'https://unpkg.com/dexie/dist/modern/dexie.mjs';

      //
      // 声明数据库
      //
      const db = new Dexie('FriendDatabase');
      db.version(1).stores({
        friends: '++id, age'
      });

      //
      // 使用示例
      //
      try {
        await db.friends.add({ name: 'Alice', age: 21 });

        const youngFriends = await db.friends
            .where('age')
            .below(30)
            .toArray();

        alert(`我的年轻朋友：${JSON.stringify(youngFriends)}`);
      } catch (e) {
        alert(`出错了：${e}`);
      }
    </script>
  </head>
</html>

Hello World（React + TypeScript）

实际应用通常使用各种框架中的组件构建。以下是为 React 和 TypeScript 编写的 Hello World 版本。在此示例下方还有更多不同框架的教程链接...

import React from 'react';
import { Dexie, type EntityTable } from 'dexie';
import { useLiveQuery } from 'dexie-react-hooks';

// 实体类型定义（建议移到单独的模块中）
export interface Friend {
  id: number;
  name: string;
  age: number;
}

// 数据库声明（也建议移到单独的模块中）
export const db = new Dexie('FriendDatabase') as Dexie & {
  friends: EntityTable<Friend, 'id'>;
};
db.version(1).stores({
  friends: '++id, age',
});

// 组件：
export function MyDexieReactComponent() {
  const youngFriends = useLiveQuery(() =>
    db.friends
      .where('age')
      .below(30)
      .toArray()
  );

  return (
    <>
      <h3>我的年轻朋友</h3>
      <ul>
        {youngFriends?.map((f) => (
          <li key={f.id}>
            姓名：{f.name}，年龄：{f.age}
          </li>
        ))}
      </ul>
      <button
        onClick={() => {
          db.friends.add({ name: 'Alice', age: 21 });
        }}
      >
        添加另一个朋友
      </button>
    </>
  );
}

React、Svelte、Vue、Angular 和原生 JS 的教程

API 参考示例

性能

Dexie拥有出色的性能。它的批量方法利用了IndexedDB中一个鲜为人知的特性，使得在存储数据时无需监听每个onsuccess事件。这将性能提升到最大。

支持的操作

above(key): Collection;
aboveOrEqual(key): Collection;
add(item, key?): Promise;
and(filter: (x) => boolean): Collection;
anyOf(keys[]): Collection;
anyOfIgnoreCase(keys: string[]): Collection;
below(key): Collection;
belowOrEqual(key): Collection;
between(lower, upper, includeLower?, includeUpper?): Collection;
bulkAdd(items: Array): Promise;
bulkDelete(keys: Array): Promise;
bulkPut(items: Array): Promise;
clear(): Promise;
count(): Promise;
delete(key): Promise;
distinct(): Collection;
each(callback: (obj) => any): Promise;
eachKey(callback: (key) => any): Promise;
eachPrimaryKey(callback: (key) => any): Promise;
eachUniqueKey(callback: (key) => any): Promise;
equals(key): Collection;
equalsIgnoreCase(key): Collection;
filter(fn: (obj) => boolean): Collection;
first(): Promise;
get(key): Promise;
inAnyRange(ranges): Collection;
keys(): Promise;
last(): Promise;
limit(n: number): Collection;
modify(changeCallback: (obj: T, ctx:{value: T}) => void): Promise;
modify(changes: { [keyPath: string]: any } ): Promise;
noneOf(keys: Array): Collection;
notEqual(key): Collection;
offset(n: number): Collection;
or(indexOrPrimayKey: string): WhereClause;
orderBy(index: string): Collection;
primaryKeys(): Promise;
put(item: T, key?: Key): Promise;
reverse(): Collection;
sortBy(keyPath: string): Promise;
startsWith(key: string): Collection;
startsWithAnyOf(prefixes: string[]): Collection;
startsWithAnyOfIgnoreCase(prefixes: string[]): Collection;
startsWithIgnoreCase(key: string): Collection;
toArray(): Promise;
toCollection(): Collection;
uniqueKeys(): Promise;
until(filter: (value) => boolean, includeStopEntry?: boolean): Collection;
update(key: Key, changes: { [keyPath: string]: any }): Promise;