ZotLit

模板工作台视图

介绍模板工作台视图如何编辑配置方案、引文文本或片段,并在 Obsidian 中实时预览各自的效果。

模板工作台视图用于编辑单个模板文档,并对照来自 Zotero 文库的数据显示其输出效果。

单一视图,三种文档

该视图可打开全部三种模板文档类型。文档类型决定了标签页、标签页标题以及预览渲染的内容。

文档标签页标题标签页预览
配置方案配置方案名称,后接 · 配置方案六个单篇文献的文献笔记
引文文本引文文本一个,引文单条插入的引用
片段片段名称,后接 · 片段一个,片段某个模板调用该片段时的渲染结果

你输入的每一个字符都会实时预览,包括尚未保存的修改。编辑依托 Obsidian 的自动保存机制,并支持其撤销和重做。包含错误的文档仍可正常编辑与保存,编辑器中会显示相应的诊断信息。

原生 Markdown 视图依然可以处理同一文件。选择 以 Markdown 打开 即可将文档以 Markdown 格式打开;在文件列表中右键点击模板文档,可选择 打开模板工作台。

在视图顶部栏中选择 帮助,可打开 模板指南、模板语法、模板数据参考 以及 向社区求助。网页版模板工作台在顶部栏中也提供了相同的 帮助 菜单。

Rougier 等人 (2014)《Ten Simple Rules for Better Figures》的模板工作台:左侧编辑器中显示 Reading notes 配置方案的笔记模板,中间的“笔记预览”显示渲染后的属性、标题和标注,右侧边缘展开“字段”弹出框并分节列出该文献的字段

预览与字段面板

编辑器旁提供了两个面板。“预览”面板展示当前文档针对选定文献生成的输出内容。“字段”面板列出该文献对应的模板数据。它可以作为覆盖在编辑器上方的“字段”弹出框打开,也可以固定为编辑器旁的一列。配置方案、引文文本和片段均可使用这两个面板。

编辑器标签页、“预览”面板和“字段”面板共用同一个选定条目和选定标注。面板上方的工具栏会标明该条目的名称(在编辑标注模板时则标明标注名称),并提供 选择条目 按钮以供更改。窗格菜单中也有相同的选项。网页版模板工作台在相同位置显示条目名称,并带有专属的示例选择器。

显示或隐藏面板

在视图顶部栏中选择 显示预览 可以显示“预览”面板。面板显示时,该按钮呈按下状态。再次选择即可隐藏面板。视图的窗格菜单中也有相同的选项,面板显示时会带有勾选标记。网页版模板工作台在顶部栏中提供了相同的操作,在 视图 菜单中也包含该选项。

在视图顶部栏中选择 字段 可打开“字段”弹出框,再次选择即可将其关闭。当“字段”面板处于固定状态时,该操作用于隐藏或显示面板。窗格菜单项 显示字段 以及网页版模板工作台 视图 菜单中同名选项的功能相同,面板打开时同样带有勾选标记。参见字段面板。

隐藏“预览”面板会保留你选定的条目和标注。重新打开面板时,它们会再次显示出来。

调整预览面板大小

拖动“预览”面板与编辑器之间的分界边框可以调整面板宽度。面板的最小宽度为 240 像素。它可以向外扩展,直到编辑器剩余宽度为 360 像素,以便你在模板旁完整阅读篇幅较宽的笔记。

该边框也支持键盘操作。按 Tab 键聚焦到边框;屏幕阅读器会将其播报为 调整预览大小。

按键效果
左方向键或右方向键向该方向移动边框 16 像素
Shift + 方向键向该方向移动边框 64 像素
Home将面板缩至最小宽度
End将面板扩至最大宽度

双击边框可将面板恢复为默认宽度。

在网页版模板工作台也可以不通过边框直接调整面板尺寸。在 视图 菜单中,指向 调整预览大小,然后选择 加宽、变窄 或 重置宽度。每次调整幅度为 64 像素,菜单会保持打开状态以便多次调整。每次调整后,屏幕阅读器会朗读面板及其新尺寸,例如“Preview: 464 pixels”。

窄视图下的面板布局

在宽度至少为 896 像素(56rem)的视图中,“预览”面板位于编辑器旁边,方便你在编辑时随时对照模板与输出结果。

在宽度小于 896 像素的视图中,“预览”会移至编辑器下方。初始状态下它占据视图高度的 40%。拖动其上方的边框,或聚焦到边框并按上方向键或下方向键,可以增减其高度;Home 和 End 键分别将其设为最小和最大占比。双击边框可恢复为 40% 高度。在网页版模板工作台的 视图 菜单中,调整预览大小 会相应提供 加高、变矮 和 重置高度,每次步进 10%。编辑器始终会保留工具栏、标签页以及至少五行模板的空间;“预览”面板会优先被压缩。每次调整都以当前高度为基准。当编辑器需要更多空间时,会自动出现滚动条。

“字段”弹出框在各种宽度下的运作方式均相同。固定的“字段”面板仅在视图空间充足时才会停靠;参见固定“字段”面板。

收窄或放宽视图只会调整“预览”的位置,不改变其他任何内容:面板始终保持显示状态,并在视图重新变宽时恢复原有宽度。已打开的弹出框会保持打开,已关闭的则保持关闭。“预览”在重排过程中会保留你的当前位置:光标所在的控件和滚动位置均不受影响。将视图移动到其他窗口时,会遵循新窗口的宽度。

视图记忆的状态

Obsidian 会将“预览”面板的显示状态、宽度以及位于编辑器下方时的高度随视图一同保存。它还会保存“字段”面板是否已固定、是否被隐藏以及其宽度。重启之后,视图会按你离开时的状态重新打开。“字段”弹出框不会被保存:重新打开视图时它处于关闭状态。网页版模板工作台在页面保持打开期间会保留固定状态和宽度。

无论通过何种途径打开模板文档,都会在工作台窗口中将其打开并显示“预览”面板。若该窗口中已打开此文档,ZotLit 会将其置于前端。“字段”弹出框会保持关闭,直到你主动选择 字段。以下入口均可打开工作台:

  • 命令面板、模板文档或文献笔记的文件菜单,或以 Markdown 格式打开的模板文档顶部栏中的 打开模板工作台。
  • 内置“默认”配置方案上的 自定义。
  • ZotLit 设置中配置方案旁的 编辑配置方案 按钮。
  • 用于引文文本的 ZotLit: 自定义引文文本。

从视图窗格菜单中打开的片段或引文文本,会在同一个窗口的新标签页中打开。

字段面板

“字段”面板是内置在视图中的模板数据浏览器。它拥有相同的筛选器、分节、根节点和复制操作。它可以作为“字段”弹出框打开,也可以固定在编辑器旁。两处的内容完全一致。每个分节都包含带有图标、名称和字段数量的标题栏。在分节内滚动浏览时,标题栏会固定在顶部。点击标题栏可折叠或展开该分节。面板顶部栏中的 折叠所有分组 按钮可一次性折叠所有分节,展开所有分组 则重新全部展开。在筛选框中输入内容时,包含匹配字段的所有分节都会自动展开。每行都有一个插入按钮,且行菜单中提供 插入字段。两者都会将该字段插入到编辑器光标所在位置。

每一行在单行内显示字段名称以及选定文献的对应值。过长的值末尾会以“…”截断。列表内部或嵌套字段会缩进排列在细线后方。点击某行可查看其详情,再次点击即可隐藏。详情中显示完整值、模板路径,并在 在笔记中 下方展示将要插入模板的代码以及该文献对应的渲染结果。使用 插入 或 复制 可将该文本插入编辑器或复制到剪贴板。两项操作都会关闭详情视图。在宽度达到或超过 600 像素的视图中,详情会展开在面板旁与对应行平齐的位置。在较窄的视图中,详情会显示在面板底部的工具栏中,以免列表发生跳动。光标悬停在某行上不会触发任何展开动作。

列表字段(如作者或标注)会显示其包含的条目数量,并在一行中列出所有条目。当这些条目拥有自己的子字段时,列表名称后的折叠箭头可将每个子字段展开为独立行,显示每个条目的值:作者字段展开后可显示各自的名和姓,标签展开后可显示其名称和类型。列表插入笔记时会包含所有条目,因此拥有三位作者的文献在笔记中会完整列出全部三位作者。列表详情按行展示各项的值并带有编号。在 在笔记中 下,选择 合为一行 可用逗号将各项拼接为单行文本,选择 每项一行 则将每一项输出为独立的 Markdown 列表行。行上的 插入字段 默认采用第一种形式。

你也可以在筛选框中通过键盘操作。按下方向键或上方向键选择某行,按 Enter 显示其详情,按 Ctrl+Enter(macOS 上为 Command+Enter)将其插入。按 Enter 打开详情后,焦点会移入详情中,因此按 Tab 可以依次切换形式选项、插入、复制 以及 关闭详情。在详情内按 Ctrl+Enter 会插入所选形式的代码。按 Escape 会关闭详情并将焦点移回筛选框。

点击详情以外的区域,或按 Escape 键,均可关闭详情。按 Escape 键会先关闭详情,随后清空筛选框,最后关闭弹出框。在固定的面板中,由于面板保持显示,按 Escape 清空筛选框后便停止。

面板默认打开在与编辑器相同的根节点上,例如笔记字段或标注字段。引文文本显示引文字段,片段显示其预览调用者对应的字段。你可以将面板切换到其他根节点,例如某个标注。当编辑器的根节点或选定条目发生变化时,面板会重新跟随编辑器。

“字段”面板处于打开状态时,窗格菜单中的 将模板数据保存为 JSON 会保存面板当前所显示根节点的数据。否则,它会保存编辑器对应根节点的数据。

“字段”面板顶部栏中的 更多选项 按钮包含 选择条目、用于当前面板显示根节点的 将模板数据保存为 JSON,以及 复制 Zotero 标识符(在标注根节点上则为标注标识符)。

字段弹出框

在固定之前,“字段”面板默认以“字段”弹出框的形式打开。弹出框出现在视图的右侧边缘,并撑满整个高度。它在各种视图宽度下外观保持一致。弹出框打开时,编辑器和“预览”面板仍可正常使用,因此你可以在查看预览的同时编写模板。

可通过以下任一方式关闭弹出框:

  • 再次选择 字段。
  • 点击弹出框以外的任意区域。
  • 点击弹出框内的 关闭字段 按钮。
  • 按 Escape 键。

焦点随后会返回至 字段。

在“预览”面板中选择 查看问题 也会关闭弹出框。随后编辑器会定位到该问题,并将焦点置于其上。

在插入字段之前,请先将光标放置在模板中。在放置光标前,面板会显示 在模板中选择插入字段的位置。。执行插入后,字段会填入光标位置,弹出框随即关闭,光标会重新回到编辑器中紧随插入字段之后。若要连续插入多个字段,可在点击插入按钮时按住 Shift 键,或聚焦在按钮上按 Shift+Enter。这样弹出框会保持打开。

固定“字段”面板

固定“字段”面板可以在书写时持续展示文献数据。在弹出框的顶部栏中选择 固定到侧边。弹出框随之关闭,“字段”面板将作为一列固定在视图左侧边缘、编辑器之前(在从右向左阅读的语言中则为右侧边缘)。编辑器会自动收窄以腾出空间。

固定的面板在键入和插入字段时保持开启。插入字段后光标会回到编辑器中该字段之后,而面板位置保持不动。

  • 选择 字段 可隐藏固定面板并将空间留给编辑器。再次选择可重新显示面板。固定状态不受影响。
  • 拖动面板与编辑器之间的边框可在 240 至 480 像素之间调整面板宽度。边框支持与“预览”边框相同的键盘操作,窗格菜单中也提供 调整字段宽度。
  • 选择 取消固定 可取消固定面板。它将重新以“字段”弹出框的形式打开。

固定面板需要视图在“预览”面板占列后,仍能为 240 像素的“字段”面板保留至少 360 像素宽度的编辑器空间。在较窄的视图中,固定功能将被禁用,并提示气泡说明 加宽视图以固定,此时点击 字段 将打开“字段”弹出框。已固定的面板在空间不足时会显示提示 已固定 · 在窄视图中浮于编辑器上方。当视图重新变宽时,面板会自动重新停靠。视图变窄时,绝不会自行在编辑器上方弹开弹出框。

模板数据浏览器

窗格标题与布局

窗格标题开头为所选数据,结尾为 字段。标注标题会显示类型、页码和简短摘录。内置示例会在标题中明确标出;未选择任何内容时,窗格显示其通用名称。

全尺寸面板在顶部栏提供选择操作。侧边栏则在数据附近提供较小的选择控件。在任一布局下右键点击窗格标题栏,均可访问其菜单。

窗格列出的根节点

窗格标题栏标明了当前读取的根节点:笔记、标注、笔记名称 或 引文。

根节点会跟随当前正在编辑的配置方案部分:笔记正文及其属性列出笔记根节点,“标注分节”列出标注根节点,清单中的 filename 值列出笔记名称根节点,“引文文本”则列出引文根节点。

独立的浏览器会从其旁边的模板工作台视图中获取根节点。当锚定在某个标注上时,列表上方会显示面包屑路径 笔记根节点,其返回按钮(工具提示为 返回笔记根节点)可将列表切回笔记根节点。

若要从笔记根节点中读取单条标注自身的字段,请打开 zt.annotations 下对应行的“更多操作”菜单,并选择 作为标注模板数据进行探索。

分节

常用字段

排在每个根节点的最前面,包含大多数模板都会用到的字段。笔记根节点和笔记名称根节点将其余字段归类在 文献信息、 标识符、 内容与文件、 整理、 链接 和

Zotero 记录

之下。标注根节点则将它们归类在 标注、 来源、 整理、 链接 和

Zotero 记录

之下。引文根节点目前暂无其他分节。

点击分节标题可以折叠或展开该分节。窗格选择控件旁的按钮可全部展开或全部折叠所有分节,工具提示分别为 展开所有分组 或 折叠所有分组。窗格菜单中也提供同样的操作。

每个顶级行都展示读者熟知的名称,其原始路径显示在工具提示以及 复制路径 中。展开包含对象或数组的行可读取其成员。较长的值在折叠状态下仅显示首行,直到你选择 更多;选择 更少 可将其重新折叠。

筛选器

在搜索框中键入内容可缩小列表范围。搜索框会标明其搜索的根节点:搜索笔记字段、搜索标注字段、搜索笔记名称字段 或 搜索引文字段。

查询通过不区分大小写的子字符串匹配字段名、键和值。匹配的行及其父级链条会自动展开。当没有任何匹配时,列表会显示 没有匹配的字段。清除搜索即可查看所有字段。。

各行提供的复制操作

每一行都带有一个菜单。可通过该行的操作按钮组(标签为 模板操作)或通过右键点击该行来打开。

数组节点提供 复制循环,当其元素可拼接为文本时还提供 复制连接结果。其他所有节点均提供 复制输出 和 复制(如果存在)。

开启 JavaScript 模板 时,代码片段项会分别归入“Liquid”和“Eta”两个子菜单,以便你按模板采用的语法进行选择。关闭该选项时,Liquid 项会直接列在菜单中。

预览面板

“预览”面板的标题行标明了预览内容,例如 笔记预览,以及笔记的 文件名。在较长的预览中滚动浏览时,该行始终保持在顶部,以便你随时确认正在查看哪篇笔记。

标题行末尾有两个按钮。第一个按钮用于在阅读视图与 Markdown 源码之间切换预览;其工具提示会标明切换目标模式,即 显示 Markdown 或 显示阅读视图。第二个按钮 更多选项 可打开下方的预览选项。

在“预览”面板显示期间,视图的窗格菜单中也会追加用于调整预览效果的选项。对于配置方案,这些选项包括:

  • 预览为新笔记、 预览为更新后的笔记 或 仅预览更新的部分。
  • 自动刷新预览 。关闭此项后,仅在你选择 运行 时才会进行渲染。
  • 显示 Markdown ,用于以 Markdown 源码查看笔记。
  • 重新加载预览数据 ,用于重新加载条目数据。

引文文本和片段会各自添加专属的预览选项,详见下文。隐藏“预览”面板时,这些选项会从窗格菜单中移除,而预览会记住你的选择,以供下次显示时使用。

预览中检测到的问题会呈现在编辑器的 问题 区域中。

配置方案文档

配置方案控制文献笔记的名称、文件夹、属性以及正文内容。它还可以定义标注的显示样式,以及哪些 Zotero 条目自动采用该配置方案。

视图将这些部分划分为六个标签页:

  • 笔记 :编辑文献笔记正文。
  • 属性 :编辑由 ZotLit 管理的 YAML 属性。
  • 标注 :编辑单个标注的格式。
  • 名称和文件夹 :编辑笔记路径、引文样式、导入笔记设置以及模板语言。 笔记路径 分组将文献笔记文件夹与笔记名称模板整合在一起,并预览完整路径。
  • 匹配 :选择自动应用该新增配置方案的 Zotero 条目。
  • 配置方案 :编辑配置方案自身的名称、描述和版本。

视图顶部栏中提供 源码 开关。选择它即可用整个配置方案文档的 Markdown 源码取代各标签页;再次选择即可切回标签页。引文文本或片段原本就在其唯一的标签页中显示源码,因此该开关仅供配置方案文档使用。

名称和文件夹与匹配标签页

在 名称和文件夹 标签页中,笔记路径 分组包含 文献笔记文件夹、笔记名称模板 以及笔记最终获得的带有 .md 后缀的 预览。笔记名称中包含斜杠(/)会在该文件夹内创建子文件夹。对于“默认”配置方案,请在 设置 > ZotLit 中修改文件夹。匹配 标签页会针对所选条目报告 匹配所选条目 或 不匹配所选条目。

预览数据

预览依托某个 Zotero 条目或内置示例进行渲染。从某篇文献笔记打开该视图时,会自动选中该笔记对应的条目。窗格菜单提供 选择条目 以便切换预览数据。

预览会随着你的编辑实时变动。数据库或引文样式警告可能会限制预览效果,但你依然可以继续编辑配置方案。

若要调整标注格式,请选择 选择标注。你可以从所选条目中搜索标注,或选用高亮、下划线、笔记、文本、图片或手绘示例。标注示例保留其所属条目的数据;笔记预览则保留其当前选定的条目。

无论你在哪个操作界面上选择,一个视图中只绑定一个选定条目和一个选定标注。打开的第二个模板工作台视图会保留其各自的选择。

保存更改

内置的“默认”配置方案为只读。你无需创建文档即可查看并选择其数值。选择 自定义 会在开放编辑前于配置的模板文件夹中创建对应的文档,或直接打开已存在的自定义文档。

若创建失败,内置数值仍可正常查看,并会显示内联错误提示重试。直接关闭尚未修改的自定义配置,已创建的文档依然会予以保留。

现有的文献笔记保持当前内容不变。运行 ZotLit: 更新文献笔记 可将编辑后的配置方案应用到当前活动笔记中。

编辑 Markdown 文档

选择 以 Markdown 打开 可将已有的配置方案文档以 Markdown 格式打开。自定义内置“默认”配置方案时,会在允许编辑前先创建对应的文档。

引文文本

引文文本在唯一的 引文 标签页中打开。其标签页标题固定为 引文文本。

以 引文预览 为标题的预览会渲染单条引用。其说明文字指明了正在预览的形式:主要 或 替代。当“预览”面板处于显示状态时,视图的窗格菜单可用于选择该形式。菜单中还提供用于一组内置引用形态的 使用示例,或用于从你自己的 Zotero 条目中选择的 选择条目。

显示“预览”面板即可查看效果。面板显示时,视图的窗格菜单提供 使用示例,内含六种内置引用形态:单个条目、两个条目、带页码的条目、隐藏作者、前缀与后缀 以及 标注引文。默认打开在 单个条目 上。

你也可以选择 选择条目,仅凭文献引用标识预览你自己的某个 Zotero 条目。这会清除当前选用的示例。

从同一菜单中在 预览主引文 与 预览替代引文 之间切换,可以分别检查模板的两个分支。预览说明会显示当前展示的形式。

“预览”面板会使用你挑选的形式与示例。操作步骤详见自定义引文文本。

片段

片段在唯一的 片段 标签页中打开。其标签页标题为片段名称后接 · 片段。

片段自身不包含任何数据:它借助调用它的模板所提供的数据进行渲染。因此,以 片段预览 为标题的预览会询问你以哪个调用者的身份进行渲染。当“预览”面板显示时,视图的窗格菜单提供 按笔记调用预览、按标注调用预览 和 按引文调用预览。它默认以“笔记”身份打开,并针对每个文件分别记住你的选择。ZotLit 绝不会根据调用该片段的模板去猜测调用者身份。

如果你的仓库中除“默认”之外还包含其他配置方案,窗格菜单的该部分还会提供 使用配置方案,以便对照该配置方案的数据进行预览。保存片段会重新渲染当前打开的所有使用该片段的预览。

在编辑器中创建片段

选中一段模板文本,右键点击并选择 提取为片段…。ZotLit 会将选中文本移动到新文档中,在原地留下匹配的调用代码,并在分屏中打开新文档。在提取源模板中,这仅计为一次撤销步骤。

片段占位符

在配置方案的标签页中(未开启 源码 时),凡是带有普通引号名称的调用(Liquid 的 render 或 include,Eta 的 include(...))都会渲染为一个片段占位符:这是一个紧凑的控件,包含片段名称、照原样书写的其余参数、预览片段 以及 编辑片段。点击预览箭头可在下方展示该片段的只读渲染结果,其中使用该调用所在分块的数据。将光标置于调用代码中,占位符便会恢复为纯文本源码,以便你编辑参数。

五个保留名称绝不会作为片段名称,因此均不会渲染占位符:{% render "annotation" %} 会渲染为该配置方案标注分节的标注占位符;而调用 filename、note、content 或 citation 则不会渲染任何控件。代码块内的调用属于关于调用的正文说明,同样不会渲染控件。

重命名操作遵循普通的 Obsidian 文件重命名规则。ZotLit 没有专门的重命名操作,也不会自动重写调用语句,因此凡是调用旧名称的模板都会将其占位符标记为 缺失。点击该标记可在编辑器的 问题 区域查看具体问题,随后你可自行修改调用语句或创建该片段。

如果模板调用的某个片段已不在仓库中,ZotLit 便完全不会写入根据该模板生成的笔记。ZotLit 会提示缺失哪个片段,并提供 打开模板工作台 以打开包含该错误调用的文档。

文档的模板语言

在引文文本或片段的编辑器上方,会有一行文字标明文档的模板语言:Liquid 或 Eta (JavaScript)。该说明仅用于展示状态,无法直接切换。

窗格菜单中提供 更改语言,可在两种语言之间切换。ZotLit 仅重写清单中的键,不会翻译任何源代码。参见模板工作原理。

配置方案文档则在 名称和文件夹 标签页的 模板语言 下设置其模板语言。

打开视图

每个视图负责编辑一个模板文档,每种类型可从其所在的位置打开:

  • 配置方案:在 设置 > ZotLit > 文献笔记配置方案 中对应的行打开,或在 设置 > ZotLit 的 模板文档 行打开。
  • 引文文本:在 设置 > ZotLit > 引文 的 引文文本 行打开。
  • 片段:在 设置 > ZotLit > 文献笔记配置方案 的 片段 下对应的行打开。

文献笔记已采用的配置方案可直接从该笔记中打开。

上述每行都包含各自的控件,自定义模板中列出了这些控件的具体名称及操作步骤。

另请参阅

最后更新于

本页目录