Obsidian Modal Form Plugin

此插件适用于 Obsidian，允许你定义表单，这些表单可以在任何可以运行 JavaScript 的地方打开，因此你可以将其与 Templater 或 QuickAdd 等其他插件结合使用。

https://github.com/danielo515/obsidian-modal-form/assets/2270425/542974aa-c58b-4733-89ea-9c20ea11bee9

功能

• 表单在模态窗口中打开并返回其值，因此你可以从以下位置触发它：
  • Templater 模板
  • QuickAdd 捕获
  • DataviewJS 查询
  • 许多其他位置...
• 使用简单的 JSON 格式定义表单
• 创建并管理一组表单，每个表单由唯一的名称标识
• 用于创建新表单的用户界面
• 使用模板直接从表单创建新笔记
  • 模板编辑器具有用于创建模板的精美 UI
• 为你的表单注册命令： 从命令面板即时触发任何表单（带模板）——对于简单用例，无需 QuickAdd 或外部模板
• 多种输入类型
  • 数字
  • 日期
  • 时间
  • 滑块
  • 切换（true/false）
  • 自由文本
  • 带有笔记名称自动补全的文本（来自文件夹或根目录）
  • 带有来自 dataview 查询自动补全的文本（需要 dataview 插件）
  • 多选输入
  • 从列表中选择
    • 固定值列表
    • 来自文件夹的笔记列表

模板构建器

我们提供了一个精美的 UI，帮助你创建所需的模板。

为什么选择此插件？

Obsidian 是一款出色的笔记工具，同时也非常适合管理数据。 然而，当需要捕获结构化数据时，它并未提供太多便利。 一些插件，如 Templater 或 QuickAdd，通过模板/自动化功能缓解了这一问题，使创建具有预定义结构的笔记变得更加轻松，但随后你仍需手动填写数据。 上述插件（Templater、QuickAdd）提供了一些便捷输入，但存在某些权衡/问题：

• 它们一次只能输入单个值
• 它们没有关于你所填写字段的标签或详细描述
• 你无法跳过字段，系统会逐一提示你填写所有字段

上述所有工具在其各自领域都表现出色，并解锁了超级便捷的工作流。 因此，与其提供一个替代方案，本插件旨在作为它们的补充，提供一些基本构建块，你可以将其集成到现有的模板和工作流中。

Modal Form 的朋友们

注意： 由于现在可以为你的表单注册命令，你不再需要仅为了触发表单而使用 QuickAdd。QuickAdd 在更高级的工作流中仍然有用，但对于简单的表单触发，Modal Forms 现在是一个完整的解决方案。

• Templater 用于从模板打开模态框
• QuickAdd 用于从模态框快速捕获数据
• dataview 用于为自动补全提供值

此插件的范围

此插件的范围刻意保持狭窄。如上一节所述，它被设计为一个构建模块，以便您可以将其与其他插件和工作流集成。 我唯一会考虑添加的功能将是那些关于改进表单本身的功能。

用法

从 JavaScript 调用表单

由于此插件的主要用途是打开表单并获取其数据，让我们从这一点开始。如果您想了解如何创建表单，请跳到下一节 定义表单。

该插件暴露了一个 API，可以从任何能够访问全局 app 对象的 JavaScript 代码中访问。因此，为了获取该 API，您可以执行以下操作：

const modalForm = app.plugins.plugins.modalforms.api;

从这里你可以调用 API 的任何主要方法，openForm 这允许你按名称打开表单并获取数据。让我们看一个示例：

const modalForm = app.plugins.plugins.modalforms.api;
const result = await modalForm.openForm("example-form");

结果是一种特殊的对象，包含表单的数据。 它还包含一些便捷的方法，帮助你处理返回的数据。 其中之一是 asFrontmatterString，它返回一个字符串形式的数据，可用于 frontmatter 块。让我们看一个使用 Templater 的示例：

与 Templater 配合使用

---
<%*
const modalForm = app.plugins.plugins.modalforms.api;
const result = await modalForm.openForm('example-form');
tR += result.asFrontmatterString();
-%>
---

当你在笔记中插入此模板时，它会打开表单，一旦你提交它，它会将数据作为 frontmatter 块插入到笔记中。

与 QuickAdd 配合使用

为了从 QuickAdd 捕获中打开表单，你需要创建一个捕获并激活捕获格式，然后在格式文本区域中，你必须创建一个语言定义为 js quickadd 的代码块，并复制以下代码：

```js quickadd
 const modalForm = app.plugins.plugins.modalforms.api;
 const result = await modalForm.openForm('example-form');
 return result.asDataviewProperties();
```

这里有一个示例截图，展示它应该是什么样子：

在打开表单时提供默认值

在打开表单时，你可以为表单字段提供默认值。这可以通过向 openForm 或 limitedForm 方法传递一个对象作为 FormOptions 参数的一部分来实现。该对象应具有与表单定义相同的结构，其中每个键对应一个字段名，其值是该字段的默认值。

以下是一个示例：

const values = {
    title: "My Default Title",
    description: "This is a default description.",
};

const modalForm = app.plugins.plugins.modalforms.api;
const result = await modalForm.openForm("example-form", { values: values });

在此示例中，表单打开时，title 字段将预填为 My Default Title，description 字段将预填为 This is a default description.。

注意：如果默认值对象中的某个字段在表单定义中不存在，它将被忽略。

FormResult 方法

当你打开一个表单时，你会得到一个 FormResult 对象。该对象包含表单的数据以及一些帮助你处理它的方法。 由 openForm 方法返回的此 FormResult 对象具有若干可用于处理表单数据的方法。以下是每个方法的简要说明：

asFrontmatterString()

此方法将表单数据返回为一个字符串，可用于 frontmatter 块中。它以 YAML 语法格式化数据。以下是使用示例：

asDataviewProperties()

此方法将表单数据返回为 dataview 属性的字符串。表单数据中的每个键值对都会转换为 key:: value 格式的字符串。以下是使用示例：

getData()

此方法返回表单数据的一个副本。当你需要操作表单数据而不影响原始数据时，可以使用它。

asString(template: string)

此方法返回格式化为字符串的表单数据，该字符串匹配所提供的模板。模板是一个字符串，可以包含格式为 {{key}} 的占位符，这些占位符将被替换为表单数据中对应的值。键周围的空白是允许的（{{ key }} 等同于 {{key}}），并且您可以通过附加 | transformation 来应用与表单模板支持的相同 transformations — 例如 {{ name | upper }} 或 {{ note | trim }}。未知的键将保持原样（字面量 {{ key }} 保留在输出中），因此拼写错误很容易发现。以下是在 templater 模板中使用它的示例：

<%*
const modalForm = app.plugins.plugins.modalforms.api;
const result = await modalForm.openForm('example-form');
tR += result.asString('{{name}} is {{age}} years old and his/her favorite food is {{favorite_meal}}. Family status: {{is_family}}');
-%>

高级用法

有关 FormResult 方法的高级用法，请参阅 FormResult 的具体文档 此处

定义表单

创建新表单

创建新表单很简单，您只需打开表单管理视图，可以通过点击功能区图标或使用命令面板（Obsidian modal form: New form）。 进入后，点击 + 按钮，您将看到一个用于创建命名表单定义的表单。 该表单不言自明，但以下是您需要牢记的几个关键点：

• 名称必须唯一，并且当您从 JavaScript 中打开表单时，它将用于识别该表单，区分大小写
• 标题是您在打开表单时将在模态窗口中看到的标题
• 除非所有字段均有效（即它们具有名称和类型），否则您将无法保存该表单

Dataview 集成

Modal Form 与 Dataview 集成，以在您的表单中提供强大的数据查询功能。您可以使用 Dataview 查询来：

• 创建带有来自您 vault 的建议的动态输入字段
• 基于表单数据在 document 和 markdown 块中生成动态内容
• 创建随着用户填写表单而更新的交互式预览

有关详细文档和示例，请参阅 Dataview 集成。

内联表单

该插件还支持内联表单，即在调用 openForm 方法时定义的表单。当您希望创建一个仅在一处使用且足够简单的表单时，这非常有用。但请注意，手动输入该格式略显冗长且容易出错，因此除非表单非常小，否则您很可能更倾向于使用命名表单。

以下是使用示例：

const modalForm = app.plugins.plugins.modalforms.api;
const result = await modalForm.openForm({
    title: "Example form",
    fields: [
        {
            name: "name",
            label: "Name",
            description: "Your name",
            input: { type: "text" },
        },
        {
            name: "age",
            label: "Age",
            description: "Your age",
            input: { type: "number" },
        },
        {
            name: "favorite_meal",
            label: "Favorite meal",
            description: "Your favorite meal",
            input: { type: "text" },
        },
        {
            name: "is_family",
            label: "Is family",
            type: "toggle",
            description: "Are you family?",
            required: true,
            input: { type: "toggle" },
        },
    ],
});

你可以通过移除一些可选字段（如 description 或 label）来使其更小，但我强烈建议你定义所有字段。

使用模板并通过命令触发表单

你可以使用模板来增强你的表单，从而根据表单响应生成动态笔记内容或插入文本。当你向表单添加模板时，你还可以注册专用命令，直接从 Obsidian 的命令面板触发该表单——无需额外的插件或脚本。

工作原理：

• 编辑表单并前往 Template 选项卡。
• 创建或编辑你的模板。
• 启用一个或两个命令选项：
  • “Create command to insert template”：允许你在提交表单后将模板输出插入到当前笔记中。
  • “Create command to create note from template”：允许你在表单提交后从模板创建新笔记。
• 保存模板。命令将被注册，并作为以下内容在命令面板中可用：
  • Modal Forms: Insert template: [Form Name]
  • Modal Forms: Create note from template: [Form Name]

这使得通过命令在任何地方触发表单并使用其模板变得轻而易举——非常适合快速创建笔记或结构化数据捕获。

有关模板语法和高级功能的详细信息，请参阅 Templates 文档。

技巧与窍门

• 如何更便捷地打开表单

安装插件

你可以直接从 Obsidian 插件商店或通过 BRAT 安装该插件。

使用 BRAT 安装

1. 安装 BRAT 插件（GitHub 页面）并启用它。
2. 打开命令面板并运行命令 BRAT: Add a beta plugin for testing。
3. 在模态框中输入 https://github.com/danielo515/obsidian-modal-form 并按下 Add Plugin 按钮。
4. 返回设置并导航到 Community plugins 选项卡。
5. 启用该插件。

手动安装插件

• 将 main.js、styles.css、manifest.json 复制到你的 vault VaultFolder/.obsidian/plugins/modalForm/。

如何开发

• 克隆此仓库。
• 确保你的 NodeJS 版本至少为 v16（node --version）。
• 运行 npm i 或 yarn 以安装依赖项。
• 运行 npm run dev 以启动 watch 模式下的编译。

发布新版本

• 在 manifest.json 中手动更新 minAppVersion 后，运行 npm version patch、npm version minor 或 npm version major。
• 将文件 manifest.json、main.js、styles.css 作为二进制附件上传。注意：manifest.json 文件必须存在于两个位置，首先是你的仓库根路径，其次是发布版本中。
• 发布该版本。

命令 npm version whatever 会更新 manifest.json 和 package.json 中的版本号，并在 versions.json 中添加新版本的条目

发布文档

我们使用 mkdocs 来生成文档。 要发布文档，请运行：

./build-docs.sh