#上下文菜单

上下文菜单为文件、画布节点和数据行提供与当前位置相关的命令。它支持鼠标右键、Shift + F10、Menu 键、方向键、子菜单、禁用项和焦点恢复。

npm install @a3s-lab/ui@0.4.1

<div class="context-menu">
  <div data-context-trigger tabindex="0">deployment.acl</div>
  <div
    data-context-content
    role="menu"
    aria-label="文件操作"
    aria-hidden="true"
  >
    <button type="button" role="menuitem" data-value="open">打开</button>
    <button type="button" role="menuitem" data-value="rename">重命名</button>
  </div>
</div>

import "@a3s-lab/ui/a3s.css";
import "@a3s-lab/ui/all";

#用法

<div class="context-menu">
  <div data-context-trigger tabindex="0">deployment.acl</div>
  <div
    data-context-content
    role="menu"
    aria-label="文件操作"
    aria-hidden="true"
  >
    <button type="button" role="menuitem" data-value="open">打开</button>
    <button type="button" role="menuitem" data-value="rename">重命名</button>
  </div>
</div>

加载共享运行时后再加载 context-menu.js，或使用完整包。

#参数

#JavaScript API

const menu = document.querySelector(".context-menu");
menu.open({ target: selectedNode });
menu.openAt(240, 160, selectedNode, { source: "api" });
menu.focusItem("rename");
console.log(menu.getState());
menu.addEventListener("a3s:context-menu-select", ({ detail }) =>
  run(detail.value, detail.target),
);

open() 锚定目标打开，openAt() 使用视口坐标。focusItem()、select() 与 setChecked() 控制带稳定 data-value 的命令。close({ reason, restoreFocus, force }) 说明关闭原因，同时兼容原来的 close(false)。getState() 返回打开状态、目标、位置与当前项，refresh() 用于替换内容后重新绑定。

a3s:context-menu-before-open、a3s:context-menu-before-select 与 a3s:context-menu-before-close 是可取消钩子，宿主可在状态变化前授权或填充命令。完成事件包含 source、reason、目标、稳定命令值与布尔选中状态。没有可用命令时控制器不会打开菜单；根菜单与子菜单都会限制在缩放后的可视视口内，并在视口移动时安全关闭。

React 的 useContextMenu 与 Vue 的同名 composable 监听同一组事件，并通过 call() 调用清单中的控制器方法。

#状态与变体

上下文菜单只放与触发目标直接相关的短命令。全局导航使用 Command，持续可见操作使用 Toolbar，破坏性确认使用 Alert Dialog。依赖权限的命令在打开前钩子中生成；不可用分组及相邻分隔线应一起移除，不展示空菜单或大面积禁用项。

#无障碍

可聚焦触发面必须提供名称或说明。禁用项使用 aria-disabled="true" 并从方向键导航中跳过。Escape 关闭整个菜单并恢复焦点；逻辑方向键在 RTL 中自动交换。