+

Dexie v3.2 and later comes with reactivity built-in.
Dexie v3.2 及更高版本内置了响应式功能。

In version 3.2 we’ve introduced live queries - queries that observe the result and make your component mirror the data in real time. If a change is made (by the app itself or from an external tab or worker), a binary range tree algorithm will efficiently detect whether those changes would affect your queries and if so, re-execute your callback and re-render component. Here’s a simple ToDo app example that demonstrates it.
在 3.2 版本中，我们引入了实时查询功能——这些查询能够观察结果，并使您的组件实时反映数据变化。如果数据发生更改（无论是由应用本身还是从外部标签页或工作线程进行的），二叉范围树算法将高效地检测这些更改是否会影响您的查询，如果影响，则重新执行回调函数并重新渲染组件。以下是一个简单的待办事项应用示例，展示了这一功能。

useLiveQuery() can be explained like this: It observes the result of a promise-returning function that queries Dexie (In contrast to just execute it imperatively). It is highly composable as you can call other functions that queries dexie and compute a result based on their outcome. Maybe you already have some functions you wrote long time ago. Calling them from within the scope of the callback passed to useLiveQuery() will turn your imperative async functions into an observable query.
useLiveQuery() 可以这样解释：它观察一个返回承诺的函数查询 Dexie 的结果（与仅仅命令式地执行它相反）。由于你可以调用其他查询 Dexie 的函数并基于它们的结果进行计算，因此它具有高度的可组合性。或许你早已编写了一些函数。在传递给 useLiveQuery() 的回调函数作用域内调用这些函数，就能将你的命令式异步函数转变为可观察的查询。

1. Create a React project
1. 创建一个 React 项目

Here we refer to React’s own Getting Started page.
这里我们参考 React 官方的入门页面。

For the impatient one, use CodeSandbox to create a React app and start code editing in your browser.
对于急于上手的人，可以使用 CodeSandbox 创建一个 React 应用，并在浏览器中开始代码编辑。

2. Install dependencies  2. 安装依赖项

yarn  纱线

yarn add dexie
yarn add dexie-react-hooks

npm

npm install dexie
npm install dexie-react-hooks

CodeSandbox  代码沙盒

3. Create a file db.js (or db.ts)
3. 创建一个文件 db.js （或 db.ts ）

Applications typically have one single Dexie instance declared as its own module. This is where you declare which tables you need and how each table shall be indexed. A Dexie instance is a singleton throughout the application - you do not need to create it on demand. Export the resulting db instance from your module so that components or other modules can use it to query or write to the database.
应用程序通常会声明一个单一的 Dexie 实例作为其自身的模块。在这里，您声明所需的数据表以及每个表的索引方式。Dexie 实例在整个应用程序中是单例的——您无需按需创建它。将生成的 db 实例从模块中导出，以便组件或其他模块可以使用它来查询或写入数据库。

// db.js
import Dexie from 'dexie';

export const db = new Dexie('myDatabase');
db.version(1).stores({
  friends: '++id, name, age' // Primary key and indexed props
});

Using Typescript?  使用 TypeScript？

If you use Typescript, table properties (such as db.friends) needs to be explicitly declared on a subclass of Dexie just to help out with the typings for your db instance, its tables and entity models.
如果你使用 TypeScript，表属性（如 db.friends ）需要在 Dexie 的子类上显式声明，以便为你的数据库实例、表和实体模型提供类型支持。

// db.ts
import Dexie, { type EntityTable } from 'dexie';

interface Friend {
  id: number;
  name: string;
  age: number;
}

const db = new Dexie('FriendsDatabase') as Dexie & {
  friends: EntityTable<
    Friend,
    'id' // primary key "id" (for the typings only)
  >;
};

// Schema declaration:
db.version(1).stores({
  friends: '++id, name, age' // primary key "id" (for the runtime!)
});

export type { Friend };
export { db };

4. Create a component that adds some data

Writing to the database can be done using Table.add(), Table.put(), Table.update() and Collection.modify() - see Dexie’s quick reference for examples. Here we’re gonna create a simple React component that allows the user to add friends into the database using Table.add().

export function AddFriendForm({ defaultAge } = { defaultAge: 21 }) {
  const [name, setName] = useState('');
  const [age, setAge] = useState(defaultAge);
  const [status, setStatus] = useState('');

  async function addFriend() {
    try {
      // Add the new friend!
      const id = await db.friends.add({
        name,
        age
      });

      setStatus(`Friend ${name} successfully added. Got id ${id}`);
      setName('');
      setAge(defaultAge);
    } catch (error) {
      setStatus(`Failed to add ${name}: ${error}`);
    }
  }

  return (
    <>
      <p>{status}</p>
      Name:
      <input
        type="text"
        value={name}
        onChange={(ev) => setName(ev.target.value)}
      />
      Age:
      <input
        type="number"
        value={age}
        onChange={(ev) => setAge(Number(ev.target.value))}
      />
      <button onClick={addFriend}>Add</button>
    </>
  );
}

5. Create a component that queries data

Write a simple component that just renders all friends in the database.

export function FriendList() {
  const friends = useLiveQuery(() => db.friends.toArray());

  return (
    <ul>
      {friends?.map((friend) => (
        <li key={friend.id}>
          {friend.name}, {friend.age}
        </li>
      ))}
    </ul>
  );
}

To make more detailed queries, refer to Dexie’s quick reference for querying items.

Notice two things here:

1. The function passed to useLiveQuery() queries dexie for all friends.
2. The result will be undefined momentarily before the very initial result arrives - which explains why we refer it as friends? rather than friends.

6. Pass some query params

Let’s improve the FriendList component and allow a parent component to pass some props that we use from within the query. This time let’s also use async / await (for pedagogical reasons only - it makes it simple to extend the function to do more queries if needed).

export function FriendList({ minAge, maxAge }) {
  const friends = useLiveQuery(
    async () => {
      //
      // Query Dexie's API
      //
      const friends = await db.friends
        .where('age')
        .between(minAge, maxAge)
        .toArray();

      // Return result
      return friends;
    },
    // specify vars that affect query:
    [minAge, maxAge]
  );

  return (
    <ul>
      {friends?.map((friend) => (
        <li key={friend.id}>
          {friend.name}, {friend.age}
        </li>
      ))}
    </ul>
  );
}

Notice two things in the above example:

1. We pass two arguments to useLiveQuery(): the async function and the deps. The callback is just a plain async function that can compute any type of result based on what it queries. It can use Promise.all() to query things in parallel or query things sequentially after each other. Any Dexie-call along the way will be marked for observation. In any case the end result will become observed.
2. Deps are needed when the querying function uses closures that affect the query. In this case the minAge and maxAge parameters. A parent component may pass new values for it and that needs to be detected and make our query reexecuted.

7. Put it together

export const App = () => (
  <>
    <h1>My simple Dexie app</h1>

    <h2>Add Friend</h2>
    <AddFriendForm defaultAge={21} />

    <h2>Friend List</h2>
    <FriendList minAge={18} maxAge={65} />
  </>
);

When running this example, notice that adding friends within the given age range will make them show up instantly in your view.

Things to play with

Test out how to edit query parameters and watch the live results update, or open up app in several windows and see them instantly reflect the changes from the other window…

Make query parameters editable

Add a new component that allows the user to specify minAge and maxAge and pass those into the props to <FriendList>. You will notice that updating the props will also be instantly reflected in the query results of your app.

Run app in multiple windows

Open your app (or for example this one) in multiple new windows and watch them react to each other’s changes.

NOTE: IndexedDB is tied to using same browser and same origin. Sync across different origins, browsers, clients and users is another topic and requires a sync solution. If you’re interested, have a look at what’s coming in Dexie Cloud.

Observe joined data

Do something similar to this sample and observe the result of a function similar to getBandsStartingWithA() (a function that compose a result from multiple related queries). Notice that any change that affects any of the queries will make the component rerender, including the related data.

More Samples and Resources

• A simple ToDo list (Stackblitz)
• Read the docs for useLiveQuery()
• Read the general docs for Dexie.js.