TinyBase 入门：使用 ui-svelte 模块构建 Svelte 5 响应式界面

• 数据库
• 后端
• 前端

本篇指南面向希望在 Svelte 项目中引入 TinyBase 的开发者，介绍ui-svelte模块的安装方式、第一个组件的编写方法，以及该模块围绕 Svelte 5 响应式运行时设计的整体思路。读完本文，你将能够在 Svelte 组件中创建 Store、写入数据，并用CellView等视图组件把数据渲染到屏幕上，同时理解响应式句柄（reactive handle）在底层如何工作，以及如何借助官方 demo 快速上手更完整的应用。

准备工作：安装 ui-svelte 模块

要用 Svelte 构建基于 TinyBase 的用户界面，除了 TinyBase 主模块之外，还需要安装ui-svelte模块，当然也离不开 Svelte 本身。在仓库的 package.json 中，Svelte 以^5.57.0作为 peer dependency 列出，因此ui-svelte是面向 Svelte 5 设计的 UI 层模块。

安装好依赖后，TinyBase 主模块和ui-svelte分别通过子路径导入。以当前仓库 src/ui-svelte/index.ts 的导出为例：

import {createStore} from 'tinybase'; import {CellView, Provider} from 'tinybase/ui-svelte';

ui-svelte模块的导出分为三大类，在 src/ui-svelte/index.ts 中可以看到完整清单：

• 视图组件：CellView、RowView、TableView、TablesView、ValueView、ValuesView、MetricView、IndexView、SliceView、SortedTableView、ResultTableView、CheckpointView等，用于声明式地渲染 Store 各层数据；
• 响应式函数：getCell、getRow、getTables、getMetric、getSliceRowIds、getResultTable等，返回带current属性的响应式句柄；
• 监听函数：onCell、onRowIds、onStartTransaction等，用于在数据变化时执行副作用代码。

第一个组件：Hello World 示例

官方入门示例展示了ui-svelte的最小可用形态。在一个 Svelte 组件中，创建 Store、写入一个 Cell，然后用CellView组件把它渲染出来：

<script> import {createStore} from 'tinybase'; import {CellView} from 'tinybase/ui-svelte'; const store = createStore(); store.setCell('t1', 'r1', 'c1', 'Hello World'); </script> <CellView tableId="t1" rowId="r1" cellId="c1" {store} />

当组件渲染时，屏幕上会出现 "Hello World" 字样。整个过程可以拆解为三步：数据被写入 Store、再从 Store 读取、最后由ui-svelte的CellView组件渲染。CellView接收tableId、rowId、cellId三个必选 props，以及可选的store（Store 实例或 Id）和debugIds布尔值，这些都在 src/@types/ui-svelte/index.d.ts 的CellViewProps中定义。

从源码看 CellView 与响应式句柄

CellView的源码非常简洁，它本质上是对getCell响应式函数的封装。src/ui-svelte/CellView.svelte 完整实现如下：

<script lang="ts"> import type {CellViewProps} from '../@types/ui-svelte/index.d.ts'; import {getCell} from './functions.svelte.ts'; let {tableId, rowId, cellId, store, debugIds}: CellViewProps = $props(); const cell = getCell( () => tableId, () => rowId, () => cellId, () => store, ); const display = $derived('' + (cell.current ?? '')); const output = $derived(debugIds ? `${cellId}:{${display}}` : display); </script> {output}

可以看到两个值得注意的实现细节：

• 所有参数都以() => tableId这样的 getter 函数形式传入getCell，这正是为了配合 Svelte 5 的响应式追踪——当 props 变化时，getCell会自动重新读取数据；
• 组件用$derived派生展示文本，debugIds为true时会输出cellId:{value}格式，便于原型调试时定位数据来源。

getCell的底层实现在 src/ui-svelte/functions.svelte.ts 中（第 500-537 行）。它通过$effect配合 Svelte 的createSubscriber注册 TinyBase 的addCellListener监听，并在清理阶段调用delListener注销；返回的WritableHandle同时具备读取与写入能力——读取时调用store.getCell()，写入current时调用store.setCell()。这意味着订阅的注册与清理完全由 Svelte 生命周期自动管理，你无需手写onDestroy清理代码。

所有响应式函数返回的对象都基于 ReactiveHandle 类：每次读取current属性都会触发订阅，从而让模板中任何读取它的位置在 Store 数据变化时自动更新。

查看可运行 demo

仓库中提供了两个与本文直接相关的可运行 demo：

Hello World (Svelte)

Hello World (Svelte) demo 展示了上述模式的完整形态：主入口每秒调用一次store.setCell()写入当前时间，App.svelte用Provider包裹组件树，并通过<CellView tableId="t1" rowId="r1" cellId="c1" />渲染实时值；Provider让后代组件无需逐层传递store。

Hello World (Svelte) demo 运行效果 demo")

浏览器环境运行 demo 时，需要先注册 esm.sh 的 import map，将tinybase、tinybase/ui-svelte、tinybase/ui-svelte-inspector与svelte都映射到对应 CDN 地址。

Countries (Svelte)

Countries (Svelte) demo 是一个更完整的示例，同时用到了 Indexes 与持久化：countryStore通过远程 persister 加载国家数据，starStore把收藏状态存入本地存储，viewStore把当前筛选的 slice 存入会话存储；组件树则通过getSliceIds、getSliceRowIds等响应式函数驱动筛选按钮与国家卡片渲染。它是理解"索引 + 持久化 + Svelte 视图"三者配合的最佳起点。

Countries (Svelte) demo 运行效果 demo")

ui-svelte 的设计哲学：围绕 Svelte 5 的响应式运行时

ui-svelte并非把 React 版的 hooks 思想照搬过来，而是完全围绕Svelte 5 的响应式运行时与组件模型设计：

• 用响应式函数（如getCell）替代 React 风格的 hooks，函数返回带current属性的句柄，配合$effect、createSubscriber与 Svelte 的自动依赖追踪实现 UI 与 Store 的同步；
• 提供视图组件（如CellView、RowView、TableView）直接渲染 Store 数据，支持通过命名 snippet 定制每一层的渲染方式；
• 提供监听函数（如onCell、onStartTransaction）处理日志、埋点、命令式同步等非渲染副作用；
• 提供Provider 组件，通过 Svelte 的 context 机制把 Store、Indexes、Queries 等对象注入组件树，避免逐层传递 props。

关于响应式函数的更多细节（如MaybeGetter<T>参数、bind:value双向绑定、可写current），请继续阅读 Using Reactive Functions 指南；视图组件的声明式用法参见 Using Svelte Components 指南；浏览器场景下的 HTML 表格组件（TableInHtmlTable、SortedTableInHtmlTable等）参见 Using Svelte DOM Components 指南；Provider上下文与多对象注入参见 Using Context 指南。

• 数据库
• 后端
• 前端