在鸿蒙（HarmonyOS）桌面应用开发中，右键菜单（Context Menu）是区分桌面级交互与移动端交互的核心分水岭。手机端通常依赖“长按”手势（存在 >500ms 延迟），而 PC 端则依赖“右键点击”（零延迟、即时响应），这代表了两种截然不同的设计哲学。
开发者可以通过 bindContextMenu、bindMenu 以及声明式 Menu 组件，构建高度自定义的桌面级上下文菜单。以下是核心开发策略与实战代码：
一、 基础右键菜单绑定（bindContextMenu）
最直接的右键菜单实现方式是通过 bindContextMenu 绑定一个 @Builder 构建器。通过指定 ResponseType.RightClick，可以确保该菜单仅在鼠标右键点击时触发。
核心代码示例：
Row() {
Text('右键点击此区域')
}
.bindContextMenu(this.contextMenuBuilder, ResponseType.RightClick)
@Builder contextMenuBuilder() {
Menu() {
MenuItem({ content: '打开' })
.onClick(() => { /* 打开文件逻辑 */ })
MenuItem({ content: '复制路径' })
.onClick(() => { /* 复制路径逻辑 */ })
MenuItem({ content: '删除' })
.onClick(() => { /* 删除逻辑 */ })
}
}
二、 数据驱动模式（bindMenu 数组）
对于选项固定、样式不敏感的简单场景，可以使用 bindMenu 配合 MenuElement 数组。这种模式代码量少，但无法自定义每一项的复杂外观。
核心代码示例：
Column() {
Text('右键打开数据菜单')
.bindMenu(this.isMenuOpen, [
{
value: '复制',
action: () => { this.selectedAction = '复制'; }
},
{
value: '粘贴',
enabled: false, // 禁用状态
action: () => { this.selectedAction = '粘贴'; }
},
{
value: '删除',
action: () => { this.selectedAction = '删除'; }
}
], {
placement: Placement.BottomLeft, // 菜单弹出位置
onDisappear: () => { this.isMenuOpen = false; } // 【关键】菜单关闭时重置状态
})
}
三、 声明式模式（完全自定义 UI）
当默认的菜单样式无法满足需求时，可以使用声明式模式。通过 @Builder 返回自定义的 Menu、MenuItemGroup 和 MenuItem，实现分组、图标、快捷键提示等复杂的桌面级菜单。
核心代码示例：
@Builder MyCustomMenu() {
Menu() {
MenuItemGroup({ header: '编辑操作' }) {
MenuItem({
content: '复制',
startIcon: $r('app.media.ic_copy'),
labelInfo: 'Ctrl+C' // 显示快捷键提示
})
MenuItem({ content: '剪切' })
}
MenuItemGroup({ header: '危险操作' }) {
MenuItem({ content: '删除' })
.contentFontColor(Color.Red)
}
}
.width(200)
.radius(8)
}
// 绑定声明式菜单
Text('右键打开自定义菜单')
.bindMenu(this.isMenuOpen, this.MyCustomMenu, {
onDisappear: () => { this.isMenuOpen = false; }
})
四、 实战进阶：带“优雅降级”的右键菜单
在 PC 端开发文件管理器时，右键菜单中的“打开文件位置”功能可能会因为系统未安装对应应用而失败。优秀的桌面级应用需要提供回退方案（Fallback），而不是直接抛出错误。
核心代码示例：
@Builder fileContextMenu(item: FileItem) {
Menu() {
MenuItem({ content: '打开文件位置' })
.onClick(async () => {
try {
const context = getContext(this) as common.UIAbilityContext;
const want: Want = {
bundleName: 'com.huawei.hmos.filemanager',
abilityName: 'com.huawei.hmos.filemanager.MainAbility',
uri: item.parentPath
};
await context.startAbility(want);
} catch (error) {
// 【优雅降级】：如果无法打开文件管理器，自动将路径复制到剪贴板
const pd = pasteboard.createData(pasteboard.SystemPasteboard.INSTANCE, item.parentPath);
await pasteboard.SystemPasteboard.INSTANCE.setData(pd);
promptAction.showToast({ message: '文件管理器不可用，已复制路径' });
}
})
}
}
五、 进阶：动态上下文菜单（根据数据状态渲染）
在真实业务中，右键菜单的选项往往取决于当前点击的元素类型（例如：文件夹与文件的菜单不同，或者处于“多选”状态时出现“批量操作”）。通过 @Builder 传参，可以实现高度动态的菜单。
核心代码示例：
// 列表项组件
ForEach(this.fileList, (item: FileInfo) => {
Row() {
Text(item.name)
}
.bindContextMenu(() => {
// 根据文件类型动态返回不同的菜单
return this.buildDynamicMenu(item);
}, ResponseType.RightClick)
})
@Builder buildDynamicMenu(item: FileInfo) {
Menu() {
MenuItem({ content: '打开' })
.onClick(() => { /* 打开逻辑 */ })
// 仅当不是系统保留文件夹时，才显示重命名和删除
if (!item.isSystemDir) {
MenuItem({ content: '重命名' })
.onClick(() => { /* 重命名逻辑 */ })
MenuItem({ content: '删除' })
.fontColor(Color.Red)
.onClick(() => { /* 删除逻辑 */ })
}
}
}
六、 高阶弹窗替代方案（OverlayManager 全局悬浮菜单）
如果右键菜单需要脱离当前组件的层级限制（例如在复杂的嵌套滚动列表、Canvas 画布或 3D 场景中触发），可以使用 UIContext.getOverlayManager() 来实现全局悬浮菜单。它独立于页面布局，可以覆盖在所有组件之上。
核心代码示例：
// 在鼠标右键点击的回调中触发
.onMouse((event?: MouseEvent) => {
if (event && event.button === MouseButton.Right && event.action === MouseAction.Press) {
const overlayManager = UIContext.getCurrentUIContext().getOverlayManager();
// 在鼠标点击的绝对坐标处弹出悬浮菜单
overlayManager.openCustomDialog({
builder: this.MyCustomMenu(),
alignment: DialogAlignment.BottomLeft,
offset: { dx: event.x, dy: event.y }, // 精确定位到鼠标指针处
autoCancel: true, // 点击外部自动关闭
onWillDismiss: () => { /* 关闭前的清理逻辑 */ }
});
}
})
