arco-design Mentions 组件受控模式:在 Form 表单中集成 @ 提及功能的完整实践
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)对子节点做了三件事:
- 注入受控值:
childProps[triggerPropName] = _value,默认triggerPropName为value,值从表单 Store 中按field路径取出; - 注入 onChange:
childProps[trigger] = this.handleTrigger,默认trigger为onChange; - 注入校验状态:当该字段存在校验错误且未显式指定
validateStatus时,注入error: true,使Mentions的TextArea呈现错误边框。
也就是说,Mentions 实际收到的 props 是 value={store 中 name 字段的值} 和 onChange={表单的 handleTrigger},受控行为由此成立。
2.2 值回写:从输入到 onValuesChange
用户在 Mentions 中每敲一个字符,链路如下:
TextArea的onChange回调先执行组件内部的setValue(value),再调用onChange(value)(index.tsx#L92-L96);- 该
onChange实为表单的handleTrigger(control.tsx#L360-L392),它标记字段为 touched、调用innerSetFieldValue(field, normalizeValue)写入 Store,并同步执行validateField(trigger)触发校验; - 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):
Esc/Enter/↑/↓四个功能键直接跳过 keyup 处理(FunctionalKeyCodeList);getBeforeSelectionText取光标前文本,getLastMeasureIndex在 utils.ts 中查找最近一次出现的触发符位置(支持string | string<a href="https://link.gitcode.com/i/3c7dbbecee26f947ab9559ce96cef118" target="_blank">]多前缀,2.66.0 版本修复了多字符前缀的匹配问题,见 [changelog);isValidSearch校验@之后文本不含split分隔符——即@后一旦敲了空格,说明提及已结束,弹层关闭;- 满足条件时置
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 场景下的实战建议
结合示例与源码,给出几条可直接落地的实践:
- 远程搜索候选人:在
FormItem中为Mentions增加onSearch={(text) => fetchUsers(text)},把请求结果赋给options;filterOption传false禁用本地过滤,完全交由服务端结果决定。 - 多字符/多前缀触发:
prefix支持数组,例如prefix={<a href="https://link.gitcode.com/i/01f18de2eb27d63cc43f27394717e99b" target="_blank">'@', '#']}同时启用"提及"与"话题"两种场景,匹配时组件会取离光标最近的前缀([utils.ts#L16-L30)。 - 校验联动:
rules中除required外还可写自定义validator,例如校验"必须提及至少一个成员";validateTrigger默认onChange,若希望提交时再校验可改为onBlur。 - 弹层定位微调:在滚动容器或
iframe中弹层溢出时,通过getPopupContainer指定挂载节点,或用triggerProps透传Trigger属性覆盖默认bl弹出位置。
六、小结与延伸阅读
Mentions 在 Form 中的受控模式并不需要你手写 value/onChange 绑定:Control 完成属性注入,useMergeValue 完成受控降级,Store 完成值的集中管理与 onValuesChange 广播,三者拼成了"输入即回写、校验即反馈"的完整闭环。围绕该主题可进一步阅读:
- 示例源码:control.md(受控)、basic.md(基础用法)、prefix.md(自定义触发字符)、status.md(状态展示)
- 组件实现:index.tsx、interface.ts、utils.ts
- 表单机制:control.tsx、store.tsx
- 自动化测试:index.test.tsx、demo 渲染快照测试 demo.test.ts