arco-design Mentions 组件受控模式:在 Form 表单中集成 @ 提及功能的完整实践

原创2026-10-12 09:38:251,920 阅读
文章标签:UI组件前端设计系统

arco-design Mentions 组件受控模式:在 Form 表单中集成 @ 提及功能的完整实践

在 arco-design 中,Mentions(提及)组件常用于发布、聊天、评论等需要"在输入中提及某人或某事"的场景;当它放入 Form 表单后,组件即进入受控模式,值由表单 Store 统一管理,校验、联动与提交全部走表单的标准链路。本文以官方示例 control.md 为骨架,完整讲解该示例的每一项配置,并结合 Mentions 组件源码 与 Form 内部实现 剖析"表单值 → 组件受控 → 输入回写表单"的完整数据流。

一、官方示例:Mentions 在 Form 中的标准用法

下面代码继承自官方示例文档,展示了 Mentions 作为受控表单项使用的完整形态:

import { Form, Input, Button, Mentions } from '@arco-design/web-react';
const FormItem = Form.Item;

function App() {
  const onValuesChange = (changeValue, values) => {
    console.log('onValuesChange: ', changeValue, values);
  };

  return (
    <Form
      style={{ width: 360 }}
      initialValues={{ task: 'Component usage' }}
      onValuesChange={onValuesChange}
    >
      <FormItem label="Task" field="task" rules={[{ required: true, message: 'Task is required' }]}>
        <Input />
      </FormItem>
      <FormItem label="Name" field="name" rules={[{ required: true, message: 'Name is required' }]}>
        <Mentions
          placeholder="You can use @ Plato to mention Platon"
          options={['Jack', 'Steven', 'Platon', 'Mary']}
          alignTextarea={false}
          rows={2}
        />
      </FormItem>
      <FormItem wrapperCol={{ offset: 5 }}>
        <Button style={{ margin: '0 12px' }} type="primary">
          Submit
        </Button>
        <Button>Reset</Button>
      </FormItem>
    </Form>
  );
}

export default App;

这个示例覆盖了表单场景的三个核心关注点:初始值注入(initialValues)、值变更监听(onValuesChange)、必填校验(rules)。下面逐项拆解。

1.1 Form 层:initialValues 与 onValuesChange

  • initialValues={{ task: 'Component usage' }}:仅给 task 字段设置初始值,name 字段留空。初始值在表单 Store 中通过 store.tsx 的 innerSetInitialValues 写入,使用 cloneDeep 做了深拷贝,避免引用被意外修改。
  • onValuesChange(changeValue, values):任意表单项值改变时触发。第一个参数是本次变更的字段键值对,第二个参数是全部字段值。从源码 store.tsx 的 triggerValuesChange 可以看到,只要变更对象非空就会依次触发 onValuesChange(value, this.getFields()) 并通知 watchers,因此 Mentions 中每一次输入、每一次点选候选人,都会走到这个回调。

注意 onValuesChange 与表单的 onChange 区别:后者仅在用户操作表单项时触发,前者对内部设置值(setFieldsValue 等)也生效,这一点在 Form 接口定义 中有明确注释。

1.2 FormItem 层:field 绑定与 required 校验

两个 FormItem 分别通过 field="task" 和 field="name" 把子组件绑定到表单数据的对应路径上。rules={[{ required: true, message: 'Task is required' }]} 声明必填校验:

  • Mentions 不传 value 时 name 字段为 undefined,失焦或表单提交时会触发 required 校验并展示 "Name is required";
  • 校验时机由 validateTrigger 控制,默认为 onChange,可在 FormItem 或 Form 上覆盖。

1.3 Mentions 层:示例中用到的关键 props

参数 示例取值 说明
placeholder "You can use @ Plato to mention Platon" 输入框提示文字
options ['Jack', 'Steven', 'Platon', 'Mary'] 下拉可选项,支持 string/number 或 { label, value, disabled } 对象形式
alignTextarea false 弹出框是否与输入框宽度对齐,默认 true;设为 false 时弹层宽度按内容自适应
rows 2 文本域行数,来自 TextArea 能力

完整 API 参见 Mentions 组件 API 文档,其中 prefix(触发关键字,默认 @)、split(选中项前后分隔符)、onSearch、filterOption、position 等参数也都可以直接在 Form 场景下使用。

二、数据流剖析:Form 如何把 Mentions 变成受控组件

示例中 Mentions 既没有写 value 也没有写 onChange,却能被表单完全接管,这套机制的实现在 Form/control.tsx 的 Control 类组件中。

2.1 属性注入:renderControl

FormItem 渲染时会用 Control 包裹子组件,其 renderControl 方法(control.tsx#L394-L435)对子节点做了三件事:

  1. 注入受控值:childProps[triggerPropName] = _value,默认 triggerPropName 为 value,值从表单 Store 中按 field 路径取出;
  2. 注入 onChange:childProps[trigger] = this.handleTrigger,默认 trigger 为 onChange;
  3. 注入校验状态:当该字段存在校验错误且未显式指定 validateStatus 时,注入 error: true,使 Mentions 的 TextArea 呈现错误边框。

也就是说,Mentions 实际收到的 props 是 value={store 中 name 字段的值} 和 onChange={表单的 handleTrigger},受控行为由此成立。

2.2 值回写:从输入到 onValuesChange

用户在 Mentions 中每敲一个字符,链路如下:

  1. TextArea 的 onChange 回调先执行组件内部的 setValue(value),再调用 onChange(value)(index.tsx#L92-L96);
  2. 该 onChange 实为表单的 handleTrigger(control.tsx#L360-L392),它标记字段为 touched、调用 innerSetFieldValue(field, normalizeValue) 写入 Store,并同步执行 validateField(trigger) 触发校验;
  3. Store 的 triggerValuesChange 最终触发 Form 上的 onValuesChange(changeValue, values)。

点击下拉选项时走另一条路径:handleOptionSelect(index.tsx#L76-L90)会把测量到的 @xxx 片段替换为"触发符 + 选中值",并在前后按需补充分隔符(split,默认空格)后调用 onChange(nextValue),后续链路同上。分隔符补全逻辑为:若选中内容前后已存在 split 或换行则不再重复添加,保证 @Platon 这样的文本不会变成 @Platon 。

2.3 受控/非受控的统一:useMergeValue

Mentions 内部通过 useMergeValue 钩子合并 value 与 defaultValue:

const [value, setValue] = useMergeValue('', {
  value: props.value,
  defaultValue: props.defaultValue,
});
  • 表单场景下 props.value 由 Control 注入(首次未输入时可能为 undefined),钩子返回内部 state 兜底,组件表现为"半受控"——外部有 value 时严格受控,无 value 时退化为内部自管理;
  • 独立使用场景(如 basic.md 中的 defaultValue="@Bytedance")则完全依赖 defaultValue 初始化。

这套合并逻辑使同一个组件既能独立非受控使用,也能无缝嵌入 Form 受控体系,是该示例"零 value/onChange 代码"的关键。

三、Mentions 的弹层测量原理(alignTextarea 的底层机制)

示例中 alignTextarea={false} 直接影响弹层宽度行为,理解它需要先理解 Mentions 独特的"隐形测量层"结构。组件渲染的 DOM 结构见 index.tsx#L153-L194:

div.arco-mentions
├── TextArea.arco-mentions-textarea        // 用户真正输入的文本域
└── div.arco-mentions-measure              // 隐形测量层(visibility: hidden)
    ├── value.slice(0, location)           // 光标前已确认的文本
    ├── Select(隐藏触发器)
    │   └── span.arco-mentions-measure-trigger  // 只渲染触发符 "@"
    └── value.slice(location + prefix.length) // "@" 之后的文本

CSS 上(style/index.less)-measure 层与 textarea 使用完全相同的内边距、字号与行高并绝对定位叠放,useEffect 中同步二者 scrollTop(index.tsx#L61-L65)。这样隐藏 Select 的触发元素在测量层中的视口位置,就精确等于 textarea 中 @ 字符的位置,下拉弹层因此能从光标处精准弹出。

alignTextarea 参数最终传给 Select 的 triggerProps.autoAlignPopupWidth(index.tsx#L180-L185):

  • true(默认):弹层宽度与输入框对齐,视觉整体感强;
  • false(本示例取值):弹层宽度按候选项内容自适应,适合选项文案长度差异大的场景。

此外 triggerProps 可透传全部 Trigger 组件属性(如 popupVisible、position),position 默认 bl(左下弹出),支持 top/tl/tr/bottom/bl/br 六个方位。

四、触发与搜索:prefix、split、onSearch 的工作细节

4.1 触发检测发生在 keyup

弹层是否出现由 onKeyUp 驱动(index.tsx#L112-L147):

  1. Esc/Enter/↑/↓ 四个功能键直接跳过 keyup 处理(FunctionalKeyCodeList);
  2. getBeforeSelectionText 取光标前文本,getLastMeasureIndex 在 utils.ts 中查找最近一次出现的触发符位置(支持 string | string<a href="https://link.gitcode.com/i/3c7dbbecee26f947ab9559ce96cef118" target="_blank">] 多前缀,2.66.0 版本修复了多字符前缀的匹配问题,见 [changelog);
  3. isValidSearch 校验 @ 之后文本不含 split 分隔符——即 @ 后一旦敲了空格,说明提及已结束,弹层关闭;
  4. 满足条件时置 measuring: true 并回调 onSearch(measureText, measurePrefix),可借此实现远程搜索(如按输入异步拉取用户列表)。

4.2 键盘交互

onKeyDown(index.tsx#L97-L111)中:

  • Esc:refTextarea.current.blur() 失焦,同时 onBlur: stopMeasure 关闭弹层;
  • 弹层打开时 ↑/↓/Enter 交给 Select 的 hotkeyHandler 处理并 preventDefault(),阻止换行/光标移动,实现方向键切换候选、回车确认选择。

这一行为有测试用例直接验证:index.test.tsx#L80-L92 模拟 @ 触发后按下 ArrowDown + Enter,断言 textarea 内容为 @shanghai;index.test.tsx#L52-L65 则验证点击选项后 onChange 收到 @beijing。这些测试同样适用于受控场景,因为值回写只是在其后追加了表单链路。

五、在 Form 场景下的实战建议

结合示例与源码,给出几条可直接落地的实践:

  1. 远程搜索候选人:在 FormItem 中为 Mentions 增加 onSearch={(text) => fetchUsers(text)},把请求结果赋给 options;filterOption 传 false 禁用本地过滤,完全交由服务端结果决定。
  2. 多字符/多前缀触发:prefix 支持数组,例如 prefix={<a href="https://link.gitcode.com/i/01f18de2eb27d63cc43f27394717e99b" target="_blank">'@', '#']} 同时启用"提及"与"话题"两种场景,匹配时组件会取离光标最近的前缀([utils.ts#L16-L30)。
  3. 校验联动:rules 中除 required 外还可写自定义 validator,例如校验"必须提及至少一个成员";validateTrigger 默认 onChange,若希望提交时再校验可改为 onBlur。
  4. 弹层定位微调:在滚动容器或 iframe 中弹层溢出时,通过 getPopupContainer 指定挂载节点,或用 triggerProps 透传 Trigger 属性覆盖默认 bl 弹出位置。

六、小结与延伸阅读

Mentions 在 Form 中的受控模式并不需要你手写 value/onChange 绑定:Control 完成属性注入,useMergeValue 完成受控降级,Store 完成值的集中管理与 onValuesChange 广播,三者拼成了"输入即回写、校验即反馈"的完整闭环。围绕该主题可进一步阅读:

登录后查看全文
arco-design