Logseq 插件 API

通过其 JavaScript 插件 API 与您的本地 Logseq 实例交互。此功能支持在您的 Logseq 图谱中进行读取、写入、查询和自动化工作流。

前提条件

Logseq 必须在本地运行并且需要一个暴露该 API 的插件。标准方式是：

1. 安装一个桥接插件该插件通过 HTTP 暴露logseqAPI（例如，通过自定义插件或本地主机端点）
2. 替代方案：使用 Node.js 搭配@logseq/libs包来针对正在运行的 Logseq 实例编写脚本

该 API 主要设计用于浏览器内插件，因此从外部脚本访问它需要一个桥接器/代理。

核心 API 命名空间

Logseq 插件 API 主要组织为以下几个代理：

logseq.App

应用级操作：获取应用信息、用户配置、当前图谱、命令、UI 状态、外部链接。

关键方法：

• 获取应用信息()- 获取应用版本与信息
• 获取用户配置()- 获取用户偏好设置（主题、格式、语言等）
• 获取当前图谱()- 获取当前图谱信息（名称、路径、URL）
• 注册命令(类型, 选项, 操作)- 注册自定义命令
• 推送状态(路由, 参数, 查询)- 导航至路由

logseq.Editor

区块与页面编辑操作：创建、更新、移动、查询内容。

关键方法：

• 获取区块(UUID)- 通过UUID获取区块
• 获取当前页面()- 获取当前页面实体
• 获取当前页面区块树()- 获取当前页面的所有区块
• 获取页面区块树(页面)- 获取指定页面的所有区块
• 插入区块(目标, 内容, 选项)- 插入新块
• updateBlock(uuid, content)- 更新块内容
• createPage(pageName, properties, opts)- 创建新页面
• deletePage(pageName)- 删除页面
• getPageLinkedReferences(page)- 获取页面的反向链接
• registerSlashCommand(tag, action)- 添加自定义斜杠命令

logseq.DB

使用Datalog进行数据库查询。

关键方法：

• q(query, ...inputs)- 运行Datalog查询
• datascriptQuery(query, ...inputs)- 直接Datascript查询

logseq.UI

UI操作：消息、对话框、主UI可见性。

关键方法：

• showMsg(content, status)- 显示通知提示
• queryElementById(id)- 查询DOM元素

logseq.Git

针对当前图谱的Git操作。

关键方法：

• execCommand(args)- 执行git命令

logseq.Assets

资产管理。

关键方法：

• listFilesOfCurrentGraph(path)- 列出图谱中的文件

常见工作流

读取内容

// Get current page
const page = await logseq.Editor.getCurrentPage();

// Get all blocks on a page
const blocks = await logseq.Editor.getPageBlocksTree('Daily Notes');

// Get a specific block
const block = await logseq.Editor.getBlock('block-uuid-here');

// Query with Datalog
const results = await logseq.DB.q(`
  [:find (pull ?b [*])
   :where [?b :block/marker "TODO"]]
`);

写入内容

// Create a new page
await logseq.Editor.createPage('Project Notes', {
  tags: 'project',
  status: 'active'
}, { redirect: false });

// Insert a block
const block = await logseq.Editor.insertBlock(
  'target-block-uuid',
  '- New task item',
  { before: false, sibling: true }
);

// Update a block
await logseq.Editor.updateBlock('block-uuid', 'Updated content');

// Batch insert multiple blocks
const blocks = [
  { content: 'First item' },
  { content: 'Second item', children: [
    { content: 'Nested item' }
  ]}
];
await logseq.Editor.insertBatchBlock('parent-uuid', blocks, { sibling: false });

任务管理

// Find all TODO items
const todos = await logseq.DB.q(`
  [:find (pull ?b [*])
   :where
   [?b :block/marker ?marker]
   [(contains? #{"TODO" "DOING"} ?marker)]]
`);

// Mark task as DONE
await logseq.Editor.updateBlock('task-uuid', 'DONE Task content');

// Get tasks on current page
const page = await logseq.Editor.getCurrentPage();
const blocks = await logseq.Editor.getPageBlocksTree(page.name);
const tasks = blocks.filter(b => b.marker === 'TODO' || b.marker === 'DOING');

导航与用户界面

// Navigate to a page
logseq.App.pushState('page', { name: 'Project Notes' });

// Show notification
logseq.UI.showMsg('✅ Task completed!', 'success');

// Get app config
const configs = await logseq.App.getUserConfigs();
console.log('Theme:', configs.preferredThemeMode);
console.log('Format:', configs.preferredFormat);

实现方案

由于Logseq的插件API基于浏览器，您有以下几种选择：

方案一：桥接插件

创建一个轻量级的Logseq插件，通过HTTP暴露API调用：

// In Logseq plugin (index.js)
logseq.ready(() => {
  // Expose API endpoints
  logseq.provideModel({
    async handleAPICall({ method, args }) {
      return await logseq.Editor[method](...args);
    }
  });
});

// Then call from external script via HTTP POST

方案二：使用 @logseq/libs 的 Node.js 脚本

对于自动化脚本，请使用@logseq/libs包：

npm install @logseq/libs

注意：这需要一个正在运行的 Logseq 实例以及正确的连接设置。

选项 3：直接插件开发

按照以下插件示例开发完整的 Logseq 插件：https://github.com/logseq/logseq-plugin-samples

API 参考

完整的 API 文档请参见：

• API 文档：https://logseq.github.io/plugins/
• 插件示例：https://github.com/logseq/logseq-plugin-samples
• 类型定义：references/api-types.md（提取自@logseq/libs）

关键数据结构

BlockEntity

{
  id: number,           // Entity ID
  uuid: string,         // Block UUID
  content: string,      // Block content
  format: 'markdown' | 'org',
  page: { id: number }, // Parent page
  parent: { id: number }, // Parent block
  left: { id: number }, // Previous sibling
  properties: {},       // Block properties
  marker?: string,      // TODO/DOING/DONE
  children?: []         // Child blocks
}

PageEntity

{
  id: number,
  uuid: string,
  name: string,              // Page name (lowercase)
  originalName: string,       // Original case
  'journal?': boolean,
  properties: {},
  journalDay?: number,       // YYYYMMDD for journals
}

提示与最佳实践

1. 始终检查空值: 如果实体不存在，API方法可能返回空值优先使用UUID而非ID
2. : 区块UUID是稳定的，而实体ID可能会改变批量操作
3. : 进行多次插入时，请使用insertBatchBlock高效查询: Datalog查询功能强大，但在大型图上可能较慢
4. 属性是对象: 通过
5. block.properties.propertyName访问格式很重要
6. : 尊重用户偏好的格式（Markdown与Org-mode）全程异步
7. : 所有API调用都返回Promise常见陷阱

Common Gotchas

• 页面名称使用小写: 查询时，请使用小写的页面名称
• 日记页面: 使用journalDay格式（YYYYMMDD），而非日期字符串
• 块层级关系: 插入时请遵循父/子关系
• 格式差异: Markdown 使用-作为项目符号，Org 使用*
• 属性语法: Markdown（prop::）和 Org（:PROPERTIES:）之间存在差异