QuickAdd API 深度解析：Obsidian自动化脚本开发指南-CSDN博客

QuickAdd API 深度解析：Obsidian自动化脚本开发指南

quickadd QuickAdd for Obsidian 项目地址: https://gitcode.com/gh_mirrors/qu/quickadd

概述

QuickAdd 是一款强大的 Obsidian 插件，而其 API 则为开发者提供了自动化操作 Obsidian 的完整接口。通过这套 API，用户可以创建复杂的脚本、宏和内联脚本，实现从简单的文本处理到复杂的知识管理流程自动化。

API 访问方式

QuickAdd API 可以通过多种方式调用，适应不同场景的需求：

在 QuickAdd 脚本中使用（宏/用户脚本）：

module.exports = async (params) => {
    const { quickAddApi, app, variables } = params;
    // 在此处使用 quickAddApi
};

在其他插件/脚本中调用：

const quickAddApi = app.plugins.plugins.quickadd.api;

在 Templater 脚本中集成：

<%*
const quickAddApi = app.plugins.plugins.quickadd.api;
const result = await quickAddApi.inputPrompt("请输入值:");
tR += result;
%>

用户交互方法详解

文本输入对话框

inputPrompt 和 wideInputPrompt 方法提供了灵活的文本输入功能：

inputPrompt：标准单行输入框
wideInputPrompt：宽版多行输入框

// 获取用户姓名
const userName = await quickAddApi.inputPrompt(
    "请输入您的姓名",
    "例如：张三",
    "默认姓名"
);

// 获取项目描述（多行）
const projectDesc = await quickAddApi.wideInputPrompt(
    "项目详细描述",
    "请详细描述项目目标、范围和要求...",
    "本项目旨在..."
);

确认对话框

yesNoPrompt 方法创建带有"是/否"选项的确认对话框：

const shouldDelete = await quickAddApi.yesNoPrompt(
    "确认删除笔记",
    "此操作不可撤销，请谨慎操作"
);

if (shouldDelete) {
    // 执行删除逻辑
}

信息展示对话框

infoDialog 用于向用户展示重要信息：

await quickAddApi.infoDialog(
    "操作完成",
    [
        "处理文件数: 15",
        "成功: 15",
        "失败: 0",
        "耗时: 3.2秒"
    ]
);

智能选择器

suggester 方法提供了强大的搜索选择功能：

// 简单选择
const fruit = await quickAddApi.suggester(
    ["🍎 苹果", "🍌 香蕉", "🍊 橙子"],
    ["apple", "banana", "orange"]
);

// 复杂对象选择
const tasks = [
    { id: 1, title: "任务1", priority: "高" },
    { id: 2, title: "任务2", priority: "低" }
];

const selectedTask = await quickAddApi.suggester(
    task => `${task.title} (${task.priority})`,
    tasks
);

多选对话框

checkboxPrompt 允许用户进行多项选择：

const selectedFeatures = await quickAddApi.checkboxPrompt(
    ["深色模式", "自动保存", "拼写检查", "行号显示"],
    ["自动保存", "行号显示"]  // 默认选中项
);

高级功能模块

日期处理

QuickAdd 提供了便捷的日期处理方法：

// 获取当前日期
const today = quickAddApi.date.now();  // "2024-01-15"

// 自定义格式
const timestamp = quickAddApi.date.now("YYYY年MM月DD日 HH时mm分ss秒");

// 带偏移量的日期
const nextWeek = quickAddApi.date.now("YYYY-MM-DD", 7);
const lastMonth = quickAddApi.date.now("YYYY-MM-DD", -30);

// 快捷方法
const yesterday = quickAddApi.date.yesterday();
const tomorrow = quickAddApi.date.tomorrow("dddd, MMMM D");

AI 集成

QuickAdd API 集成了强大的 AI 功能：

// 简单AI提示
const { summary } = await quickAddApi.ai.prompt(
    "总结以下文本: " + noteContent,
    "gpt-4",
    {
        variableName: "summary",
        modelOptions: {
            temperature: 0.3,
            max_tokens: 150
        }
    }
);

// 获取可用模型
const availableModels = quickAddApi.ai.getModels();

// 计算文本token数
const tokenCount = quickAddApi.ai.countTokens(longText, "gpt-4");

字段建议

快速获取知识库中已有字段值：

// 获取所有状态值
const statuses = await quickAddApi.fieldSuggestions.getFieldValues("status");

// 带过滤条件的字段查询
const projectTypes = await quickAddApi.fieldSuggestions.getFieldValues(
    "type",
    { folder: "projects", tags: ["active"] }
);

实战案例：研究助手

下面是一个结合多种API功能的完整示例：

module.exports = async (params) => {
    const { quickAddApi, app, variables } = params;
    
    try {
        // 获取研究主题
        const topic = await quickAddApi.inputPrompt("研究主题:");
        if (!topic) return;
        
        // 选择资料来源
        const sources = await quickAddApi.checkboxPrompt(
            ["网络搜索", "学术论文", "书籍", "视频"],
            ["网络搜索", "学术论文"]
        );
        
        // AI生成研究大纲
        const { outline } = await quickAddApi.ai.prompt(
            `为以下主题创建研究大纲: ${topic}`,
            "gpt-4",
            {
                variableName: "outline",
                modelOptions: { temperature: 0.7 }
            }
        );
        
        // 创建研究文件夹
        const folder = `研究/${topic}`;
        await app.vault.createFolder(folder);
        
        // 设置模板变量
        variables.topic = topic;
        variables.sources = sources.join(", ");
        variables.date = quickAddApi.date.now("YYYY-MM-DD HH:mm");
        variables.outline = outline;
        
        // 执行模板
        await quickAddApi.executeChoice("研究模板", variables);
        
        // 显示完成信息
        await quickAddApi.infoDialog(
            "研究项目已创建",
            [
                `主题: ${topic}`,
                `资料来源: ${sources.length} 项`,
                `位置: ${folder}`,
                "AI大纲已生成"
            ]
        );
        
    } catch (error) {
        console.error("研究助手错误:", error);
        await quickAddApi.infoDialog("错误", `发生错误: ${error.message}`);
    }
};

最佳实践与性能优化

错误处理：始终使用try-catch包裹API调用
输入验证：检查用户输入的有效性
批量操作：合理控制循环频率
缓存管理：适时清理字段建议缓存
性能监控：记录关键操作的执行时间

// 错误处理示例
module.exports = async (params) => {
    const { quickAddApi } = params;
    
    try {
        const input = await quickAddApi.inputPrompt("请输入值:");
        if (!input) return;  // 用户取消
        
        // 处理输入...
        
    } catch (error) {
        console.error("脚本错误:", error);
        await quickAddApi.infoDialog("错误", error.message);
    }
};