# 

> X-callback-URLs 是通过 API 来进行熊掌记内操作的工具。你可以打开一篇笔记或标签，添加文本或文件，重命名或删除标签，甚至可以将笔记归档。

Source: https://bear.app/zh/faq/x-callback-url-scheme-documentation/

# X-callback-url Scheme 文档

熊掌记支持 [x-callback-url][1] 协议，它允许 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-%E6%89%93%E5%BC%80%E7%AC%94%E8%AE%B0) - [创建新笔记](#create-%E5%88%9B%E5%BB%BA%E6%96%B0%E7%AC%94%E8%AE%B0)
* [添加文本](#add-text-%E6%B7%BB%E5%8A%A0%E6%96%87%E6%9C%AC) -  [添加文件](#add-file-%E6%B7%BB%E5%8A%A0%E6%96%87%E4%BB%B6)
* [标签](#tags-%E6%A0%87%E7%AD%BE) -  [打开标签](#open-tag-%E6%89%93%E5%BC%80%E6%A0%87%E7%AD%BE) - [重命名标签](#rename-tag-%E9%87%8D%E5%91%BD%E5%90%8D%E6%A0%87%E7%AD%BE)- [删除标签](#delete-tag-%E5%88%A0%E9%99%A4%E6%A0%87%E7%AD%BE)
* [移至废纸篓](#trash-%E7%A7%BB%E8%87%B3%E5%BA%9F%E7%BA%B8%E7%AF%93) - [归档](#archive-%E5%BD%92%E6%A1%A3) - [无标签](#untagged-%E6%97%A0%E6%A0%87%E7%AD%BE) - [待办事项](#todo-%E5%BE%85%E5%8A%9E%E4%BA%8B%E9%A1%B9)- [今天](#today-%E4%BB%8A%E5%A4%A9) - [已加密](#locked-%E5%B7%B2%E5%8A%A0%E5%AF%86)
* [搜索](#search-%E6%90%9C%E7%B4%A2) - [抓取网页](#grab-url-%E6%8A%93%E5%8F%96%E7%BD%91%E9%A1%B5)
* [设置工作区](#open-workspace-%E8%AE%BE%E7%BD%AE%E5%B7%A5%E4%BD%9C%E5%8C%BA) - [解除工作区](#close-workspace-%E8%A7%A3%E9%99%A4%E5%B7%A5%E4%BD%9C%E5%8C%BA)

---

### /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` 表示打开后光标定位在编辑器
* **search** (搜索) *【可选】* 如设定为 `yes` 打开笔记内查找和替换面板并带有指定文本

#### x-success
* **note** 笔记内容
* **identifier** 笔记唯一的识别码
* **title** 笔记标题
* **tags** 笔记标签数组
* **is_trashed** 如笔记在废纸篓中，则返回值为 `yes`
* **modificationDate** 笔记修改时间，采用 [ISO 8601 标准时间格式][2]。
* **creationDate** 笔记创建时间，采用 [ISO 8601 标准时间格式][3]。

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

使用我们的 [URL 在线生成器][4] 创建并尝试执行 `/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 在线生成器][5] 创建并尝试执行`/create` 动作

**注意**
当作为 url 参数传递时，必须对 base64 **文件**参数进行 [编码][6]。

---

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

#### 参数
* **id** (识别码)*【可选】* 每篇笔记都有独一无二的识别码
* **title** (标题)*【可选】* 笔记标题	
* **selected** (已选中) *【可选】* 如设定为 `yes` 则使用在熊掌记中当前选中的笔记 (需要 [API 令牌](#生成令牌))
* **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 在线生成器][7] 创建并尝试执行`/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 生成器][8] 在线创建并体验在几秒钟内执行 `/add-file` 动作。

#### 注意
当作为 url 参数传递时，必须对 base64 **文件** 参数进行 [编码][9] 。

---

### /tags 标签
返回熊掌记侧边栏中当前显示的所有标签。
* **token** (令牌) *【必选】* 应用 [API令牌](#生成令牌)

#### x-success
* **tags** (标签) 以 json 数组形式显示标签 
  `[{ name }, ...]`

#### 示例
`bear://x-callback-url/tags?token=123456-123456-123456`

用我们的 [URL 生成器][11] 在线创建并体验在几秒钟内执行 `/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 生成器][13] 在线创建并体验在几秒钟内执行 `/open-tag` 动作。

---
### /rename-tag 重命名标签

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

#### 参数

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

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

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

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

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

#### 示例
`bear://x-callback-url/delete-tag?name=todo`

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

---

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

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

#### 示例
`bear://x-callback-url/trash?id=7E4B681B` 
`bear://x-callback-url/trash?search=old`

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

#### 注意
若 id (识别码) 已指定，搜索项将会被忽略。

---

### /archive 归档

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

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

#### 示例
`bear://x-callback-url/archive?id=7E4B681B` 
`bear://x-callback-url/archive?search=projects`

使用我们的 [URL 生成器][17] 在线创建并体验在几秒钟内执行 `/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 生成器][19] 在线创建并体验在几秒钟内执行 `/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 生成器][21] 在线创建并体验在几秒钟内执行 `/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 生成器][23] 在线创建并体验在几秒钟内执行 `/today` 动作。

---

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

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

#### 示例
`bear://x-callback-url/locked?search=data`

使用我们的 [URL 生成器][24] 在线创建并体验在几秒钟内执行 `/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 生成器][26]在线创建并体验在几秒钟内执行 `/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 生成器][27]在线创建并体验在几秒钟内执行 `/grab-url` 动作。

---
### /open-workspace 设置工作区
设置一个选定标签作为工作区

#### 参数

* **name** (名称) 作为工作区的标签名称

#### 示例

`bear://x-callback-url/open-workspace?name=工作`

---

### /close-workspace 解除工作区
解除在熊掌记中已设置的工作区

#### 示例

`bear://x-callback-url/close-workspace`
---

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

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

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

## 帮助与支持
想要讨论 URL 方案的改进或报错，请前往[熊掌记帮助页面](https://bear.app/zh/contact/)或在[微博](https://www.weibo.com/xiongzhangji)/[微信](http://weixin.qq.com/r/cSodBQfE4kqdrUNm939j)直接联系我们。

[1]:	http://x-callback-url.com/
[2]:	https://baike.baidu.com/item/ISO%208601
[3]:	https://baike.baidu.com/item/ISO%208601
[4]:	https://bear.app/xurl/open-note/
[5]:	https://bear.app/xurl/create/
[6]:	https://www.w3schools.com/tags/ref_urlencode.asp
[7]:	https://bear.app/xurl/add-text/
[8]:	https://bear.app/xurl/add-file/
[9]:	https://www.w3schools.com/tags/ref_urlencode.asp
[10]:	#生成令牌
[11]:	https://bear.app/xurl/tags/
[12]:	#生成令牌
[13]:	https://bear.app/xurl/open-tag/
[14]:	https://bear.app/xurl/rename-tag/
[15]:	https://bear.app/xurl/delete-tag/
[16]:	https://bear.app/xurl/trash/
[17]:	https://bear.app/xurl/archive/
[18]:	#生成令牌
[19]:	https://bear.app/xurl/untagged/
[20]:	#生成令牌
[21]:	https://bear.app/xurl/todo/
[22]:	#生成令牌
[23]:	https://bear.app/xurl/today/
[24]:	https://bear.app/xurl/locked/
[25]:	#生成令牌
[26]:	https://bear.app/xurl/search/
[27]:	https://bear.app/xurl/grab-url/
[28]:	https://bear.app/xurl/change-theme/
[29]:	https://bear.app/xurl/change-font/
[30]:	https://bear.app/cn/contact/