ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

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

Tolaria Properties 属性系统完全指南:Frontmatter 结构化字段的创建、编辑与引用 Tolaria Properties 属性系统完全指南Frontmatter 结构化字段的创建、编辑与引用【免费下载链接】tolariaDesktop app to manage markdown knowledge bases项目地址: https://gitcode.com/GitHub_Trending/to/tolariaProperties属性是 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 ---这个定义决定了三件事显示属性会出现在右侧 Properties 面板、笔记列表的 chips 或列中过滤Saved View保存视图可以把属性作为过滤条件详见 site/reference/view-filters.md编辑Properties 面板为不同属性提供类型匹配的编辑控件日期选择器、下拉、文本输入等。从源码结构看属性系统在渲染层有清晰的数据模型支撑。src/types.ts 定义了属性值的类型export type VaultPropertyScalar string | number | boolean | null export type VaultPropertyArray Arraystring | number | boolean export type VaultPropertyValue VaultPropertyScalar | VaultPropertyArray即属性值既可以是标量字符串、数字、布尔、null也可以是标量组成的数组每个VaultEntry通过properties: Recordstring, VaultPropertyValuesrc/types.ts持有全部自定义属性。Tolaria 不强制 schema——它采用约定而非必需字段的模型这一点在 site/reference/frontmatter-fields.md 中有完整字段总表。建议属性Suggested Properties一键补齐常用字段“建议属性”是 Tolaria 知道如何快速创建的字段。当某条笔记缺少某个建议属性时Properties 面板会显示一个快捷入口shortcut点击即可用正确的编辑器添加该字段——例如date会得到日期选择器status会得到状态下拉。site/concepts/properties.md给出了四个内置建议属性字段用途type将笔记归入某种类型如 Project、Person、Topic。status跟踪生命周期状态如 Active、Done、Blocked。url存储规范的外部链接。date表示单个日期。源码可以印证这一列表。在 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: Recordstring, PropertyDisplayMode { Status: status, date: date, URL: url, icon: text, }面板通过getSuggestedDisplayModesrc/components/DynamicPropertiesPanel.tsx为建议属性选择渲染模式SuggestedPropertySlot组件则渲染“点击即添加”的入口其onAdd回调完成属性写入。此外type字段缺失时面板还会借助resolveMissingTypeNamesrc/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 为最终写入形式同时兼容旧键读取规范化键旧键回退读取写入方_archivedArchived、archivedArchive 操作_trashedTrashed、trashedTrash 操作_trashed_atTrashed at、trashed_atTrash 操作_favorite—收藏切换_favorite_index—收藏排序以收藏为例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 面板是编辑结构化属性最安全的地方。打开方式macOSCmdShiftIWindows / LinuxCtrlShiftI面板的价值在于“类型感知”date字段使用 Tolaria 自带的日期选择器关系字段可以使用 wikilink 直接输入并解析而当你需要对 YAML 做精细控制例如直接修改系统属性、查看嵌套键时可以切换到Raw Markdown 模式——这也是唯一能触及_*系统字段的编辑入口ADR 0008 明确保留这一能力。建议属性的显示模式status/date/url/text由SUGGESTED_PROPERTY_MODES映射决定见上文 src/components/DynamicPropertiesPanel.tsx它在后台把每种属性路由到对应的编辑控件例如状态属性复用StatusDropdownsrc/components/StatusDropdown.tsx及其预置状态列表SUGGESTED_STATUSESsrc/utils/statusStyles.ts。值得一提的编辑行为细节按 docs/adr/0122-scalar-array-frontmatter-properties.mdTolaria 会保留自定义的标量数组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 typeapplication/json idnotes-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常用过滤方向包括目标过滤条件活跃项目typeis Project 且statusis Active草稿typeis Article 且statusis Draft待跟进联系人typeis Person 且 date 早于今天近期工作修改日期在最近区间内Saved View 可以组合文本、日期、关系字段与 frontmatter 值的过滤条件支持相对日期表达式如“本周修改”与正则过滤供高级用户使用建议在小视图上先验证再推广。排序方面支持按最近修改、标题升序、状态升序以及任意自定义属性升/降序。视图过滤的实现与属性类型紧密相关标量属性采用大小写不敏感的文本匹配而标量数组属性如tags按 ADR 0122 采用集合语义——contains与any_of匹配的是精确的、大小写不敏感的元素而非元素内的子串。小结Tolaria 的属性系统可以概括为三层约定建议属性type、status、url、date——开箱即用、一键补齐并由源码中的SUGGESTED_PROPERTIES/SUGGESTED_PROPERTY_MODES驱动对应编辑器系统属性_前缀——隐藏于常规编辑但保留在纯文本 frontmatter 中由 ADR 0008 约定统一管理承载图标、颜色、排序、固定属性等内部配置自定义属性与关系——任意字段皆可含 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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表