FxMention 提及输入框

用于在输入中提及某人或某物（@ 提及）。不依赖任何 UI 框架，继承 FxInput 全部能力，内部组合 FxTooltip + FxScrollbar + 下拉面板，支持自定义前缀、textarea、远程搜索、整体删除、自定义模板与 header/footer。

基础用法

输入 @ 触发提及，按 ↑ / ↓ 选择，Enter 确认，Esc 关闭。

<template>
  <div class="demo-mention">
    <FxMention
      v-model="value"
      :options="options"
      placeholder="请输入"
      style="width: 320px"
      @select="handleSelect"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"

import type { MentionOption } from "@fx/components"

const value = ref("@")

const options = ref<MentionOption[]>([
  { label: "Fuphoenixes", value: "Fuphoenixes" },
  { label: "kooriookami", value: "kooriookami" },
  { label: "Jeremy", value: "Jeremy" },
  { label: "btea", value: "btea" },
])

const handleSelect = (option: MentionOption, prefix: string) => {
  console.log(option, prefix)
}
</script>

<style scoped>
.demo-mention {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;
}
</style>

自定义选项别名

通过 props 属性自定义 options 的字段别名（默认为 { value: 'value', label: 'label', disabled: 'disabled' }）。

<template>
  <div class="demo-mention">
    <FxMention
      v-model="value"
      :options="options"
      :props="aliasProps"
      placeholder="请输入"
      style="width: 320px"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"

const value = ref("@")
// 自定义字段别名：name 作为 label、id 作为 value、unable 作为 disabled
const aliasProps = { label: "name", value: "id", disabled: "unable" }
const options = ref([
  { name: "Fuphoenixes", id: "Fuphoenixes", unable: true },
  { name: "kooriookami", id: "kooriookami" },
  { name: "Jeremy", id: "Jeremy", unable: true },
  { name: "btea", id: "btea" },
])
</script>

<style scoped>
.demo-mention {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;
}
</style>

多行输入

设置 type="textarea" 切换为多行输入，光标定位同样有效。

<template>
  <div class="demo-mention">
    <FxMention
      v-model="value"
      type="textarea"
      :options="options"
      placeholder="请输入"
      style="width: 320px"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"

import type { MentionOption } from "@fx/components"

const value = ref("")
const options = ref<MentionOption[]>([
  { label: "Fuphoenixes", value: "Fuphoenixes" },
  { label: "kooriookami", value: "kooriookami" },
  { label: "Jeremy", value: "Jeremy" },
  { label: "btea", value: "btea" },
])
</script>

<style scoped>
.demo-mention {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;
}
</style>

自定义选项模板

通过 label 插槽自定义选项内容，作用域内可访问 item 与 index。

<template>
  <div class="demo-mention">
    <FxMention
      v-model="value"
      :options="options"
      placeholder="请输入"
      style="width: 320px"
    >
      <template #label="{ item }">
        <div class="demo-label">
          <FxAvatar :size="24" :src="item.avatar" />
          <span class="demo-label-text">{{ item.value }}</span>
        </div>
      </template>
    </FxMention>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"

const value = ref("")
const options = ref([
  {
    value: "Fuphoenixes",
    avatar: "https://avatars.githubusercontent.com/u/27912232",
  },
  {
    value: "kooriookami",
    avatar: "https://avatars.githubusercontent.com/u/38392315",
  },
  {
    value: "Jeremy",
    avatar: "https://avatars.githubusercontent.com/u/15975785",
  },
  {
    value: "btea",
    avatar: "https://avatars.githubusercontent.com/u/24516654",
  },
])
</script>

<style scoped>
.demo-mention {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;
}
.demo-label {
  display: flex;
  align-items: center;
}
.demo-label-text {
  margin-left: 6px;
}
</style>

远程搜索

监听 search 事件异步拉取选项，配合 loading 显示加载态。

<template>
  <div class="demo-mention">
    <FxMention
      v-model="value"
      :options="options"
      :loading="loading"
      placeholder="请输入"
      style="width: 320px"
      @search="handleSearch"
    />
  </div>
</template>

<script setup lang="ts">
import { onBeforeUnmount, ref } from "vue"

import type { MentionOption } from "@fx/components"

const value = ref("")
const loading = ref(false)
const options = ref<MentionOption[]>([])

let timer: ReturnType<typeof setTimeout> | undefined
const handleSearch = (pattern: string) => {
  if (timer) clearTimeout(timer)

  loading.value = true
  timer = setTimeout(() => {
    options.value = ["Fuphoenixes", "kooriookami", "Jeremy", "btea"].map(
      (item) => ({
        label: pattern + item,
        value: pattern + item,
      }),
    )
    loading.value = false
  }, 1500)
}

onBeforeUnmount(() => {
  if (timer) clearTimeout(timer)
})
</script>

<style scoped>
.demo-mention {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;
}
</style>

自定义前缀

通过 prefix 自定义触发前缀，默认 @；支持 string[] 配置多个前缀。

<template>
  <div class="demo-mention">
    <FxMention
      v-model="value"
      :options="options"
      :prefix="['@', '#']"
      placeholder="输入 @ 提及用户，# 提及标签"
      style="width: 320px"
      @search="handleSearch"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"

import type { MentionOption } from "@fx/components"

const MOCK_DATA: Record<string, string[]> = {
  "@": ["Fuphoenixes", "kooriookami", "Jeremy", "btea"],
  "#": ["1.0", "2.0", "3.0"],
}
const value = ref("")
const options = ref<MentionOption[]>([])

const handleSearch = (_pattern: string, prefix: string) => {
  options.value = (MOCK_DATA[prefix] || []).map((value) => ({ value }))
}
</script>

<style scoped>
.demo-mention {
  display: flex;
  flex-wrap: wrap;
  gap: 1rem;
}
</style>

整体删除

设置 whole 为 true，退格时会将提及内容整体删除；check-is-whole 可自定义判断逻辑（常用于远程选项场景）。

<template>
  <div class="demo-mention">
    <div class="demo-block">
      <div class="demo-title">本地选项整体删除</div>
      <FxMention
        v-model="value1"
        whole
        :options="options1"
        placeholder="请输入"
        style="width: 320px"
        @whole-remove="handleWholeRemove"
      />
    </div>
    <div class="demo-block">
      <div class="demo-title">远程选项 + check-is-whole</div>
      <FxMention
        v-model="value2"
        :options="options2"
        :prefix="['@', '#']"
        whole
        :check-is-whole="checkIsWhole"
        placeholder="输入 @ 提及用户，# 提及标签"
        style="width: 320px"
        @search="handleSearch"
        @whole-remove="handleWholeRemove"
      />
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"

import type { MentionOption } from "@fx/components"

const MOCK_DATA: Record<string, string[]> = {
  "@": ["Fuphoenixes", "kooriookami", "Jeremy", "btea"],
  "#": ["1.0", "2.0", "3.0"],
}
const value1 = ref("")
const value2 = ref("")
const options1 = ref<MentionOption[]>(
  MOCK_DATA["@"].map((value) => ({ value })),
)
const options2 = ref<MentionOption[]>([])

const handleSearch = (_pattern: string, prefix: string) => {
  options2.value = (MOCK_DATA[prefix] || []).map((value) => ({ value }))
}

// 远程选项场景下，options 不一定包含已选值，需自定义整体判断逻辑
const checkIsWhole = (pattern: string, prefix: string) => {
  return (MOCK_DATA[prefix] || []).includes(pattern)
}

const handleWholeRemove = (pattern: string, prefix: string) => {
  console.log("whole-remove:", pattern, prefix)
}
</script>

<style scoped>
.demo-mention {
  display: flex;
  flex-wrap: wrap;
  gap: 2rem;
}
.demo-block {
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
}
.demo-title {
  font-size: 0.875rem;
  color: var(--fx-text-color-secondary, #909399);
  min-height: 2.5em;
  display: flex;
  align-items: center;
}
@media screen and (max-width: 768px) {
  .demo-mention {
    gap: 1rem;
  }
  .demo-block {
    width: 100%;
  }
}
</style>

配合表单

与 FxForm 配合使用，支持校验。

<template>
  <FxForm
    ref="formRef"
    :model="form"
    :rules="rules"
    style="max-width: 600px"
  >
    <FxFormItem label="姓名" prop="name">
      <FxMention v-model="form.name" :options="options" />
    </FxFormItem>
    <FxFormItem label="描述" prop="desc">
      <FxMention
        v-model="form.desc"
        type="textarea"
        :options="options"
      />
    </FxFormItem>
    <FxFormItem>
      <FxBtn type="primary" @click="submit">提交</FxBtn>
      <FxBtn style="margin-left: 8px" @click="reset">重置</FxBtn>
    </FxFormItem>
  </FxForm>
</template>

<script setup lang="ts">
import { reactive, ref } from "vue"

import type { FxFormInstance, FormRules, MentionOption } from "@fx/components"

interface RuleForm {
  name: string
  desc: string
}
const formRef = ref<FxFormInstance>()
const form = reactive<RuleForm>({
  name: "",
  desc: "",
})

const options = ref<MentionOption[]>([
  { label: "Fuphoenixes", value: "Fuphoenixes" },
  { label: "kooriookami", value: "kooriookami" },
  { label: "Jeremy", value: "Jeremy" },
  { label: "btea", value: "btea" },
])

const rules = reactive<FormRules<RuleForm>>({
  name: [{ required: true, message: "请输入姓名", trigger: "blur" }],
  desc: [{ required: true, message: "请输入描述", trigger: "blur" }],
})

const submit = async () => {
  if (!formRef.value) return
  await formRef.value.validate((valid) => {
    if (valid) {
      console.log("submit!", form)
    }
  })
}

const reset = () => {
  formRef.value?.resetFields()
}
</script>

TIP

本组件基于 FxInput 开发，原输入框属性不变，此处不再重复，请前往原组件查看文档。

API

Attributes

属性	说明	类型	默认值
options	提及选项列表	MentionOption[]	[]
props	选项字段别名配置	MentionOptionProps	{ value: 'value', label: 'label', disabled: 'disabled' }
prefix	触发提及的前缀字符（长度须为 1）；支持多前缀	string / string[]	'@'
split	分隔提及的字符（长度须为 1）	string	' '
filter-option	自定义过滤逻辑；传 false 关闭过滤	false / ((pattern: string, option: MentionOption) => boolean)	内置大小写不敏感包含匹配
placement	弹层方位	'bottom' / 'top'	'bottom'
show-arrow	弹层是否显示箭头	boolean	false
offset	弹层偏移量	number	0
whole	退格删除时是否将提及内容整体删除	boolean	false
check-is-whole	退格删除时判断是否为整体提及	(pattern: string, prefix: string) => boolean	—
loading	弹层是否加载中	boolean	false
model-value (v-model)	输入值	string	—
popper-class	弹层自定义类名	string / array / object	—
popper-style	弹层自定义样式	string / CSSProperties	—
popper-options	floating-ui 参数	object	—
input 属性	—	—	—

Events

事件名	说明	类型
search	命中前缀时触发	(pattern: string, prefix: string) => void
select	选中某个选项时触发	(option: MentionOption, prefix: string) => void
whole-remove	整体提及被删除时触发（whole 为 true 或 check-is-whole 返回 true）	(pattern: string, prefix: string) => void
update:modelValue	绑定值更新	(value: string) => void
input	输入时	(value: string) => void
focus	聚焦	(event: FocusEvent) => void
blur	失焦	(event: FocusEvent) => void
input 事件	—	—

Slots

插槽名	说明	类型
label	自定义选项内容	{ item: MentionOption, index: number }
loading	自定义加载内容	—
header	下拉顶部内容	—
footer	下拉底部内容	—
input 插槽	—	—

Exposes

名称	说明	类型
input	FxInput 实例	Ref<FxInputInstance | null>
tooltip	FxTooltip 实例	Ref<FxTooltipInstance | null>
dropdownVisible	下拉显隐状态	ComputedRef<boolean>

类型声明

展开声明

type MentionOption = {
  value?: string
  label?: string
  disabled?: boolean
  [key: string]: any
}

type MentionOptionProps = {
  value?: string
  label?: string
  disabled?: string
  [key: string]: string | undefined
}