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

场景界面里的弹出菜单由模板顶层的 selectionMenu 决定。插件负责命令本身，模板负责菜单上摆的条目。 selectionMenu 是一个对象，对象中的每个字段是一张清单。每张清单是一个字符串数组，数组里的每个元素是一个动作代号。清单列出的是该菜单允许出现的最大集。字段整体留空表示不接管，菜单沿用收藏管理器里的收藏。这一条与其他位置一致，参见最小打包。模板编辑器把这些清单集中在卡片与摘录菜单这一页。该页顶部的搜索框同时过滤卡片与摘录菜单、卡片多选工具栏与划线快捷项，只留下名字命中的条目，一条都没有命中时给出提示，清空搜索框即恢复全部。搜索框下方的折叠段写着菜单设置说明，内容与本篇的最大集语义一致。

清单与作用位置

SelectionMenu 的字段如下。

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

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

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

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

最大集语义

清单里列出的条目限定的是最大范围，与逐条打开的开关不同。菜单真正弹出时，宿主还会按当时实际可用的操作过滤一遍。因此在同一张清单里同时写出删除卡片与删除摘录，菜单上仍然只出现其中实际可用的动作。选中文本菜单的过滤方式与卡片菜单不同：清单之外的条目不会消失，而是收进 More 子菜单，仍然可以点到。其余几点同样需要注意。

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

摘录完成后，场景阅读现场会浮出一条结果浮条，浮条上的 摘录操作 按钮打开摘录菜单。该浮条由 surfaces.excerptResultBar 控制，参见顶部工作栏与浮窗。

候选项

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

编辑顺序与恢复默认

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

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

菜单项代号

清单里的每个元素是一个动作代号。内置动作的代号是封闭集合，全部列出见代号词汇表。本文只取其中几项作示例。 部分代号末尾带冒号，冒号是代号本身的一部分，写的时候不能省。 也有不带冒号的代号，带冒号与不带冒号的写法都合法。

template.json

{
  "id": "u-hello",
  "name": "你好世界",
  "selectionMenu": {
    "cards": [
      "noteHighlight:",
      "commentNote"
    ],
    "documents": [
      "sendHighlight:",
      "noteHighlight:"
    ]
  }
}

数组中的顺序即菜单中的排列顺序。内置动作的代号除上述几项外还有许多，全部清单见代号词汇表。同一个功能在不同菜单里的代号可能不同，写入时以目标菜单的清单为准。

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

插件命令项

插件贡献的命令使用另一形状的代号：addon.<插件id>.<命令id>:。末尾的冒号同样不能省略。这类条目需要两边齐备。插件在 mnaddon.json 的 cardCommands 中声明这条命令，模板在对应的清单中写出这个代号，两边都写才会出现在菜单上。命令的声明写法与接收方式见卡片与摘录菜单命令。插件本身需先列入模板顶层的 plugins 白名单，未列入时不存在。

mnaddon.json

{
  "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" }
    }
  ]
}

template.json

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

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

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

现象	排查方向
菜单上没有这一项	插件是否在 `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 任务。

按钮摆在条上的哪几个槽位，由 text 清单决定。清单中列出对应的槽位条目，哪几个槽位才真正摆到条上。槽位条目的完整清单见代号词汇表。

template.json

{
  "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 控制，与本篇的清单分属不同字段，参见顶部工作栏与浮窗。

完整示例

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

template.json

{
  "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": "" }
  ]
}

开始

基础

模板配置

深入插件

API 参考

卡片与摘录菜单

清单与作用位置

最大集语义

候选项

编辑顺序与恢复默认

菜单项代号

插件命令项

划线快捷项

与多选工具栏的关系

完整示例

​清单与作用位置

​最大集语义

​候选项

​编辑顺序与恢复默认

​菜单项代号

​插件命令项

​划线快捷项

​与多选工具栏的关系

​完整示例

清单与作用位置

最大集语义

候选项

编辑顺序与恢复默认

菜单项代号

插件命令项

划线快捷项

与多选工具栏的关系

完整示例