> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/zh/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/zh/llms-full.txt.

# ContextMenu

导航`@rockshin/tao-ui`

[代码演示](#代码演示)[API](#api)

通过右键或长按为对象提供上下文操作菜单。

## 何时使用

对象或区域需要提供次要操作时使用 ContextMenu。

**推荐**

- 菜单项使用简短、动作导向的文案。
- 关键操作必须提供其他可访问入口。

**避免**

- 不要把主要工作流只放进上下文菜单。

## 代码演示


### 基础用法
```tsx preview
import { ContextMenu } from '@rockshin/tao-ui';

function ContextMenuExample() {
  return (
    <ContextMenu
      menu={{
        items: [
          { key: 'cut', label: 'Cut', extra: '⌘X' },
          { key: 'copy', label: 'Copy', extra: '⌘C' },
          { key: 'paste', label: 'Paste', extra: '⌘V' },
          { type: 'divider' },
          { key: 'delete', label: 'Delete', danger: true },
        ],
      }}
    >
      <div
        style={{
          padding: 32,
          border: '1px dashed var(--tao-color-border)',
          borderRadius: 8,
        }}
      >
        Right-click this area
      </div>
    </ContextMenu>
  );
}

export default ContextMenuExample;
```

### 分组、禁用项与子菜单
```tsx preview
import { ContextMenu } from '@rockshin/tao-ui';

function ContextMenuGroups() {
  return (
    <ContextMenu
      menu={{
        items: [
          {
            type: 'group',
            label: 'View',
            children: [
              { key: 'zoom-in', label: 'Zoom in' },
              { key: 'zoom-out', label: 'Zoom out' },
            ],
          },
          { type: 'divider' },
          {
            key: 'share',
            label: 'Share',
            children: [
              { key: 'copy-link', label: 'Copy link' },
              { key: 'email', label: 'Email' },
            ],
          },
          { key: 'locked', label: 'Locked action', disabled: true },
        ],
      }}
    >
      <div
        style={{
          padding: 32,
          border: '1px dashed var(--tao-color-border)',
          borderRadius: 8,
        }}
      >
        Right-click for grouped actions
      </div>
    </ContextMenu>
  );
}

export default ContextMenuGroups;
```

### 可选择菜单项
```tsx preview
import { ContextMenu } from '@rockshin/tao-ui';
import { useState } from 'react';

function SelectableContextMenu() {
  const [selected, setSelected] = useState(['comfortable']);

  return (
    <ContextMenu
      menu={{
        selectable: true,
        selectedKeys: selected,
        onSelect: ({ selectedKeys }) => setSelected(selectedKeys),
        items: [
          { key: 'compact', label: 'Compact' },
          { key: 'comfortable', label: 'Comfortable' },
          { key: 'spacious', label: 'Spacious' },
        ],
      }}
    >
      <div
        style={{
          padding: 32,
          border: '1px dashed var(--tao-color-border)',
          borderRadius: 8,
        }}
      >
        Current density: {selected[0]}
      </div>
    </ContextMenu>
  );
}

export default SelectableContextMenu;
```

### 分组与子菜单
用分组和嵌套 `children` 组织操作，危险操作使用 `danger`。在区域内右键打开。
```tsx preview
import { ContextMenu } from '@rockshin/tao-ui';

function Area({ children = 'Right-click here' }: { children?: string }) {
  return (
    <div
      style={{
        display: 'grid',
        placeItems: 'center',
        width: 320,
        height: 160,
        border: '1px dashed var(--tao-color-border)',
        borderRadius: 8,
        color: 'var(--tao-color-text-tertiary)',
        fontSize: 13,
        userSelect: 'none',
      }}
    >
      {children}
    </div>
  );
}

export default function ContextMenuGroupsAndSubmenu() {
  return (
    <ContextMenu
      menu={{
        items: [
          {
            type: 'group',
            label: 'View',
            children: [
              { key: 'zoom-in', label: 'Zoom in' },
              { key: 'zoom-out', label: 'Zoom out' },
            ],
          },
          { type: 'divider' },
          {
            key: 'share',
            label: 'Share',
            children: [
              { key: 'mail', label: 'Email' },
              { key: 'link', label: 'Copy link' },
            ],
          },
          { key: 'rename', label: 'Rename' },
          { key: 'delete', label: 'Delete', danger: true },
        ],
      }}
    >
      <Area />
    </ContextMenu>
  );
}
```

### 菜单多选
通过 `selectedKeys` 和 `onSelect` 保留选中状态，可用于视图选项。
```tsx preview
import { ContextMenu } from '@rockshin/tao-ui';

import { useState } from 'react';

function Area({ children = 'Right-click here' }: { children?: string }) {
  return (
    <div
      style={{
        display: 'grid',
        placeItems: 'center',
        width: 320,
        height: 160,
        border: '1px dashed var(--tao-color-border)',
        borderRadius: 8,
        color: 'var(--tao-color-text-tertiary)',
        fontSize: 13,
        userSelect: 'none',
      }}
    >
      {children}
    </div>
  );
}

export default function ContextMenuSelectable() {
  const [checked, setChecked] = useState<string[]>(['grid']);
  return (
    <ContextMenu
      menu={{
        selectable: true,
        multiple: true,
        selectedKeys: checked,
        onSelect: ({ selectedKeys }) => setChecked(selectedKeys),
        items: [
          { key: 'grid', label: 'Show grid' },
          { key: 'ruler', label: 'Show ruler' },
          { key: 'guides', label: 'Show guides' },
        ],
      }}
    >
      <Area>{`Right-click — ${checked.length} shown`}</Area>
    </ContextMenu>
  );
}
```

### 禁用右键菜单
`disabled` 停用自定义菜单；不要把关键操作只放在右键菜单里。
```tsx preview
import { ContextMenu, type MenuItem } from '@rockshin/tao-ui';

function Area({ children = 'Right-click here' }: { children?: string }) {
  return (
    <div
      style={{
        display: 'grid',
        placeItems: 'center',
        width: 320,
        height: 160,
        border: '1px dashed var(--tao-color-border)',
        borderRadius: 8,
        color: 'var(--tao-color-text-tertiary)',
        fontSize: 13,
        userSelect: 'none',
      }}
    >
      {children}
    </div>
  );
}

export default function ContextMenuDisabled() {
  return (
    <ContextMenu
      menu={{
        items: [
          { key: 'undo', label: 'Undo', extra: '⌘Z' },
          { key: 'redo', label: 'Redo', disabled: true, extra: '⇧⌘Z' },
          { type: 'divider' },
          { key: 'select-all', label: 'Select all', extra: '⌘A' },
        ] as MenuItem[],
      }}
    >
      <Area />
    </ContextMenu>
  );
}
```

## API


### [#](#contextmenu)ContextMenu



| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| children | Element whose right-click (long-press on touch) opens the menu. | `ReactNode` **(必填)** | `-` |
| disabled | 是否禁用 | `boolean | undefined` | `-` |
| className | Merged onto the floating content. | `string | undefined` | `-` |
| style | 节点样式 | `CSSProperties | undefined` | `-` |

