跳转到主要内容

这是本节的多页打印视图。 .

返回本页常规视图.

使用指南

安装与首次启动、搜索语法、双语阅读、笔记与本地更正、片段和快捷键。

1 - 安装与首次启动

Crib 现在能不能装、需要什么系统、两种版本有什么区别,以及第一次打开时会发生什么。
还没有公开安装包

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 资料包文件时,可以在资料库中“导入资料包…”。

首次启动

  1. 打开 Crib。不需要账号,也不需要联网:两种版本都直接使用随应用附带的内容和索引。
  2. 窗口默认打开 PG 18 中文手册,内容版本是 18.6。搜索范围默认是“PG 18 · 简体中文 · 手册”。
  3. 按 ⌘ 加 L 开始搜索。搜索语法见搜索。
  4. 点工具栏的主页按钮(⇧ 加 ⌘ 加 H)可以回到主页,从“获取版本”“资料库”“搜索方案”“快捷键”四个入口继续设置。

本地 API 和三个全局快捷键默认关闭,不会在首次启动时请求权限。只有“搜索选中文字”全局快捷键需要辅助功能权限,开启时再授予。

个人资料放在哪里

设置、片段库、笔记、书签、更正、阅读历史和下载的资料包都存放在:

~/Library/Application Support/Crib/

这个目录不在应用包内。卸载某个文档版本不会删除挂在上面的笔记和更正。各文件的用途见用户数据与迁移。

从 PGDash 迁移

Crib 以前叫 PGDash。如果本机有 ~/Library/Application Support/PGDash/,Crib 启动时会把它复制一份到新目录,旧目录原样保留,不修改也不删除。

  • 迁移失败时,Crib 以只读方式运行:可以阅读和搜索内置内容,但笔记、书签、更正、阅读历史、下载和设置都不能修改。每次启动会重试;提示中也可以“重试迁移”或“跳过迁移…”。
  • 跳过迁移后,Crib 从空白的个人资料开始,旧资料原样留在原目录。
  • 已经有 Crib 资料时又发现旧资料,Crib 会提示“发现 PGDash 旧资料”,由你选择“迁移旧资料”或“不再提示”。选择迁移时,现有的 Crib 资料会整体移到一旁保留。

迁移的完整规则和恢复办法见用户数据与迁移。

2 - 搜索

用版本前缀和筛选条件把搜索限定到某个版本、语言或资料类型,查技术符号和中文词语,并在没有结果时调整范围。
搜索 work_mem 的结果:中间结果栏列出 14 条 PG 18.6 中文手册结果,每条标注版本、语言、资料类型和“精确”,底部是 Google 与 Stack Overflow 网页搜索;右侧阅读区是 PostgreSQL 18.6 中文手册
搜索 work_mem(2026-11-06 开发构建,深色外观)

按 ⌘ 加 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目前只有这一个项目
Wiki 集合筛选要离开“手册”

左侧栏选的是“手册”时,搜索限定在手册内,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+、\dCpsql 命令,区分大小写,只做精确匹配
23505SQLSTATE 代码,按字符串匹配
复制延迟、事务隔离中文词语,按相邻两字匹配
锁单个汉字,只匹配标题和名称
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 个版本”。
  • 分组标题下有版本摘要,点它或按 → 展开,按 ← 收起。
  • 折叠时按 ↩ 打开组内排在最前的一条。组内先列范围栏选定的版本,其余从新到旧。

搜索方案

范围栏最左边的“搜索方案”菜单保存常用范围:版本、语言、资料类别,以及可选的搜索框提示语和触发词。

  1. 调好范围栏,在菜单中选“将当前范围存为方案…”。
  2. 在“设置 › 搜索”中编辑、停用或删除方案,并可以指定“新窗口默认方案”。
  3. 给方案加触发词后,在搜索框输入 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 - 阅读与双语对照

在目录、标签页和历史之间移动,页内查找,切到另一种语言的同一章节或两栏对照,调整外观,复制链接和查看来源。
阅读 PostgreSQL 18.6 中文手册:左侧栏是资料分类,中间一栏是手册目录,右侧阅读区显示手册首页;阅读区右上角依次是目录、版本、添加书签、书签、阅读历史、English 和更多按钮
阅读手册(2026-11-06 开发构建,深色外观)

窗口布局

窗口分三栏:

  • 侧栏:资料分类。“手册”“全部资料”、六组 Wiki 集合,以及“个人资料”下的笔记、更正、书签、阅读历史、标签和待重新定位。
  • 中间一栏:有查询时是“结果”,没有查询时是当前范围的“目录”,按手册顺序列出章节。
  • 阅读区:标题下方写明正在读的版本、语言和资料类型,例如“PostgreSQL 18 · 中文 · 手册”。正文的版本和语言以这里为准,不以范围栏为准。

工具栏按钮可以隐藏侧栏或结果栏;“设置 › 通用 › 显示”中的“显示侧栏”“显示搜索结果栏”决定默认状态。

本页目录

阅读区右上角的“目录”按钮(⇧ 加 ⌘ 加 F,菜单名“筛选目录”)列出当前页面的全部章节,当前章节有标记。在“筛选章节”框中输入标题或对象名可以过滤。

按键作用
↑ ↓选择章节
↩跳转
⌘ 加 ↩在新标签页打开
Esc关闭,回到正文

双语对照时,在哪一栏打开目录,就列出哪种语言的章节。目录不改变搜索框的查询和范围。

标签页与窗口

Crib 使用 macOS 原生窗口标签页。每个标签页有自己的查询、搜索范围、正文和前进后退记录。

操作方法
新建标签页⌘ 加 T
在新标签页打开结果、目录或历史条目⌘ 加 ↩,或右键“在新标签页打开”
复制当前标签页文件 › 复制标签页
重新打开关闭的标签页⇧ 加 ⌘ 加 T
上一个 / 下一个标签页⇧ 加 ⌘ 加 [ / ⇧ 加 ⌘ 加 ]
关闭标签页或窗口⌘ 加 W

“设置 › 通用 › 启动”中的“启动时恢复窗口和标签页”默认开启,恢复时包括查询、搜索范围和阅读位置。

后退与前进

⌘ 加 [ 和 ⌘ 加 ] 在当前标签页读过的页面之间后退、前进。按住工具栏的后退或前进按钮会列出可以跳到的页面;同样的列表也在“阅读 › 后退到 / 前进到”中。

这份记录只属于当前标签页。跨标签页、跨启动保留的阅读记录是“阅读历史”(⇧ 加 ⌘ 加 Y),见笔记、书签与本地更正。

页内查找

操作按键
页内查找⌘ 加 F
查找下一个 / 上一个⌘ 加 G / ⇧ 加 ⌘ 加 G
用选中的文字查找⌘ 加 E
跳到选中的文字⌘ 加 J

查找栏右侧的“完成”关闭查找栏。双语对照时,查找作用于获得焦点的那一栏,查找栏左侧标出“中文正文”或“English 正文”。

切换语言

按 ⇧ 加 ⌘ 加 L,或点阅读区右上角的“English”/“中文”,打开另一种语言中对应的章节,并停在同一小节。

对应关系在构建资料包时确定,手册依据源码中的章节标识,不按标题或网址猜测。

  • 当前小节在另一种语言中有对应时,直接打开。
  • 没有对应时,Crib 逐级向上找,打开最近的有对应的上级章节。按钮的悬停提示写明“已定位到上级章节”。
  • 对应关系不是逐段核对过的,提示“对应章节未逐段核对”。
  • 一直找不到时,按钮不可用,提示“这一节还没有已核对的对应章节。”

双语对照

按 ⇧ 加 ⌘ 加 B,或点工具栏的“双语对照”按钮,阅读区分成两栏:左栏是当前正文,右栏是另一种语言的对应页面。

  • 滚动任一栏,另一栏跳到对应的章节。对齐只到章节一级,不逐句对齐。
  • 找不到对应章节时,右栏显示“没有对应章节”和原因。
  • 阅读设置同时作用于两栏。
  • 页内查找、“目录”和“在浏览器中打开”作用于获得焦点的那一栏;“更多”菜单中另有“在浏览器中打开 English 页面”或“中文页面”。

切换版本

阅读区右上角的“版本”按钮显示正在读的版本,并列出资料库中的其他版本。点某个版本的“阅读”,Crib 尽量停在同一位置:

  1. 先找同一章节标识;
  2. 找不到时打开上级章节或同名页面,提示“PG N 中没有这一节,已打开上级章节”之类的说明;
  3. 连页面都没有时打开该版本的目录首页。

未安装的版本显示“在资料库中显示”。打开“专家模式”后,列表也包括历史版本和开发版。安装与启用版本见资料库。

外观与缩放

浅色、深色或跟随系统在“设置 › 通用 › 显示 › 外观”中选择。正文排版在“设置 › 阅读”中调整,立即作用于所有窗口:

设置范围
页面缩放60%–300%,步长 10%
字体系统字体、衬线字体
字号12–24 pt
行距1.30–2.00
行宽适应窗口、紧凑 640 pt、标准 800 pt、宽 1040 pt

⌘ 加 + / ⌘ 加 - 每次缩放 10%,⌘ 加 0 回到 100%,“阅读 › 放大到 200%”一步放大。“设置 › 阅读”底部的“恢复默认”重置以上各项。

  • 代码:代码块右上角有“复制”按钮,复制后短暂显示“已复制”。
  • 链接:“更多 › 复制链接”复制正在阅读的章节的 crib:// 链接;在结果上右键也有“复制链接”。链接带有章节和资料包标识,格式与打开规则见链接。
  • 选中的文字:“更多”菜单中可以“搜索选中文字”,或用网页搜索查它。

在浏览器中打开

按 ⌥ 加 ⌘ 加 B,或选“更多 › 在浏览器中打开”,Crib 生成这一页的本地副本,用默认浏览器打开。副本是官方原文,不含你的笔记和更正,也不运行脚本。生成期间状态栏显示“正在准备页面…”,可以取消。

来源与许可

“更多 › 来源与许可”显示这一页的出处:

  • 版本:项目、内容版本和渠道;
  • 资料包及其修订号;
  • 页面路径、锚点和章节标识;
  • 页面和正文的校验值;
  • “来源”和“许可”两个标签页,列出该资料包的来源清单和许可证。

4 - 笔记、书签与本地更正

在章节上写 Markdown 笔记、加书签和标签、查阅读历史、更正译文,内容更新后重新定位,以及导出、导入、备份和恢复个人资料。

笔记、书签、标签、阅读历史和更正统称个人资料,保存在 ~/Library/Application Support/Crib/ 中,与资料包分开。卸载或更新文档版本不会删除它们;个人资料出问题时,阅读和搜索照常可用。

侧栏“个人资料”下有笔记、更正、书签、阅读历史、标签和待重新定位六个分类。选中某个分类时,搜索框改为在其中按标题、正文和标签做字面筛选。

笔记

点工具栏的“笔记”按钮打开笔记面板,按 ⇧ 加 ⌘ 加 N 新建笔记。

  • 新笔记的标题默认是当前章节的标题。新建时正文中有选中的文字,笔记就关联到这段原文,面板中显示“关联的原文”和“打开原文”。
  • 以后要改关联位置,在正文中选中新的文字,点“关联当前选区”。
  • 正文是 Markdown,“编辑”与“预览”之间切换。预览只打开 http、https 和 mailto 链接。
  • 标签写在“标签,用逗号分隔”一栏。
  • “修订”菜单列出保存过的版本,“恢复修订 N”会把它存为一个新修订,不覆盖历史。
  • 在侧栏“笔记”中右键可以“编辑笔记”“打开原文”或“删除笔记…”。删除会连同所有修订一起删除,无法撤销。

自动保存与冲突

停止输入片刻后笔记自动保存,面板底部依次显示“等待自动保存…”和“已自动保存 · 修订 N”。

  • 保存失败时显示“保存失败:”和原因,草稿留在编辑器中,不会显示为已保存。
  • 同一条笔记在两个窗口里都改过时,后保存的一份不会覆盖先保存的:它的编辑器显示保存失败,草稿保留。
  • 导出、导入和备份前,Crib 先保存所有草稿;上面那种冲突的草稿另存为标题带“(冲突副本)”的新笔记并提示,之后的修改保存到这份副本。
  • 退出时仍有无法保存的草稿,会弹出“无法保存个人资料”,可以“另存为副本并退出”“放弃修改并退出”或“继续编辑”。
说明

草稿只在保存成功后才写入磁盘。应用崩溃或磁盘不可写时,最后一次保存之后的输入可能丢失。

书签

按 ⌘ 加 D 给当前章节加书签,同时弹出编辑框,可以改名称、加标签。书签在弹出时就已添加,“取消”只放弃这次的修改。加过书签的章节,工具栏的书签图标变为实心。

⇧ 加 ⌘ 加 D 打开书签列表,可以按标题、版本或标签筛选,⌘ 加 ↩ 在新标签页打开,“在侧栏中查看全部”转到侧栏的“书签”分类。

标签

笔记和书签都可以加标签。侧栏“标签”分类顶部的标签选择器按标签列出笔记;“书签”分类顶部也有同样的选择器。

阅读历史

打开过的章节记入阅读历史。⇧ 加 ⌘ 加 Y 打开历史列表,可以按标题或版本筛选;侧栏“阅读历史”显示全部。

  • 保留最近 5,000 条、180 天以内的记录,连续重复打开同一处只记一次。超出的部分在启动时清理。
  • 右键单条记录可以“从历史中删除”。在侧栏“阅读历史”分类中,“个人资料操作”菜单里的“清除阅读历史…”删除全部历史,不影响笔记、书签和更正,无法撤销。

阅读历史与标签页的后退、前进记录是两回事,后者见后退与前进。

更正

更正用来记下你对正文(通常是译文)的修改。它只保存在你的个人资料里,不改动官方原文。

  1. 在正文中选中要改的文字。选区要在同一章节内,只含正文。
  2. 选“阅读 › 更正选中文字…”,或阅读区“更多”菜单中的同名命令。
  3. 在“更正为”中写新文字,点“保存”。

保存后,阅读区顶部显示“N 处更正”。更正过的文字带底色和下划线,悬停可以看到原文。取消勾选“显示更正”即看到官方原文;“查看全部”转到侧栏“更正”分类。

  • 更正只在保存它的版本和语言中显示,不会套用到另一种语言或其他版本。
  • 更正绑定保存时的资料包和原文。资料包更新后,即使这段文字没变,更正也不再套用,列入“待重新定位”,状态为“原文已更新”。
  • 在侧栏“更正”中右键可以“编辑更正”“恢复原文”或“删除更正…”。恢复原文会存为一个新修订;删除会移除全部修订,无法撤销。
  • “在浏览器中打开”生成的页面只含官方原文,不含更正。

内容更新后重新定位

笔记和更正记住的是一段原文和它前后的文字。安装、更新或回滚资料包,以及导入个人资料之后,Crib 会重新核对每条记录的位置。也可以在“待重新定位”分类中点“重新定位”,或在“个人资料操作”菜单中选“重新定位全部”。

Crib 只在原文和保存时的前后文完全一致、并且只出现一次时自动找回位置。它不做近似匹配,也不会跳到另一种语言或另一个版本。找不到的记录列入“待重新定位”:

状态含义
原文已更新更正所在的资料包或原文变了,更正不再显示
原文出现多处同样的文字和前后文出现了不止一次
找不到原文页面还在,那段文字没有了
找不到原页面页面不在资料库中,例如对应版本已卸载

点“打开记录”打开对应的笔记或更正:

  • 笔记:在正文中选中新位置,点“关联当前选区”。旧的关联和每次核对的结果都会保留。
  • 更正:对新原文重新选中文字,另建一条更正。

导出、导入与备份

这些命令在“个人资料操作”菜单中(侧栏个人资料分类标题右侧的“…”)。

命令结果
导出个人资料…一个文件夹,默认名 Crib-personal,含全部笔记、更正、书签、阅读历史和修订
导出更正…同样格式的文件夹,默认名 Crib-corrections,只含更正
导入个人资料…选择一个导出的文件夹并合并进来
备份个人资料…一个 SQLite 文件,默认名 Crib-user-backup.sqlite

导出的文件夹结构如下:

Crib-personal/
├── manifest.json        # 全部记录、修订、位置信息和各 Markdown 文件的校验值
├── notes/<ID>.md        # 每条笔记的正文
└── corrections/         # 每条更正的原文、新文字和一份对照说明
  • 导入时,完全相同的条目跳过;与本机条目冲突的另存为副本,完成后提示“已导入 N 条,M 条冲突另存为副本”。
  • manifest.json 记录了每个 Markdown 文件的校验值。只改动某个 .md 文件会使整个导出无法导入。导出格式用于在 Crib 之间搬运,不是通用的 Markdown 导入入口。
  • 导出和备份不能保存到 Crib 自己的数据文件夹里。

个人资料无法打开时

磁盘已满、文件损坏等原因导致个人资料无法打开时,Crib 只停用个人资料功能,阅读和搜索不受影响。侧栏个人资料分类中显示“无法打开个人资料”,有两个处理办法:

  • 从备份恢复…:选择之前用“备份个人资料…”保存的文件。Crib 先检查备份,再替换;原文件改名保留。
  • 新建个人资料…:确认后以空白的个人资料重新打开,原文件改名保留在原目录,不会删除。

启动时的提示默认按钮是“稍后处理”。如果提示的是“个人资料需要更新版本的 Crib”,说明文件完好,只是由更新版本的 Crib 写入;此时只提供“从备份恢复…”,更新 Crib 后即可正常使用。

5 - 片段

保存常用的 SQL 和命令文本,用参数和当前日期时间展开后复制,在多台 Mac 之间共用一个片段库,或从其他应用直接创建片段。

片段是常用的 SQL、命令或说明文字,保存在片段库中。用的时候填好参数,复制到剪贴板,再粘贴到需要的地方。Crib 不会在其他应用里自动展开片段。

片段库

片段库在“设置 › 片段”中,“文件 › 打开片段库”直接打开这一页。

  • 顶部的“启用片段”和“在搜索结果中显示片段”都勾选时,片段才出现在主搜索结果中。
  • 列表上方可以按名称、触发词或正文搜索,也可以按标签筛选。
  • “新建片段…”新建;“更多操作”菜单中有“从剪贴板新建…”“导入片段库…”“导出片段库…”。
  • 选中一个片段后可以“复制”“复制原文”“编辑…”“创建副本”或“删除”。

“文件”菜单中的“新建片段…”和“从剪贴板新建片段…”也会打开这一页并直接进入编辑。

新建与编辑

字段规则
名称必填,1–80 个字符,不能与其他片段重名(不分大小写)
触发词可选,1–32 个小写字母、数字、- 或 _,以字母开头,不能重复;搜索时也会匹配
语言默认 SQL,最多 32 个字符;决定是否按 SQL 着色
标签用逗号分隔,最多 20 个,每个不超过 40 个字符
正文最多 1,000,000 个字符

新片段的正文默认是 SELECT * FROM __TABLE__;,可以直接改。

编辑器按键

按键作用
Tab在光标处插入 4 个空格;选中多行时整体增加缩进
⇧ 加 Tab每行去掉一个行首 Tab 或最多 4 个空格
↩换行
⌘ 加 ↩保存
⌃ 加 Tab / ⌃ 加 ⇧ 加 Tab离开正文,移到下一个 / 上一个控件

正文上方也有“增加缩进”“减少缩进”按钮。编辑器不会把引号、破折号自动替换成排版符号;每个编辑器有自己的撤销记录。用中文输入法选词时,保存会等组合输入结束后再进行。

参数与展开

正文中用分隔符括起的词是参数,复制时填写:

SELECT pg_size_pretty(pg_total_relation_size('__TABLE__'));
-- 生成于 @date @time
  • 默认分隔符是两个下划线,__TABLE__ 就是名为 TABLE 的参数。同名参数出现多次,只填一次。
  • 参数名不能含空格或换行;只有开头没有结尾的分隔符按普通文字处理。
  • @date 和 @time 换成复制时的日期和时间,默认格式分别是 MM.dd.yyyy 和 HH:mm:ss。

分隔符和两种格式在“设置 › 片段”中修改。分隔符是 1–8 个字符,不能含字母或数字。日期格式点“查看写法”可以看到 yyyy、MM、dd、HH、mm、ss 等写法和示例,修改后要点“应用”才生效。

复制一个有参数的片段时,会打开“填写参数”:

  1. 逐个填写参数。确实要留空的,勾选该参数旁的“留空”。
  2. 下方“预览”实时显示结果。
  3. 全部参数填好或标为留空后,按 ⌘ 加 ↩ 或点“复制”。

没有参数的片段直接复制。“复制原文”不替换参数和日期时间,原样复制正文。

SQL 着色

语言写成 SQL、PostgreSQL、Postgres、pgsql、PLpgSQL 或 PL/pgSQL(不分大小写)时,编辑器、片段详情和参数预览按 SQL 着色:关键词、字符串、带引号的标识符、注释、数字和 $1 这类位置参数,包括 E'…' 字符串、$$ 引用和嵌套注释。

着色只是阅读辅助,不检查 SQL 是否正确。其他语言按普通文本显示。

搜索框有内容时,名称、触发词、正文、语言或标签中含查询文字的片段,显示在结果最上方的“片段”分组中。右键可以“复制正文”“展开并复制…”或“打开片段库”。

“设置 › 片段”中关闭“在搜索结果中显示片段”即可隐藏;单个搜索方案也可以关闭“在结果中显示片段”。

从其他应用创建

在其他应用中选中文字,选“服务 › 在 Crib 中创建片段”,Crib 打开新建片段,正文是选中的文字,名称是“所选文字片段”,确认后保存。菜单中没有这一项时的设置办法见系统服务。

片段库文件与共用

默认片段库是用户目录中的 snippets.json:

~/Library/Application Support/Crib/snippets.json

片段、参数分隔符和日期时间格式都保存在这个文件里。在“设置 › 片段”的“片段库”一行可以换文件:

  • 另存为…:把当前片段库另存为新文件,并改用新文件。原文件保留,已有的同名文件不会被覆盖。
  • 打开…:改用一个已有的片段库文件,不合并、不修改原来的库。要把片段合并进当前库,用“导入片段库…”,冲突的片段会自动改名。

当前用的是哪个文件只记在本机,不写进片段库本身。所以可以把片段库放进 iCloud Drive 等同步文件夹,在另一台 Mac 上“打开…”同一个文件。Crib 每两秒检查一次文件,别处的修改会自动出现。文件的传送由同步服务负责。

双机同步未经实测两个 Crib 先后编辑同一个本机文件已经测试过;通过 iCloud Drive、Dropbox 等服务在两台 Mac 之间同步还没有实测。

共用时要注意:

  • 在别处被改过的片段,保存会被拒绝,草稿保留,可以“另存为新片段”。副本使用新的标识,触发词清空。
  • 删除片段会同时从所有共用这个文件的 Mac 上删除。
  • 文件丢失、只写了一半或来自更新版本的 Crib 时,片段库变为只读:已经载入的内容继续显示,从未载入时显示“片段库未载入”。Crib 不会自动新建一个空库代替它。文件恢复或打开另一个有效的库后即可继续编辑。
  • 片段库文件上限 8 MiB,必须是普通文件,不能是符号链接。

6 - 快捷键

Crib 的全部默认快捷键,怎样修改、停用或恢复,以及三个默认关闭的全局快捷键。

下表是开发构建的默认值,均可在“设置 › 快捷键”中修改,见修改快捷键。菜单和工具栏的悬停提示始终显示当前生效的组合。

命令默认菜单
搜索资料库⌘ 加 L编辑
搜索资料库(备用)⌘ 加 K编辑
页内查找⌘ 加 F编辑
查找下一个⌘ 加 G编辑
查找上一个⇧ 加 ⌘ 加 G编辑
使用所选内容查找⌘ 加 E编辑
跳到所选内容⌘ 加 J编辑
筛选目录⇧ 加 ⌘ 加 F编辑

阅读

命令默认菜单
切换语言⇧ 加 ⌘ 加 L编辑
双语对照⇧ 加 ⌘ 加 B阅读
后退⌘ 加 [阅读
前进⌘ 加 ]阅读
返回主页⇧ 加 ⌘ 加 H阅读
放大⌘ 加 +阅读
缩小⌘ 加 -阅读
实际大小⌘ 加 0阅读
在浏览器中打开⌥ 加 ⌘ 加 B阅读

书签、历史与笔记

命令默认菜单
添加书签⌘ 加 D书签
显示书签⇧ 加 ⌘ 加 D书签
显示历史⇧ 加 ⌘ 加 Y书签
新建笔记⇧ 加 ⌘ 加 N文件

标签页

命令默认菜单
新建标签页⌘ 加 T文件
重新打开关闭的标签页⇧ 加 ⌘ 加 T文件
显示上一个标签页⇧ 加 ⌘ 加 [窗口
显示下一个标签页⇧ 加 ⌘ 加 ]窗口

不能修改的按键

位置按键作用
全局⌘ 加 ,设置
全局⌘ 加 W关闭标签页或窗口
搜索框与结果↑ ↓选择结果
搜索框与结果↩打开
搜索框与结果⌘ 加 ↩在新标签页打开
搜索框与结果Esc回到正文
结果列表→ / ←展开 / 收起多版本结果
目录、书签、历史弹出框↑ ↓、↩、⌘ 加 ↩、Esc选择、打开、在新标签页打开、关闭
填写片段参数⌘ 加 ↩复制

片段编辑器的按键见片段。用中文输入法选词时,↩、Esc 和方向键先交给输入法,选词结束后才执行上表中的操作。

修改快捷键

打开“设置 › 快捷键”,“命令”分组列出上面四张表中的全部命令。

  1. 点某个命令右侧的“修改”,输入框显示“按下快捷键…”。
  2. 按下新的组合:至少一个修饰键(⌘ ⌥ ⌃ ⇧)加一个按键。按 Esc 取消。
  3. 新组合立即生效。改过的命令旁出现“恢复默认”;没改过的命令旁是“停用”,停用后显示“已停用”。

两个命令不能用同一个组合,也不能与已开启的全局快捷键相同;重复时 Crib 会提示是哪两项冲突,设置保持不变。录制期间全局快捷键暂停。

全局快捷键

全局快捷键在其他应用处于前台时也能唤出 Crib。三个都默认关闭,在“设置 › 通用 › 全局快捷键”中逐个打开:

动作默认组合
显示窗口⌃ 加 ⌥ 加 ⌘ 加 Space
打开搜索⌥ 加 ⌘ 加 Space
搜索选中文字⌃ 加 ⌥ 加 ⌘ 加 D
  • 点“修改”录制新组合,规则与上面相同。组合被系统或其他应用占用时,该行显示原因和“重试”。
  • “搜索选中文字”需要辅助功能权限,用“授予权限…”打开系统设置,授权后点“重新检查”。读不到选中文字时,可以在原应用中用“服务 › 在 Crib 中查找”。
  • 组合按当前键盘布局解析,切换输入法后会重新注册。
说明

设置页的开关与录制已经验证过;在其他应用处于前台时用实体键盘唤出 Crib,还没有实测。

全局快捷键、系统服务和其他集成方式的完整说明见集成。