这是本节的多页打印视图。 .
使用指南
1 - 安装与首次启动
Crib 仍在开发中,没有公开下载,也没有确定价格和许可证。发布后安装包会放在下载页。本页描述的是当前开发构建的行为。开发构建只有临时签名,没有经过 Apple 公证。
系统要求
| 项目 | 现状 |
|---|---|
| 部署目标 | macOS 14 |
| 已测试 | 只在 Apple 芯片(arm64)的开发机上测试过 |
| 未测试 | 实际运行在 macOS 14 上、Intel Mac |
| 网络 | 首次启动和日常阅读、搜索都不需要;只有下载其他版本时需要 |
部署目标是编译设置,不等于已经在 macOS 14 上验证过。正式发布前会单列实测过的系统和机型。
两种版本
| 完整离线版 | Core | |
|---|---|---|
| 内置手册 | 全部 31 条版本线,中英文共 62 套 | PG 18.6 中英文手册 |
| 内置 Wiki | 有 | 无,按需下载 |
| 搜索索引 | 随应用附带,覆盖全部内置内容 | 随应用附带 18.6 的索引;下载其他版本后在本机建立 |
| 其他版本 | 不需要下载 | 从签名的版本目录选择安装 |
两种版本的区别在于随应用附带多少内容。Core 下载的每个资料包都会先校验签名,再建立索引、切换到新内容;下载失败或取消时,已安装的内容照常可用。获取和管理版本见资料库。
Core 按需下载所用的版本目录还没有在正式地址上线,在那之前 Core 无法联网下载其他版本。手头有 .crib 资料包文件时,可以在资料库中“导入资料包…”。
首次启动
- 打开 Crib。不需要账号,也不需要联网:两种版本都直接使用随应用附带的内容和索引。
- 窗口默认打开 PG 18 中文手册,内容版本是 18.6。搜索范围默认是“PG 18 · 简体中文 · 手册”。
- 按 ⌘ 加 L 开始搜索。搜索语法见搜索。
- 点工具栏的主页按钮(⇧ 加 ⌘ 加 H)可以回到主页,从“获取版本”“资料库”“搜索方案”“快捷键”四个入口继续设置。
本地 API 和三个全局快捷键默认关闭,不会在首次启动时请求权限。只有“搜索选中文字”全局快捷键需要辅助功能权限,开启时再授予。
个人资料放在哪里
设置、片段库、笔记、书签、更正、阅读历史和下载的资料包都存放在:
这个目录不在应用包内。卸载某个文档版本不会删除挂在上面的笔记和更正。各文件的用途见用户数据与迁移。
从 PGDash 迁移
Crib 以前叫 PGDash。如果本机有 ~/Library/Application Support/PGDash/,Crib 启动时会把它复制一份到新目录,旧目录原样保留,不修改也不删除。
- 迁移失败时,Crib 以只读方式运行:可以阅读和搜索内置内容,但笔记、书签、更正、阅读历史、下载和设置都不能修改。每次启动会重试;提示中也可以“重试迁移”或“跳过迁移…”。
- 跳过迁移后,Crib 从空白的个人资料开始,旧资料原样留在原目录。
- 已经有 Crib 资料时又发现旧资料,Crib 会提示“发现 PGDash 旧资料”,由你选择“迁移旧资料”或“不再提示”。选择迁移时,现有的 Crib 资料会整体移到一旁保留。
迁移的完整规则和恢复办法见用户数据与迁移。
2 - 搜索

搜索框
按 ⌘ 加 L 聚焦工具栏中的搜索框,⌘ 加 K 是备用快捷键。结果随输入更新。
| 按键 | 作用 |
|---|---|
| ↑ ↓ | 选择结果 |
| ↩ | 打开选中的结果;结果还没出来时,出来后打开第一条 |
| ⌘ 加 ↩ | 在新标签页打开 |
| Esc | 回到正文,查询保留 |
在结果上点右键可以“在新标签页打开”或“复制链接”。搜索框为空、或查询里只有筛选条件时,中间一栏显示当前范围的“目录”,而不是搜索结果。
搜索范围
工具栏下方的范围栏决定默认在哪里搜:
- 搜索方案:保存的范围,见搜索方案。
- 版本:例如“PG18 · 18.6”。选“默认版本”回到 PG 18;选“常规版本”搜索全部默认和常规版本。历史版本和开发版不在其中,在阅读区“版本”弹出框中打开“专家模式”后,这一项变为“全部已启用版本”,搜索也包含它们。
- 语言:中文、English 或全部语言。
- 资料类别:由左侧栏决定。“手册”只搜手册,“全部资料”包括 Wiki,点某个 Wiki 集合则只搜该集合。
新窗口的默认语言和版本在“设置 › 通用 › 默认搜索范围”中修改;设了默认搜索方案时以方案为准。
搜索语法
查询由关键词、版本前缀和筛选条件组成,顺序不限。前缀和筛选只作用于本次查询,并优先于范围栏。它们以“仅本次查询”标签显示在范围栏中,点标签可以单独移除;“清除筛选”移除全部筛选,保留关键词。
版本前缀
| 写法 | 含义 |
|---|---|
pg18: | PG 18。大小写不限,PG18: 相同 |
pg96:、pg9.6: | PG 9.6。10 以前的版本可以省略点号 |
[email protected]: | 指定内容版本 18.6;本机装的不是这个小版本时提示未安装,不用其他小版本代替 |
pg: | 默认版本,目前是 PG 18 |
pgdevel: | 开发版,目前是 20devel |
前缀后面可以不加空格,pg18:vacuum 等于 pg18: vacuum。
筛选条件
| 筛选 | 取值 | 作用 |
|---|---|---|
lang: | en、zh-Hans | 只搜这种语言的正文 |
branch: | 版本号,如 18、9.6 | 只搜这个版本;与版本前缀同时写时必须一致 |
domain: | manual、wiki、release、security、capability、provenance | 只搜手册、Wiki、发布、安全、能力或来源资料 |
collection: | Wiki 集合键,如 guc、func、sqlstate、psql、waitevent | 只搜这个 Wiki 集合 |
kind: | 集合键或 domain: 的取值 | 写集合键等于 collection:,写资料类型等于 domain: |
project: | postgresql,可写 pg | 目前只有这一个项目 |
左侧栏选的是“手册”时,搜索限定在手册内,collection:guc 不会有结果。先在侧栏选“全部资料”,或在查询里加 domain:wiki;更直接的办法是在侧栏点该集合。
其他规则:
- 同一种筛选写了两个不同的值,或版本前缀与
branch:指向不同版本,搜索会报错,不会替你挑一个。 - 中文输入法打出的全角冒号
:和全角字母、数字可以直接用。 - 不是筛选名的冒号按普通文字处理。粘贴报错时不必删掉
ERROR:、DETAIL:、错误:的冒号;x::int、localhost:5432也原样保留。 - 用英文双引号括起的短语要求在原文中连续出现。
- 查询最多 256 个字符。超过 32 个词时只用前 32 个,结果栏上方会提示。
示例
| 查询 | 含义 |
|---|---|
work_mem | 找配置参数,名称完全一致的条目排在最前 |
PG96: vacuum | 在 PG 9.6 中搜 vacuum |
[email protected]: max_connections lang:en | 在 18.6 英文手册中找 max_connections |
SELECT branch:18 lang:en | 在 PG 18 英文资料中找 SELECT |
->>、@@ | 运算符,标点原样参与匹配 |
\d+、\dC | psql 命令,区分大小写,只做精确匹配 |
23505 | SQLSTATE 代码,按字符串匹配 |
复制延迟、事务隔离 | 中文词语,按相邻两字匹配 |
锁 | 单个汉字,只匹配标题和名称 |
domain:wiki SELECT | 只在 Wiki 中找 SELECT |
匹配规则
结果先按名称匹配,再按标题和正文匹配。大致顺序是:名称、命令或定义完全一致,别名,名称前缀,章节标题,标题相关的章节,最后是正文。每条结果的说明行末尾标出匹配方式:精确、别名、前缀、标题、相关章节、正文或标题/名称;悬停可以看到解释。
- 大小写:普通英文标识符不区分大小写,
WORK_MEM与work_mem相同。含标点的名称和 psql 命令区分大小写,\dC与\dc是两个命令。 - 反斜杠:查询中有以
\开头的词时,只做精确匹配,不退回正文搜索。 - 英文词形:3 个字母以上的单词同时匹配常见词形,
lock也匹配 locks、locked、locking。末尾还没输完的英文词按前缀匹配,例如transaction isol。 - 中文:连续的汉字按相邻两字切分,“事务隔离”拆成“事务”“务隔”“隔离”,这几组都出现才算命中,不要求相邻。需要连续出现时加英文双引号。
- 单个汉字:只输入一个字时(如
锁),只匹配标题和名称中含这个字的条目,结果标为“标题/名称”。和其他词一起出现的单字按词首近似匹配,结果栏会提示“单个汉字只按标题和词首匹配,输入完整词语更准确”。 - 语言:英文标识符在中文手册里原样存在,在中文范围内搜
work_mem也能命中中文手册。写了lang:en就不会返回中文正文。
多版本结果
搜索多个版本时,同一种语言下的同一个对象合成一组:Wiki 按同一概念,手册按同一章节标识。没有可靠对应关系的同名条目各自单列。
- 结果栏顶部显示“N 组 · M 个版本”。
- 分组标题下有版本摘要,点它或按 → 展开,按 ← 收起。
- 折叠时按 ↩ 打开组内排在最前的一条。组内先列范围栏选定的版本,其余从新到旧。
搜索方案
范围栏最左边的“搜索方案”菜单保存常用范围:版本、语言、资料类别,以及可选的搜索框提示语和触发词。
- 调好范围栏,在菜单中选“将当前范围存为方案…”。
- 在“设置 › 搜索”中编辑、停用或删除方案,并可以指定“新窗口默认方案”。
- 给方案加触发词后,在搜索框输入
sql:select或sql select,这一次就按触发词为sql的方案搜索 select。删掉触发词即恢复范围栏原来的范围。
每个方案最多 8 个触发词,以英文字母开头,最长 32 个字符;不能使用 pg 开头的词和 lang、branch 等筛选名。方案里的“在结果中显示片段”可以单独关闭片段结果。
没有结果时
结果栏显示“没有结果”和实际搜索的关键词(不含筛选),并给出几个操作,都会保留关键词:
- 清除筛选:查询中有筛选条件时出现。
- 清除查询。
- 调整范围 › 搜索全部版本:从单个版本扩大到全部版本。
- 调整范围 › 仅搜索 PG N:回到正在阅读的版本和语言。
搜索未安装或已停用的版本(例如在 Core 中写 pg96:)时,Crib 会说明该版本未安装或未启用,状态栏出现“查看 PG96”,打开资料库获取或启用。
最近搜索
点搜索框左侧的放大镜,菜单中列出最近 12 条查询,选“清除最近搜索”可清空。按 ↩ 或打开某条结果时记录当前查询。
片段与个人资料
- 匹配的片段显示在结果最上方的“片段”分组中,见片段。在“设置 › 片段”中关闭“在搜索结果中显示片段”即可隐藏。
- 侧栏选中“个人资料”下的分类时,搜索框改为筛选笔记、更正、书签或阅读历史,按标题、正文和标签做字面匹配,不分词。
网页搜索
本地没找到时,结果栏底部的“网页搜索”在默认浏览器中打开外部搜索。默认启用 Google 和 Stack Overflow,DuckDuckGo 默认关闭。发送的只有查询文字,筛选条件会先去掉。
在“设置 › 网页搜索”中可以添加、停用、拖动排序或恢复默认。地址必须以 https:// 开头,用 {query} 标出查询文字的位置。阅读区“更多”菜单中的“在网页中搜索选中文字”使用同一份列表。
3 - 阅读与双语对照

窗口布局
窗口分三栏:
- 侧栏:资料分类。“手册”“全部资料”、六组 Wiki 集合,以及“个人资料”下的笔记、更正、书签、阅读历史、标签和待重新定位。
- 中间一栏:有查询时是“结果”,没有查询时是当前范围的“目录”,按手册顺序列出章节。
- 阅读区:标题下方写明正在读的版本、语言和资料类型,例如“PostgreSQL 18 · 中文 · 手册”。正文的版本和语言以这里为准,不以范围栏为准。
工具栏按钮可以隐藏侧栏或结果栏;“设置 › 通用 › 显示”中的“显示侧栏”“显示搜索结果栏”决定默认状态。
本页目录
阅读区右上角的“目录”按钮(⇧ 加 ⌘ 加 F,菜单名“筛选目录”)列出当前页面的全部章节,当前章节有标记。在“筛选章节”框中输入标题或对象名可以过滤。
| 按键 | 作用 |
|---|---|
| ↑ ↓ | 选择章节 |
| ↩ | 跳转 |
| ⌘ 加 ↩ | 在新标签页打开 |
| Esc | 关闭,回到正文 |
双语对照时,在哪一栏打开目录,就列出哪种语言的章节。目录不改变搜索框的查询和范围。
标签页与窗口
Crib 使用 macOS 原生窗口标签页。每个标签页有自己的查询、搜索范围、正文和前进后退记录。
| 操作 | 方法 |
|---|---|
| 新建标签页 | ⌘ 加 T |
| 在新标签页打开结果、目录或历史条目 | ⌘ 加 ↩,或右键“在新标签页打开” |
| 复制当前标签页 | 文件 › 复制标签页 |
| 重新打开关闭的标签页 | ⇧ 加 ⌘ 加 T |
| 上一个 / 下一个标签页 | ⇧ 加 ⌘ 加 [ / ⇧ 加 ⌘ 加 ] |
| 关闭标签页或窗口 | ⌘ 加 W |
“设置 › 通用 › 启动”中的“启动时恢复窗口和标签页”默认开启,恢复时包括查询、搜索范围和阅读位置。
后退与前进
⌘ 加 [ 和 ⌘ 加 ] 在当前标签页读过的页面之间后退、前进。按住工具栏的后退或前进按钮会列出可以跳到的页面;同样的列表也在“阅读 › 后退到 / 前进到”中。
这份记录只属于当前标签页。跨标签页、跨启动保留的阅读记录是“阅读历史”(⇧ 加 ⌘ 加 Y),见笔记、书签与本地更正。
页内查找
| 操作 | 按键 |
|---|---|
| 页内查找 | ⌘ 加 F |
| 查找下一个 / 上一个 | ⌘ 加 G / ⇧ 加 ⌘ 加 G |
| 用选中的文字查找 | ⌘ 加 E |
| 跳到选中的文字 | ⌘ 加 J |
查找栏右侧的“完成”关闭查找栏。双语对照时,查找作用于获得焦点的那一栏,查找栏左侧标出“中文正文”或“English 正文”。
切换语言
按 ⇧ 加 ⌘ 加 L,或点阅读区右上角的“English”/“中文”,打开另一种语言中对应的章节,并停在同一小节。
对应关系在构建资料包时确定,手册依据源码中的章节标识,不按标题或网址猜测。
- 当前小节在另一种语言中有对应时,直接打开。
- 没有对应时,Crib 逐级向上找,打开最近的有对应的上级章节。按钮的悬停提示写明“已定位到上级章节”。
- 对应关系不是逐段核对过的,提示“对应章节未逐段核对”。
- 一直找不到时,按钮不可用,提示“这一节还没有已核对的对应章节。”
双语对照
按 ⇧ 加 ⌘ 加 B,或点工具栏的“双语对照”按钮,阅读区分成两栏:左栏是当前正文,右栏是另一种语言的对应页面。
- 滚动任一栏,另一栏跳到对应的章节。对齐只到章节一级,不逐句对齐。
- 找不到对应章节时,右栏显示“没有对应章节”和原因。
- 阅读设置同时作用于两栏。
- 页内查找、“目录”和“在浏览器中打开”作用于获得焦点的那一栏;“更多”菜单中另有“在浏览器中打开 English 页面”或“中文页面”。
切换版本
阅读区右上角的“版本”按钮显示正在读的版本,并列出资料库中的其他版本。点某个版本的“阅读”,Crib 尽量停在同一位置:
- 先找同一章节标识;
- 找不到时打开上级章节或同名页面,提示“PG N 中没有这一节,已打开上级章节”之类的说明;
- 连页面都没有时打开该版本的目录首页。
未安装的版本显示“在资料库中显示”。打开“专家模式”后,列表也包括历史版本和开发版。安装与启用版本见资料库。
外观与缩放
浅色、深色或跟随系统在“设置 › 通用 › 显示 › 外观”中选择。正文排版在“设置 › 阅读”中调整,立即作用于所有窗口:
| 设置 | 范围 |
|---|---|
| 页面缩放 | 60%–300%,步长 10% |
| 字体 | 系统字体、衬线字体 |
| 字号 | 12–24 pt |
| 行距 | 1.30–2.00 |
| 行宽 | 适应窗口、紧凑 640 pt、标准 800 pt、宽 1040 pt |
⌘ 加 + / ⌘ 加 - 每次缩放 10%,⌘ 加 0 回到 100%,“阅读 › 放大到 200%”一步放大。“设置 › 阅读”底部的“恢复默认”重置以上各项。
复制与链接
- 代码:代码块右上角有“复制”按钮,复制后短暂显示“已复制”。
- 链接:“更多 › 复制链接”复制正在阅读的章节的
crib://链接;在结果上右键也有“复制链接”。链接带有章节和资料包标识,格式与打开规则见链接。 - 选中的文字:“更多”菜单中可以“搜索选中文字”,或用网页搜索查它。
在浏览器中打开
按 ⌥ 加 ⌘ 加 B,或选“更多 › 在浏览器中打开”,Crib 生成这一页的本地副本,用默认浏览器打开。副本是官方原文,不含你的笔记和更正,也不运行脚本。生成期间状态栏显示“正在准备页面…”,可以取消。
来源与许可
“更多 › 来源与许可”显示这一页的出处:
- 版本:项目、内容版本和渠道;
- 资料包及其修订号;
- 页面路径、锚点和章节标识;
- 页面和正文的校验值;
- “来源”和“许可”两个标签页,列出该资料包的来源清单和许可证。
4 - 笔记、书签与本地更正
笔记、书签、标签、阅读历史和更正统称个人资料,保存在 ~/Library/Application Support/Crib/ 中,与资料包分开。卸载或更新文档版本不会删除它们;个人资料出问题时,阅读和搜索照常可用。
侧栏“个人资料”下有笔记、更正、书签、阅读历史、标签和待重新定位六个分类。选中某个分类时,搜索框改为在其中按标题、正文和标签做字面筛选。
笔记
点工具栏的“笔记”按钮打开笔记面板,按 ⇧ 加 ⌘ 加 N 新建笔记。
- 新笔记的标题默认是当前章节的标题。新建时正文中有选中的文字,笔记就关联到这段原文,面板中显示“关联的原文”和“打开原文”。
- 以后要改关联位置,在正文中选中新的文字,点“关联当前选区”。
- 正文是 Markdown,“编辑”与“预览”之间切换。预览只打开
http、https和mailto链接。 - 标签写在“标签,用逗号分隔”一栏。
- “修订”菜单列出保存过的版本,“恢复修订 N”会把它存为一个新修订,不覆盖历史。
- 在侧栏“笔记”中右键可以“编辑笔记”“打开原文”或“删除笔记…”。删除会连同所有修订一起删除,无法撤销。
自动保存与冲突
停止输入片刻后笔记自动保存,面板底部依次显示“等待自动保存…”和“已自动保存 · 修订 N”。
- 保存失败时显示“保存失败:”和原因,草稿留在编辑器中,不会显示为已保存。
- 同一条笔记在两个窗口里都改过时,后保存的一份不会覆盖先保存的:它的编辑器显示保存失败,草稿保留。
- 导出、导入和备份前,Crib 先保存所有草稿;上面那种冲突的草稿另存为标题带“(冲突副本)”的新笔记并提示,之后的修改保存到这份副本。
- 退出时仍有无法保存的草稿,会弹出“无法保存个人资料”,可以“另存为副本并退出”“放弃修改并退出”或“继续编辑”。
草稿只在保存成功后才写入磁盘。应用崩溃或磁盘不可写时,最后一次保存之后的输入可能丢失。
书签
按 ⌘ 加 D 给当前章节加书签,同时弹出编辑框,可以改名称、加标签。书签在弹出时就已添加,“取消”只放弃这次的修改。加过书签的章节,工具栏的书签图标变为实心。
⇧ 加 ⌘ 加 D 打开书签列表,可以按标题、版本或标签筛选,⌘ 加 ↩ 在新标签页打开,“在侧栏中查看全部”转到侧栏的“书签”分类。
标签
笔记和书签都可以加标签。侧栏“标签”分类顶部的标签选择器按标签列出笔记;“书签”分类顶部也有同样的选择器。
阅读历史
打开过的章节记入阅读历史。⇧ 加 ⌘ 加 Y 打开历史列表,可以按标题或版本筛选;侧栏“阅读历史”显示全部。
- 保留最近 5,000 条、180 天以内的记录,连续重复打开同一处只记一次。超出的部分在启动时清理。
- 右键单条记录可以“从历史中删除”。在侧栏“阅读历史”分类中,“个人资料操作”菜单里的“清除阅读历史…”删除全部历史,不影响笔记、书签和更正,无法撤销。
阅读历史与标签页的后退、前进记录是两回事,后者见后退与前进。
更正
更正用来记下你对正文(通常是译文)的修改。它只保存在你的个人资料里,不改动官方原文。
- 在正文中选中要改的文字。选区要在同一章节内,只含正文。
- 选“阅读 › 更正选中文字…”,或阅读区“更多”菜单中的同名命令。
- 在“更正为”中写新文字,点“保存”。
保存后,阅读区顶部显示“N 处更正”。更正过的文字带底色和下划线,悬停可以看到原文。取消勾选“显示更正”即看到官方原文;“查看全部”转到侧栏“更正”分类。
- 更正只在保存它的版本和语言中显示,不会套用到另一种语言或其他版本。
- 更正绑定保存时的资料包和原文。资料包更新后,即使这段文字没变,更正也不再套用,列入“待重新定位”,状态为“原文已更新”。
- 在侧栏“更正”中右键可以“编辑更正”“恢复原文”或“删除更正…”。恢复原文会存为一个新修订;删除会移除全部修订,无法撤销。
- “在浏览器中打开”生成的页面只含官方原文,不含更正。
内容更新后重新定位
笔记和更正记住的是一段原文和它前后的文字。安装、更新或回滚资料包,以及导入个人资料之后,Crib 会重新核对每条记录的位置。也可以在“待重新定位”分类中点“重新定位”,或在“个人资料操作”菜单中选“重新定位全部”。
Crib 只在原文和保存时的前后文完全一致、并且只出现一次时自动找回位置。它不做近似匹配,也不会跳到另一种语言或另一个版本。找不到的记录列入“待重新定位”:
| 状态 | 含义 |
|---|---|
| 原文已更新 | 更正所在的资料包或原文变了,更正不再显示 |
| 原文出现多处 | 同样的文字和前后文出现了不止一次 |
| 找不到原文 | 页面还在,那段文字没有了 |
| 找不到原页面 | 页面不在资料库中,例如对应版本已卸载 |
点“打开记录”打开对应的笔记或更正:
- 笔记:在正文中选中新位置,点“关联当前选区”。旧的关联和每次核对的结果都会保留。
- 更正:对新原文重新选中文字,另建一条更正。
导出、导入与备份
这些命令在“个人资料操作”菜单中(侧栏个人资料分类标题右侧的“…”)。
| 命令 | 结果 |
|---|---|
| 导出个人资料… | 一个文件夹,默认名 Crib-personal,含全部笔记、更正、书签、阅读历史和修订 |
| 导出更正… | 同样格式的文件夹,默认名 Crib-corrections,只含更正 |
| 导入个人资料… | 选择一个导出的文件夹并合并进来 |
| 备份个人资料… | 一个 SQLite 文件,默认名 Crib-user-backup.sqlite |
导出的文件夹结构如下:
- 导入时,完全相同的条目跳过;与本机条目冲突的另存为副本,完成后提示“已导入 N 条,M 条冲突另存为副本”。
manifest.json记录了每个 Markdown 文件的校验值。只改动某个.md文件会使整个导出无法导入。导出格式用于在 Crib 之间搬运,不是通用的 Markdown 导入入口。- 导出和备份不能保存到 Crib 自己的数据文件夹里。
个人资料无法打开时
磁盘已满、文件损坏等原因导致个人资料无法打开时,Crib 只停用个人资料功能,阅读和搜索不受影响。侧栏个人资料分类中显示“无法打开个人资料”,有两个处理办法:
- 从备份恢复…:选择之前用“备份个人资料…”保存的文件。Crib 先检查备份,再替换;原文件改名保留。
- 新建个人资料…:确认后以空白的个人资料重新打开,原文件改名保留在原目录,不会删除。
启动时的提示默认按钮是“稍后处理”。如果提示的是“个人资料需要更新版本的 Crib”,说明文件完好,只是由更新版本的 Crib 写入;此时只提供“从备份恢复…”,更新 Crib 后即可正常使用。
5 - 片段
片段是常用的 SQL、命令或说明文字,保存在片段库中。用的时候填好参数,复制到剪贴板,再粘贴到需要的地方。Crib 不会在其他应用里自动展开片段。
片段库
片段库在“设置 › 片段”中,“文件 › 打开片段库”直接打开这一页。
- 顶部的“启用片段”和“在搜索结果中显示片段”都勾选时,片段才出现在主搜索结果中。
- 列表上方可以按名称、触发词或正文搜索,也可以按标签筛选。
- “新建片段…”新建;“更多操作”菜单中有“从剪贴板新建…”“导入片段库…”“导出片段库…”。
- 选中一个片段后可以“复制”“复制原文”“编辑…”“创建副本”或“删除”。
“文件”菜单中的“新建片段…”和“从剪贴板新建片段…”也会打开这一页并直接进入编辑。
新建与编辑
| 字段 | 规则 |
|---|---|
| 名称 | 必填,1–80 个字符,不能与其他片段重名(不分大小写) |
| 触发词 | 可选,1–32 个小写字母、数字、- 或 _,以字母开头,不能重复;搜索时也会匹配 |
| 语言 | 默认 SQL,最多 32 个字符;决定是否按 SQL 着色 |
| 标签 | 用逗号分隔,最多 20 个,每个不超过 40 个字符 |
| 正文 | 最多 1,000,000 个字符 |
新片段的正文默认是 SELECT * FROM __TABLE__;,可以直接改。
编辑器按键
| 按键 | 作用 |
|---|---|
| Tab | 在光标处插入 4 个空格;选中多行时整体增加缩进 |
| ⇧ 加 Tab | 每行去掉一个行首 Tab 或最多 4 个空格 |
| ↩ | 换行 |
| ⌘ 加 ↩ | 保存 |
| ⌃ 加 Tab / ⌃ 加 ⇧ 加 Tab | 离开正文,移到下一个 / 上一个控件 |
正文上方也有“增加缩进”“减少缩进”按钮。编辑器不会把引号、破折号自动替换成排版符号;每个编辑器有自己的撤销记录。用中文输入法选词时,保存会等组合输入结束后再进行。
参数与展开
正文中用分隔符括起的词是参数,复制时填写:
- 默认分隔符是两个下划线,
__TABLE__就是名为 TABLE 的参数。同名参数出现多次,只填一次。 - 参数名不能含空格或换行;只有开头没有结尾的分隔符按普通文字处理。
@date和@time换成复制时的日期和时间,默认格式分别是MM.dd.yyyy和HH:mm:ss。
分隔符和两种格式在“设置 › 片段”中修改。分隔符是 1–8 个字符,不能含字母或数字。日期格式点“查看写法”可以看到 yyyy、MM、dd、HH、mm、ss 等写法和示例,修改后要点“应用”才生效。
复制一个有参数的片段时,会打开“填写参数”:
- 逐个填写参数。确实要留空的,勾选该参数旁的“留空”。
- 下方“预览”实时显示结果。
- 全部参数填好或标为留空后,按 ⌘ 加 ↩ 或点“复制”。
没有参数的片段直接复制。“复制原文”不替换参数和日期时间,原样复制正文。
SQL 着色
语言写成 SQL、PostgreSQL、Postgres、pgsql、PLpgSQL 或 PL/pgSQL(不分大小写)时,编辑器、片段详情和参数预览按 SQL 着色:关键词、字符串、带引号的标识符、注释、数字和 $1 这类位置参数,包括 E'…' 字符串、$$ 引用和嵌套注释。
着色只是阅读辅助,不检查 SQL 是否正确。其他语言按普通文本显示。
在搜索结果中
搜索框有内容时,名称、触发词、正文、语言或标签中含查询文字的片段,显示在结果最上方的“片段”分组中。右键可以“复制正文”“展开并复制…”或“打开片段库”。
“设置 › 片段”中关闭“在搜索结果中显示片段”即可隐藏;单个搜索方案也可以关闭“在结果中显示片段”。
从其他应用创建
在其他应用中选中文字,选“服务 › 在 Crib 中创建片段”,Crib 打开新建片段,正文是选中的文字,名称是“所选文字片段”,确认后保存。菜单中没有这一项时的设置办法见系统服务。
片段库文件与共用
默认片段库是用户目录中的 snippets.json:
片段、参数分隔符和日期时间格式都保存在这个文件里。在“设置 › 片段”的“片段库”一行可以换文件:
- 另存为…:把当前片段库另存为新文件,并改用新文件。原文件保留,已有的同名文件不会被覆盖。
- 打开…:改用一个已有的片段库文件,不合并、不修改原来的库。要把片段合并进当前库,用“导入片段库…”,冲突的片段会自动改名。
当前用的是哪个文件只记在本机,不写进片段库本身。所以可以把片段库放进 iCloud Drive 等同步文件夹,在另一台 Mac 上“打开…”同一个文件。Crib 每两秒检查一次文件,别处的修改会自动出现。文件的传送由同步服务负责。
共用时要注意:
- 在别处被改过的片段,保存会被拒绝,草稿保留,可以“另存为新片段”。副本使用新的标识,触发词清空。
- 删除片段会同时从所有共用这个文件的 Mac 上删除。
- 文件丢失、只写了一半或来自更新版本的 Crib 时,片段库变为只读:已经载入的内容继续显示,从未载入时显示“片段库未载入”。Crib 不会自动新建一个空库代替它。文件恢复或打开另一个有效的库后即可继续编辑。
- 片段库文件上限 8 MiB,必须是普通文件,不能是符号链接。
6 - 快捷键
下表是开发构建的默认值,均可在“设置 › 快捷键”中修改,见修改快捷键。菜单和工具栏的悬停提示始终显示当前生效的组合。
搜索与查找
| 命令 | 默认 | 菜单 |
|---|---|---|
| 搜索资料库 | ⌘ 加 L | 编辑 |
| 搜索资料库(备用) | ⌘ 加 K | 编辑 |
| 页内查找 | ⌘ 加 F | 编辑 |
| 查找下一个 | ⌘ 加 G | 编辑 |
| 查找上一个 | ⇧ 加 ⌘ 加 G | 编辑 |
| 使用所选内容查找 | ⌘ 加 E | 编辑 |
| 跳到所选内容 | ⌘ 加 J | 编辑 |
| 筛选目录 | ⇧ 加 ⌘ 加 F | 编辑 |
阅读
| 命令 | 默认 | 菜单 |
|---|---|---|
| 切换语言 | ⇧ 加 ⌘ 加 L | 编辑 |
| 双语对照 | ⇧ 加 ⌘ 加 B | 阅读 |
| 后退 | ⌘ 加 [ | 阅读 |
| 前进 | ⌘ 加 ] | 阅读 |
| 返回主页 | ⇧ 加 ⌘ 加 H | 阅读 |
| 放大 | ⌘ 加 + | 阅读 |
| 缩小 | ⌘ 加 - | 阅读 |
| 实际大小 | ⌘ 加 0 | 阅读 |
| 在浏览器中打开 | ⌥ 加 ⌘ 加 B | 阅读 |
书签、历史与笔记
| 命令 | 默认 | 菜单 |
|---|---|---|
| 添加书签 | ⌘ 加 D | 书签 |
| 显示书签 | ⇧ 加 ⌘ 加 D | 书签 |
| 显示历史 | ⇧ 加 ⌘ 加 Y | 书签 |
| 新建笔记 | ⇧ 加 ⌘ 加 N | 文件 |
标签页
| 命令 | 默认 | 菜单 |
|---|---|---|
| 新建标签页 | ⌘ 加 T | 文件 |
| 重新打开关闭的标签页 | ⇧ 加 ⌘ 加 T | 文件 |
| 显示上一个标签页 | ⇧ 加 ⌘ 加 [ | 窗口 |
| 显示下一个标签页 | ⇧ 加 ⌘ 加 ] | 窗口 |
不能修改的按键
| 位置 | 按键 | 作用 |
|---|---|---|
| 全局 | ⌘ 加 , | 设置 |
| 全局 | ⌘ 加 W | 关闭标签页或窗口 |
| 搜索框与结果 | ↑ ↓ | 选择结果 |
| 搜索框与结果 | ↩ | 打开 |
| 搜索框与结果 | ⌘ 加 ↩ | 在新标签页打开 |
| 搜索框与结果 | Esc | 回到正文 |
| 结果列表 | → / ← | 展开 / 收起多版本结果 |
| 目录、书签、历史弹出框 | ↑ ↓、↩、⌘ 加 ↩、Esc | 选择、打开、在新标签页打开、关闭 |
| 填写片段参数 | ⌘ 加 ↩ | 复制 |
片段编辑器的按键见片段。用中文输入法选词时,↩、Esc 和方向键先交给输入法,选词结束后才执行上表中的操作。
修改快捷键
打开“设置 › 快捷键”,“命令”分组列出上面四张表中的全部命令。
- 点某个命令右侧的“修改”,输入框显示“按下快捷键…”。
- 按下新的组合:至少一个修饰键(⌘ ⌥ ⌃ ⇧)加一个按键。按 Esc 取消。
- 新组合立即生效。改过的命令旁出现“恢复默认”;没改过的命令旁是“停用”,停用后显示“已停用”。
两个命令不能用同一个组合,也不能与已开启的全局快捷键相同;重复时 Crib 会提示是哪两项冲突,设置保持不变。录制期间全局快捷键暂停。
全局快捷键
全局快捷键在其他应用处于前台时也能唤出 Crib。三个都默认关闭,在“设置 › 通用 › 全局快捷键”中逐个打开:
| 动作 | 默认组合 |
|---|---|
| 显示窗口 | ⌃ 加 ⌥ 加 ⌘ 加 Space |
| 打开搜索 | ⌥ 加 ⌘ 加 Space |
| 搜索选中文字 | ⌃ 加 ⌥ 加 ⌘ 加 D |
- 点“修改”录制新组合,规则与上面相同。组合被系统或其他应用占用时,该行显示原因和“重试”。
- “搜索选中文字”需要辅助功能权限,用“授予权限…”打开系统设置,授权后点“重新检查”。读不到选中文字时,可以在原应用中用“服务 › 在 Crib 中查找”。
- 组合按当前键盘布局解析,切换输入法后会重新注册。
设置页的开关与录制已经验证过;在其他应用处于前台时用实体键盘唤出 Crib,还没有实测。
全局快捷键、系统服务和其他集成方式的完整说明见集成。