获取块面包屑 - 思源笔记 API 文档

接口描述

获取指定块 ID 的面包屑路径信息，即从其根节点（通常是文档）到该块自身的路径节点列表。

请求参数

参数名	类型	必选	描述
id	string	是	需要获取面包屑的块 ID。
excludeTypes	string[]	否	一个字符串数组，指定在面包屑路径中需要排除的块类型。例如，传入 `["d"]` 可以排除文档块节点。常见的类型缩写包括： `d`: 文档 (Document) `h`: 标题 (Heading) `l`: 列表 (List) `i`: 列表项 (ListItem) `p`: 段落 (Paragraph) `b`: 引述 (Blockquote) `t`: 表格 (Table) `c`: 代码块 (CodeBlock) `m`: 数学公式块 (MathBlock) `s`: 超级块 (SuperBlock) `html`: HTML 块 `av`: 属性视图 (AttributeView) 注意：此处的类型是内部类型表示，可能与前端显示或 `type` 字段的完整名称（如 `NodeDocument`）不同。

返回值

返回一个标准的 API 响应 JSON 对象。

字段名类型描述

code number 0 表示成功，非 0 表示失败。

msg string 如果失败，则包含错误信息。

data

BlockPath[] | null

一个对象数组 (BlockPath[])，按从根节点到目标节点的顺序排列。如果找不到块或发生错误，可能为 null 或空数组 []。
BlockPath 对象结构如下:

字段名	类型	描述
id	string	路径节点的块 ID。
name	string	路径节点的名称。通常是文档标题、标题内容或块的主要文本内容的缩略（经过 HTML 转义）。文档块的 name 可能是 "笔记本名/文档路径"。
type	string	路径节点的块类型 (例如 "NodeDocument", "NodeHeading", "NodeParagraph", "NodeListItem" 等)。
subType	string	路径节点的块子类型 (例如 "h1"-"h6" 对于标题, "task" 对于任务列表项)。
children	array	子路径数组 (在此 API 中通常为空数组 `[]`)。

请求示例

成功响应

失败响应 (Not Found)

失败响应 (Param Error)

请求示例

POST /api/block/getBlockBreadcrumb HTTP/1.1
Host: 127.0.0.1:6806
Content-Type: application/json
Authorization: Token your-api-token

{
  "id": "20231018102400-abcde1f",
  "excludeTypes": ["d"]
}

成功响应示例

{
   "code": 0,
   "msg": "",
   "data": [
     {
       "id": "20200811211906-nbe3hp1",
    
        需要认证
    

    接口描述
    获取指定块 ID 的面包屑路径信息，即从其根节点（通常是文档）到该块自身的路径节点列表。

    请求参数
    
        
            
                参数名
                类型
                必选
                描述
            
        
        
            
                id
                string
                是
                需要获取面包屑的块 ID。
            
            
                excludeTypes
                string[]
                否
                一个字符串数组，指定在面包屑路径中需要排除的块类型。例如，传入 `["d"]` 可以排除文档块节点。常见的类型缩写包括：
                    
                        d: 文档 (Document)
                        h: 标题 (Heading)
                        l: 列表 (List)
                        i: 列表项 (ListItem)
                        p: 段落 (Paragraph)
                        b: 引述 (Blockquote)
                        t: 表格 (Table)
                        c: 代码块 (CodeBlock)
                        m: 数学公式块 (MathBlock)
                        s: 超级块 (SuperBlock)
                        html: HTML 块
                        av: 属性视图 (AttributeView)
                    
                    注意：此处的类型是内部类型表示，可能与前端显示或 `type` 字段的完整名称（如 `NodeDocument`）不同。
                
            
        
    

    返回值
    返回一个标准的 API 响应 JSON 对象。
     
        
            
                字段名
                类型
                描述
            
        
        
            
                code
                number
                0 表示成功，非 0 表示失败。
            
            
                msg
                string
                如果失败，则包含错误信息。
            
            
                data
                BlockPath[] | null
                一个对象数组 (BlockPath[])，按从根节点到目标节点的顺序排列。如果找不到块或发生错误，可能为 null 或空数组 []。
                 
BlockPath 对象结构如下:
                    
                        字段名 类型 描述
                        
                            id string 路径节点的块 ID。
                            name string 路径节点的名称。通常是文档标题、标题内容或块的主要文本内容的缩略（经过 HTML 转义）。文档块的 name 可能是 "笔记本名/文档路径"。
                            type string 路径节点的块类型 (例如 "NodeDocument", "NodeHeading", "NodeParagraph", "NodeListItem" 等)。
                            subType string 路径节点的块子类型 (例如 "h1"-"h6" 对于标题, "task" 对于任务列表项)。
                            children array 子路径数组 (在此 API 中通常为空数组 [])。
                        
                    
                
            
        
    

    
        
            请求示例
            成功响应
            失败响应 (Not Found)
            失败响应 (Param Error)
        

        
            请求示例
            POST /api/block/getBlockBreadcrumb HTTP/1.1
Host: 127.0.0.1:6806
Content-Type: application/json
Authorization: Token your-api-token

{
  "id": "20231018102400-abcde1f",
  "excludeTypes": ["d"]
}
        

        
             成功响应示例
             {
  "code": 0,
  "msg": "",
  "data": [
    {
      "id": "20200811211906-nbe3hp1",
      "name": "API 文档规范",
      "type": "NodeHeading",
      "subType": "h2",
      "children": []
    },
    {
      "id": "20231018102400-abcde1f",
      "name": "这是一个段落",
      "type": "NodeParagraph",
      "subType": "",
      "children": []
    }
  ]
}
        

         
            失败响应示例 (块不存在)
            {
  "code": 0, 
  "msg": "",
  "data": [] 
}
         

         
            失败响应示例 (参数错误)
             {
  "code": -1,
  "msg": "json: cannot unmarshal string into Go struct field .id of type string",
  "data": null
}
         
    

    备注
    
        面包屑路径包含了从根节点（通常是文档块）到指定块的所有符合条件的父级块。
        excludeTypes 参数可以用来过滤掉不希望在面包屑中显示的节点类型。
        返回的 name 字段经过 HTML 转义，前端显示时可能需要解码。
        对于列表项等块，其 name 可能是其首个子块内容的缩略。
    

    
        注意：这是一个社区维护的文档，可能与官方最新版本存在差异。
        如果您觉得本文档有帮助，可以考虑赞助支持：爱发电
    

    
        在线测试
        
             
                API Token:
                
            

            
                接口地址:
                
            

            
                请求方法:
                
            

            
                请求参数 (JSON):
                {
  "id": "",
  "excludeTypes": []
}
                请填入 id (必需) 和可选的 excludeTypes 数组。
            

            
        

        
    

    
        上一个接口: 检查块是否为引用
        下一个接口: 获取块 DOM