library 返回帮助页面首页

X-callback-url Scheme 文档

熊掌记支持 x-callback-url 协议,它允许 iOS 和 Mac 开发者公开和记录他们向其他应用程序提供的 API 方法并返回有用数据。

熊掌记的 URL Scheme actions 长这样:

bear://x-callback-url/[action]?[action parameters]&[x-callback parameters]

在这里,x-success 和 x-error 是 x-callback 的可变参数。

Actions 动作


/open-note 打开笔记

通过标题或 id 定位到一篇笔记并返回其内容。

参数

  • id (识别码) 【可选】 每篇笔记独一无二的识别码
  • title (标题) 【可选】 笔记标题
  • header (文本标题) 【可选】 笔记内的各级可选标题
  • exclude_trashed (排除废纸篓) 【可选】 如设定为 yes 则不从废纸篓中查找
  • new_window (新窗口) 【可选】 如设定为 yes 则在新窗口中打开笔记 (仅限 MacOS)
  • float (浮动窗口) 【可选】 如设定为 yes 则使新窗口浮动在顶部 (仅限 MacOS)
  • show_window (显示窗口) 【可选】 如设定为 no 则不强制打开熊掌记主窗口 (仅限 MacOS)
  • open_note (打开笔记) 【可选】 如设定为no 则不在熊掌记的主窗口或外部窗口中打开新笔记
  • selected (已选中) 【可选】 如设定为 yes 则使用在熊掌记中当前选中的笔记 (需要 API 令牌)
  • pin (置顶) 【可选】 如设定为 yes 则将所选笔记置顶在列表顶部
  • edit (编辑) 【可选】 如设定为 yes 表示打开后光标定位在编辑器

x-success

  • note 笔记内容
  • identifier 笔记唯一的识别码
  • title 笔记标题
  • tags 笔记标签数组
  • is_trashed 如笔记在废纸篓中,则返回值为 yes
  • modificationDate 笔记修改时间,采用 ISO 8601 标准时间格式
  • creationDate 笔记创建时间,采用 ISO 8601 标准时间格式

示例

bear://x-callback-url/open-note?id=7E4B681B
bear://x-callback-url/open-note?id=7E4B681B&header=Secondary%20Ttitle

使用我们的 URL 在线生成器 创建并尝试执行 /open-note 动作


/create 创建新笔记

创建一篇新的笔记并返回其唯一识别码,内容不可为空。

参数

  • title (标题) 【可选】 笔记标题
  • text (文本) 【可选】 笔记正文
  • clipboard (剪贴板) 【可选】 如设定为 yes,则使用当前剪贴板内的文字
  • Tags (标签) 【可选】 以逗号分隔多个标签
  • file (文件) 【可选】 文件使用 base64 编码
  • filename (文件名) 【可选】 带文件类型后缀的文件名。若想成功添加文件,文件文件名都为必填项
  • open_note (打开笔记) 【可选】 如设定为 no,则不在熊掌记的主窗口或外部窗口中打开新笔记
  • new_window (新窗口) 【可选】 如设定为 yes ,则在新窗口中打开一篇笔记 (仅限 MacOS)
  • float (浮动) 【可选】 如设定为 yes ,则将新窗口浮动于顶端(仅限 MacOS)
  • show_window (显示窗口)【可选】 如设定为 no ,则不强制打开熊掌记主窗口 (仅限 MacOS)
  • pin (置顶) 【可选】 如设定为 yes ,则将所选笔记置顶在列表顶部
  • edit (编辑) 【可选】 如设定为 yes ,表示打开后光标定位在编辑器
  • timestamp (时间戳) 【可选】 如设定为 yes ,则将当前日期和时间添加到文本最前端
  • type (类型)【可选】 如设定为 html ,则提供的 text (文本) 参数将由 html 转换为 markdown
  • url (网址) 【可选】type (类型) 设定为 html,则此参数将会被用作解析相对图像链接

x-success

  • identifier 笔记唯一的识别码
  • title 笔记标题

示例

bear://x-callback-url/create?title=My%20note%20Title&text=First%20line&tags=home,home%2Fgroceries

使用我们的 URL 在线生成器 创建并尝试执行/create 动作

注意 当作为 url 参数传递时,必须对 base64 文件参数进行 编码


/add-text 添加文本

在标题或 id 所定位的笔记中添加或追加文本。已加密的笔记无法通过此调用方式访问。

参数

  • id (识别码)【可选】 每篇笔记都有独一无二的识别码
  • title (标题)【可选】 笔记标题
  • selected (已选中) 【可选】 如设定为 yes 则使用在熊掌记中当前选中的笔记 (需要 API 令牌)
  • text (文本)【必选】 需添加的文本
  • header (文本标题)【可选】 笔记内的各级标题
  • mode (模式)【可选】 允许的值为 prepend (添加到最前)、append (追加到最后)、replace_all (替换全部) 和 replace (替换部分) (笔记标题保持不变)
  • new_line (另起一行) 【可选】 如设定为 yesmodeappend,则将在笔记内另起一行
  • Tags (标签) 【可选】 以逗号分隔多个标签
  • exclude_trashed (排除废纸篓)【可选】 如设定为yes则不从废纸篓中查找
  • open_note (打开笔记)【可选】 如设定为no,则不在熊掌记的主窗口或外部窗口中显示新笔记
  • new_window (新窗口) 【可选】 如设定为 yes 则在新窗口中打开笔记 (仅限 MacOS)
  • show_window (显示窗口)【可选】 如设定为 no 则不强制打开熊掌记主窗口 (仅限 MacOS)
  • edit (编辑) 【可选】 如设定为 yes 表示打开后光标定位在编辑器
  • timestamp 【可选】 如设定为 yes 则将当前日期和时间添加到文本之前

x-success

  • note 笔记内容
  • title 笔记标题

示例

bear://x-callback-url/add-text?text=new%20line&id=4EDAF0D1&mode=append

使用我们的 URL 在线生成器 创建并尝试执行/add-text 动作


/add-file 添加文件

在标题或 id 所定位的笔记中添加或追加文件。如果应用处于锁定状态,则无法执行此调用。该指令亦无法访问加密的笔记。

  • id (识别码) 【可选】 每篇笔记独一无二的识别码
  • title (标题) 【可选】 笔记标题
  • selected (已选中) 【可选】 如设定为 yes 则使用在熊掌记中现时选中的笔记 (需要 API 令牌)
  • file (文件) 【必选】 base64 编码形式的文件
  • header (文本标题)【可选】 笔记内的各级标题
  • filename (文件名)【可选】 带文件类型后缀的文件名。若想成功添加文件,文件和文件名都为必填项
  • mode (模式) 【可选】 允许的值为 prepend (添加到最前)、append (追加到最后)、replace_all (替换全部) 和 replace (替换部分) (笔记标题保持不变)
  • open_note (打开笔记) 【可选】 如设定为no 则不在熊掌记的主窗口或外部窗口中显示新笔记
  • new_window (新窗口) 【可选】 如设定为 yes 则在新窗口中打开笔记 (仅限 MacOS)
  • show_window (显示窗口) 【可选】 如设定为 no 则不强制打开熊掌记主窗口 (仅限 MacOS)
  • edit (编辑) 【可选】 如设定为 yes 表示打开后光标定位在编辑器

x-success

  • note 笔记内容

示例

bear://x-callback-url/add-file?filename=test.gif&id=4EDAF0D1-2EFF-4190-BC1D-67D9BAE49BA9-28433-000187BAA3D182EF&mode=append&file=R0lGODlhAQABAIAAAP%2F%2F%2F%2F%2F%2F%2FyH5BAEKAAEALAAAAAABAAEAAAICTAEAOw%3D%3D

用我们的 URL 生成器 在线创建并体验在几秒钟内执行 /add-file 动作。

注意

当作为 url 参数传递时,必须对 base64 文件 参数进行 编码


/tags 标签

返回熊掌记侧边栏中当前显示的所有标签。

  • token (令牌) 【必选】 应用 API令牌

x-success

  • tags (标签) 以 json 数组形式显示标签 [{ name }, ...]

示例

bear://x-callback-url/tags?token=123456-123456-123456

用我们的 URL 生成器 在线创建并体验在几秒钟内执行 /tags 动作。


/open-tag 打开标签

显示熊掌记中所有带有指定标签的笔记。

参数

  • name (标签名) 【必选】 标签名称,或以英文逗号 , 分隔的标签名称列表
  • token (令牌) 【可选】 应用 API 令牌

x-success

  • notes (笔记) 以 json 数组形式显示指定标签下的笔记 [{ title, identifier, modificationDate, creationDate, pin }, ...]

加密的笔记将不会显示在笔记数组中。

若未提供应用 API 令牌,则不会有任何数据返回。

示例

bear://x-callback-url/open-tag?name=work bear://x-callback-url/open-tag?name=todo%2Fwork

使用我们的 URL 生成器 在线创建并体验在几秒钟内执行 /open-tag 动作。


/rename-tag 重命名标签

重命名现有标签。如果应用处于锁定状态或标签包含任何锁定的笔记,则不能执行此调用。

参数

  • name (标签名) 【必选】
  • new_name (新标签名) 【必选】 要更换的新标签名
  • show_window (显示窗口) 【可选】 如设定为 no 则不强制打开熊掌记主窗口 (仅限 MacOS)

示例

bear://x-callback-url/rename-tag?name=todo&new_name=done

使用我们的 URL 生成器 在线创建并体验在几秒钟内执行 /rename-tag 动作。


/delete-tag 删除标签

删除现有标签。如果应用处于锁定状态或标签包含任何锁定的笔记,则不能执行此调用。

参数

  • name (标签名) 【必选】
  • show_window (显示窗口) 【可选】 如设定为 no 则不强制打开熊掌记主窗口 (仅限 MacOS)

示例

bear://x-callback-url/delete-tag?name=todo

使用我们的 URL 生成器 URL 生成器 在线创建并体验在几秒钟内执行 /delete-tag 动作。


/trash 移至废纸篓

移动一篇笔记至熊掌记废纸篓并选中侧边栏中“废纸篓”一栏。 如果应用处于锁定状态,则无法执行此调用。加密的笔记亦不能通过此方式调用。

参数

  • id (识别码) 【可选】 每篇笔记独一无二的识别码
  • search (搜索) 【可选】 通过字符串搜索
  • show_window (显示窗口) 【可选】 如设定为 no 则不强制打开熊掌记主窗口 (仅限 MacOS)

示例

bear://x-callback-url/trash?id=7E4B681B bear://x-callback-url/trash?search=old

使用我们的 URL 生成器 在线创建并体验在几秒钟内执行 /trash 动作。

注意

若 id (识别码) 已指定,搜索项将会被忽略。


/archive 归档

移动一篇笔记至熊掌记归档并选中侧边栏中“归档”栏。 如果应用处于锁定状态,则无法执行此调用。加密的笔记亦不能通过此方式调用。

参数

  • id (识别码)【可选】 每篇笔记独一无二的识别码
  • search (搜索)【可选】 通过字符串搜索
  • show_window (显示窗口)【可选】 如设定为 no 则不强制打开熊掌记主窗口 (仅限 MacOS)

示例

bear://x-callback-url/archive?id=7E4B681B bear://x-callback-url/archive?search=projects

使用我们的 URL 生成器 在线创建并体验在几秒钟内执行 /archive 动作。

注意

若 id (识别码) 已指定,搜索项将会被忽略。


/untagged 无标签

选择侧边栏中“无标签”条目。

参数

  • search (搜索) 【可选】 通过字符串搜索
  • show_window (显示窗口) 【可选】 如设定为 no 则不强制打开熊掌记主窗口 (仅限 MacOS)
  • token (令牌) 【可选】 应用 API 令牌

x-success

  • notes (笔记) 以 json 数组形式显示“无标签”笔记 [{ title, identifier, modificationDate, creationDate, pin }, ...]

加密的笔记将从笔记数组中排除。

若未提供应用 API 令牌,则不会有任何数据返回。

示例

bear://x-callback-url/untagged?search=home

使用我们的 URL 生成器 在线创建并体验在几秒钟内执行 /untagged 动作。


/todo 待办事项

选中侧边栏上的“待办事项”条目。

参数

  • search (搜索) 【可选】 通过字符串搜索
  • show_window (显示窗口) 【可选】 如设定为 no 则不强制打开熊掌记主窗口 (仅限 MacOS)
  • token (令牌) 【可选】 应用 API 令牌

x-success

  • notes (笔记) 以 json 数组形式显示包含“待办事项”的笔记 [{ title, identifier, modificationDate, creationDate, pin }, ...]

加密的笔记将从笔记数组中排除。

若未提供应用 API 令牌,则不会有任何数据返回。

示例

bear://x-callback-url/todo?search=home

使用我们的 URL 生成器 在线创建并体验在几秒钟内执行 /todo 动作。


/today 今天

选中侧边栏中的“今天”条目。

参数

  • search (搜索) 【可选】 通过字符串搜索
  • show_window (显示窗口) 【可选】 如设定为 no 则不强制打开熊掌记主窗口 (仅限 MacOS)
  • token 【可选】 应用 API 令牌

x-success

  • notes (笔记) 以 json 数组形式显示包含“今天”的笔记 [{ title, identifier, modificationDate, creationDate, pin }, ...]

加密的笔记将从笔记数组中排除。

若未提供应用 API 令牌,则不会有任何数据返回

示例

bear://x-callback-url/today?search=family

使用我们的 URL 生成器 在线创建并体验在几秒钟内执行 /today 动作。


/locked 已加密

选中侧边栏中的“已加密”条目。

参数

  • search (搜索) 【可选】 通过字符串搜索
  • show_window (显示窗口) 【可选】 如设定为 no 则不强制打开熊掌记主窗口 (仅限 MacOS)

示例

bear://x-callback-url/locked?search=data

使用我们的 URL 生成器 在线创建并体验在几秒钟内执行 /locked 动作。


/search 搜索

在熊掌记中显示特定标签的所有笔记搜索结果。

参数

  • term (项) 【可选】 触发搜索项
  • tag (标签) 【可选】 需搜索的标签
  • show_window (显示窗口) 【可选】 如设定为 no 则不强制打开熊掌记主窗口 (仅限 MacOS)
  • token 【可选】 应用 API 令牌

x-success

  • notes (笔记) 以 json 数组形式显示包含所有特定搜索结果的笔记 [{ title, identifier, modificationDate, creationDate, pin }, ...]

已加密的笔记将从笔记数组中排除。

若未提供应用 API 令牌,则不会有任何数据返回。

示例

bear://x-callback-url/search?term=nemo&tag=movies

使用我们的 URL 生成器在线创建并体验在几秒钟内执行 /search 动作。


/grab-url 抓取网页

创建一篇包含网页内容的新笔记。

参数

  • url (链接地址) 【必选】 需抓取的网页链接地址
  • tags (标签) 【可选】 以逗号分隔多个标签,如果熊掌记的页面内容中首选项标签已指定,则此参数将被忽略
  • pin (置顶) 【可选】 如设定为 yes 则将所选笔记置顶在列表顶部
  • wait (等待) 【可选】 若设定为 no 则无需 identifiertitle 就可即刻唤出 x-success

x-success

  • identifier 笔记唯一的识别码
  • title 笔记标题

有效值

yes no

示例

bear://x-callback-url/grab-url?url=https://bear.app

使用我们的 URL 生成器在线创建并体验在几秒钟内执行 /grab-url 动作。


生成令牌

为了扩展功能,某些 API 调用允许将 app 生成的令牌与其他参数一起传递。 请注意,在 iOS 上生成的令牌对 MacOS 无效,反之亦然。

在 MacOS 上,选择帮助API 令牌复制令牌,它将在您的剪贴板上可用。

在 iOS 上,转到 设置通用,找到 API 令牌部分,然后点击下面的单元格以生成令牌或复制到您的剪贴板。

帮助与支持

想要讨论 URL 方案的改进或报错,请前往熊掌记帮助页面或在微博/微信直接联系我们。

Group 9

故障排除

部分常见问题的解决方案。

同步故障排除 如何处理冲突笔记 熊掌记的笔记储存在哪里

问题仍未解决?在博客、论坛上寻找答案,或直接给我们留言。

联系我们

订阅熊掌记月度资讯

订阅以获取熊掌记的小窍门和新资讯,以及更多信息和 Shiny Frog 幕后故事。我们永远不会发送任何垃圾邮件,但隔空熊抱我们管够!