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 令牌::[^1]) - pin (置顶) 【可选】 如设定为
yes则将所选笔记置顶在列表顶部 - edit (编辑) 【可选】 如设定为
yes表示打开后光标定位在编辑器
x-success
- note 笔记内容
- identifier 笔记唯一的识别码
- title 笔记标题
- 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 (文本) 【可选】 笔记正文
- Tags (标签) 【可选】 以逗号分隔多个标签
- file (文件) 【可选】 文件使用 base64 编码
- filename (文件名) 【可选】 带文件类型后缀的文件名。若想成功添加文件，文件和文件名都为必填项
- open_note (打开笔记) 【可选】 如设定为
no，则不在熊掌记的主窗口或外部窗口中打开新笔记 - new_window (新窗口) 【可选】 如设定为
yes则在新窗口中打开一篇笔记 (仅限 MacOS) - show_window (显示窗口)【可选】 如设定为
no则不强制打开熊掌记主窗口 (仅限 MacOS) - pin (置顶) 【可选】 如设定为
yes则将所选笔记置顶在列表顶部 - edit (编辑) 【可选】 如设定为
yes表示打开后光标定位在编辑器 - timestamp (时间戳) 【可选】 如设定为
yes则将当前日期和时间添加到文本之前
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 (标题)【可选】 笔记标题
- text (文本)【必选】 需添加的文本
- header (文本标题)【可选】 笔记内的各级标题
- mode (模式)【可选】 允许的值为
prepend(添加到最前)、append(追加到最后)、replace_all(替换全部) 和replace(替换部分) (笔记标题保持不变) - new_line (另起一行) 【可选】 如设定为
yes且mode为append，则将在笔记内另起一行 - 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 (标题) 【可选】 笔记标题
- 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则无需 identifier 和 title 就可即刻唤出 x-success
x-success
- identifier 笔记唯一的识别码
- title 笔记标题
有效值
yes no
示例
bear://x-callback-url/grab-url?url=https://bear.app
使用我们的 URL 生成器在线创建并体验在几秒钟内执行 /grab-url 动作。
/change-theme
更改选中的熊掌记主题。有些主题可能需要 Bear Pro 订阅。
参数
- theme (主题) 【必选】
- show_window (显示窗口) 【可选】 如设定为
no则不强制打开熊掌记主窗口 (仅限 MacOS)
有效值
Red Graphite Charcoal Solarized Light Solarized Dark Panic Mode Dracula Gotham Toothpaste Cobalt Duotone Light Duotone Snow Dieci Ayu Ayu Mirage Dark Graphite Duotone Heat Gandalf
示例
bear://x-callback-url/change-theme?theme=Solarized%20Dark
使用我们的 URL 生成器在线创建并体验在几秒钟内执行 /change-theme 动作。
/change-font 更改字体
更改选中的熊掌记字体。
参数
- font (字体) 【必选】
- show_window (显示窗口) 【可选】 如设定为
no则不强制打开熊掌记主窗口 (仅限 MacOS)
有效值
Avenir Next System Helvetica Neue Menlo Georgia Courier Open Dyslexic
示例
bear://x-callback-url/change-font?font=Helvetica%20Neue
使用我们的 URL 生成器在线创建并体验在几秒钟内执行 /change-font 动作。
生成令牌
为了扩展功能，某些 API 调用允许将 app 生成的令牌与其他参数一起传递。 请注意，在 iOS 上生成的令牌对 MacOS 无效，反之亦然。
在 MacOS 上，选择帮助→API 令牌→复制令牌，它将在您的剪贴板上可用。
在 iOS 上，转到 设置→通用，找到 API 令牌部分，然后点击下面的单元格以生成令牌或复制到您的剪贴板。
帮助与支持
想要讨论 URL 方案的改进或报错，请前往 熊掌记帮助页面 或在微博/微信直接联系我们。
[^1]: need link for token-generationq
