> ## Documentation Index
> Fetch the complete documentation index at: https://dev.marginnote.com.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 卡片与摘录菜单

> 卡片菜单、文档菜单与选中文本菜单的模板配置，以及选中文本菜单上的划线快捷项

<Warning>
  本文由 AI 撰写，暂未经过人工校对，请谨慎参考。
</Warning>

场景界面里的弹出菜单由模板顶层的 `selectionMenu` 决定。插件负责命令本身，模板负责菜单上摆的条目。

`selectionMenu` 是一个对象，对象中的每个字段是一张清单。每张清单是一个字符串数组，数组里的每个元素是一个动作代号。清单列出的是该菜单允许出现的最大集。

字段整体留空表示不接管，菜单沿用收藏管理器里的收藏。这一条与其他位置一致，参见[最小打包](/zh/basic-package)。

模板编辑器把这些清单集中在卡片与摘录菜单这一页。该页顶部的搜索框同时过滤卡片与摘录菜单、卡片多选工具栏与划线快捷项，只留下名字命中的条目，一条都没有命中时给出提示，清空搜索框即恢复全部。搜索框下方的折叠段写着菜单设置说明，内容与本篇的最大集语义一致。

# 清单与作用位置

`SelectionMenu` 的字段如下。

| 字段 | 类型 | 作用位置 |
| - | - | - |
| `cards` | `[String]?` | 卡片菜单。在脑图与大纲中共用一张清单。 |
| `documents` | `[String]?` | 文档上的卡片菜单。在 PDF、EPub、视频等界面上共用一张清单。 |
| `text` | `[String]?` | 选中文本时弹出的菜单。在 PDF 与 EPub 上共用一张清单。 |
| `PDFReader` | `[String]?` | 按宿主界面细分的写法，仅 PDF 阅读器生效。 |
| `EPubReader` | `[String]?` | 按宿主界面细分的写法，仅 EPub 阅读器生效。 |
| `MindMap` | `[String]?` | 按宿主界面细分的写法，仅脑图生效。 |
| `Digest` | `[String]?` | 按宿主界面细分的写法，仅 Digest 界面生效。 |

模板编辑器中呈现的清单如下：卡片菜单、文档上的卡片菜单、选中文本菜单。表中后四项是按宿主界面细分的写法，用于覆盖特定界面。

<Note>
  `text` 的取值范围与其他清单不同。该清单给出的是条上允许出现的最大集，清单之外的动作收进 `More` 子菜单，仍然可以点到。其余清单之外的条目不出现。
</Note>

`text` 留空表示沿用收藏管理器里收在折叠集中的条目，与其余清单的留空含义一致。

# 最大集语义

清单里列出的条目限定的是最大范围，与逐条打开的开关不同。菜单真正弹出时，宿主还会按当时实际可用的操作过滤一遍。因此在同一张清单里同时写出删除卡片与删除摘录，菜单上仍然只出现其中实际可用的动作。

选中文本菜单的过滤方式与卡片菜单不同：清单之外的条目不会消失，而是收进 `More` 子菜单，仍然可以点到。

其余几点同样需要注意。

* 未接管过时，菜单显示的是当前的收藏。一经勾选即视为接管，此后这张菜单的摆法由模板决定。
* 场景界面下这些菜单只认场景模板。在卡片菜单上添加条目、在选中文本菜单的 `More` 里打开定制入口、以及长按菜单项收藏或取消收藏，改的都是模板里的这几张清单，不再写学习集或全局设置。传统界面不受影响。
* 每份清单一行一个功能，已勾选的条目排在前面。清单标题右侧有编辑顺序与恢复默认按钮，恢复默认按钮在接管之后才出现。

<Note>
  摘录完成后，场景阅读现场会浮出一条结果浮条，浮条上的 `摘录操作` 按钮打开摘录菜单。该浮条由 `surfaces.excerptResultBar` 控制，参见[顶部工作栏与浮窗](/zh/template-surfaces)。
</Note>

## 候选项

清单在编辑器中列出的条目取自候选项。候选项由默认收藏与该菜单实际出现过的条目组成，因此刚接管时清单可能为空，编辑器会提示需要进入场景界面打开一次对应的菜单才会登记。菜单在此后出现过的新条目同样会补进候选。

## 编辑顺序与恢复默认

清单标题右侧提供编辑顺序与恢复默认按钮。编辑顺序打开一个可以拖动排序、增删条目的编辑器，只在该清单已有候选项时出现。恢复默认按钮在接管之后才出现。

<Tip>
  系统场景模板下这几份清单也能在编辑器中直接修改，改动只存在当前设备上，不随模板分发给别人。
</Tip>

# 菜单项代号

清单里的每个元素是一个动作代号。内置动作的代号是封闭集合，全部列出见[代号词汇表](/zh/template-vocabulary)。本文只取其中几项作示例。

**部分代号末尾带冒号，冒号是代号本身的一部分，写的时候不能省。** 也有不带冒号的代号，带冒号与不带冒号的写法都合法。

```json template.json theme={null}
{
  "id": "u-hello",
  "name": "你好世界",
  "selectionMenu": {
    "cards": [
      "noteHighlight:",
      "commentNote"
    ],
    "documents": [
      "sendHighlight:",
      "noteHighlight:"
    ]
  }
}
```

数组中的顺序即菜单中的排列顺序。

内置动作的代号除上述几项外还有许多，全部清单见[代号词汇表](/zh/template-vocabulary)。同一个功能在不同菜单里的代号可能不同，写入时以目标菜单的清单为准。

<Warning>
  代号拼错时宿主不报错，该条目被静默忽略。模板校验脚本检查字段名与各份名册的条目，`selectionMenu` 中的代号不在其检查范围内。
</Warning>

# 插件命令项

插件贡献的命令使用另一形状的代号：`addon.<插件id>.<命令id>:`。末尾的冒号同样不能省略。

这类条目需要两边齐备。插件在 `mnaddon.json` 的 `cardCommands` 中声明这条命令，模板在对应的清单中写出这个代号，两边都写才会出现在菜单上。命令的声明写法与接收方式见[卡片与摘录菜单命令](/zh/menu-commands)。

插件本身需先列入模板顶层的 `plugins` 白名单，未列入时不存在。

```json mnaddon.json theme={null}
{
  "addonid": "mn.starter",
  "title": "起步",
  "version": "0.3.0",
  "marginnote_version_min": "4.5.0",
  "panel": "index.html",
  "cardCommands": [
    {
      "id": "annotate",
      "title": { "zh-Hans": "添加批注", "en": "add a comment" }
    }
  ]
}
```

```json template.json theme={null}
{
  "id": "u-hello",
  "name": "你好世界",
  "plugins": ["mn.starter"],
  "selectionMenu": {
    "cards": [
      "noteHighlight:",
      "commentNote",
      "addon.mn.starter.annotate:"
    ],
    "documents": [
      "sendHighlight:",
      "noteHighlight:",
      "addon.mn.starter.annotate:"
    ]
  }
}
```

<Note>
  菜单上找不到这一项时，逐一核对下表即可定位原因。
</Note>

常见现象与排查方向如下。

| 现象 | 排查方向 |
| - | - |
| 菜单上没有这一项 | 插件是否在 `mnaddon.json` 的 `cardCommands` 中声明了该命令。 |
| 声明之后仍不出现 | 插件是否列进了模板顶层的 `plugins` 白名单。 |
| 卡片菜单上出现，文档菜单上没有 | 模板是否在 `documents` 中也写出了同一个代号。 |
| 任何清单里都写不生效 | 代号末尾的冒号是否漏写。 |
| 同一条命令在卡片菜单与文档菜单里表现不同 | 命令在 `mnaddon.json` 中声明的 `when` 条件是否在这张菜单所对应的卡片上成立。 |

# 划线快捷项

选中文本时弹出的菜单上有一排快捷按钮，每个按钮点下去就把选中的文字按预定的设置摘录成卡片。这排按钮由模板顶层的 `excerptShortcuts` 定义，该字段不在 `selectionMenu` 之内，最多容纳 8 个按钮。

字段的值是字典数组，每个按钮是一个字典对象。可确证的字段如下。

| 字段 | 类型 | 说明 |
| - | - | - |
| `title` | `String` | 按钮上显示的文字。 |
| `hashtag` | `String` | 该项摘录出的卡片所带的标签。 |
| `color_index` | `Int` | 该项使用的颜色序号。 |
| `ai_addon` | `String` | 该项的 AI 处理交给的插件 id，对应编辑器里的 `AI 交给：……`。取值写法见[AI 任务](/zh/template-ai)。 |

按钮摆在条上的哪几个槽位，由 `text` 清单决定。清单中列出对应的槽位条目，哪几个槽位才真正摆到条上。槽位条目的完整清单见[代号词汇表](/zh/template-vocabulary)。

```json template.json theme={null}
{
  "id": "u-hello",
  "name": "你好世界",
  "excerptShortcuts": [
    { "title": "抓取一句", "hashtag": "", "color_index": 0, "ai_addon": "" },
    { "title": "标记标题", "hashtag": "#重点", "color_index": 1, "ai_addon": "" }
  ],
  "selectionMenu": {
    "text": [
      "noteHighlight:"
    ]
  }
}
```

留空表示跟随当前生效的快捷项设置，在学习集保存摘录设置时跟随学习集，否则跟随全局。写出取值之后，场景界面期间使用模板中登记的快捷项，在场景界面里新建、编辑、删除快捷项都写回该字段，每个模板各自独立。

编辑器中这一块的标题写作 `划线快捷项（选中文本菜单上的快捷按钮，最多 8 个）`，当前生效的一行写明眼下使用的是哪一套。接管之后出现用当前这套覆盖场景模板里的按钮，同时提供改回跟随学习集或全局的入口以放弃接管。每一项右侧有编辑与删除按钮，未满上限时底部出现新建快捷项的入口。装有会接 AI 任务的插件时，每一项下方还有 AI 交给的菜单。还没有快捷项时编辑器给出提示；从场景界面之外打开编辑器读不到当前生效的快捷项，同样给出提示。

系统场景模板下这一整块只能查看，复制为个人模板之后才能修改。

# 与多选工具栏的关系

卡片被多选时底部出现的工具栏由 `surfaces.multiSelect` 控制，与本篇的清单分属不同字段，参见[顶部工作栏与浮窗](/zh/template-surfaces)。

# 完整示例

下面这份模板接管卡片菜单、文档上的卡片菜单、选中文本菜单、划线快捷项与一条插件命令。

```json template.json theme={null}
{
  "id": "u-starter",
  "name": "起步",
  "minAppVersion": "4.5.0",
  "plugins": ["mn.starter"],
  "selectionMenu": {
    "cards": [
      "noteHighlight:",
      "commentNote",
      "addon.mn.starter.annotate:"
    ],
    "documents": [
      "sendHighlight:",
      "noteHighlight:",
      "addon.mn.starter.annotate:"
    ],
    "text": [
      "noteHighlight:"
    ]
  },
  "excerptShortcuts": [
    { "title": "抓取一句", "hashtag": "", "color_index": 0, "ai_addon": "" },
    { "title": "标记标题", "hashtag": "#重点", "color_index": 1, "ai_addon": "" }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.