数据模型

相关源文件

• package.json
• packages/app-cli/package.json
• packages/app-desktop/gui/EmojiBox.tsx
• packages/app-desktop/gui/FolderIconBox.tsx
• packages/app-desktop/package.json
• packages/app-desktop/tsconfig.json
• packages/app-mobile/components/Checkbox.tsx
• packages/app-mobile/components/NoteItem.tsx
• packages/app-mobile/components/NoteList.tsx
• packages/app-mobile/components/ScreenHeader/WarningBanner.test.tsx
• packages/app-mobile/components/ScreenHeader/WarningBanner.tsx
• packages/app-mobile/components/buttons/MultiTouchableOpacity.tsx
• packages/app-mobile/package.json
• packages/app-mobile/utils/hooks/useOnLongPressProps.ts
• packages/editor/package.json
• packages/fork-htmlparser2/package.json
• packages/lib/ArrayUtils.test.js
• packages/lib/ArrayUtils.ts
• packages/lib/BaseModel.ts
• packages/lib/JoplinDatabase.ts
• packages/lib/JoplinServerApi.ts
• packages/lib/SyncTargetJoplinCloud.ts
• packages/lib/SyncTargetJoplinServer.ts
• packages/lib/Synchronizer.ts
• packages/lib/WebDavApi.js
• packages/lib/components/shared/config/shouldShowMissingPasswordWarning.test.ts
• packages/lib/database.ts
• packages/lib/file-api-driver-joplinServer.ts
• packages/lib/file-api.ts
• packages/lib/geolocation-node.ts
• packages/lib/models/BaseItem.test.ts
• packages/lib/models/BaseItem.ts
• packages/lib/models/Folder.sharing.test.ts
• packages/lib/models/Folder.test.ts
• packages/lib/models/Folder.ts
• packages/lib/models/Note.test.ts
• packages/lib/models/Note.ts
• packages/lib/models/Note_CustomSortOrder.test.js
• packages/lib/models/Resource.ts
• packages/lib/models/utils/itemCanBeEncrypted.ts
• packages/lib/models/utils/paginationToSql.ts
• packages/lib/models/utils/types.ts
• packages/lib/package.json
• packages/lib/registry.ts
• packages/lib/services/database/types.ts
• packages/lib/services/share/ShareService.test.ts
• packages/lib/services/share/ShareService.ts
• packages/lib/services/synchronizer/ItemUploader.ts
• packages/pdf-viewer/package.json
• packages/plugin-repo-cli/package.json
• packages/renderer/package.json
• packages/server/package.json
• packages/tools/generate-database-types.ts
• packages/tools/package.json
• packages/tools/release-server.ts
• yarn.lock

本文档描述了构成 Joplin 应用程序基础的核心数据模型。它涵盖了模型层级、属性、关系以及这些模型如何在设备之间持久化和同步。有关设置管理的信息，请参阅设置管理，有关同步过程的详细信息，请参阅同步引擎。

模型层级结构

Joplin 使用分层模型结构，其中包含多个基类，这些基类为更具体的模型提供通用功能。

来源：packages/lib/BaseModel.ts58-101 packages/lib/models/BaseItem.ts48-56 packages/lib/models/Note.ts46-54 packages/lib/models/Folder.ts29-32 packages/lib/models/Resource.ts40-50

核心数据模型

BaseModel

BaseModel 是 Joplin 中所有模型的基类。它提供了与数据库交互的通用功能，包括 CRUD 操作。

主要功能

• 不同模型类型的类型常量
• 基本加载/保存/删除操作
• 通过数据库接口进行查询操作
• 事件分发

来源：packages/lib/BaseModel.ts58-101

BaseItem

BaseItem 扩展了 BaseModel，并增加了同步和加密功能。它是所有面向用户的模型的基类。

主要属性

• id：唯一标识该项目的 UUID
• created_time：创建时间戳（由系统设置）
• updated_time：最后更新时间戳（由系统设置）
• user_created_time：面向用户的创建时间戳
• user_updated_time：面向用户的更新时间戳
• encryption_applied：指示项目是否已加密的标志
• share_id：如果项目已共享，则为共享的 ID
• is_shared：指示项目是否已共享的标志

来源：packages/lib/models/BaseItem.ts48-56

注意

Note 模型代表用户笔记或待办事项。

主要属性

• title：笔记标题
• body：笔记内容（Markdown 格式）
• parent_id：包含该笔记的文件夹 ID
• is_todo：指示该笔记是否为待办事项的标志
• todo_completed：待办事项完成的时间戳
• todo_due：待办事项的到期日期
• latitude、longitude、altitude：地理位置数据
• markup_language：笔记使用的标记语言

关键方法

• linkedItemIds()：提取链接资源或笔记的 ID
• linkedItems()：加载链接的项目（资源、笔记）
• sortNotes()：按各种标准对笔记进行排序

来源：packages/lib/models/Note.ts46-380

文件夹

Folder 模型代表包含笔记和其他文件夹（用于嵌套）的容器。

主要属性

• title：文件夹名称
• parent_id：父文件夹的 ID（用于嵌套文件夹）

关键方法

• notes()：获取文件夹中的所有笔记
• noteIds()：获取文件夹中所有笔记的 ID
• subFolderIds()：获取所有子文件夹的 ID
• noteCount()：获取文件夹中笔记的数量
• allChildrenFolders()：获取所有嵌套的子文件夹

来源：packages/lib/models/Folder.ts29-371

资源

Resource 模型代表附件，如图片或文件。

主要属性

• title：资源名称
• mime：MIME 类型
• filename：原始文件名
• file_extension：文件扩展名
• size：文件大小（字节）

关键方法

• fullPath()：获取资源文件的完整路径
• localState()：获取资源本地状态的信息
• needToBeFetched()：确定是否需要下载该资源

来源：packages/lib/models/Resource.ts40-550

标签

Tag 模型代表可附加到笔记上的标签。

主要属性

• title：标签名称

关键方法

• setNoteTagsByIds()：按 ID 设置笔记的标签
• addNote()：将标签添加到笔记
• removeNote()：从笔记中移除标签

模型关系

来源：packages/lib/JoplinDatabase.ts11-147 packages/lib/models/Folder.ts29-371 packages/lib/models/Note.ts46-380 packages/lib/models/Resource.ts40-550

数据库 Schema

模型存储在 SQLite 数据库中，具有以下核心表

表格	描述	关键字段
folders	存储文件夹数据	id, title, parent_id, created_time, updated_time
notes	存储笔记数据	id, title, body, parent_id, is_todo, todo_due, todo_completed
resources	存储资源元数据	id, title, mime, filename, file_extension, size
tags	存储标签数据	id, title
note_tags	链接笔记和标签的连接表	id, note_id, tag_id
item_changes	跟踪更改以进行同步	id, item_id, item_type, type
sync_items	存储同步状态	id, sync_target, sync_time, item_id, item_type

存在用于加密、共享和其他专门功能的附加表。

来源：packages/lib/JoplinDatabase.ts11-147

模型类型系统

Joplin 使用类型枚举系统来标识不同的模型类型。这在 BaseModel 中定义。

来源： packages/lib/BaseModel.ts12-29

数据存储和资源管理

与其他模型相比，资源（附件）的生命周期更复杂，因为它涉及实际文件。Resource 模型同时管理数据库中的元数据和磁盘上的相应文件。

关键资源操作

• 资源数据存储在 resourceDir 目录中
• 资源元数据存储在 resources 表中
• 资源具有用于跟踪下载进度的获取状态
• 维护本地状态以跟踪资源是否已完全下载

来源：packages/lib/models/Resource.ts40-550

同步支持

所有 BaseItem 模型都支持同步，通过

1. 使用 item_changes 表跟踪更改
2. 在 sync_items 表中维护同步状态
3. 支持加密以实现安全同步
4. 处理冲突解决

在同步期间，updated_time 字段对于确定哪个项目版本更新至关重要。

来源： packages/lib/models/BaseItem.ts48-56 packages/lib/Synchronizer.ts57-61

共享系统

Joplin 实现了一个共享系统，允许将文件夹及其内容与其它用户共享

• share_id 属性将项目链接到共享容器
• is_shared 标志指示项目是否已个人共享
• 当文件夹被共享时，其所有子项目将继承相同的 share_id
• ShareService 管理共享操作

来源： packages/lib/services/share/ShareService.ts35-50 packages/lib/models/Folder.ts170-243

模型创建和更新

创建或更新模型时，系统会

1. 验证输入数据
2. 应用任何必要的转换
3. 更新时间戳（系统和用户可见的）
4. 生成 UI 更新事件
5. 创建更改记录以供同步

例如，在创建笔记时

Note.save({ title: 'New note', body: 'Content', parent_id: 'folderId' })

这将创建一个新笔记，应用默认值，生成 ID，设置时间戳，并通知系统有关更改。

来源： packages/lib/models/Note.ts269-279 packages/lib/BaseModel.ts465-509