[RFC]- Sender 词槽能力（Slotting）

[Chuck-Ray]

Summary

为 Sender 组件引入结构化词槽能力（Slotting），以支持更灵活的输入场景（如参数化、变量填充、结构化输入等），提升 AI 对话、表单等场景的可用性和扩展性。词槽能力允许用户在输入内容中插入可编辑/可选择的 slot，实现内容的结构化与参数化。

#552

---

Motivation

• 现有输入框仅支持纯文本，难以满足参数化、结构化输入等复杂场景。
• 词槽能力可提升 AI 场景下的 prompt 组装、参数填充、动态表单等体验。
• 便于后续扩展更多 slot 类型，支持更丰富的交互。
• 结构化输入有助于后端/模型更好地解析和利用用户输入。

---

Detailed Design

1. 词槽类型与数据结构

1.1 支持的 Slot 类型

• 文本节点（text）：普通文本内容
• 输入词槽（input）：可编辑的输入框
• 选择词槽（select）：可下拉选择的 slot
• 标签词槽（tag）：显示标签内容的 slot
• 自定义词槽（custom）：支持自定义渲染

1.2 SlotConfigType 结构定义

interface SlotConfigBaseType {
  type: 'text' | 'input' | 'select' | 'tag' | 'custom';
  formatResult?: (value: any) => string;
}

interface SlotConfigTextType extends SlotConfigBaseType {
  type: 'text';
  text?: string;
  key?: string;
}

interface SlotConfigInputType extends SlotConfigBaseType {
  type: 'input';
  key: string;
  props?: {
    defaultValue?: string;
    placeholder?: string;
  };
}

interface SlotConfigSelectType extends SlotConfigBaseType {
  type: 'select';
  key: string;
  props?: {
    defaultValue?: string;
    options: string[];
    placeholder?: string;
  };
}

interface SlotConfigTagType extends SlotConfigBaseType {
  type: 'tag';
  key: string;
  props?: {
    label: React.ReactNode;
    value?: string;
  };
}

interface SlotConfigCustomType extends SlotConfigBaseType {
  type: 'custom';
  key: string;
  props?: {
    defaultValue?: any;
    [key: string]: any;
  };
  customRender?: (
    value: any,
    onChange: (value: any) => void,
    item: SlotConfigType,
  ) => React.ReactNode;
}

export type SlotConfigType =
  | SlotConfigTextType
  | SlotConfigInputType
  | SlotConfigSelectType
  | SlotConfigTagType
  | SlotConfigCustomType;

1.3 词槽插入与解析流程

• 词槽配置：通过 slotConfig 属性传递词槽配置数组
• 渲染：SlotConfigType[] 渲染为 contenteditable DOM
• 解析：contenteditable DOM 解析回 SlotConfigType[]
• 取值：提供文本值和结构化配置两种格式

---

2. 组件 API 设计

2.1 Sender Props

属性名	类型	说明
slotConfig	SlotConfigType[]	词槽配置数组
onChange	(value: string, event?: React.FormEvent, slotConfig?: SlotConfigType[]) => void	内容变更回调
onSubmit	(message: string, slotConfig?: SlotConfigType[]) => void	提交回调
disabled	boolean	是否禁用
readOnly	boolean	是否只读
loading	boolean	是否加载中
placeholder	string	占位符

2.2 Sender Ref 方法

方法名	类型	说明
focus	(options?: { cursor?: 'start' | 'end' | 'all' }) => void	聚焦到输入框
blur	() => void	失去焦点
insert	(value: string) => void	插入文本内容
clear	() => void	清空内容
getValue	() => { value: string; config: SlotConfigType[]; }	获取当前值和配置

2.3 事件与回调

• onChange：内容变化时触发，返回文本值、事件对象和词槽配置
• onSubmit：提交时触发，返回文本值和词槽配置
• 词槽内部的 value 变化会触发 onChange 回调

---

3. 交互与行为说明

3.1 词槽渲染与编辑

• 通过 slotConfig 配置词槽结构
• input 类型显示为可编辑的输入框
• select 类型显示为下拉选择器
• tag 类型显示为标签样式
• custom 类型通过 customRender 自定义渲染

---

5. 示例与用法

5.1 基础用法

import { Sender } from '@ant-design/x';

const slotConfig = [
  { type: 'text', text: 'I want to go to ' },
  {
    type: 'select',
    key: 'destination',
    props: {
      options: ['Beijing', 'Shanghai', 'Guangzhou'],
      placeholder: 'Please select a destination',
    },
  },
  { type: 'text', text: ' for travel.' },
];

<Sender
  slotConfig={slotConfig}
  onSubmit={(value, config) => {
    console.log('Text value:', value);
    console.log('Slot config:', config);
  }}
/>

5.2 复杂示例

import { Sender } from '@ant-design/x';
import { Slider } from 'antd';

const complexSlotConfig = [
  { type: 'text', text: 'I want to go to ' },
  {
    type: 'select',
    key: 'destination',
    props: {
      options: ['Beijing', 'Shanghai', 'Guangzhou'],
      placeholder: 'Please select a destination',
    },
  },
  { type: 'text', text: ' with ' },
  { 
    type: 'tag', 
    key: 'tag', 
    props: { 
      label: '@ Chuck', 
      value: 'a friend' 
    } 
  },
  { type: 'text', text: ', the date is ' },
  {
    type: 'input',
    key: 'date',
    props: {
      placeholder: 'Please enter a date',
    },
  },
  { type: 'text', text: ', price range: ' },
  {
    type: 'custom',
    key: 'priceRange',
    props: {
      defaultValue: [20, 50],
    },
    customRender: (value, onChange) => (
      <div style={{ width: '100px' }}>
        <Slider 
          style={{ margin: 0 }} 
          range 
          value={value} 
          onChange={onChange} 
        />
      </div>
    ),
    formatResult: (value) => `between ${value[0]} and ${value[1]} RMB`,
  },
];

<Sender
  slotConfig={complexSlotConfig}
  onSubmit={(value, config) => {
    console.log('Formatted result:', value);
    console.log('Slot configuration:', config);
  }}
/>

6. 未来展望与扩展点

• 支持动态插入词槽（目前只能整体变更后修改光标位置）

---

实现细节

7.1 渲染机制

• 词槽内容使用 contenteditable div 作为容器
• slot 节点通过 React Portal 渲染到对应的 DOM 位置
• 每个 slot 设置 contenteditable="false" 防止直接编辑
• 通过 data-slot-key 属性标识不同的 slot

7.2 状态管理

• 使用 useGetState Hook 管理 slot 值的状态
• 通过 Map 结构缓存 slot DOM 节点和配置
• 状态变化时统一触发 onChange 回调

7.3 事件处理

• 组合输入事件处理，防止输入法冲突
• 键盘事件处理，支持 Enter/Shift+Enter 提交
• 粘贴事件处理，支持纯文本和文件粘贴
• 焦点管理，处理光标位置和选择范围

7.4 DOM 操作

• 使用原生 DOM API 进行精确的光标控制
• 通过 Selection API 管理文本选择和光标位置
• 动态创建和管理 slot 对应的 DOM 结构

7.5 数据转换

• 从 SlotConfigType[] 到 DOM 的渲染转换
• 从 DOM 到文本值和配置的解析转换
• 支持 formatResult 函数自定义输出格式

---

[onefeng123]

类似下面的技能选择也是一个比较常见的需求：

另外有个初步想法：
简化 SenderContentNode 的定义，充分利用 antd 已有组件和API。

interface SenderContentNode {
  type: 'text' | 'slot';
  content: ReactNode ;
}


const initialValue: SenderContentNode[] = [
  { type: 'text', text: '我想去' },
  {
    type: 'slot',
    content:  <Select 
    placeholder="请选择目的地" 
    options={['北京', '上海', '广州']} 
    onChange= 
  />,
  },
  
];

[Chuck-Ray]

有个问题就是一旦这个编辑器是 react 渲染的，每次值变化就会导致光标位置丢失，也不能很好控制光标删除词槽时的位移

---

技能选择感觉可以单独做个功能，不和词槽混在一起。

[onefeng123]

有个问题就是一旦这个编辑器是 react 渲染的，每次值变化就会导致光标位置丢失，也不能很好控制光标删除词槽时的位移

鱼和熊掌要是能兼得就好了 😀

[Chuck-Ray]

更改了实现方式，现在能支持把任意 react 组件放到词槽里了

[zombieJ]

不要通过 ref 来设置值 setValue / getValue / insertSlot ，始终使用受控实现

<XXX
  slots={[...]}
  onSlotChange={...}
/>

slots 类型可以细化

interface SlotType {
  type: 'static' | 'select' | 'input' | 'textarea' | 'date' | 'color';
  value: xxx; // 语法糖配对 onChange 出现
  onChange: xxx;
  props: xxx; // 不同组件额外的属性配置，可以覆盖 value 和 onChange
}

非 jsx 结构不需要提供 key 属性

[mushan0x0]

需要一个文件路径的选择，或者可以通过自定义来支持

[buzheng666]

这个功能目前有成型的版本吗？

[buzheng666]

简单版本如何实现的呀 光标的位置是个问题

[Sylas196]

话说，如何把一个带有词槽的模板文本存到DB去呢🤔

[luckymore]

自己做一层 schema 映射呗