> Leaf UI 0.8.1 · Package: @ifhover/leaf-ui · Source: 435bab23cad7d343653d9b63b049c0b0601eeefb
> Browser documentation: https://ifhover.github.io/leaf-ui/components/mentions.html

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

# Mentions 提及

在文本中插入成员或内容引用。

## 基础用法


basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/mentions/basic.tsx"
import { Mentions } from '@ifhover/leaf-ui';

export function MentionsBasic() {
  return (
    <Mentions
      aria-label={'评论'}
      placeholder={'输入 @ 提及团队成员'}
      options={[
        { value: 'ada', label: 'Ada' },
        { value: 'lin', label: 'Lin' },
        { value: 'morgan', label: 'Morgan', disabled: true },
      ]}
    />
  );
}
```

展开代码

## 不同的前缀


basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/mentions/basic.tsx"
import { Mentions } from '@ifhover/leaf-ui';

export function MentionsPrefixes() {
  return (
    <Mentions
      prefixes={['@', '#']}
      aria-label={'项目备注'}
      placeholder={'使用 @ 或 # 插入引用'}
      options={[
        { value: 'design', label: '设计' },
        { value: 'engineering', label: '工程' },
      ]}
    />
  );
}
```

展开代码

## 浮层宽度

浮层默认与控件等宽（`popupWidth="trigger"`）。设置 `popupWidth="auto"` 仅按内容定宽，也可以比控件窄；`popupWidth={300}` 固定为 300px，也支持 CSS 长度。`popupMaxWidth` 默认未设置，下面的示例按内容定宽并显式设置最大宽度。浮层仍会在视口边缘避让。


popup.tsx

复制代码

```tsx lineNumbers file="../../src/examples/mentions/popup.tsx"
import { Mentions } from '@ifhover/leaf-ui';

export function MentionsPopup() {
  return (
    <Mentions
      aria-label={'按内容定宽的提及建议'}
      placeholder={'输入 @ 查看建议'}
      popupWidth="auto"
      popupMaxWidth={280}
      options={[
        { value: 'design', label: '设计团队' },
        { value: 'engineering', label: '研发团队' },
      ]}
    />
  );
}
```

展开代码

## MentionOption

| 属性            | 类型          | 默认值 | 说明         |
| ------------- | ----------- | --- | ---------- |
| `value`       | `string`    | —   | 必需。受控值。    |
| `label`       | `ReactNode` | —   | 展示文字或内容。   |
| `searchLabel` | `string`    | —   | 搜索时使用的纯文本。 |
| `disabled`    | `boolean`   | —   | 禁用交互。      |

## Mentions API

| 属性                  | 类型                                                                                                                                                                   | 默认值         | 说明                                                       |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------- |
| `size`              | `'sm' \| 'md' \| 'lg'`                                                                                                                                               | —           | 展示尺寸。                                                    |
| `status`            | `'error' \| 'warning'`                                                                                                                                               | —           | 设置 status。                                               |
| `resize`            | `'none' \| 'vertical' \| 'both'`                                                                                                                                     | —           | 设置 resize。                                               |
| `autoSize`          | `boolean \| `[`TextareaAutoSize`](https://ifhover.github.io/leaf-ui/components/textarea.md#textareaautosize-api)                                                     | —           | 设置 autoSize。                                             |
| `showCount`         | `boolean \| ((value: string, maxLength?: number) => ReactNode)`                                                                                                      | —           | 设置 showCount。                                            |
| `popupPlacement`    | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | —           | 浮层相对触发控件的位置。                                             |
| `popupWidth`        | `number \| string`                                                                                                                                                   | `'trigger'` | 浮层宽度；trigger 与控件等宽，auto 按内容定宽（可比控件窄），数字为固定像素值，也支持 CSS 长度 |
| `popupMaxWidth`     | `number \| string`                                                                                                                                                   | —           | 可选的最大宽度；默认不限制，仍受视口限制                                     |
| `popupClassName`    | `string`                                                                                                                                                             | —           | 浮层的自定义类名。                                                |
| `popupStyle`        | `CSSProperties`                                                                                                                                                      | —           | 浮层的自定义样式。                                                |
| `popupRender`       | `(content: React.ReactNode) => React.ReactNode`                                                                                                                      | —           | 包装或补充面板内容，保留传入的内容以维持交互。                                  |
| `getPopupContainer` | `() => Element \| DocumentFragment`                                                                                                                                  | —           | 返回浮层的挂载容器，也可返回 ShadowRoot。                               |
| `value`             | `string`                                                                                                                                                             | —           | 受控值。                                                     |
| `defaultValue`      | `string`                                                                                                                                                             | `''`        | 初始值；非受控模式支持表单重置。                                         |
| `onChange`          | `(value: string) => void`                                                                                                                                            | —           | 值发生变化时调用。                                                |
| `onSearch`          | `(query: string, prefix: string) => void`                                                                                                                            | —           | 搜索文字改变时调用。                                               |
| `onSelect`          | `(option: `[`MentionOption`](#mentionoption)`, prefix: string) => void`                                                                                              | —           | 条目被选择时调用。                                                |
| `options`           | `readonly `[`MentionOption`](#mentionoption)`[]`                                                                                                                     | —           | 必需。可供选择的选项。                                              |
| `prefixes`          | `readonly string[]`                                                                                                                                                  | —           | 可触发建议的文本前缀。                                              |
| `split`             | `string`                                                                                                                                                             | `' '`       | 插入引用后追加的分隔文字。                                            |
| `loading`           | `boolean`                                                                                                                                                            | —           | 展示加载状态。                                                  |
| `notFoundContent`   | `ReactNode`                                                                                                                                                          | —           | 没有匹配选项时的内容。                                              |

## 类型与交互

组装可复用配置时，可导入对应的属性和数据类型。

```ts
import type { MentionOption, MentionsProps } from '@ifhover/leaf-ui';
```

为仅展示图标的操作提供可访问名称。交互控件支持键盘操作，并跟随 ConfigProvider 的主题和减少动画设置。