Templater文档（机翻）

经验分享
1

个人对官网文档机翻整理了，还望大家看到错误帮我指正，感谢(･ω･)ﾉ

1.介绍

Templater 是一种模板语言，可让您将变量和函数结果插入到笔记中。它还允许您执行 JavaScript 代码来操作这些变量和函数。

使用 Templater，您将能够创建强大的模板来自动执行手动任务。

简单示例

以下模板文件，使用 Templater 语法：

---
creation date: <% tp.file.creation_date() %>
modification date: <% tp.file.last_modified_date("dddd Do MMMM YYYY HH:mm:ss") %>
---

<< [[<% tp.date.now("YYYY-MM-DD", -1) %>]] | [[<% tp.date.now("YYYY-MM-DD", 1) %>]] >>

# <% tp.file.title %>

<% tp.web.daily_quote() %>

插入时将产生以下结果：

---
creation date: 2021-01-07 17:20
modification date: Thursday 7th January 2021 17:20:43
---

<< [[2021-04-08]] | [[2021-04-10]] >>

# Test Test

> Do the best you can until you know better. Then when you know better, do better.
> &mdash; <cite>Maya Angelou</cite>

1.1 安装

您可以通过 Obsidian 中的“社区插件”选项卡安装此插件。搜索“Templater”。
最好在安装 Templater 后重新启动 Obsidian 应用程序，以确保一切正常。

1.2 术语

为了理解 Templater 的工作原理，让我们定义几个术语：

  • 模板是包含命令的文件。
  • 以开始标记 <% 开头的文本片段，以结束标记 %> 结尾，这就是我们所说的命令。
  • 函数是一个对象，我们可以在命令中调用它，它返回一个值（替换字符串）

可以使用两种类型的函数：

  • 内部功能。它们是在插件中构建的预定义函数。例如， tp.date.now 是一个将返回当前日期的内部函数。
  • 用户功能。用户可以定义自己的功能。它们要么是系统命令，要么是用户脚本。

例
以下模板包含 2 个命令，调用 2 个不同的内部函数：

明天: <% tp.date.yesterday("YYYY-MM-DD") %>
昨天: <% tp.date.tomorrow("YYYY-MM-DD") %>

我们将在下一部分看到编写一些命令所需的语法

1.3 语法

Templater 使用自定义模板引擎 （rusty_engine） 语法来声明命令。你可能需要一点时间来适应它，但一旦你有了这个想法，语法就不那么难了

Templater 的所有函数都是使用命令调用的 JavaScript 对象。

命令语法

命令必须同时具有开始标记 <% 和结束标记 %> 。

使用 tp.date.now 内部函数的完整命令是： `<% tp.date.now() %>

函数语法

对象层次结构

Templater 的所有函数，无论是内部函数还是用户函数，都可以在 tp 对象下使用。你可以说我们所有的函数都是对象的 tp 子函数。要访问对象的“子项”，我们必须使用点表示法 .

这意味着 Templater 函数调用将始终以 tp.<something>

函数调用

要调用函数，我们需要使用特定于函数调用的语法：在函数名称后附加一个左括号和一个右括号。

例如，我们将用于 tp.date.now() 调用 tp.date.now 内部函数。

函数可以有参数和可选参数。它们位于左括号和右括号之间，如下所示：

tp.date.now(arg1_value, arg2_value, arg3_value, ...)

所有参数必须按正确的顺序传递。

函数的参数可以具有不同的类型。以下是函数的可能类型的非详尽列表：

  • 文本 类型必须放在简单引号或双引号 （ "value" 或 'value' ） 内
  • 数值 类型必须为整数 （ 15 ， -5 ， …）
  • 布尔 类型必须是 trueorfalse （完全小写），而不是其他值。

调用函数时必须遵守参数的类型，否则它将不起作用。

函数文档语法

Templater 内部函数的文档使用以下语法：

tp.<my_function>(arg1_name: type, arg2_name?: type, arg3_name: type = <default_value>, arg4_name: type1|type2, ...)

解释:

  • arg_name 是参数的符号名称，以了解它是什么
  • type 表示目标参数的类型。调用内部函数时必须遵循此类型，否则将引发错误。

如果参数是可选的，则会附加一个问号 ? ，例如 arg2_name?: type

如果参数具有默认值，则将使用等号 = 指定它，例如 arg3_name: type = <default_value> 。

语法警告

请注意，此语法仅用于文档目的，以便能够理解函数所需的参数。

调用函数时，不能指定参数的名称、类型或默认值。如此处所述，只有需要修改参数的值。

例

我们以 tp.date.now 内部函数文档为例：

tp.date.now(format: string = "YYYY-MM-DD", offset?: number|string, reference?: string, reference_format?: string)

此内部函数有 4 个可选参数：

  • 类型为 string 的日期格式，默认值为 "YYYY-MM-DD"
  • 类型为 number 或 string 的数值。
  • 类型的 string 引用
  • 类型的 string 的reference_format。

这意味着此内部函数的有效调用为：

  • <% tp.date.now() %>
  • <% tp.date.now("YYYY-MM-DD", 7) %>
  • <% tp.date.now("YYYY-MM-DD", 7, "2021-04-09", "YYYY-MM-DD") %>
  • <% tp.date.now("dddd, MMMM Do YYYY", 0, tp.file.title, "YYYY-MM-DD") %> *假设文件名的格式为：“YYYY-MM-DD”

另一方面，无效调用为：

  • tp.date.now(format: string = "YYYY-MM-DD")
  • tp.date.now(format: string = "YYYY-MM-DD", offset?: 0)

1.4 设置

您可以设置“模板”文件夹的位置，以告诉 Templater 只检查此文件夹中的模板。

您可以使用“超时”选项为系统命令设置超时。所用时间超过您定义的时间的系统命令将被取消，并被视为失败。

您可以将 Templater 设置为在创建新文件时触发。它将侦听新文件创建事件，并替换在新文件内容中找到的每个命令。

这使得 Templater 与其他插件兼容，如每日笔记核心插件、日历插件、评论插件、笔记重构插件……

安全警告

如果在创建时创建内容未知/不安全的新文件，则可能会有危险。确保每个新文件的内容在创建时都是安全的。
文件夹模板

您可以使用“文件夹模板”功能指定将自动用于选定文件夹及其子文件夹的模板。

注意：默认情况下，此设置是隐藏的。要查看它，请首先启用新文件创建时的触发器模板设置。

系统命令

您可以启用系统命令。这允许您创建链接到系统命令的用户函数。

任意系统命令

从不受信任的来源执行任意系统命令可能是危险的。仅运行您理解的、来自可信来源的系统命令。

1.5 常见问题

2. 内部函数

Templater 提供的不同内部变量和函数可在不同的模块下使用，以对它们进行排序。现有的内部模块包括：

配置模块：tp. config
日期模块：tp. date
文件模块：tp. file
前沿模块：tp. frontmatter
挂钩模块：tp. hooks
黑石模块：tp. obsidian
系统模块：tp. system
Web 模块：tp. web

如果您正确理解了对象层次结构，这意味着典型的内部函数调用如下所示：<%tp<模块名称><internal_function_name>%>

捐款

我邀请大家通过添加新的内部函数来为这个插件的开发做出贡献。更多信息请点击此处。

2.1 配置模块

此模块公开 Templater 的运行配置。

这在编写需要一些上下文信息的脚本时非常有用。

文档

tp.config.active_file?
启动 Templater 时的活动文件（如果存在）。

tp.config.run_mode
这个 RunMode表示启动 Templater 的方式（从模板创建新模板、附加到活动文件…）。

tp.config.target_file
这个 tfile 对象，表示将插入模板的目标文件。

tp. config. template_file
这个 TFile 对象表示模板文件。

2.2 日期模块

此模块包含与日期相关的每个内部函数。

文档

函数文档使用特定的语法。更多信息请点击此处。

2.2.1检索日期。

tp.date.now(format: string = "YYYY-MM-DD", offset?: number⎮string, reference?: string, reference_format?: string)
参数
  • format：日期的格式。默认为“YYYY-MM-DD”。请参阅格式参考。
  • offset：从中偏移日期的持续时间。如果提供了数字，则持续时间将添加到以天为单位的日期中。也可以使用 ISO 8601 格式将偏移指定为字符串。
  • reference：引用的日期，例如将其设置为注释的标题。
  • reference_format: 引用日期的格式。请参阅格式参考。
示例
//现在日期
<% tp.date.now() %>
//带格式的当前日期
<% tp.date.now("Do MMMM YYYY") %>
//上周
<% tp.date.now("YYYY-MM-DD", -7) %>
下个星期
<% tp.date.now("YYYY-MM-DD", 7) %>
//上个月
<% tp.date.now("YYYY-MM-DD", "P-1M") %>
//明年
<% tp.date.now("YYYY-MM-DD", "P1Y") %>
//文件标题日期+1 天（明天）
<% tp.date.now("YYYY-MM-DD", 1, tp.file.title, "YYYY-MM-DD") %>
//文件的标题日期-1 天（昨天）
<% tp.date.now("YYYY-MM-DD", -1, tp.file.title, "YYYY-MM-DD") %>

2.2.2检索工作日

tp.date.weekday(format: string = "YYYY-MM-DD", weekday: number, reference?: string, reference_format?: string)
参数
  • format：日期的格式。默认为“YYYY-MM-DD”。请参阅格式参考。
  • weekday：星期日编号。如果区域设置将星期一指定为一周的第一天，则 0 将为星期一，-7 将为上周的一天。
  • reference：参考日期，例如将其设置为注释的标题。
  • reference_format: 引用日期的格式。请参阅格式参考。
示例
//本周的星期一
<% tp.date.weekday("YYYY-MM-DD", 0) %>
//下周一
<% tp.date.weekday("YYYY-MM-DD", 7) %>
//文件标题星期一
<% tp.date.weekday("YYYY-MM-DD", 0, tp.file.title, "YYYY-MM-DD") %>
//上周一的文件标题
<% tp.date.weekday("YYYY-MM-DD", -7, tp.file.title, "YYYY-MM-DD") %>

2.2.3检索昨天的日期。

tp.date.yesterday(format: string = "YYYY-MM-DD")
参数
  • format：日期的格式。默认为“YYYY-MM-DD”。请参阅格式参考。
示例
//昨天的日期
<% tp.date.yesterday() %>
//昨天的日期（设置格式）
<% tp.date.yesterday("Do MMMM YYYY") %>

//昨天的日期
<%tp.date.yesterday（）%>
//昨天的日期，格式为
<%tp.date.yesterday(“Do MMMM YYYY”)%>

2.2.4检索明天的日期。

tp.date.tomorrow(format: string = "YYYY-MM-DD")
参数
  • format：日期的格式。默认为“YYYY-MM-DD”。请参阅格式参考。
示例
//明天的日期
<% tp.date.tomorrow() %>
//明天的日期和格式
<% tp.date.tomorrow("Do MMMM YYYY") %>

Moment. js

Templater 允许您访问即时对象及其所有功能。

有关 moment. js 的更多信息，请点击此处。
示例

//现在日期
<% moment(tp.file.title, "YYYY-MM-DD").format("YYYY-MM-DD") %>
//从备注标题获取月初
<% moment(tp.file.title, "YYYY-MM-DD").startOf("month").format("YYYY-MM-DD") %>
//从备注标题获取月末
<% moment(tp.file.title, "YYYY-MM-DD").endOf("month").format("YYYY-MM-DD") %>

示例

//现在日期
<% tp.date.now() %>
//带格式的当前日期
<% tp.date.now("Do MMMM YYYY") %>
//上周
<% tp.date.now("YYYY-MM-DD", -7) %>
//下周
<% tp.date.now("YYYY-MM-DD", 7) %>
//上个月
<% tp.date.now("YYYY-MM-DD", "P-1M") %>
//明年
<% tp.date.now("YYYY-MM-DD", "P1Y") %>
//文件标题日期+1 天（明天）
<% tp.date.now("YYYY-MM-DD", 1, tp.file.title, "YYYY-MM-DD") %>
//文件的标题日期-1 天（昨天）
<% tp.date.now("YYYY-MM-DD", -1, tp.file.title, "YYYY-MM-DD") %>

//本周的星期一
<% tp.date.weekday("YYYY-MM-DD", 0) %>
//下周一
<% tp.date.weekday("YYYY-MM-DD", 7) %>
//文件标题星期一
<% tp.date.weekday("YYYY-MM-DD", 0, tp.file.title, "YYYY-MM-DD") %>
//上周一的文件标题
<% tp.date.weekday("YYYY-MM-DD", -7, tp.file.title, "YYYY-MM-DD") %>

//明天的日期
<% tp.date.tomorrow() %>
//明天的日期和格式
<% tp.date.tomorrow("Do MMMM YYYY") %>

//昨天的日期
<% tp.date.yesterday() %>
//昨天的日期，格式为
<% tp.date.yesterday("Do MMMM YYYY") %>

2.3 文件模块

此模块包含与文件相关的每个内部函数。

文档

函数文档使用特定的语法。更多信息请点击此处。

2.3.1 获取文件

tp.file.content

执行 Templater 时文件的字符串内容。操作此字符串不会更新当前文件。

示例
//检索文件内容
<% tp.file.content %>

2.3.2 创建文件

tp.file.create_new(template: TFile ⎮ string, filename?: string, open_new: boolean = false, folder?: TFolder)

使用指定的模板或指定的内容创建新文件。

参数
  • template：用于新文件内容的模板，或作为字符串的文件内容。如果它是要使用的模板，则使用 tp. file. find_tfile（TEMPLATENAME）进行检索。
  • filename：新文件的文件名，默认为“无标题”。
  • open_new：是否打开新创建的文件。警告：如果使用此选项，由于命令是异步执行的，因此可以先打开文件，然后将其他命令附加到新文件，而不是前一个文件。
  • folder：放置新文件的文件夹，默认为黑石的默认位置。如果要将文件显示在其他文件夹中，请使用 app.vault.getAbstractFileByPath("FOLDERNAME") 指定该文件。
示例
//文件创建
<%* await tp.file.create_new("MyFileContent", "MyFilename") %>
//使用模板创建文件
<%* await tp.file.create_new(tp.file.find_tfile("MyTemplate"), "MyFilename") %>
//文件创建和打开创建的笔记
<%* await tp.file.create_new("MyFileContent", "MyFilename", true) %>
//在当前文件夹中创建文件
<%* await tp.file.create_new("MyFileContent", "MyFilename", false, tp.file.folder()) %>
//在指定文件夹中创建文件
<%* await tp.file.create_new("MyFileContent", "MyFilename", false, app.vault.getAbstractFileByPath("MyFolder")) %>
//创建文件并将链接附加到当前注释
[[<% (await tp.file.create_new("MyFileContent", "MyFilename")).basename %>]]

2.3.3 根据创建日期检索文件

tp.file.creation_date(format: string = "YYYY-MM-DD HH:mm")
参数
  • format：日期的格式。默认为“YYYY-MM-DD HH: MM”。请参阅格式参考。
示例
//文件创建日期
<% tp.file.creation_date() %>
//具有格式的文件创建日期
<% tp.file.creation_date("dddd Do MMMM YYYY HH:mm") %>

2.3.4 插入模版并设置光标位置

tp.file.cursor(order?: number)

插入模板后，将光标设置到此位置。

您可以使用黑石设置中配置的热键在不同的光标之间导航。

参数
  • order：不同光标的跳转顺序，例如从 1 到 2 到 3，依此类推。如果指定多个具有相同顺序的 tp. file. cursor，编辑器将切换到多光标。
示例
//文件光标
<% tp.file.cursor() %>
//文件多光标
<% tp.file.cursor(1) %>Content<% tp.file.cursor(1) %>

2.3.5 在光标后追加内容

p.file.cursor_append(content: string)

在文件中的活动光标后追加一些内容。

参数
  • content：要附加在活动光标后面的内容。
示例
//文件光标附加
<% tp.file.cursor_append("Some text") %>

2.3.6 检查文件是否存在

tp.file.exists(filepath: string)

根据文件路径检查文件是否存在。必须提供文件的完整路径（相对于 Vault 并包含扩展名）。

参数
  • filepath：我们要检查是否存在的文件的完整文件路径。
示例
//文件存在
<% await tp.file.exists("MyFolder/MyFile.md") %>
//当前文件的文件存在
<% await tp.file.exists(tp.file.folder(true) + "/" + tp.file.title + ".md") %>

2.3.7检索文件并返回实例

tp.file.find_tfile(filename: string)

搜索文件并返回其 TFile 实例。

参数
  • filename：我们要搜索并解析为 TFile 的文件名。
  • string：检索内容
示例
//文件查找 TFile
<% tp.file.find_tfile("MyFile").basename %>

2.3.8 检索文件的文件夹

tp.file.folder(relative: boolean = false)

检索文件的文件夹名称。

参数
  • relative：如果设置为 true，则将 vault 相对路径附加到文件夹名称。如果为 false，则仅检索文件夹的名称。默认为 false。
示例
//文件文件夹（文件夹）
<% tp.file.folder() %>
//具有相对路径的文件文件夹（路径/目标/文件夹）
<% tp.file.folder(true) %>

2.3.9 引用其他模版

tp.file.include(include_link: string ⎮ TFile)

引用特定模版，一同使用

参数

include_link：指向要包含的文件的链接，例如 [[MyFile]]或 TFile 对象,还包括章节引用和块引用。

示例
//文件包括
<% tp.file.include ("[[Template1]]") %>
//文件包括 TFile
<% tp.file.include(tp.file.find_tfile("MyFile")) %>
//文件包含部分
<% tp.file.include ("[[MyFile#Section1]]") %>
//文件包含块
<% tp.file.include ("[[MyFile#^block1]]") %>

2.3.10 根据文件修改时间检索文件

tp.file.last_modified_date(format: string = "YYYY-MM-DD HH:mm")

检索文件的上次修改日期。

参数
  • format：日期的格式。默认为“YYYY-MM-DD HH: MM”。请参阅格式参考。
示例
//文件上次修改日期
<% tp.file.last_modified_date() %>
//文件上次修改日期，格式为
<% tp.file.last_modified_date("dddd Do MMMM YYYY HH:mm") %>

2.3.11 将文件移动到所需位置

tp.file.move(new_path: string, file_to_move?: TFile)

将文件移动到所需的位置。

参数

  • new_path：文件的新 vault 相对路径，不包含文件扩展名。注意：新路径需要包括文件夹和文件名，例如“/Notes/MyNote”。

  • file_to_move：要移动的文件，默认为当前文件。

示例
//文件移动
<% await tp.file.move("/A/B/NewTitle") %>
//文件移动和重命名
<% await tp.file.move("/A/B/" + tp.file.title) %>

2.3.12 检索文件在系统上的绝对路径。

tp. file. path（相对值：boolean=false）

检索文件在系统上的绝对路径

参数

relative：如果设置为 true，则仅检索 vault 的相对路径。

示例
//文件路径
<% tp.file.path() %>
//文件相对路径（相对于 vault 根）
<% tp.file.path(true) %>

2.3.13 重命名文件

tp.file.rename(new_title: string)

重命名文件（保持相同的文件扩展名）。

参数
  • new_title: 新的文件标题。
示例
//文件重命名
<% await tp.file.rename("MyNewName") %>
//文件在文件名后附加一个 2
<% await tp.file.rename(tp.file.title + "2") %>

2.3.14 检索活动文件的选中文本

tp.file.selection()

检索活动文件的文本选择。

示例
//文件选择
<% tp.file.selection() %>

2.3.15检索文件的标签

tp.file.tags

检索文件的标记（字符串数组）。

示例
//文件标记
<% tp.file.tags %>

2.3.16 检索文件的标题

tp.file.title

检索文件的标题。

示例
//文件标题
<% tp.file.title %>
//剥去标题的 Zettelkasten ID（如果用空格分隔）
<% tp.file.title.split(" ")[1] %>

示例

//检索文件内容
<% tp.file.content %>

//文件创建
<%* await tp.file.create_new("MyFileContent", "MyFilename") %>
//使用模板创建文件
<%* await tp.file.create_new(tp.file.find_tfile("MyTemplate"), "MyFilename") %>
//文件创建和打开创建的笔记
<%* await tp.file.create_new("MyFileContent", "MyFilename", true) %>
//在当前文件夹中创建文件
<%* await tp.file.create_new("MyFileContent", "MyFilename", false, tp.file.folder()) %>
//在指定文件夹中创建文件
<%* await tp.file.create_new("MyFileContent", "MyFilename", false, app.vault.getAbstractFileByPath("MyFolder")) %>
//创建文件并将链接附加到当前注释
[[<% (await tp.file.create_new("MyFileContent", "MyFilename")).basename %>]]

//文件创建日期
<% tp.file.creation_date() %>
//具有格式的文件创建日期
<% tp.file.creation_date("dddd Do MMMM YYYY HH:mm") %>

//文件光标
<% tp.file.cursor() %>
//文件多光标
<% tp.file.cursor(1) %>Content<% tp.file.cursor(1) %>

//文件光标附加
<% tp.file.cursor_append("Some text") %>

//文件存在
<% await tp.file.exists("MyFolder/MyFile.md") %>
//当前文件的文件存在
<% await tp.file.exists(tp.file.folder(true) + "/" + tp.file.title + ".md") %>

//文件查找 TFile
<% tp.file.find_tfile("MyFile").basename %>

//文件文件夹（文件夹）
[//具有相对路径的文件文件夹（路径/目标/文件夹）](<%3C% tp.file.folder() %%3E>)
// File folder with relative path (Path/To/Folder)
<% tp.file.folder(true) %>

//文件引用
<% tp.file.include ("[[Template1]]") %>
//文件包括 TFile
<% tp.file.include(tp.file.find_tfile("MyFile")) %>
//文件部分引用
<% tp.file.include ("[[MyFile#Section1]]") %>
//文件包含块
<% tp.file.include ("[[MyFile#^block1]]") %>

//文件上次修改日期
<% tp.file.last_modified_date() %>
//文件上次修改日期，格式为
<% tp.file.last_modified_date("dddd Do MMMM YYYY HH:mm") %>

//文件移动
<% await tp.file.move("/A/B/" + tp.file.title) %>
//文件移动和重命名
<% await tp.file.move("/A/B/NewTitle") %>

//文件路径
<% tp.file.path() %>
//文件相对路径（相对于 vault 根）
<% tp.file.path(true) %>

//文件重命名
<% await tp.file.rename("MyNewName") %>
//文件在文件名后附加一个 2
<% await tp.file.rename(tp.file.title + "2") %>

//文件选择
<% tp.file.selection() %>

//文件标记
<% tp.file.tags %>

//文件标题
<% tp.file.title %>
//剥去标题的 Zettelkasten ID（如果用空格分隔）
<% tp.file.title.split(" ")[1] %>

2.4 文件属性模块

此模块将文件的所有 frontmatter 变量公开为变量。

文档

检索文件的属性值。

tp.frontmatter.<frontmatter_variable_name>

检索文件 frontmatter 模块的变量，如果您的变量名称包含空格，则可以使用括号表示法引用它，如下所示：

<% tp.frontmatter["variable name with spaces"] %>

实例

假设您有以下文件：

---
alias: myfile
note type: seedling
---

file content

然后，您可以使用以下模板：

File's metadata alias: <% tp.frontmatter.alias %>
Note's type: <% tp.frontmatter["note type"] %>

对于 frontmatter 中的列表，您可以使用 JavaScript 数组原型方法来操作数据的显示方式。

---
categories:
  - book
  - movie
---

<% tp.frontmatter.categories.map(prop => `  - "${prop}"`). join ("\n") %>

2.5 钩子模块

此模块公开了允许您在发生 Templater 事件时执行代码的钩子。

文档

函数文档使用特定语法。更多信息请点击此处。

挂载活动模板

tp.hooks.on_all_templates_executed(callback_function: () => any)

当所有活动运行的模板都完成执行时挂接到 any。大多数情况下，这将是一个模板，除非您使用的 tp.file.include 是或 tp.file.create_new .
此方法的多次调用将使其回调函数并行运行。

参数
  • callback_function ：当所有活动正在运行的模板都完成执行时将执行的回调函数。

示例

//模板执行完成后更新frontmatter
<%*
tp. hooks. on_all_templates_executed (async () => {
  const file = tp. file. find_tfile (tp.file.path (true));
  await app.fileManager.processFrontMatter (file, (frontmatter) => {
    frontmatter["key"] = "value";
  });
});
%>
//在Templater更新文件后，从另一个插件运行一个命令来修改当前文件e
<%*
tp. hooks. on_all_templates_executed (() => {
  app.commands.executeCommandById ("obsidian-linter: lint-file");
});
-%>

2.6 obsidian 模块

此模块公开了 Obsidian API 中的所有函数和类
这在编写脚本时非常有用。
有关详细信息，请参阅 Obsidian API 声明文件。

示例

//获取所有文件夹
<%
app.vault.getAllLoadedFiles ()
  .filter (x => x instanceof tp. obsidian. TFolder)
  .map (x => x.name)
%>

//规格化路径
<% tp.obsidian.normalizePath("Path/to/file.md") %>

//要标记的Html
<% tp.obsidian.htmlToMarkdown("\<h1>Heading\</h1>\<p>Paragraph\</p>") %>

//HTTP请求
<%*
const response = await tp.obsidian.requestUrl (" https://jsonplaceholder.typicode.com/todos/1" );
tR += response. json. title;
%>

2.7 系统模块

该模块包含与系统相关的功能。

文档

函数文档使用特定语法。更多信息请点击此处。

2.7.1 检索剪贴板的内容。

tp.system.clipboard()

检索剪贴板的内容。

示例
// 剪贴板
<% tp.system.clipboard() %>

2.7.2 生成提示

tp.system.prompt(prompt_text?: string, default_value?: string, throw_on_cancel: boolean = false, multiline?: boolean = false)

生成提示模式并返回用户的输入。

参数
  • prompt_text ：位于输入字段上方的文本
  • default_value ：输入字段的默认值。
  • throw_on_cancel ：如果取消提示，则引发错误，而不是返回 null 值。
  • multiline ：如果设置为 true ，则输入字段将为多行文本区域。默认值为 false
示例
//提示
<% tp.system.prompt("Please enter a value") %>
//使用默认值提示
<% tp.system.prompt("What is your mood today?", "happy") %>
//多行提示
<% tp.system.prompt("What is your mood today?", null, false, true) %>

2.7.3 生成用户选择

tp.system.suggester(text_items: string[] ⎮ ((item: T) => string), items: T[], throw_on_cancel: boolean = false, placeholder: string = "", limit?: number = undefined)

生成建议器提示并返回用户选择的项目

参数
  • text_items ：字符串数组，表示将在建议器提示中为每个项目显示的文本。这也可以是将项目映射到其文本表示形式的函数。
  • items ：按正确顺序包含每个项值的数组。
  • throw_on_cancel ：如果取消提示，则引发错误，而不是返回 null 值。
  • placeholder ：提示符的占位符字符串。
  • limit ：限制一次呈现的项目数（有助于提高显示大型列表时的性能）。
示例
// 选择
<% tp.system.suggester(["Happy", "Sad", "Confused"], ["Happy", "Sad", "Confused"]) %>
//具有映射功能的选择（与上例相同）
<% tp.system.suggester((item) => item, ["Happy", "Sad", "Confused"]) %>
//文件选择
[[<% (await tp.system.suggester((item) => item. basename, app.vault.getMarkdownFiles ())). basename %> ]]
//根据标签选择
<% tp.system.suggester(item => item, Object.keys (app.metadataCache.getTags ()). map (x => x.replace ("#", ""))) %>

示例

// 剪贴板
<% tp.system.clipboard() %>

//提示
<% tp.system.prompt("Please enter a value") %>
//使用默认值提示
<% tp.system.prompt("What is your mood today?", "happy") %>
//多行提示
<% tp.system.prompt("What is your mood today?", null, false, true) %>

// 选择
<% tp.system.suggester(["Happy", "Sad", "Confused"], ["Happy", "Sad", "Confused"]) %>
//具有映射功能的选择（与上例相同）
<% tp.system.suggester((item) => item, ["Happy", "Sad", "Confused"]) %>
//文件选择
[[<% (await tp.system.suggester((item) => item. basename, app. vault. getMarkdownFiles ())). basename %>  ]]
//根据标签选择
<% tp.system.suggester(item => item, Object. keys (app. metadataCache. getTags ()). map (x => x.replace ("#", ""))) %>

2.8 web 模块

该模块包含与 Web 相关的所有内部功能（发出 Web 请求）。

文档

函数文档使用特定语法。更多信息请点击此处。

2.8.1 每日建议

tp.web.daily_quote()

从 API https://api.quotable.io 检索并获取每日建议

示例
// 每日建议
<% tp.web.daily_quote() %>

2.8.2 获取随机图案

tp.web.random_picture(size?: string, query?: string, include_size?: boolean)

从 https://unsplash.com/ 中获取随机图像。

参数
  • size ：格式 <width>x<height> 中的图像大小。
  • query ：将选择范围限制为与搜索字词匹配的照片。可以传递多个搜索词，用逗号分隔。
  • include_size ：用于在图像链接 Markdown 中包含指定大小的可选参数。默认值为 false。
示例
//随机图片
<% tp.web.random_picture() %>
//随机图片大小
<% tp.web.random_picture("200x200") %>
//带有大小和查询的随机图片
<% tp.web.random_picture("200x200", "landscape,water") %>

示例

// 每日建议
<% tp.web.daily_quote() %>

//随机图片
<% tp.web.random_picture() %>
//随机图片大小
<% tp.web.random_picture("200x200") %>
//带有大小和查询的随机图片
<% tp.web.random_picture("200x200", "landscape,water") %>

2.9 贡献

您可以通过开发一个新的内部函数/变量来为 Templater 做出贡献。

开发新产品的过程真的很容易。

请记住，只有相关的提交才会被接受，不要提交一个非常具体的内部变量/函数，你将是唯一一个使用它的人。

布局

内部变量/函数按模块排序。每个模块在 src/InternalTemplates 下都有一个专用文件夹。

让我们以日期模块为例。

它包含一个 InternalModuleDate 文件，其中定义并注册了我们所有内部日期的相关变量和函数：

export class InternalModuleDate extends InternalModule {
    name = "date";

    async createStaticTemplates() {
        this.static_templates.set("now", this.generate_now());
        this.static_templates.set("tomorrow", this.generate_tomorrow());
        this.static_templates.set("yesterday", this.generate_yesterday());
    }

    async updateTemplates() {}

    generate_now() {
        return (format: string = "YYYY-MM-DD", offset?: number, reference?: string, reference_format?: string) => {
            if (reference && !window.moment(reference, reference_format).isValid()) {
                throw new Error("Invalid title date format, try specifying one with the argument 'reference'");
            }
            return get_date_string(format, offset, reference, reference_format);
        }
    }

    generate_tomorrow() {
        return (format: string = "YYYY-MM-DD") => {
            return get_date_string(format, 1);
        }
    }

    generate_yesterday() {
        return (format: string = "YYYY-MM-DD") => {
            return get_date_string(format, -1);
        }
    }
}

每个模块都扩展了 InternalModule 抽象类，这意味着它们包含以下属性和方法：

  • this. app 属性：obsidian API 应用程序对象。
  • this. file 属性：将插入模板的目标文件。
  • this. plugin 属性：Templater 插件对象。
  • this. static_templates 属性：一个包含所有静态（名称；变量/函数）的映射。
    • 静态变量/函数意味着它在执行时不依赖于文件。这些类型的变量/函数不会在每次插入新模板时更新，以节省一些开销。
  • this. dynamic_templates 属性：与 static_templates 相同，只是它包含执行时依赖于文件的变量/函数。
  • this. createStaticTemplates（）方法：为该模块注册所有静态内部变量/函数。
  • this. updateTemplates（）方法：为该模块注册每个动态内部变量/函数。

如果需要，可以在新的内部变量/函数中使用这些属性。

注册新的内部变量/函数

以下是您需要遵循的不同步骤，以便在模块中注册新的内部变量/函数。

第一步：

在模块内部创建一个名为 generate_<internal_variable_or_function_name>（）的方法，该方法将生成内部变量/函数，这意味着它将返回 lambda 函数（表示内部函数）或直接返回要公开的内部变量。

所有生成方法都是根据内部变量/函数名称按字母顺序排列的。

试着给你的变量/函数起一个好的、不言自明的名字。

第二步：

在 static_templates 或 dynamic_templates 映射中注册内部变量/函数，具体取决于执行时文件中是否存在内部变量/功能。注册发生在 createStaticTemplates 或 updateTemplates 中。

要注册变量/函数，请使用您之前定义的 this. generate_<internal_variable_or_function_name>（）方法：

this.static_templates.set(<internal_variable_or_function_name>, this.generate_<internal_variable_or_function_name>());
OR
this.dynamic_templates.set(<internal_variable_or_function_name>, this.generate_<internal_variable_or_function_name>());

内部变量/函数注册也根据变量/函数名称按字母顺序排列。

第三步：

将您的内部变量/函数文档添加到 Templater 的文档中。

你完了！感谢您对 Templater的贡献！

现在，只要在 Github 上提交一个 pull 请求，我就会尽可能地做出反应。

3. 用户功能

您可以在 Templater 中定义自己的函数。

您可以使用两种类型的用户功能

调用用户函数

您可以使用通常的函数调用语法来调用用户函数： tp.user.<user_function_name>() ，其中 <user_function_name> 是定义的函数名称。

例如，如果定义了一个名为 echo 的系统命令用户函数，则完整的命令调用将如下所示：

<% tp.user.echo() %>

不支持移动设备

目前，用户功能在 Obsidian for mobile 上不可用。

3.1 脚本用户函数

这种类型的用户函数允许您从 JavaScript 文件调用 JavaScript 函数并检索其输出。

要使用脚本用户函数，您需要在 Templater 的设置中指定脚本文件夹。此文件夹需要可从您的保管库访问

定义脚本用户函数

假设您在 Templater 的设置中将 Scripts 文件夹指定为您的脚本文件夹。

Templater 将加载 scripts 文件夹中的所有 JavaScript（. js 文件）脚本。

例如，您可以创建名为 Scripts/my_script. js 的脚本（需要. js 扩展名）。您可能必须在 obsidian之外创建文件，因为obsidian只会创建 md 文件。

然后，您将能够将脚本作为用户函数进行调用。函数名与脚本文件名相对应。

脚本应遵循 CommonJS 模块规范，并导出单个函数。

function my_function (msg) {
    return `Message from my script: ${msg}`;
}
module.exports = my_function;

在本例中，完整的命令调用如下所示：

<% tp.user.my_script("Hello World!") %>

这将输出 Message from my script: Hello World! .

全局命名空间

在脚本用户函数中，您仍然可以访问全局命名空间变量，如 app 或 moment。

但是，您不能访问模板引擎范围内的变量，如 tp 或 tR。如果要使用它们，必须将它们作为函数的参数传递。

函数参数

根据定义函数的方式，可以向函数传递任意数量的参数。

例如，您可以将 tp 对象传递给您的函数，以便能够使用 Templater:<% tp.user.<user_function_name>(tp) %>

3.2 系统命令用户功能

这种类型的用户函数允许您执行系统命令并检索其输出。

系统命令用户功能需要在模板的设置中启用。

定义系统命令用户功能

要定义新的系统命令用户函数，需要定义与系统命令相关联的函数名称。

要做到这一点，请转到插件的设置，然后单击 Add User Function （添加用户功能）。

完成后，Templater 将创建一个以您定义的内容命名的用户函数，该函数将执行您的系统命令并返回其输出。

就像内部函数一样，用户函数在tp JavaScript 对象下可用，更具体地说是在 tp.user 对象下可用。

![[Template文档.png]]

函数参数

您可以将可选参数传递给用户函数。它们必须作为包含属性及其相应值的单个 JavaScript 对象传递：｛arg 1：value 1，arg 2：value 2，…｝。

这些参数将以环境变量的形式提供给您的程序/脚本。

在我们前面的示例中，这将给出以下命令声明：

<% tp. user. echo ({a: "value 1", b: "value 2"}) %>

如果我们的系统命令调用 bash 脚本，我们将能够访问变量 a 并使用 b $a 和 $b

系统命令中的内部功能

您可以在系统命令中使用内部函数。在执行系统命令之前，内部功能将被替换。

例如，如果您配置了系统命令 cat <% tp.file.path() %>,，则在执行系统命令之前，它将被替换为 cat /path/to/file。

4. 命令

Templater 定义了 2 种类型的开始标记，定义了 2 种类型的命令：

  • <% %> ：插值命令。它将输出内部表达式的结果。
  • <%* %>：JavaScript 执行命令。它将执行里面的 JavaScript 代码。默认情况下，它不输出任何内容

命令的结束标记始终相同 %>

命令实用程序

除了不同类型的命令外，您还可以使用命令实用程序。它们也在命令的开始标记中声明。所有命令实用程序都适用于所有命令类型。

4.1 动态命令

使用此命令实用程序，可以将命令声明为“动态”，这意味着在进入预览模式时将解析此命令。

要声明动态命令，请在命令打开标记后添加加号：＜%+

就是这样，您的命令现在只能在预览模式下执行。

这对于 tp. file. last_modified_date 等内部函数非常有用，例如：

上次修改日期: <%+ tp.file.last_modified_date() %>

注意：动态命令存在已知问题，今后可能不会进行维护（有关更多详细信息，请参阅此问题）。在大多数情况下，Dataview 插件是建议的替代方案。

刷新问题

预览模式的一个“缺点”是，它将渲染的笔记放在缓存中，以加快速度。

这意味着您的动态命令将只在打开注释时渲染一次，但之后不会刷新。

如果要刷新它，必须关闭笔记以清除缓存，然后再次打开它。

4.2 Javascript 执行命令

这种类型的命令允许我们执行 JavaScript 代码。

有了 JavaScript Execution 命令，我们几乎可以完成 JavaScript 允许我们做的一切。下面给出了一些例子。

我们仍然可以通过这种类型的命令访问 tp 对象和所有内部变量/函数。

JavaScript 执行命令允许您访问全局命名空间变量。这意味着您可以访问 app 或 moment .

异步功能

一些内部函数是异步的。在 JavaScript 执行命令中调用此类函数时，如有必要，请不要忘记使用 await 关键字。

如何从 JavaScript 执行命令输出值？

有时，在使用 JS 执行命令时，您可能想要输出一些内容。

当我们的模板引擎使用我们所有的命令结果生成替换字符串时，它被存储在一个名为 tR 的变量中。这个字符串将包含处理后的文件内容。您可以通过 JS 执行命令访问该变量。

这意味着，要从 JS 执行命令中输出一些内容，只需要将要输出的内容附加到 tR 字符串变量中。

例如，以下命令：<%* tR += "test" %> 输出 test

建议和提示

需要注意的是，tp.system.prompt()和tp.system.suggester() 都需要一个 await 语句来将值保存到变量中

以下是使用 JavaScript 执行命令可以执行的一些操作示例：

<%* if (tp.file.title.startsWith("Hello")) { %>
This is a hello file !
<%* } else { %>
This is a normal file !
<%* } %>
    
<%* if (tp.frontmatter.type === "seedling") { %>
This is a seedling file !
<%* } else { %>
This is a normal file !
<%* } %>
    
<%* if (tp.file.tags.contains("#todo")) { %>
This is a todo file !
<%* } else { %>
This is a finished file !
<%* } %>

<%*
function log (msg) {
    console.log (msg);
}
%>
<%* log("Title: " + tp.file.title) %>
    
<%* tR += tp.file.content.replace(/stuff/, "things"); %>

4.3 空白控制

默认情况下，Templater 中的命令不会删除任何换行符。命令被替换为其值，仅此而已。

有时，在插入命令后进行一些空格控制会很有用，这正是此命令实用程序所提供的。

让我们举个例子。以下模板：

<%* if (tp.file.title == "MyFile" ) { %>
This is my file!
<%* } else { %>
This isn't my file!
<%* } %>
Some content ...

如果条件为 false，将产生以下输出（当它为 true 时也会发生同样的情况），请注意空行：


This isn't my file!

Some content ...

您可能希望删除执行命令生成的不产生任何输出的空行。

空格控件存在特定的语法：

标记 （  <%_ ） 开头的下划线 _ 将修剪命令前的所有空格
标记 （ _%>  ） 末尾的下划线 _ 将修剪命令后的所有空格
标记 （  <%- ） 开头的破折号 - 将修剪命令前的一个换行符
标记 （ -%>  ） 末尾的破折号 - 将修剪命令后面的一个换行符。

在我们的示例中，为了修复模板以删除空行，我们将使用以下模板（注意标签末尾的破折号 - ）来删除执行命令后面的空行符：

<%* if (tp.file.title == "MyFile" ) { -%>
This is my file!
<%* } else { -%>
This isn't my file!
<%* } -%>
Some content ...

这将产生以下输出：

This isn't my file!
Some content ...
2 个赞
2

不清楚有没有分享错区域，分享错的话麻烦和我说声，让我改下

3

感谢分享, 即使在现在一堆翻译工具的帮助下, 把文本弄完善了, 排版好了, 也是要花费心思的


提个小建议

标题里 Template 应该是 Templater
前者是 Ob 自带的功能, 后者是这个社区插件


另外还有些无关紧要的

  • 必须是 or true false => true or false
  • weekay：星期日编号 => weekday
  • <%tp.date.昨天（“Do MMMM YYYY”）%> => yesterday
  • 还支持截面或块体夹杂物 => 还包括章节引用和块引用 (哈哈, 可能是 DeepL)
4

感谢指正，我现在就改