Tolaria Properties 属性系统完全指南：Frontmatter 结构化字段的创建、编辑与引用

Tolaria Properties 属性系统完全指南：Frontmatter 结构化字段的创建、编辑与引用

【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria

Properties（属性）是 Tolaria 中一类特殊的 Markdown frontmatter 字段：它们以 YAML 键值对形式存储在笔记头部，同时被编辑器、笔记列表、过滤器与表达式引擎统一识别与操作。本文以site/concepts/properties.md为主线，结合仓库中的 ADR 决策记录与源码实现，系统讲解建议属性（Suggested Properties）、下划线系统属性（System Properties）、属性编辑流程，以及如何在 HTML 块与表格公式中引用属性，帮助你充分利用 Tolaria 的“约定优于配置”数据模型。

什么是 Properties：一个字段、三处生效

在 Tolaria 中，Properties 就是笔记 frontmatter 中可被应用显示、过滤和编辑的字段。例如：

--- type: Project status: Active url: https://example.com date: 2026-09-01 ---

这个定义决定了三件事：

1. 显示：属性会出现在右侧 Properties 面板、笔记列表的 chips 或列中；
2. 过滤：Saved View（保存视图）可以把属性作为过滤条件（详见 site/reference/view-filters.md）；
3. 编辑：Properties 面板为不同属性提供类型匹配的编辑控件（日期选择器、下拉、文本输入等）。

从源码结构看，属性系统在渲染层有清晰的数据模型支撑。src/types.ts 定义了属性值的类型：

export type VaultPropertyScalar = string | number | boolean | null export type VaultPropertyArray = Array<string | number | boolean> export type VaultPropertyValue = VaultPropertyScalar | VaultPropertyArray

即属性值既可以是标量（字符串、数字、布尔、null），也可以是标量组成的数组；每个VaultEntry通过properties: Record<string, VaultPropertyValue>（src/types.ts）持有全部自定义属性。Tolaria 不强制 schema——它采用约定而非必需字段的模型，这一点在 site/reference/frontmatter-fields.md 中有完整字段总表。

建议属性（Suggested Properties）：一键补齐常用字段

“建议属性”是 Tolaria 知道如何快速创建的字段。当某条笔记缺少某个建议属性时，Properties 面板会显示一个快捷入口（shortcut），点击即可用正确的编辑器添加该字段——例如date会得到日期选择器，status会得到状态下拉。

site/concepts/properties.md给出了四个内置建议属性：

源码可以印证这一列表。在 src/components/DynamicPropertiesPanel.tsx 中，SUGGESTED_PROPERTIES与实际渲染的显示模式一一对应：

const SUGGESTED_PROPERTIES = [ { key: 'Status', label: 'Status' }, { key: 'date', label: 'Date' }, { key: 'URL', label: 'URL' }, { key: 'icon', label: 'Icon' }, ] as const const SUGGESTED_PROPERTY_MODES: Record<string, PropertyDisplayMode> = { Status: 'status', date: 'date', URL: 'url', icon: 'text', }

面板通过getSuggestedDisplayMode（src/components/DynamicPropertiesPanel.tsx）为建议属性选择渲染模式，SuggestedPropertySlot组件则渲染“点击即添加”的入口，其onAdd回调完成属性写入。此外type字段缺失时，面板还会借助resolveMissingTypeName（src/components/DynamicPropertiesPanel.tsx）对比可用类型列表，提示为笔记补上类型。

需要说明的是：这里的type是 Tolaria 的规范化字段。根据 docs/adr/0025-type-field-canonical.md，早期版本使用Is A:这种自然语言命名，因解析不便且不符合 AI 智能体对标准 YAML 约定的预期，改为以type:作为主字段，Is A:仅作为兼容旧库的别名回退读取，新笔记一律写入type:。

系统属性（System Properties）：_前缀约定

所有以_开头的 frontmatter 字段都是系统属性。它们仍然以纯文本形式保存在 YAML 中（保持文件可读、可被 git 追踪），但会从常规属性编辑中隐藏，不会出现在普通属性面板的编辑行里，也不会暴露给搜索与过滤器。

site/concepts/properties.md列举的典型系统属性包括_icon、_color、_order、_sidebar_label、_width、_pinned_properties、_list_properties_display，它们既可能出现在类型文档（type documents）上，也可能出现在普通笔记上。其中：

• _pinned_properties（类型文档使用）：决定哪些字段出现在编辑器的 inline bar（内联栏）中；
• _list_properties_display（类型文档使用）：决定哪些字段以 chips 或列的形式出现在笔记列表行中。

这一约定来自 docs/adr/0008-underscore-system-properties.md：随着 pinned properties、类型图标、颜色、侧边栏标签、排序等特性不断把配置写进 frontmatter，属性面板开始被用户本不该编辑的内部字段挤占，因此需要一套约定区分“用户可见属性”与“系统内部属性”。决策结果是：

任何以_开头的 frontmatter 字段都是系统属性。它从 Properties 面板隐藏、不暴露给搜索/过滤器，但仍可在 raw 编辑器中查看和修改。frontmatter 解析器在把属性交给 UI 之前会过滤掉所有_*字段。

该 ADR 还给出了规范化系统属性的读写规则（canonical key 为最终写入形式，同时兼容旧键读取）：

以收藏为例，docs/adr/0038-frontmatter-backed-favorites.md 说明_favorite: true与_favorite_index: <整数>存储在每条笔记的 frontmatter 中，随 vault 通过 git 同步；取消收藏时直接删除键而不是写入_favorite: false。图标方面，docs/adr/0049-per-note-icon-property.md 规定_icon同时支持在类型文档与普通笔记上使用（emoji、Phosphor 图标名或 HTTP(S) 图片 URL），笔记级_icon会覆盖类型级继承的图标。

另外注意 site/reference/frontmatter-fields.md 的一个细节：系统字段下的嵌套键同样归系统所有。例如_sheet.cells.B6.num_fmt属于表格编辑器，不应作为普通用户属性出现在面板中。

自定义字段与关系字段：约定驱动的数据建模

除了建议属性与系统属性，你可以为笔记添加任意自定义 frontmatter 字段。关键规则是：如果某个字段的值包含 wikilink（[[...]]），Tolaria 就会把它当作关系字段处理。

这背后的机制来自 docs/adr/0010-dynamic-wikilink-relationship-detection.md：早期版本依赖硬编码的RELATIONSHIP_KEYS列表识别关系字段，新增一种关系就需要改代码。决策改为动态检测——Rust 解析器扫描 frontmatter 的所有键，凡是值中含有[[wikilinks]]的字段都收入VaultEntry.relationships映射，无需任何配置或硬编码名单。因此你可以自由定义诸如depends_on:、key_people:之类的任意关系字段，它们会自动出现在 Inspector 的关系面板中；而belongs_to、related_to、has这些标准字段仅作向后兼容保留，并不享有特权。

关系字段的“建议入口”也体现在源码中：src/components/inspector/RelationshipsPanel.tsx 定义了SUGGESTED_RELATIONSHIPS = ['belongs_to', 'related_to', 'has']，面板会过滤掉已存在的关系键后给出添加建议。

属性编辑：Properties 面板、类型感知控件与 Raw 模式

Properties 面板是编辑结构化属性最安全的地方。打开方式：

• macOS：Cmd+Shift+I
• Windows / Linux：Ctrl+Shift+I

面板的价值在于“类型感知”：date字段使用 Tolaria 自带的日期选择器；关系字段可以使用 wikilink 直接输入并解析；而当你需要对 YAML 做精细控制（例如直接修改系统属性、查看嵌套键）时，可以切换到Raw Markdown 模式——这也是唯一能触及_*系统字段的编辑入口（ADR 0008 明确保留这一能力）。

建议属性的显示模式（status/date/url/text）由SUGGESTED_PROPERTY_MODES映射决定（见上文 src/components/DynamicPropertiesPanel.tsx），它在后台把每种属性路由到对应的编辑控件，例如状态属性复用StatusDropdown（src/components/StatusDropdown.tsx）及其预置状态列表SUGGESTED_STATUSES（src/utils/statusStyles.ts）。

值得一提的编辑行为细节：按 docs/adr/0122-scalar-array-frontmatter-properties.md，Tolaria 会保留自定义的标量数组frontmatter 字段（如tags: [a, b]）作为属性；单一元素的数组会规范化为标量，多元素数组保持数组形态。这使得“标签类”字段在保存、重载、切换视图与重启后都能被稳定过滤——早期实现会丢弃多元素非 wikilink 数组，导致tags / contains / blues这类视图在重启后失效，该 ADR 通过提升 vault cache 版本强制重建缓存解决。

引用属性：HTML 块表达式与表格公式

属性的最终价值在于被引用。Tolaria 提供了一套Vault Expressions表达式语言，让渲染内容能读取当前笔记或其他笔记的属性值。

HTML 块中的模板表达式

site/concepts/properties.md给出的三个例子：

<p>{{status}}</p> <p>{{formatDate(date, "long")}}</p> <p>{{[[project-alpha]].status}}</p>

• {{status}}：当前笔记的属性；
• {{formatDate(date, "long")}}：调用格式化辅助函数；
• {{[[project-alpha]].status}}：读取另一条笔记的标量属性（wikilink 目标按 Tolaria 常规链接解析规则解析，可使用文件名、路径或标题，只要目标无歧义）。

完整的引用语法见 site/reference/vault-expressions.md，包括嵌套标量路径{{[[device]].power.watts}}、关系数组的逗号分隔文本输出{{[[essay]].has_notes}}、引用笔记标题{{[[essay]].title}}、表格笔记单格{{[[budget]].B5}}乃至原始正文行{{[[brief]].2}}。格式化辅助函数也很丰富：upper、lower、title、trim、truncate(value, length, suffix?)、replace(value, from, to)、round(value, digits?)、formatNumber、formatPercent、formatCurrency(value, currency, digits?)、formatDate(value, "short"|"medium"|"long"|"YYYY-MM-DD")、default(value, fallback)、isEmpty(value)、json(value)等。唯一的运算符是+（文本拼接），表达式不执行任意 JavaScript，不支持循环、变更、自定义函数、raw HTML 插值与远程数据访问，输出默认转义为纯文本——未解析的表达式会保留为可见的占位符（如{{missing_property}}），让破损的仪表盘显式暴露而不是静默出错。

需要结构化 JSON 时，可用json(...)配合沙箱脚本块：

<script type="application/json" id="notes-data"> {{json([[essay]].has_notes)}} </script>

表格公式中的同构引用

site/concepts/properties.md特别指出：表格公式可以读取标量属性，使用与 HTML 表达式相同的笔记目标形式：

=[[project-alpha]].status

更完整的等价示例（同样来自 site/reference/vault-expressions.md）：

=[[newsletter-revenue]].B5 =[[project-alpha]].status =[[launch-brief]].2

注意行号引用是 1 基且排除 YAML frontmatter：[[note]].A1表示单元格/网格访问（可能拆分逗号分隔内容），[[note]].1表示整个第一行正文（保留逗号作为文本）。表格内计算本身仍使用 IronCalc 函数，语法细节见 site/reference/spreadsheet-functions.md。

属性驱动的视图过滤实战

属性 + 过滤器是 Tolaria 组织笔记的核心工作流。根据 site/reference/view-filters.md，常用过滤方向包括：

Saved View 可以组合文本、日期、关系字段与 frontmatter 值的过滤条件，支持相对日期表达式（如“本周修改”）与正则过滤（供高级用户使用，建议在小视图上先验证再推广）。排序方面支持按最近修改、标题升序、状态升序以及任意自定义属性升/降序。

视图过滤的实现与属性类型紧密相关：标量属性采用大小写不敏感的文本匹配；而标量数组属性（如tags）按 ADR 0122 采用集合语义——contains与any_of匹配的是精确的、大小写不敏感的元素，而非元素内的子串。

小结

Tolaria 的属性系统可以概括为三层约定：

1. 建议属性（type、status、url、date）——开箱即用、一键补齐，并由源码中的SUGGESTED_PROPERTIES/SUGGESTED_PROPERTY_MODES驱动对应编辑器；
2. 系统属性（_前缀）——隐藏于常规编辑但保留在纯文本 frontmatter 中，由 ADR 0008 约定统一管理，承载图标、颜色、排序、固定属性等内部配置；
3. 自定义属性与关系——任意字段皆可，含 wikilink 即自动成为关系，配合 Vault Expressions 与表格公式实现跨笔记引用，最终在 Saved View 中完成过滤与排序。

这套设计让属性既是人类可读、可 git 同步的 Markdown 元数据，又是应用内结构化数据的单一事实来源。继续深入可阅读 site/reference/frontmatter-fields.md 查看全部字段含义，或阅读 docs/ARCHITECTURE.md 了解整体架构。

【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolaria