diff --git a/README.md b/README.md index d6820651..ccc4c66f 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ ![templater_logo](./imgs/templater_logo.svg) +[English](README.md) | [简体中文](README_zh.md) + [Templater](https://github.com/SilentVoid13/Templater) is a template plugin for [Obsidian.md](https://obsidian.md/). It defines a templating language that lets you insert variables and functions results into your notes. It will also let you execute JavaScript code manipulating those variables and functions. ## Documentation diff --git a/README_zh.md b/README_zh.md new file mode 100644 index 00000000..6dfd4f1a --- /dev/null +++ b/README_zh.md @@ -0,0 +1,62 @@ +# Templater Obsidian 插件 + +![templater_logo](./imgs/templater_logo.svg) + +[English](README.md) | [简体中文](README_zh.md) + +[Templater](https://github.com/SilentVoid13/Templater) 是一个为 [Obsidian.md](https://obsidian.md/) 设计的模板插件。它定义了一种模板语言,允许您在笔记中插入变量和函数结果。它还允许您执行 JavaScript 代码来操作这些变量和函数。 + +## 文档 + +查看完整的[文档](https://silentvoid13.github.io/Templater/)([中文版](https://fjie.github.io/Templater/zh/))开始使用 [Templater](https://github.com/SilentVoid13/Templater)。 + +## 警告 + +[Templater](https://github.com/SilentVoid13/Templater) 允许您执行任意 JavaScript 代码和系统命令。 + +从不受信任的来源执行任意 JavaScript 代码或系统命令可能很危险。只运行您理解的、来自可信来源的代码/命令。 + +## 模板展示 / 问题 / 想法 / 帮助 + +前往[讨论](https://github.com/SilentVoid13/Templater/discussions)标签页提问和查找相关内容。 + +不要害羞,在[模板展示](https://github.com/SilentVoid13/Templater/discussions/categories/templates-showcase)类别中分享您使用 [Templater](https://github.com/SilentVoid13/Templater) 创建的模板。使用 [gists](https://gist.github.com/) 分享模板文件。 + +## 资源 + +关于 [Templater](https://github.com/SilentVoid13/Templater) 的有用资源列表: + +- @GitMurf 快速演示 `如何设置并运行您的第一个 Templater JS 脚本`:https://github.com/SilentVoid13/Templater/discussions/187 +- @shabegom `如何使用 Templater JS 脚本`:https://shbgm.ca/blog/obsidian/how-to-use-templater-js-scripts +- @chhoumann 模板展示:https://github.com/chhoumann/Templater_Templates +- @zachatoo 模板展示:https://zachyoung.dev/posts/templater-snippets +- @lguenth 模板展示:https://github.com/lguenth/obsidian-templates +- @tallguyjenks 视频:https://youtu.be/2234DXKbNgM?t=1944 +- @ProductivityGuru 视频:https://www.youtube.com/watch?v=cSawi0tYPMM + +## 替代方案 + +- https://github.com/chhoumann/quickadd +- https://github.com/garyng/obsidian-temple +- https://github.com/avirut/obsidian-metatemplates + +## 贡献 + +欢迎您做出贡献。 + +您可以创建一个 [issue](https://github.com/SilentVoid13/Templater/issues) 来报告错误、提出改进建议、提问等。 + +您可以提交 [pull request](https://github.com/SilentVoid13/Templater/pulls) 来为该插件的开发做出贡献。 + +查看[这里](https://silentvoid13.github.io/Templater/internal-functions/contribute.html)获取有关如何开发新的内置变量/函数的更多信息。 + +## 许可证 + +[Templater](https://github.com/SilentVoid13/Templater) 使用 GNU AGPLv3 许可证。更多信息请参考 [LICENSE](https://github.com/SilentVoid13/Templater/blob/master/LICENSE.TXT)。 + +## 支持 + +如果您想支持我和我的工作,您可以[在 Github 上赞助我](https://github.com/sponsors/SilentVoid13)(首选方法)或在 [**Paypal**](https://www.paypal.com/donate?hosted_button_id=U2SRGAFYXT32Q) 上捐赠。 + +[![GitHub Sponsors](https://img.shields.io/github/sponsors/silentvoid13?label=Sponsor&logo=GitHub%20Sponsors&style=for-the-badge)](https://github.com/sponsors/silentvoid13) +[![Paypal](https://img.shields.io/badge/paypal-silentvoid13-yellow?style=social&logo=paypal)](https://www.paypal.com/donate?hosted_button_id=U2SRGAFYXT32Q) \ No newline at end of file diff --git a/docs_zh/.gitignore b/docs_zh/.gitignore new file mode 100644 index 00000000..7585238e --- /dev/null +++ b/docs_zh/.gitignore @@ -0,0 +1 @@ +book diff --git a/docs_zh/book.toml b/docs_zh/book.toml new file mode 100644 index 00000000..a572508c --- /dev/null +++ b/docs_zh/book.toml @@ -0,0 +1,13 @@ +[book] +authors = ["SilentVoid13"] +language = "zh-CN" +multilingual = false +src = "src" +title = "Templater" + +[preprocessor.tera] +command = "mdbook-tera --toml ./documentation.toml" + +[preprocessor.toc] +command = "mdbook-toc" +renderer = ["html"] \ No newline at end of file diff --git a/docs_zh/documentation.toml b/docs_zh/documentation.toml new file mode 100644 index 00000000..f906f354 --- /dev/null +++ b/docs_zh/documentation.toml @@ -0,0 +1,651 @@ +[tp.app] +name = "app" +description = "This module exposes the app instance. Prefer to use this over the global app instance." + +[tp.user] +name = "user" +description = "This module exposes custom made scripts, written by yourself within the script file folder location" + +[tp.config] +name = "config" +description = """This module exposes Templater's running configuration. + +This is mostly useful when writing scripts requiring some context information. +""" + +[tp.config.functions.template_file] +name = "template_file" +description = "The `TFile` object representing the template file." +definition = "tp.config.template_file" + +[tp.config.functions.target_file] +name = "target_file" +description = "The `TFile` object representing the target file where the template will be inserted." +definition = "tp.config.target_file" + +[tp.config.functions.run_mode] +name = "run_mode" +description = "The `RunMode`, representing the way Templater was launched (Create new from template, Append to active file, ...)." +definition = "tp.config.run_mode" + +[tp.config.functions.active_file] +name = "active_file" +description = "The active file (if existing) when launching Templater." +definition = "tp.config.active_file?" + + + + +[tp.date] +name = "date" +description = "This module contains every internal function related to dates." + +[tp.date.functions.now] +name = "now" +description = "Retrieves the date." +definition = "tp.date.now(format: string = \"YYYY-MM-DD\", offset?: number⎮string, reference?: string, reference_format?: string)" + +[[tp.date.functions.now.args]] +name = "format" +description = """The format for the date. Defaults to `"YYYY-MM-DD"`. Refer to [format reference](https://momentjs.com/docs/#/displaying/format/).""" + +[[tp.date.functions.now.args]] +name = "offset" +description = "Duration to offset the date from. If a number is provided, duration will be added to the date in days. You can also specify the offset as a string using the ISO 8601 format." + +[[tp.date.functions.now.args]] +name = "reference" +description = "The date referential, e.g. set this to the note's title." + +[[tp.date.functions.now.args]] +name = "reference_format" +description = "The format for the reference date. Refer to [format reference](https://momentjs.com/docs/#/displaying/format/)." + +[[tp.date.functions.now.examples]] +name = "Date now" +example = "<% tp.date.now() %>" + +[[tp.date.functions.now.examples]] +name = "Date now with format" +example = """<% tp.date.now("Do MMMM YYYY") %>""" + +[[tp.date.functions.now.examples]] +name = "Last week" +example = """<% tp.date.now("YYYY-MM-DD", -7) %>""" + +[[tp.date.functions.now.examples]] +name = "Next week" +example = """<% tp.date.now("YYYY-MM-DD", 7) %>""" + +[[tp.date.functions.now.examples]] +name = "Last month" +example = """<% tp.date.now("YYYY-MM-DD", "P-1M") %>""" + +[[tp.date.functions.now.examples]] +name = "Next year" +example = """<% tp.date.now("YYYY-MM-DD", "P1Y") %>""" + +[[tp.date.functions.now.examples]] +name = "File's title date + 1 day (tomorrow)" +example = """<% tp.date.now("YYYY-MM-DD", 1, tp.file.title, "YYYY-MM-DD") %>""" + +[[tp.date.functions.now.examples]] +name = "File's title date - 1 day (yesterday)" +example = """<% tp.date.now("YYYY-MM-DD", -1, tp.file.title, "YYYY-MM-DD") %>""" + +[tp.date.functions.tomorrow] +name = "tomorrow" +description = "Retrieves tomorrow's date." +definition = "tp.date.tomorrow(format: string = \"YYYY-MM-DD\")" + +[[tp.date.functions.tomorrow.args]] +name = "format" +description = """The format for the date. Defaults to `"YYYY-MM-DD"`. Refer to [format reference](https://momentjs.com/docs/#/displaying/format/).""" + +[[tp.date.functions.tomorrow.examples]] +name = "Date tomorrow" +example = "<% tp.date.tomorrow() %>" + +[[tp.date.functions.tomorrow.examples]] +name = "Date tomorrow with format" +example = """<% tp.date.tomorrow("Do MMMM YYYY") %>""" + +[tp.date.functions.yesterday] +name = "yesterday" +description = "Retrieves yesterday's date." +definition = "tp.date.yesterday(format: string = \"YYYY-MM-DD\")" + +[[tp.date.functions.yesterday.args]] +name = "format" +description = """The format for the date. Defaults to `"YYYY-MM-DD"`. Refer to [format reference](https://momentjs.com/docs/#/displaying/format/).""" + +[[tp.date.functions.yesterday.examples]] +name = "Date yesterday" +example = "<% tp.date.yesterday() %>" + +[[tp.date.functions.yesterday.examples]] +name = "Date yesterday with format" +example = """<% tp.date.yesterday("Do MMMM YYYY") %>""" + +[tp.date.functions.weekday] +name = "weekday" +description = "" +definition = "tp.date.weekday(format: string = \"YYYY-MM-DD\", weekday: number, reference?: string, reference_format?: string)" + +[[tp.date.functions.weekday.args]] +name = "format" +description = """The format for the date. Defaults to `"YYYY-MM-DD"`. Refer to [format reference](https://momentjs.com/docs/#/displaying/format/).""" + +[[tp.date.functions.weekday.args]] +name = "weekday" +description = "Week day number. If the locale assigns Monday as the first day of the week, `0` will be Monday, `-7` will be last week's day." + +[[tp.date.functions.weekday.args]] +name = "reference" +description = "The date referential, e.g. set this to the note's title." + +[[tp.date.functions.weekday.args]] +name = "reference_format" +description = "The format for the reference date. Refer to [format reference](https://momentjs.com/docs/#/displaying/format/)." + +[[tp.date.functions.weekday.examples]] +name = "This week's Monday" +example = """<% tp.date.weekday("YYYY-MM-DD", 0) %>""" + +[[tp.date.functions.weekday.examples]] +name = "Next Monday" +example = """<% tp.date.weekday("YYYY-MM-DD", 7) %>""" + +[[tp.date.functions.weekday.examples]] +name = "File's title Monday" +example = """<% tp.date.weekday("YYYY-MM-DD", 0, tp.file.title, "YYYY-MM-DD") %>""" + +[[tp.date.functions.weekday.examples]] +name = "File's title previous Monday" +example = """<% tp.date.weekday("YYYY-MM-DD", -7, tp.file.title, "YYYY-MM-DD") %>""" + +[[tp.date.momentjs.examples]] +name = "Date now" +example = """<% moment(tp.file.title, "YYYY-MM-DD").format("YYYY-MM-DD") %>""" + +[[tp.date.momentjs.examples]] +name = "Get start of month from note title" +example = """<% moment(tp.file.title, "YYYY-MM-DD").startOf("month").format("YYYY-MM-DD") %>""" + +[[tp.date.momentjs.examples]] +name = "Get end of month from note title" +example = """<% moment(tp.file.title, "YYYY-MM-DD").endOf("month").format("YYYY-MM-DD") %>""" + + +[tp.file] +name = "file" +description = "This module contains every internal function related to files." + +[tp.file.functions.content] +name = "content" +description = "The string contents of the file at the time that Templater was executed. Manipulating this string will *not* update the current file." +definition = "tp.file.content" + +[[tp.file.functions.content.examples]] +name = "Retrieve file content" +example = "<% tp.file.content %>" + +[tp.file.functions.create_new] +name = "create_new" +description = "Creates a new file using a specified template or with a specified content." +definition = "tp.file.create_new(template: TFile ⎮ string, filename?: string, open_new: boolean = false, folder?: TFolder | string)" + +[[tp.file.functions.create_new.args]] +name = "template" +description = "Either the template used for the new file content, or the file content as a string. If it is the template to use, you retrieve it with `tp.file.find_tfile(TEMPLATENAME)`." + +[[tp.file.functions.create_new.args]] +name = "filename" +description = "The filename of the new file, defaults to \"Untitled\"." + +[[tp.file.functions.create_new.args]] +name = "open_new" +description = "Whether to open or not the newly created file. Warning: if you use this option, since commands are executed asynchronously, the file can be opened first and then other commands are appended to that new file and not the previous file." + +[[tp.file.functions.create_new.args]] +name = "folder" +description = """The folder to put the new file in, defaults to Obsidian's default location. If you want the file to appear in a different folder, specify it with `"PATH/TO/FOLDERNAME"` or `app.vault.getAbstractFileByPath(\"PATH/TO/FOLDERNAME\")`.""" + +[[tp.file.functions.create_new.examples]] +name = "File creation" +example = """<%* await tp.file.create_new("MyFileContent", "MyFilename") %>""" + +[[tp.file.functions.create_new.examples]] +name = "File creation with template" +example = """<%* await tp.file.create_new(tp.file.find_tfile("MyTemplate"), "MyFilename") %>""" + +[[tp.file.functions.create_new.examples]] +name = "File creation and open created note" +example = """<%* await tp.file.create_new("MyFileContent", "MyFilename", true) %>""" + +[[tp.file.functions.create_new.examples]] +name = "File creation in current folder" +example = """<%* await tp.file.create_new("MyFileContent", "MyFilename", false, tp.file.folder(true)) %>""" + +[[tp.file.functions.create_new.examples]] +name = "File creation in specified folder with string path" +example = """<%* await tp.file.create_new("MyFileContent", "MyFilename", false, "Path/To/MyFolder") %>""" + +[[tp.file.functions.create_new.examples]] +name = "File creation in specified folder with TFolder" +example = """<%* await tp.file.create_new("MyFileContent", "MyFilename", false, app.vault.getAbstractFileByPath("MyFolder")) %>""" + +[[tp.file.functions.create_new.examples]] +name = "File creation and append link to current note" +example = """[[<% (await tp.file.create_new("MyFileContent", "MyFilename")).basename %>]]""" + +[tp.file.functions.creation_date] +name = "creation_date" +description = "Retrieves the file's creation date." +definition = "tp.file.creation_date(format: string = \"YYYY-MM-DD HH:mm\")" + +[[tp.file.functions.creation_date.args]] +name = "format" +description = """The format for the date. Defaults to `"YYYY-MM-DD HH:mm"`. Refer to [format reference](https://momentjs.com/docs/#/displaying/format/).""" + +[[tp.file.functions.creation_date.examples]] +name = "File creation date" +example = "<% tp.file.creation_date() %>" + +[[tp.file.functions.creation_date.examples]] +name = "File creation date with format" +example = """<% tp.file.creation_date("dddd Do MMMM YYYY HH:mm") %>""" + +[tp.file.functions.cursor] +name = "cursor" +description = """ +Sets the cursor to this location after the template has been inserted. + +You can navigate between the different cursors using the configured hotkey in Obsidian settings. +""" +definition = "tp.file.cursor(order?: number)" + +[[tp.file.functions.cursor.args]] +name = "order" +description = """ +The order of the different cursors jump, e.g. it will jump from 1 to 2 to 3, and so on. +If you specify multiple tp.file.cursor with the same order, the editor will switch to multi-cursor. +""" + +[[tp.file.functions.cursor.examples]] +name = "File cursor" +example = "<% tp.file.cursor() %>" + +[[tp.file.functions.cursor.examples]] +name = "File multi-cursor" +example = "<% tp.file.cursor(1) %>Content<% tp.file.cursor(1) %>" + +[tp.file.functions.cursor_append] +name = "cursor_append" +description = "Appends some content after the active cursor in the file." +definition = "tp.file.cursor_append(content: string)" + +[[tp.file.functions.cursor_append.args]] +name = "content" +description = "The content to append after the active cursor." + +[[tp.file.functions.cursor_append.examples]] +name = "File cursor append" +example = """<% tp.file.cursor_append("Some text") %>""" + +[tp.file.functions.exists] +name = "exists" +description = """Check to see if a file exists by it's file path. The full path to the file, relative to the Vault and containing the extension, must be provided.""" +definition = "tp.file.exists(filepath: string)" + +[[tp.file.functions.exists.args]] +name = "filepath" +description = "The full file path of the file we want to check existence for." + +[[tp.file.functions.exists.examples]] +name = "File existence" +example = """<% await tp.file.exists("MyFolder/MyFile.md") %>""" + +[[tp.file.functions.exists.examples]] +name = "File existence of current file" +example = """<% await tp.file.exists(tp.file.folder(true) + "/" + tp.file.title + ".md") %>""" + +[tp.file.functions.find_tfile] +name = "find_tfile" +description = "Search for a file and returns its `TFile` instance." +definition = "tp.file.find_tfile(filename: string)" + +[[tp.file.functions.find_tfile.args]] +name = "filename" +description = "The filename we want to search and resolve as a `TFile`." + +[[tp.file.functions.find_tfile.examples]] +name = "File find TFile" +example = """<% tp.file.find_tfile("MyFile").basename %>""" + +[tp.file.functions.folder] +name = "folder" +description = "Retrieves the file's folder name." +definition = "tp.file.folder(absolute: boolean = false)" + +[[tp.file.functions.folder.args]] +name = "absolute" +description = "If set to `true`, returns the vault-absolute path of the folder. If `false`, only returns the basename of the folder (the last part). Defaults to `false`." + +[[tp.file.functions.folder.examples]] +name = "File folder (Folder)" +example = "<% tp.file.folder() %>" + +[[tp.file.functions.folder.examples]] +name = "File folder with vault-absolute path (Path/To/Folder)" +example = "<% tp.file.folder(true) %>" + +[tp.file.functions.include] +name = "include" +description = "Includes the file's link content. Templates in the included content will be resolved." +definition = "tp.file.include(include_link: string ⎮ TFile)" + +[[tp.file.functions.include.args]] +name = "include_link" +description = """The link to the file to include, e.g. `"[[MyFile]]"`, or a TFile object. Also supports sections or blocks inclusions.""" + +[[tp.file.functions.include.examples]] +name = "File include" +example = """<% tp.file.include("[[Template1]]") %>""" + +[[tp.file.functions.include.examples]] +name = "File include TFile" +example = """<% tp.file.include(tp.file.find_tfile("MyFile")) %>""" + +[[tp.file.functions.include.examples]] +name = "File include section" +example = """<% tp.file.include("[[MyFile#Section1]]") %>""" + +[[tp.file.functions.include.examples]] +name = "File include block" +example = """<% tp.file.include("[[MyFile#^block1]]") %>""" + +[tp.file.functions.last_modified_date] +name = "last_modified_date" +description = "Retrieves the file's last modification date." +definition = "tp.file.last_modified_date(format: string = \"YYYY-MM-DD HH:mm\")" + +[[tp.file.functions.last_modified_date.args]] +name = "format" +description = """The format for the date. Defaults to `"YYYY-MM-DD HH:mm"`. Refer to [format reference](https://momentjs.com/docs/#/displaying/format/).""" + +[[tp.file.functions.last_modified_date.examples]] +name = "File last modified date" +example = "<% tp.file.last_modified_date() %>" + +[[tp.file.functions.last_modified_date.examples]] +name = "File last modified date with format" +example = """<% tp.file.last_modified_date("dddd Do MMMM YYYY HH:mm") %>""" + +[tp.file.functions.move] +name = "move" +description = "Moves the file to the desired vault location." +definition = "tp.file.move(new_path: string, file_to_move?: TFile)" + +[[tp.file.functions.move.args]] +name = "new_path" +description = "The new vault relative path of the file, without the file extension. Note: the new path needs to include the folder and the filename, e.g. `\"/Notes/MyNote\"`." + +[[tp.file.functions.move.args]] +name = "file_to_move" +description = "The file to move, defaults to the current file." + +[[tp.file.functions.move.examples]] +name = "File move" +example = """<% await tp.file.move("/A/B/" + tp.file.title) %>""" + +[[tp.file.functions.move.examples]] +name = "File move and rename" +example = """<% await tp.file.move("/A/B/NewTitle") %>""" + +[tp.file.functions.path] +name = "path" +description = "Retrieves the file's absolute path on the system." +definition = "tp.file.path(relative: boolean = false)" + +[[tp.file.functions.path.args]] +name = "relative" +description = "If set to `true`, only retrieves the vault's relative path." + +[[tp.file.functions.path.examples]] +name = "File path" +example = "<% tp.file.path() %>" + +[[tp.file.functions.path.examples]] +name = "File relative path (relative to vault root)" +example = "<% tp.file.path(true) %>" + +[tp.file.functions.rename] +name = "rename" +description = "Renames the file (keeps the same file extension)." +definition = "tp.file.rename(new_title: string)" + +[[tp.file.functions.rename.args]] +name = "new_title" +description = "The new file title." + +[[tp.file.functions.rename.examples]] +name = "File rename" +example = """<% await tp.file.rename("MyNewName") %>""" + +[[tp.file.functions.rename.examples]] +name = "File append a 2 to the file name" +example = """<% await tp.file.rename(tp.file.title + "2") %>""" + +[tp.file.functions.selection] +name = "selection" +description = "Retrieves the active file's text selection." +definition = "tp.file.selection()" + +[[tp.file.functions.selection.examples]] +name = "File selection" +example = "<% tp.file.selection() %>" + +[tp.file.functions.tags] +name = "tags" +description = "Retrieves the file's tags (array of string)." +definition = "tp.file.tags" + +[[tp.file.functions.tags.examples]] +name = "File tags" +example = "<% tp.file.tags %>" + +[tp.file.functions.title] +name = "title" +definition = "tp.file.title" +description = "Retrieves the file's title." + +[[tp.file.functions.title.examples]] +name = "File title" +example = "<% tp.file.title %>" + +[[tp.file.functions.title.examples]] +name = "Strip the Zettelkasten ID of title (if space separated)" +example = """<% tp.file.title.split(" ")[1] %>""" + + + +[tp.frontmatter] +name = "frontmatter" +description = "This modules exposes all the frontmatter variables of a file as variables." + + + +[tp.hooks] +name = "hooks" +description = "This module exposes hooks that allow you to execute code when a Templater event occurs." + +[tp.hooks.functions.on_all_templates_executed] +name = "on_all_templates_executed" +description = """Hooks into when all actively running templates have finished executing. Most of the time this will be a single template, unless you are using `tp.file.include` or `tp.file.create_new`. + +Multiple invokations of this method will have their callback functions run in parallel.""" +definition = "tp.hooks.on_all_templates_executed(callback_function: () => any)" + +[[tp.hooks.functions.on_all_templates_executed.args]] +name = "callback_function" +description = "Callback function that will be executed when all actively running templates have finished executing." + + + +[tp.obsidian] +name = "obsidian" +description = "This module exposes all the functions and classes from the Obsidian API." + + +[tp.system] +name = "system" +description = "This module contains system related functions." + +[tp.system.functions.clipboard] +name = "clipboard" +description = "Retrieves the clipboard's content." +definition = "tp.system.clipboard()" + +[[tp.system.functions.clipboard.examples]] +name = "Clipboard" +example = "<% tp.system.clipboard() %>" + +[tp.system.functions.prompt] +name = "prompt" +description = "Spawns a prompt modal and returns the user's input." +definition = "tp.system.prompt(prompt_text?: string, default_value?: string, throw_on_cancel: boolean = false, multiline?: boolean = false)" + +[[tp.system.functions.prompt.args]] +name = "prompt_text" +description = "Text placed above the input field." + +[[tp.system.functions.prompt.args]] +name = "default_value" +description = "A default value for the input field." + +[[tp.system.functions.prompt.args]] +name = "throw_on_cancel" +description = "Throws an error if the prompt is canceled, instead of returning a `null` value." + +[[tp.system.functions.prompt.args]] +name = "multiline" +description = "If set to `true`, the input field will be a multiline textarea. Defaults to `false`." + +[[tp.system.functions.prompt.examples]] +name = "Prompt" +example = """<% tp.system.prompt("Please enter a value") %>""" + +[[tp.system.functions.prompt.examples]] +name = "Prompt with default value" +example = """<% tp.system.prompt("What is your mood today?", "happy") %>""" + +[[tp.system.functions.prompt.examples]] +name = "Multiline prompt" +example = """<% tp.system.prompt("What is your mood today?", null, false, true) %>""" + +[tp.system.functions.suggester] +name = "suggester" +description = "Spawns a suggester prompt and returns the user's chosen item." +definition = "tp.system.suggester(text_items: string[] ⎮ ((item: T) => string), items: T[], throw_on_cancel: boolean = false, placeholder: string = \"\", limit?: number = undefined)" + +[[tp.system.functions.suggester.args]] +name = "text_items" +description = "Array of strings representing the text that will be displayed for each item in the suggester prompt. This can also be a function that maps an item to its text representation." + +[[tp.system.functions.suggester.args]] +name = "items" +description = "Array containing the values of each item in the correct order." + +[[tp.system.functions.suggester.args]] +name = "throw_on_cancel" +description = "Throws an error if the prompt is canceled, instead of returning a `null` value." + +[[tp.system.functions.suggester.args]] +name = "placeholder" +description = "Placeholder string of the prompt." + +[[tp.system.functions.suggester.args]] +name = "limit" +description = "Limit the number of items rendered at once (useful to improve performance when displaying large lists)." + +[[tp.system.functions.suggester.examples]] +name = "Suggester" +example = """<% tp.system.suggester(["Happy", "Sad", "Confused"], ["Happy", "Sad", "Confused"]) %>""" + +[[tp.system.functions.suggester.examples]] +name = "Suggester with mapping function (same as above example)" +example = """<% tp.system.suggester((item) => item, ["Happy", "Sad", "Confused"]) %>""" + +[[tp.system.functions.suggester.examples]] +name = "Suggester for files" +example = """[[<% (await tp.system.suggester((item) => item.basename, app.vault.getMarkdownFiles())).basename %>]]""" + +[[tp.system.functions.suggester.examples]] +name = "Suggester for tags" +example = """<% tp.system.suggester(item => item, Object.keys(app.metadataCache.getTags()).map(x => x.replace("#", ""))) %>""" + +[tp.web] +name = "web" +description = "This modules contains every internal function related to the web (making web requests)." + +[tp.web.functions.daily_quote] +name = "daily_quote" +description = "Retrieves and parses the daily quote from `https://github.com/Zachatoo/quotes-database` as a callout." +definition = "tp.web.daily_quote()" + +[[tp.web.functions.daily_quote.examples]] +name = "Daily quote" +example = "<% tp.web.daily_quote() %>" + +[tp.web.functions.random_picture] +name = "random_picture" +description = "Gets a random image from `https://unsplash.com/`." +definition = "tp.web.random_picture(size?: string, query?: string, include_size?: boolean)" + +[[tp.web.functions.random_picture.args]] +name = "size" +description = "Image size in the format `x`." + +[[tp.web.functions.random_picture.args]] +name = "query" +description = "Limits selection to photos matching a search term. Multiple search terms can be passed separated by a comma." + +[[tp.web.functions.random_picture.args]] +name = "include_size" +description = "Optional argument to include the specified size in the image link markdown. Defaults to false." + +[[tp.web.functions.random_picture.examples]] +name = "Random picture" +example = "<% tp.web.random_picture() %>" + +[[tp.web.functions.random_picture.examples]] +name = "Random picture with size" +example = """<% tp.web.random_picture("200x200") %>""" + +[[tp.web.functions.random_picture.examples]] +name = "Random picture with size and query" +example = """<% tp.web.random_picture("200x200", "landscape,water") %>""" + +[tp.web.functions.request] +name = "request" +description = "Makes a HTTP request to the specified URL. Optionally, you can specify a path to extract specific data from the response." +definition = "tp.web.request(url: string, path?: string)" + +[[tp.web.functions.request.args]] +name = "url" +description = "The URL to which the HTTP request will be made." + +[[tp.web.functions.request.args]] +name = "path" +description = "A path within the response JSON to extract specific data." + +[[tp.web.functions.request.examples]] +name = "Simple request" +example = """<% tp.web.request("https://jsonplaceholder.typicode.com/todos/1") %>""" + +[[tp.web.functions.request.examples]] +name = "Request with path" +example = """<% tp.web.request("https://jsonplaceholder.typicode.com/todos", "0.title") %>""" + + diff --git a/docs_zh/src/SUMMARY.md b/docs_zh/src/SUMMARY.md new file mode 100644 index 00000000..227f52c5 --- /dev/null +++ b/docs_zh/src/SUMMARY.md @@ -0,0 +1,26 @@ +# 目录 + +- [简介](./introduction.md) + - [安装](./installation.md) + - [术语](./terminology.md) + - [语法](./syntax.md) + - [设置](./settings.md) + - [常见问题](./faq.md) +- [内置函数](./internal-functions/overview.md) + - [tp.app](./internal-functions/internal-modules/app-module.md) + - [tp.config](./internal-functions/internal-modules/config-module.md) + - [tp.date](./internal-functions/internal-modules/date-module.md) + - [tp.file](./internal-functions/internal-modules/file-module.md) + - [tp.frontmatter](./internal-functions/internal-modules/frontmatter-module.md) + - [tp.hooks](./internal-functions/internal-modules/hooks-module.md) + - [tp.obsidian](./internal-functions/internal-modules/obsidian-module.md) + - [tp.system](./internal-functions/internal-modules/system-module.md) + - [tp.web](./internal-functions/internal-modules/web-module.md) + - [贡献](./internal-functions/contribute.md) +- [用户函数](./user-functions/overview.md) + - [用户脚本](./user-functions/script-user-functions.md) + - [系统命令](./user-functions/system-user-functions.md) +- [命令](./commands/overview.md) + - [动态命令](./commands/dynamic-command.md) + - [执行命令](./commands/execution-command.md) + - [空白控制](./commands/whitespace-control.md) \ No newline at end of file diff --git a/docs_zh/src/commands/dynamic-command.md b/docs_zh/src/commands/dynamic-command.md new file mode 100644 index 00000000..e6a8b611 --- /dev/null +++ b/docs_zh/src/commands/dynamic-command.md @@ -0,0 +1,23 @@ +# 动态命令 + +通过这个命令工具,您可以将命令声明为"动态的",这意味着此命令将在进入预览模式时解析。 + +要声明动态命令,请在命令开始标签后添加加号`+`:`<%+` + +就是这样,您的命令现在将只在预览模式下执行。 + +这对于像`tp.file.last_modified_date`这样的内置函数很有用,例如: + +```javascript +最后修改日期:<%+ tp.file.last_modified_date() %> +``` + +**注意**:动态命令存在已知问题,并且可能不会在未来继续维护(有关更多详细信息,请参阅[此问题](https://github.com/SilentVoid13/Templater/issues/913))。在大多数情况下,建议使用[Dataview](https://github.com/blacksmithgu/obsidian-dataview)插件作为替代方案。 + +## 刷新问题 + +预览模式的一个"缺点"是它将渲染后的笔记放入缓存中,以加快速度。 + +这意味着您的动态命令将只在您打开笔记时渲染一次,但之后不会刷新。 + +如果您想刷新它,必须关闭笔记以清除缓存,然后再次打开它。 \ No newline at end of file diff --git a/docs_zh/src/commands/execution-command.md b/docs_zh/src/commands/execution-command.md new file mode 100644 index 00000000..6ff61a2a --- /dev/null +++ b/docs_zh/src/commands/execution-command.md @@ -0,0 +1,60 @@ +# JavaScript执行命令 + +这种类型的命令允许我们执行JavaScript代码。 + +通过JavaScript执行命令,我们几乎可以做JavaScript允许我们做的所有事情。下面给出了一些示例。 + +我们仍然可以从这种类型的命令中访问`tp`对象和所有内置变量/函数。 + +JavaScript执行命令允许您访问全局命名空间变量。这意味着您可以访问诸如`app`或`moment`之类的内容。 + +## 异步函数 + +某些内置函数是异步的。在JavaScript执行命令中调用此类函数时,如有必要,不要忘记使用`await`关键字。 + +## 如何从JavaScript执行命令输出值? + +有时,您可能希望在使用JS执行命令时输出某些内容。 + +当我们的模板引擎使用所有命令结果生成替换字符串时,它存储在名为`tR`的变量中。这个字符串将包含处理后的文件内容。您可以从JS执行命令访问该变量。 + +这意味着,要从JS执行命令输出内容,您只需要将要输出的内容附加到`tR`字符串变量上。 + +例如,以下命令:`<%* tR += "测试" %>`将输出`测试`。 + +### 建议器和提示 + +重要的是要注意`tp.system.prompt()`和`tp.system.suggester()`都需要`await`语句才能将值保存到变量中 + +## 示例 + +以下是使用JavaScript执行命令可以做的一些事情的示例: + +```javascript +<%* if (tp.file.title.startsWith("Hello")) { %> +这是一个hello文件! +<%* } else { %> +这是一个普通文件! +<%* } %> + +<%* if (tp.frontmatter.type === "seedling") { %> +这是一个seedling文件! +<%* } else { %> +这是一个普通文件! +<%* } %> + +<%* if (tp.file.tags.contains("#todo")) { %> +这是一个待办事项文件! +<%* } else { %> +这是一个已完成文件! +<%* } %> + +<%* +function log(msg) { + console.log(msg); +} +%> +<%* log("标题: " + tp.file.title) %> + +<%* tR += tp.file.content.replace(/stuff/, "things"); %> +``` \ No newline at end of file diff --git a/docs_zh/src/commands/overview.md b/docs_zh/src/commands/overview.md new file mode 100644 index 00000000..e0000701 --- /dev/null +++ b/docs_zh/src/commands/overview.md @@ -0,0 +1,17 @@ +# 命令 + +## 命令类型 + +[Templater](https://github.com/SilentVoid13/Templater) 定义了2种开始标签,它们定义了2种**命令**: + +- `<%`: 插值命令。它将输出其中表达式的结果。 +- `<%*`: [JavaScript执行命令](./execution-command.md)。它将执行其中的JavaScript代码。默认情况下不输出任何内容。 + +命令的结束标签始终相同:`%>` + +## 命令工具 + +除了不同类型的命令外,您还可以使用命令工具。它们也在命令的开始标签中声明。所有命令工具适用于所有命令类型。可用的命令工具有: + +- [空白控制](./whitespace-control.md) +- [动态命令](./dynamic-command.md) \ No newline at end of file diff --git a/docs_zh/src/commands/whitespace-control.md b/docs_zh/src/commands/whitespace-control.md new file mode 100644 index 00000000..4921b56a --- /dev/null +++ b/docs_zh/src/commands/whitespace-control.md @@ -0,0 +1,52 @@ +# 空白控制 + +默认情况下,Templater中的**命令**不会删除任何换行符。命令被替换为它们的值,仅此而已。 + +有时候在插入命令后控制一些空白非常有用,这正是此命令工具提供的功能。 + +让我们看一个例子。以下模板: + +``` +<%* if (tp.file.title == "MyFile" ) { %> +这是我的文件! +<%* } else { %> +这不是我的文件! +<%* } %> +一些内容... +``` + +如果条件为假(当条件为真时也一样),将产生以下输出,注意空行: + +``` + +这不是我的文件! + +一些内容... +``` + +您可能想要删除由**执行命令**产生的空行,这些命令不会产生任何输出。 + +空白控制有一种特定的语法: + +- 标签**开头**的下划线`_`(`<%_`)将修剪命令**之前**的**所有**空白 +- 标签**结尾**的下划线`_`(`_%>`)将修剪命令**之后**的**所有**空白 +- 标签**开头**的破折号`-`(`<%-`)将修剪命令**之前**的**一个**换行符 +- 标签**结尾**的破折号`-`(`-%>`)将修剪命令**之后**的**一个**换行符 + +在我们的例子中,要修复我们的模板以删除空行,我们将使用以下模板(注意标签末尾的破折号`-`),以删除执行命令**之后**的空行: + +``` +<%* if (tp.file.title == "MyFile" ) { -%> +这是我的文件! +<%* } else { -%> +这不是我的文件! +<%* } -%> +一些内容... +``` + +这将产生以下输出: + +``` +这不是我的文件! +一些内容... +``` \ No newline at end of file diff --git a/docs_zh/src/faq.md b/docs_zh/src/faq.md new file mode 100644 index 00000000..3720895f --- /dev/null +++ b/docs_zh/src/faq.md @@ -0,0 +1,11 @@ +# 常见问题 + +## Windows系统下Unicode字符(表情符号等)无法正常工作? + +Windows上的`cmd.exe`和`powershell`已知存在Unicode字符问题。 + +您可以查看 https://github.com/SilentVoid13/Templater/issues/15#issuecomment-824067020 寻找解决方案。 + +另一个好的解决方案(可能是最佳方案)是使用 [Windows Terminal](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701) 并在Templater的设置中将其设置为默认shell。 + +另一个包含可能适合您的解决方案的资源:[https://stackoverflow.com/questions/49476326/displaying-unicode-in-powershell](https://stackoverflow.com/questions/49476326/displaying-unicode-in-powershell) \ No newline at end of file diff --git a/docs_zh/src/imgs/templater_user_templates.png b/docs_zh/src/imgs/templater_user_templates.png new file mode 100644 index 00000000..0e72a5c0 Binary files /dev/null and b/docs_zh/src/imgs/templater_user_templates.png differ diff --git a/docs_zh/src/installation.md b/docs_zh/src/installation.md new file mode 100644 index 00000000..8f11c29b --- /dev/null +++ b/docs_zh/src/installation.md @@ -0,0 +1,5 @@ +# 安装 + +您可以通过Obsidian内的社区插件标签页安装此插件。搜索"Templater"。 + +安装[Templater](https://github.com/SilentVoid13/Templater)后重启Obsidian应用是一个好习惯,以确保一切正常工作。 \ No newline at end of file diff --git a/docs_zh/src/internal-functions/contribute.md b/docs_zh/src/internal-functions/contribute.md new file mode 100644 index 00000000..d0927c01 --- /dev/null +++ b/docs_zh/src/internal-functions/contribute.md @@ -0,0 +1,90 @@ +# 贡献 + +您可以通过开发新的内置函数/变量来为[Templater](https://github.com/SilentVoid13/Templater)做出贡献。 + +开发新功能的过程非常简单。 + +请记住,只有相关的提交才会被接受,不要提交只有您自己会使用的非常特定的内置变量/函数。 + +## 布局 + +内置变量/函数按模块分类。每个模块在[src/InternalTemplates](https://github.com/SilentVoid13/Templater/tree/master/src/InternalTemplates)下都有专门的文件夹。 + +让我们以[date模块](https://github.com/SilentVoid13/Templater/tree/master/src/InternalTemplates/date)为例。 + +它包含一个[InternalModuleDate](https://github.com/SilentVoid13/Templater/blob/master/src/core/functions/internal_functions/date/InternalModuleDate.ts)文件,其中定义并注册了所有与日期相关的内置变量和函数: + +```typescript +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](https://github.com/SilentVoid13/Templater/blob/master/src/core/functions/internal_functions/InternalModule.ts)抽象类,这意味着它们包含以下属性和方法: + +- `this.app`属性:Obsidian API的`App`对象。 +- `this.file`属性:模板将被插入的目标文件。 +- `this.plugin`属性:Templater插件对象。 +- `this.static_templates`属性:包含所有静态(名称;变量/函数)的映射。静态变量/函数意味着它在执行时不依赖于文件。每次插入新模板时,这类变量/函数不会更新,以节省开销。 +- `this.dynamic_templates`属性:与`static_templates`相同,只是它包含执行时依赖于文件的变量/函数。 +- `this.createStaticTemplates()`方法:注册该模块的所有静态内置变量/函数。 +- `this.updateTemplates()`方法:注册该模块的所有动态内置变量/函数。 + +如果需要,您可以在新的内置变量/函数中使用这些属性。 + +## 注册新的内置变量/函数 + +以下是注册模块中新内置变量/函数的不同步骤。 + +**第1步:**在模块内创建一个名为`generate_<内置变量或函数名>()`的方法,该方法将生成您的内置变量/函数,这意味着它将返回lambda函数(表示内置函数)或直接返回您想要暴露的内置变量。 + +所有生成方法按照内置变量/函数名称的字母顺序排序。 + +尝试为您的变量/函数提供一个好的、自解释的名称。 + +**第2步:**根据您的内置变量/函数在执行时是否依赖于文件,在`static_templates`或`dynamic_templates`映射中注册它。注册发生在`createStaticTemplates`或`updateTemplates`中。 + +要注册您的变量/函数,请使用您之前定义的`this.generate_<内置变量或函数名>()`方法: + +```typescript +this.static_templates.set(<内置变量或函数名>, this.generate_<内置变量或函数名>()); +或 +this.dynamic_templates.set(<内置变量或函数名>, this.generate_<内置变量或函数名>()); +``` + +内置变量/函数注册也按变量/函数名称的字母顺序排序。 + +**第3步:**将您的内置变量/函数文档添加到Templater的[文档](https://github.com/SilentVoid13/Templater/tree/master/docs/docs/internal-variables-functions/internal-modules)中。 + +完成了!感谢您为[Templater](https://github.com/SilentVoid13/Templater)做出贡献! + +现在,只需在Github上提交一个[拉取请求](https://github.com/SilentVoid13/Templater/pulls),我会尽可能快地做出反应。 \ No newline at end of file diff --git a/docs_zh/src/internal-functions/internal-modules/app-module.md b/docs_zh/src/internal-functions/internal-modules/app-module.md new file mode 100644 index 00000000..1a09c025 --- /dev/null +++ b/docs_zh/src/internal-functions/internal-modules/app-module.md @@ -0,0 +1,26 @@ +# App模块 + +App模块提供对Obsidian App对象的访问,允许您使用Obsidian的核心功能。 + +这主要在编写脚本时有用。 + +更多信息请参考Obsidian的[开发者文档](https://docs.obsidian.md/Reference/TypeScript+API/App)。 + +## 示例 + +```javascript +// 获取所有文件夹 +<% +tp.app.vault.getAllLoadedFiles() + .filter(x => x instanceof tp.obsidian.TFolder) + .map(x => x.name) +%> + +// 更新现有文件的frontmatter +<%* +const file = tp.file.find_tfile("path/to/file"); +await tp.app.fileManager.processFrontMatter(file, (frontmatter) => { + frontmatter["key"] = "value"; +}); +%> +``` \ No newline at end of file diff --git a/docs_zh/src/internal-functions/internal-modules/config-module.md b/docs_zh/src/internal-functions/internal-modules/config-module.md new file mode 100644 index 00000000..c94d8c41 --- /dev/null +++ b/docs_zh/src/internal-functions/internal-modules/config-module.md @@ -0,0 +1,23 @@ +# Config模块 + +Config模块允许您访问和更新Templater的配置设置。 + + + +## 文档 + +### `tp.config.active_file_template` + +获取当前活动文件模板的相对路径。 + +### `tp.config.template_file` + +获取当前执行模板文件的相对路径。 + +### `tp.config.target_file` + +获取目标文件的相对路径(模板将应用到该文件)。 + +### `tp.config.tR` + +检索与当前上下文相关的模板结果对象(tR)。 \ No newline at end of file diff --git a/docs_zh/src/internal-functions/internal-modules/date-module.md b/docs_zh/src/internal-functions/internal-modules/date-module.md new file mode 100644 index 00000000..45acaa63 --- /dev/null +++ b/docs_zh/src/internal-functions/internal-modules/date-module.md @@ -0,0 +1,167 @@ +# Date模块 + +日期模块包含与日期和时间相关的函数。 + + + +## 文档 + +函数文档使用特定语法。更多信息[在此](../../syntax.md#函数文档语法)。 + +### `tp.date.now(format, offset, reference, reference_format)` + +返回当前日期和时间。 + +##### 参数 + +- `format`: 日期的输出格式。默认为"YYYY-MM-DD"。 +- `offset`: 从当前日期开始的偏移量(可以是正数或负数)。默认为0。 +- `reference`: 参考日期,偏移量将从该日期计算而不是当前日期。默认为null。 +- `reference_format`: 参考日期的输入格式。默认为null。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.date.now() %> + +// 自定义格式 +<% tp.date.now("Do MMMM YYYY") %> + +// 带偏移量 +<% tp.date.now("dddd Do MMMM YYYY", 7) %> + +// 使用参考日期 +<% tp.date.now("dddd Do MMMM YYYY", 0, "2021-04-09") %> + +// 使用参考日期和格式 +<% tp.date.now("YYYY-MM-DD", 0, "2021-04-09", "YYYY-MM-DD") %> +``` + +### `tp.date.tomorrow(format)` + +返回明天的日期。 + +##### 参数 + +- `format`: 日期的输出格式。默认为"YYYY-MM-DD"。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.date.tomorrow() %> + +// 自定义格式 +<% tp.date.tomorrow("Do MMMM YYYY") %> +``` + +### `tp.date.weekday(format, weekday, reference, reference_format)` + +返回特定的工作日。 + +##### 参数 + +- `format`: 日期的输出格式。默认为"YYYY-MM-DD"。 +- `weekday`: 工作日的数字(0-6,0表示星期日)。默认为1(星期一)。 +- `reference`: 参考日期,将返回最接近参考日期的工作日。默认为null。 +- `reference_format`: 参考日期的输入格式。默认为null。 + +##### 示例 + +```javascript +// 基本用法(默认星期一) +<% tp.date.weekday() %> + +// 星期三 +<% tp.date.weekday("YYYY-MM-DD", 3) %> + +// 从参考日期开始的星期一 +<% tp.date.weekday("YYYY-MM-DD", 1, "2021-04-09") %> + +// 从参考日期开始的星期天 +<% tp.date.weekday("YYYY-MM-DD", 0, "2021-04-09", "YYYY-MM-DD") %> +``` + +### `tp.date.yesterday(format)` + +返回昨天的日期。 + +##### 参数 + +- `format`: 日期的输出格式。默认为"YYYY-MM-DD"。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.date.yesterday() %> + +// 自定义格式 +<% tp.date.yesterday("Do MMMM YYYY") %> +``` + +## Moment.js + +Templater提供了对`moment`对象的访问,可以使用它的所有功能。 + +关于moment.js的更多信息[在此](https://momentjs.com/docs/#/displaying/)。 + +##### 示例 + +```javascript +// 当前日期,格式为YYYY-MM-DD +<% moment().format("YYYY-MM-DD") %> + +// 当前日期,使用"星期几,月份+日 年份"的格式 +<% moment().format("dddd, MMMM Do YYYY") %> + +// 7天前的日期 +<% moment().subtract(7, 'days').format("YYYY-MM-DD") %> + +// 一个月后的日期,使用自定义格式 +<% moment().add(1, 'month').format("YYYY-MM-DD") %> +``` + +## 示例 + +```javascript +// 基本用法 +<% tp.date.now() %> + +// 自定义格式 +<% tp.date.now("Do MMMM YYYY") %> + +// 带偏移量 +<% tp.date.now("dddd Do MMMM YYYY", 7) %> + +// 使用参考日期 +<% tp.date.now("dddd Do MMMM YYYY", 0, "2021-04-09") %> + +// 使用参考日期和格式 +<% tp.date.now("YYYY-MM-DD", 0, "2021-04-09", "YYYY-MM-DD") %> + +// 基本用法(默认星期一) +<% tp.date.weekday() %> + +// 星期三 +<% tp.date.weekday("YYYY-MM-DD", 3) %> + +// 从参考日期开始的星期一 +<% tp.date.weekday("YYYY-MM-DD", 1, "2021-04-09") %> + +// 从参考日期开始的星期天 +<% tp.date.weekday("YYYY-MM-DD", 0, "2021-04-09", "YYYY-MM-DD") %> + +// 基本用法 +<% tp.date.yesterday() %> + +// 自定义格式 +<% tp.date.yesterday("Do MMMM YYYY") %> + +// 基本用法 +<% tp.date.tomorrow() %> + +// 自定义格式 +<% tp.date.tomorrow("Do MMMM YYYY") %> +``` \ No newline at end of file diff --git a/docs_zh/src/internal-functions/internal-modules/file-module.md b/docs_zh/src/internal-functions/internal-modules/file-module.md new file mode 100644 index 00000000..7a872ebf --- /dev/null +++ b/docs_zh/src/internal-functions/internal-modules/file-module.md @@ -0,0 +1,345 @@ +# File模块 + +File模块包含与当前文件和文件系统相关的函数和属性。 + + + +## 文档 + +函数文档使用特定语法。更多信息[在此](../../syntax.md#函数文档语法)。 + +### `tp.file.content` + +获取当前文件的全部内容。 + +### `tp.file.create_new(template, filename, open_new, folder)` + +使用指定的模板创建一个新文件。 + +##### 参数 + +- `template`: 要使用的模板路径(相对于模板文件夹)。 +- `filename`: 新文件的文件名。 +- `open_new`: 创建后是否打开新文件。默认为true。 +- `folder`: 新文件的目标文件夹(相对于保险库根目录)。默认为当前文件所在文件夹。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.file.create_new("my_template", "MyFile") %> + +// 不打开新文件 +<% tp.file.create_new("my_template", "MyFile", false) %> + +// 指定目标文件夹(即保险库根目录下的"target_folder"文件夹) +<% tp.file.create_new("my_template", "MyFile", true, "target_folder") %> + +// 指定目标文件夹(当前文件所在文件夹的子文件夹"target_folder") +<% tp.file.create_new("my_template", "MyFile", true, "./target_folder") %> +``` + +### `tp.file.creation_date(format)` + +获取文件的创建日期。 + +##### 参数 + +- `format`: 日期的输出格式。默认为"YYYY-MM-DD"。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.file.creation_date() %> + +// 自定义格式 +<% tp.file.creation_date("dddd Do MMMM YYYY HH:mm") %> +``` + +### `tp.file.cursor(order)` + +在渲染后将光标放置在特定位置。 + +##### 参数 + +- `order`: 决定光标放置的顺序(如果有多个光标)。默认为1。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.file.cursor() %> + +// 指定顺序 +<% tp.file.cursor(2) %> +``` + +### `tp.file.cursor_append(content)` + +在光标位置追加内容。 + +##### 参数 + +- `content`: 要追加的内容。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.file.cursor_append("追加的内容") %> +``` + +### `tp.file.exists(filename)` + +检查文件是否存在。 + +##### 参数 + +- `filename`: 要检查的文件名(绝对路径或相对于保险库根目录的路径)。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.file.exists("MyFile.md") %> + +// 使用绝对路径 +<% tp.file.exists("C:\\Path\\To\\MyFile.md") %> +``` + +### `tp.file.find_tfile(filename)` + +通过名称查找一个TFile对象。 + +##### 参数 + +- `filename`: 文件名(绝对路径或相对于保险库根目录的路径)。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.file.find_tfile("MyFile.md") %> +``` + +### `tp.file.folder(relative)` + +获取文件所在的文件夹路径。 + +##### 参数 + +- `relative`: 是否返回相对于保险库根目录的路径。默认为false。 + +##### 示例 + +```javascript +// 绝对路径 +<% tp.file.folder() %> + +// 相对路径 +<% tp.file.folder(true) %> +``` + +### `tp.file.include(include_link)` + +包含另一个文件的内容。 + +##### 参数 + +- `include_link`: 要包含的文件链接(可以是文件名、相对路径或Wiki链接)。 + +##### 示例 + +```javascript +// 使用文件名 +<% tp.file.include("MyFile") %> + +// 使用Wiki链接 +<% tp.file.include("[[MyFile]]") %> +``` + +### `tp.file.last_modified_date(format)` + +获取文件的最后修改日期。 + +##### 参数 + +- `format`: 日期的输出格式。默认为"YYYY-MM-DD"。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.file.last_modified_date() %> + +// 自定义格式 +<% tp.file.last_modified_date("dddd Do MMMM YYYY HH:mm") %> +``` + +### `tp.file.move(new_path, file_to_move)` + +将文件移动到新位置。 + +##### 参数 + +- `new_path`: 新的文件路径(相对于保险库根目录)。 +- `file_to_move`: 要移动的文件(TFile对象)。如果未提供,则使用当前文件。 + +##### 示例 + +```javascript +// 移动当前文件 +<% tp.file.move("target_folder/new_name") %> + +// 移动指定文件 +<% tp.file.move("target_folder/new_name", tp.file.find_tfile("MyFile.md")) %> +``` + +### `tp.file.path(relative)` + +获取文件的路径。 + +##### 参数 + +- `relative`: 是否返回相对于保险库根目录的路径。默认为false。 + +##### 示例 + +```javascript +// 绝对路径 +<% tp.file.path() %> + +// 相对路径 +<% tp.file.path(true) %> +``` + +### `tp.file.rename(new_title)` + +重命名当前文件。 + +##### 参数 + +- `new_title`: 文件的新标题/名称。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.file.rename("新文件名") %> +``` + +### `tp.file.selection()` + +获取当前选择的文本。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.file.selection() %> +``` + +### `tp.file.tags` + +获取文件的标签列表。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.file.tags %> +``` + +### `tp.file.title` + +获取当前文件的标题(不带扩展名)。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.file.title %> +``` + +## 示例 + +```javascript +// 基本用法 +<% tp.file.creation_date() %> + +// 自定义格式 +<% tp.file.creation_date("dddd Do MMMM YYYY HH:mm") %> + +// 基本用法 +<% tp.file.cursor() %> + +// 指定顺序 +<% tp.file.cursor(2) %> + +// 基本用法 +<% tp.file.cursor_append("追加的内容") %> + +// 基本用法 +<% tp.file.exists("MyFile.md") %> + +// 使用绝对路径 +<% tp.file.exists("C:\\Path\\To\\MyFile.md") %> + +// 基本用法 +<% tp.file.find_tfile("MyFile.md") %> + +// 绝对路径 +<% tp.file.folder() %> + +// 相对路径 +<% tp.file.folder(true) %> + +// 使用文件名 +<% tp.file.include("MyFile") %> + +// 使用Wiki链接 +<% tp.file.include("[[MyFile]]") %> + +// 基本用法 +<% tp.file.last_modified_date() %> + +// 自定义格式 +<% tp.file.last_modified_date("dddd Do MMMM YYYY HH:mm") %> + +// 移动当前文件 +<% tp.file.move("target_folder/new_name") %> + +// 移动指定文件 +<% tp.file.move("target_folder/new_name", tp.file.find_tfile("MyFile.md")) %> + +// 绝对路径 +<% tp.file.path() %> + +// 相对路径 +<% tp.file.path(true) %> + +// 基本用法 +<% tp.file.rename("新文件名") %> + +// 基本用法 +<% tp.file.selection() %> + +// 基本用法 +<% tp.file.tags %> + +// 基本用法 +<% tp.file.title %> + +// 基本用法 +<% tp.file.create_new("my_template", "MyFile") %> + +// 不打开新文件 +<% tp.file.create_new("my_template", "MyFile", false) %> + +// 指定目标文件夹(即保险库根目录下的"target_folder"文件夹) +<% tp.file.create_new("my_template", "MyFile", true, "target_folder") %> + +// 指定目标文件夹(当前文件所在文件夹的子文件夹"target_folder") +<% tp.file.create_new("my_template", "MyFile", true, "./target_folder") %> +``` \ No newline at end of file diff --git a/docs_zh/src/internal-functions/internal-modules/frontmatter-module.md b/docs_zh/src/internal-functions/internal-modules/frontmatter-module.md new file mode 100644 index 00000000..a3ebac9a --- /dev/null +++ b/docs_zh/src/internal-functions/internal-modules/frontmatter-module.md @@ -0,0 +1,52 @@ +# Frontmatter模块 + +这个模块允许您访问当前文件的frontmatter变量。 + + + +## 文档 + +### `tp.frontmatter.` + +获取文件frontmatter变量的值。 + +如果您的frontmatter变量名称包含空格,可以使用方括号表示法引用它,如下所示: + +```` +<% tp.frontmatter["包含空格的变量名"] %> +```` + +## 示例 + +假设您有以下文件: + +```` +--- +alias: myfile +note type: seedling +--- + +文件内容 +```` + +那么您可以使用以下模板: + +```` +文件元数据别名:<% tp.frontmatter.alias %> +笔记类型:<% tp.frontmatter["note type"] %> +```` + +对于frontmatter中的列表,您可以使用JavaScript数组原型方法来操作数据的显示方式。 + +``` +--- +categories: + - book + - movie +--- +``` + +``` +<% tp.frontmatter.categories.map(prop => ` - "${prop}"`).join("\n") %> +``` +` \ No newline at end of file diff --git a/docs_zh/src/internal-functions/internal-modules/hooks-module.md b/docs_zh/src/internal-functions/internal-modules/hooks-module.md new file mode 100644 index 00000000..9d1dba16 --- /dev/null +++ b/docs_zh/src/internal-functions/internal-modules/hooks-module.md @@ -0,0 +1,37 @@ +# Hooks模块 + +Hooks模块允许您在特定事件发生时注册回调函数。 + + + +## 文档 + +函数文档使用特定语法。更多信息[在此](../../syntax.md#函数文档语法)。 + +### `tp.hooks.on_all_templates_executed(callback)` + +当当前活动文件中的所有模板都已执行完毕时调用。 + +##### 参数 + +- `callback`: 在所有模板执行完毕后要调用的回调函数。 + +## 示例 + +```javascript +// 模板执行完成后更新frontmatter +<%* +tp.hooks.on_all_templates_executed(async () => { + const file = tp.file.find_tfile(tp.file.path(true)); + await tp.app.fileManager.processFrontMatter(file, (frontmatter) => { + frontmatter["key"] = "value"; + }); +}); +%> +// Templater更新文件后,从另一个插件运行修改当前文件的命令 +<%* +tp.hooks.on_all_templates_executed(() => { + tp.app.commands.executeCommandById("obsidian-linter:lint-file"); +}); +-%> +``` \ No newline at end of file diff --git a/docs_zh/src/internal-functions/internal-modules/obsidian-module.md b/docs_zh/src/internal-functions/internal-modules/obsidian-module.md new file mode 100644 index 00000000..4d008f1d --- /dev/null +++ b/docs_zh/src/internal-functions/internal-modules/obsidian-module.md @@ -0,0 +1,30 @@ +# Obsidian模块 + +Obsidian模块提供对Obsidian API的访问,允许您使用Obsidian的内部功能。 + +这主要在编写脚本时有用。 + +更多信息请参考Obsidian API的[声明文件](https://github.com/obsidianmd/obsidian-api/blob/master/obsidian.d.ts)。 + +## 示例 + +```javascript +// 获取所有文件夹 +<% +tp.app.vault.getAllLoadedFiles() + .filter(x => x instanceof tp.obsidian.TFolder) + .map(x => x.name) +%> + +// 规范化路径 +<% tp.obsidian.normalizePath("Path/to/file.md") %> + +// HTML转Markdown +<% tp.obsidian.htmlToMarkdown("\

标题\

\

段落\

") %> + +// HTTP请求 +<%* +const response = await tp.obsidian.requestUrl("https://jsonplaceholder.typicode.com/todos/1"); +tR += response.json.title; +%> +``` \ No newline at end of file diff --git a/docs_zh/src/internal-functions/internal-modules/system-module.md b/docs_zh/src/internal-functions/internal-modules/system-module.md new file mode 100644 index 00000000..eac741f6 --- /dev/null +++ b/docs_zh/src/internal-functions/internal-modules/system-module.md @@ -0,0 +1,94 @@ +# System模块 + +System模块包含与系统交互相关的函数,例如复制到剪贴板、显示提示或创建建议器。 + + + +## 文档 + +函数文档使用特定语法。更多信息[在此](../../syntax.md#函数文档语法)。 + +### `tp.system.clipboard()` + +返回剪贴板的内容。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.system.clipboard() %> +``` + +### `tp.system.prompt(prompt_text, default_value, throw_on_cancel, multiline)` + +显示一个提示窗口,要求用户输入内容。 + +##### 参数 + +- `prompt_text`: 显示给用户的提示文本。 +- `default_value`: 提示中的默认值。默认为空字符串。 +- `throw_on_cancel`: 如果为true,当用户取消提示时抛出错误。默认为false。 +- `multiline`: 如果为true,显示多行输入框。默认为false。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.system.prompt("请输入文本") %> + +// 带默认值 +<% tp.system.prompt("请输入文本", "默认值") %> + +// 多行输入 +<% tp.system.prompt("请输入多行文本", "", false, true) %> +``` + +### `tp.system.suggester(text_items, items, throw_on_cancel, placeholder, limit)` + +显示一个带有自动完成功能的建议器,让用户从列表中选择一个项目。 + +##### 参数 + +- `text_items`: 要向用户显示的文本项目数组。 +- `items`: 选择相应文本项目时返回的值数组。默认为`text_items`。 +- `throw_on_cancel`: 如果为true,当用户取消建议器时抛出错误。默认为false。 +- `placeholder`: 建议器的占位符文本。默认为空字符串。 +- `limit`: 要显示的项目数量限制。默认为无限制。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.system.suggester(["选项1", "选项2", "选项3"], ["值1", "值2", "值3"]) %> + +// 使用相同的文本和值 +<% tp.system.suggester(["值1", "值2", "值3"]) %> + +// 带有占位符 +<% tp.system.suggester(["选项1", "选项2", "选项3"], ["值1", "值2", "值3"], false, "请选择一个选项") %> +``` + +## 示例 + +```javascript +// 基本用法 +<% tp.system.clipboard() %> + +// 基本用法 +<% tp.system.prompt("请输入文本") %> + +// 带默认值 +<% tp.system.prompt("请输入文本", "默认值") %> + +// 多行输入 +<% tp.system.prompt("请输入多行文本", "", false, true) %> + +// 基本用法 +<% tp.system.suggester(["选项1", "选项2", "选项3"], ["值1", "值2", "值3"]) %> + +// 使用相同的文本和值 +<% tp.system.suggester(["值1", "值2", "值3"]) %> + +// 带有占位符 +<% tp.system.suggester(["选项1", "选项2", "选项3"], ["值1", "值2", "值3"], false, "请选择一个选项") %> +``` \ No newline at end of file diff --git a/docs_zh/src/internal-functions/internal-modules/web-module.md b/docs_zh/src/internal-functions/internal-modules/web-module.md new file mode 100644 index 00000000..86802374 --- /dev/null +++ b/docs_zh/src/internal-functions/internal-modules/web-module.md @@ -0,0 +1,59 @@ +# Web模块 + +Web模块提供与网络资源交互的功能,允许您获取网页内容或生成URL。 + + + +## 文档 + +函数文档使用特定语法。更多信息[在此](../../syntax.md#函数文档语法)。 + +### `tp.web.daily_quote()` + +从https://api.quotable.io/random获取每日名言。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.web.daily_quote() %> +``` + +### `tp.web.random_picture(size, query, provider)` + +从Unsplash获取随机图片。 + +##### 参数 + +- `size`: 图片尺寸,格式为"宽度x高度",例如"200x300"。 +- `query`: 搜索查询,以获取特定类型的图片。 +- `provider`: 提供商,目前只支持"unsplash"。 + +##### 示例 + +```javascript +// 基本用法 +<% tp.web.random_picture() %> + +// 指定尺寸 +<% tp.web.random_picture("200x200") %> + +// 使用查询 +<% tp.web.random_picture("200x200", "nature") %> +``` + +## 示例 + +```javascript +// 基本用法 +<% tp.web.daily_quote() %> + +// 基本用法 +<% tp.web.random_picture() %> + +// 指定尺寸 +<% tp.web.random_picture("200x200") %> + +// 使用查询 +<% tp.web.random_picture("200x200", "nature") %> +``` \ No newline at end of file diff --git a/docs_zh/src/internal-functions/overview.md b/docs_zh/src/internal-functions/overview.md new file mode 100644 index 00000000..7b9a1492 --- /dev/null +++ b/docs_zh/src/internal-functions/overview.md @@ -0,0 +1,19 @@ +# 内置函数 + +[Templater](https://github.com/SilentVoid13/Templater) 提供的不同内置变量和函数分布在不同的**模块**中,以便对它们进行分类。现有的**内置模块**有: + +- [App模块](./internal-modules/app-module.md): `tp.app` +- [Config模块](./internal-modules/config-module.md): `tp.config` +- [Date模块](./internal-modules/date-module.md): `tp.date` +- [File模块](./internal-modules/file-module.md): `tp.file` +- [Frontmatter模块](./internal-modules/frontmatter-module.md): `tp.frontmatter` +- [Hooks模块](./internal-modules/hooks-module.md): `tp.hooks` +- [Obsidian模块](./internal-modules/obsidian-module.md): `tp.obsidian` +- [System模块](./internal-modules/system-module.md): `tp.system` +- [Web模块](./internal-modules/web-module.md): `tp.web` + +如果您正确理解了[对象层次结构](../syntax.md#对象层次结构),这意味着一个典型的内置函数调用看起来像这样:`<% tp.<模块名>.<内置函数名> %>` + +## 贡献 + +我邀请每个人通过添加新的内置函数来为这个插件的开发做出贡献。更多信息请点击[这里](./contribute.md)。 \ No newline at end of file diff --git a/docs_zh/src/introduction.md b/docs_zh/src/introduction.md new file mode 100644 index 00000000..da87d0ff --- /dev/null +++ b/docs_zh/src/introduction.md @@ -0,0 +1,38 @@ +# 简介 + +[Templater](https://github.com/SilentVoid13/Templater) 是一种模板语言,允许你在笔记中插入**变量**和**函数**的结果。它还允许你执行JavaScript代码来操作这些变量和函数。 + +通过 [Templater](https://github.com/SilentVoid13/Templater),你将能够创建强大的模板来自动化手动任务。 + +## 快速示例 + +以下是使用 [Templater](https://github.com/SilentVoid13/Templater) 语法的模板文件: + +```javascript +--- +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. +> — Maya Angelou +```` \ No newline at end of file diff --git a/docs_zh/src/settings.md b/docs_zh/src/settings.md new file mode 100644 index 00000000..870b07d5 --- /dev/null +++ b/docs_zh/src/settings.md @@ -0,0 +1,57 @@ +# 设置 + +## 常规设置 + +- `模板文件夹位置`:此文件夹中的文件将作为模板可用。 +- `桌面端语法高亮` 在编辑模式下为 [Templater](https://github.com/SilentVoid13/Templater) 命令添加语法高亮。 +- `移动端语法高亮` 在移动端编辑模式下为 [Templater](https://github.com/SilentVoid13/Templater) 命令添加语法高亮。谨慎使用:这可能会破坏移动平台上的实时预览。 +- `自动跳转到光标位置` 在插入模板后自动触发 `tp.file.cursor`。您也可以设置热键手动触发 `tp.file.cursor`。 +- `在新建文件时触发Templater`:[Templater](https://github.com/SilentVoid13/Templater) 将监听新文件创建事件,如果匹配您设置的规则,将替换在新文件内容中找到的每个命令。这使 [Templater](https://github.com/SilentVoid13/Templater) 与其他插件兼容,如每日笔记核心插件、日历插件、复习插件、笔记重构插件等。 + - 确保在下面的文件夹模板或文件正则表达式模板中设置规则。 + - **警告:** 如果您在创建时创建具有未知/不安全内容的新文件,这可能会很危险。确保每个新文件在创建时的内容都是安全的。 + +## 模板热键 + +模板热键允许您将模板绑定到热键。 + +## 文件夹模板 + +**注意**:默认情况下,此设置是隐藏的。要查看它,首先启用 `在新建文件时触发模板` 设置。由于它与文件正则表达式模板互斥,启用一个将禁用另一个。 + +您可以使用 `文件夹模板` 功能为选定的文件夹和子文件夹指定将自动使用的模板。将使用最深层的匹配,因此规则的顺序无关紧要。 + +如果需要全部捕获,可以为 "`/`" 添加规则。 + +## 文件正则表达式模板 + +**注意**:默认情况下,此设置是隐藏的。要查看它,首先启用 `在新建文件时触发模板` 设置。由于它与文件夹模板互斥,启用一个将禁用另一个。 + +您可以指定新文件路径将测试的正则表达式声明。如果正则表达式匹配,将自动使用关联的模板。规则按从上到下的顺序测试,并使用第一个匹配项。 + +如果需要全部捕获,最后添加一个 "`.*`" 规则。 + +使用 [Regex101](https://regex101.com/) 等工具验证您的正则表达式。 + +## 启动模板 + +启动模板是Templater启动时将执行一次的模板。 + +这些模板不会输出任何内容。 + +这对于设置添加到Obsidian事件的钩子的模板非常有用。 + +## 用户脚本函数 + +此文件夹中的所有JavaScript文件将作为CommonJS模块加载,以导入自定义[用户函数](./user-functions/overview.md)。 + +该文件夹需要从保管库访问。 + +查看[文档](./user-functions/script-user-functions.md)了解更多信息。 + +## 用户系统命令函数 + +允许您创建与系统命令关联的[用户函数](./user-functions/overview.md)。 + +查看[文档](./user-functions/system-user-functions.md)了解更多信息。 + +**警告:** 从不受信任的来源执行任意系统命令可能很危险。只运行您理解的、来自可信来源的系统命令。 \ No newline at end of file diff --git a/docs_zh/src/syntax.md b/docs_zh/src/syntax.md new file mode 100644 index 00000000..1e26f3c9 --- /dev/null +++ b/docs_zh/src/syntax.md @@ -0,0 +1,96 @@ +# 语法 + +[Templater](https://github.com/SilentVoid13/Templater) 使用自定义模板引擎([rusty_engine](https://github.com/SilentVoid13/rusty_engine))语法来声明命令。您可能需要一些时间来适应它,但一旦理解了基本概念,这种语法并不难掌握。 + +Templater的所有函数都是JavaScript对象,通过**命令**调用。 + +## 命令语法 + +命令**必须**同时包含开始标签`<%`和结束标签`%>`。 + +使用`tp.date.now`内置函数的完整命令示例:`<% tp.date.now() %>` + +## 函数语法 + +### 对象层次结构 + +Templater的所有函数,无论是内置函数还是用户函数,都在`tp`对象下可用。可以说所有函数都是`tp`对象的子对象。要访问对象的"子对象",我们需要使用点表示法`.`。 + +这意味着Templater函数调用总是以`tp.`开始。 + +#### 函数调用 + +要调用函数,我们需要使用函数调用的特定语法:在函数名后附加一个开括号和一个闭括号。 + +例如,我们使用`tp.date.now()`来调用`tp.date.now`内置函数。 + +函数可以有参数和可选参数。它们放在开括号和闭括号之间,如下所示: + +```javascript +tp.date.now(arg1_value, arg2_value, arg3_value, ...) +``` + +所有参数必须按正确顺序传递。 + +函数的参数可以有不同的**类型**。以下是函数可能的类型的非详尽列表: + +- `string`类型表示值必须放在单引号或双引号内(`"value"`或`'value'`) +- `number`类型表示值必须是整数(`15`、`-5`等) +- `boolean`类型表示值必须是`true`或`false`(完全小写),不能是其他值。 + +调用函数时必须遵守参数的类型,否则函数将无法正常工作。 + +### 函数文档语法 + +Templater内置函数的文档使用以下语法: + +```javascript +tp.(arg1_name: type, arg2_name?: type, arg3_name: type = , arg4_name: type1|type2, ...) +``` + +其中: + +- `arg_name`表示参数的**符号性**名称,以便理解其用途。 +- `type`表示参数的预期类型。调用内置函数时必须遵守此类型,否则会抛出错误。 + +如果参数是可选的,它将附加一个问号`?`,例如`arg2_name?: type` + +如果参数有默认值,它将使用等号`=`指定,例如`arg3_name: type = `。 + +如果参数可以有不同的类型,它将使用管道符号`|`指定,例如`arg4_name: type1|type2` + +#### 语法警告 + +请注意,此语法仅用于文档目的,以便能够理解函数期望的参数。 + +调用函数时,您不必指定参数的名称、类型或默认值。如[此处](./syntax.md#函数调用)所述,只需要参数的值。 + +##### 示例 + +以`tp.date.now`内置函数文档为例: + +``` +tp.date.now(format?: string = "YYYY-MM-DD", offset?: number|string, reference?: string, reference_format?: string) +``` + +这个内置函数有4个可选参数: + +- 类型为`string`的format,默认值为`"YYYY-MM-DD"`。 +- 类型为`number`或`string`的offset。 +- 类型为`string`的reference。 +- 类型为`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)` +- `tp.date.now(format = "YYYY-MM-DD")` +- `tp.date.now(offset: 7)` +- `tp.date.now(tp.file.title)` \ No newline at end of file diff --git a/docs_zh/src/terminology.md b/docs_zh/src/terminology.md new file mode 100644 index 00000000..cd9a7c8c --- /dev/null +++ b/docs_zh/src/terminology.md @@ -0,0 +1,22 @@ +# 术语 + +在Templater中,我们使用以下术语: + +- **命令**:一个由开始标签`<%`和结束标签`%>`包围的代码块,例如`<% tp.date.now() %>`。命令是用户与Templater交互的基本方式。 + +- **内置函数**:Templater预定义的函数,用于执行特定任务,如`tp.date.now()`、`tp.file.title`等。这些函数按功能分组到不同的模块中。 + +- **用户函数**:用户自定义的函数,可以是JavaScript脚本或系统命令。 + +- **变量**:存储值的容器,如`tp`(Templater的主对象)或`tR`(模板结果)。 + +### 示例 + +以下模板包含2个命令,调用2个不同的内置函数: + +``` +昨天: <% tp.date.yesterday("YYYY-MM-DD") %> +明天: <% tp.date.tomorrow("YYYY-MM-DD") %> +``` + +我们将在下一部分看到编写命令所需的语法。 \ No newline at end of file diff --git a/docs_zh/src/user-functions/overview.md b/docs_zh/src/user-functions/overview.md new file mode 100644 index 00000000..ce22c166 --- /dev/null +++ b/docs_zh/src/user-functions/overview.md @@ -0,0 +1,22 @@ +# 用户函数 + +您可以在Templater中定义自己的函数。 + +您可以使用两种类型的用户函数: + +- [脚本用户函数](./script-user-functions.md) +- [系统命令用户函数](./system-user-functions.md) + +## 调用用户函数 + +您可以使用常规的函数调用语法调用用户函数:`tp.user.<用户函数名>()`,其中`<用户函数名>`是您定义的函数名。 + +例如,如果您定义了一个名为`echo`的系统命令用户函数,完整的命令调用将如下所示: + +```js +<% tp.user.echo() %> +``` + +## 无移动端支持 + +目前,用户函数在Obsidian移动版上不可用。 \ No newline at end of file diff --git a/docs_zh/src/user-functions/script-user-functions.md b/docs_zh/src/user-functions/script-user-functions.md new file mode 100644 index 00000000..bab2e7cd --- /dev/null +++ b/docs_zh/src/user-functions/script-user-functions.md @@ -0,0 +1,61 @@ +# 脚本用户函数 + +这种类型的用户函数允许您从JavaScript文件中调用JavaScript函数并获取其输出。 + +要使用脚本用户函数,您需要在Templater的设置中指定一个脚本文件夹。该文件夹需要可以从您的保管库访问。 + +## 定义脚本用户函数 + +假设您在Templater的设置中将`Scripts`文件夹指定为脚本文件夹。 + +Templater将加载`Scripts`文件夹中的所有JavaScript(`.js`文件)脚本。 + +然后您可以创建名为`Scripts/my_script.js`的脚本(需要`.js`扩展名)。您可能需要在Obsidian外部创建该文件,因为Obsidian只创建markdown文件。 + +然后您将能够将您的脚本作为用户函数调用。函数名对应于脚本文件名。 + +脚本应遵循[CommonJS模块规范](https://flaviocopes.com/commonjs/),并导出单个函数。 + +```javascript +function my_function (msg) { + return `来自我的脚本的消息: ${msg}`; +} +module.exports = my_function; +``` + +在此示例中,完整的命令调用如下所示: + +```javascript +<% tp.user.my_script("Hello World!") %> +``` + +这将输出`来自我的脚本的消息: Hello World!`。 + +## 全局命名空间 + +在脚本用户函数中,您仍然可以访问全局命名空间变量,如`app`或`moment`。 + +但是,您不能访问模板引擎作用域变量,如`tp`或`tR`。如果您想使用它们,必须将它们作为参数传递给您的函数。 + +## 函数参数 + +您可以根据函数的定义方式向函数传递任意数量的参数。 + +例如,您可以将`tp`对象传递给您的函数,以便能够使用Templater的所有[内置变量/函数](../internal-functions/overview.md):`<% tp.user.<用户函数名>(tp) %>` + +## 用户脚本文档 + +您可以选择使用[TSDoc标准](https://tsdoc.org/)在方法文件的**顶部**记录脚本的功能。如果提供,这将为您的用户脚本提供类似intellisense的体验,类似于其他templater函数的体验。 + +### 带文档的用户脚本示例 + +```javascript +/** + * 这会做一些很酷的事情 + */ +function doSomething() { + console.log('完成了某事') +} + +module.exports = doSomething; +``` \ No newline at end of file diff --git a/docs_zh/src/user-functions/system-user-functions.md b/docs_zh/src/user-functions/system-user-functions.md new file mode 100644 index 00000000..09723570 --- /dev/null +++ b/docs_zh/src/user-functions/system-user-functions.md @@ -0,0 +1,33 @@ +# 系统命令用户函数 + +这种类型的用户函数允许您执行系统命令并获取其输出。 + +系统命令用户函数需要在Templater的设置中启用。 + +## 定义系统命令用户函数 + +要定义新的系统命令用户函数,您需要定义一个**函数名**,并与**系统命令**关联。 + +为此,请转到插件设置并点击`添加用户函数`。 + +完成后,[Templater](https://github.com/SilentVoid13/Templater)将创建一个以您定义的名称命名的用户函数,该函数将执行您的系统命令并返回其输出。 + +与内置函数一样,用户函数在`tp` JavaScript对象下可用,更具体地说是在`tp.user`对象下。 + +![用户模板](../imgs/templater_user_templates.png) + +## 函数参数 + +您可以向用户函数传递可选参数。它们必须作为单个JavaScript对象传递,该对象包含属性及其对应的值:`{arg1: value1, arg2: value2, ...}`。 + +这些参数将以[环境变量](https://en.wikipedia.org/wiki/Environment_variable)的形式提供给您的程序/脚本。 + +在我们之前的示例中,这将给出以下命令声明:`<% tp.user.echo({a: "值 1", b: "值 2"})>`。 + +如果我们的系统命令调用bash脚本,我们将能够使用`$a`和`$b`访问变量`a`和`b`。 + +## 系统命令中的内置函数 + +您可以在系统命令中使用内置函数。内置函数将在系统命令执行前被替换。 + +例如,如果您配置了系统命令`cat <% tp.file.path() %>`,在系统命令执行前,它将被替换为`cat /path/to/file`。 \ No newline at end of file