Introduction

XSender is a component with built-in smart conversation features including input, tag selection, command popup, user mention, and other scenarios.

📌 Warning

The plugin version must be greater than 1.3.98. The previous version was named EditorSender, and there are significant API differences. Please take note.

Code Examples

Basic Usage

基本使用

这是一个XSender 输入框，最简单的使用例子。

<template>
  <XSender />
</template>

Placeholder

提示语

可以通过 placeholder 设置输入框的提示语。

<template>
  <XSender placeholder="💌 欢迎使用 Element-Plus-X ~" />
</template>

Auto Focus

提示语

可以通过 auto-focus 设置输入框自动聚焦。

<template>
  <XSender placeholder="自动聚焦" auto-focus />
</template>

Status

组件状态

可以通过简单属性是，实现组件的状态

💌 Info

• 通过 loading 属性，可以控制输入框是否加载中。
• 通过 disabled 属性，可以控制输入框是否禁用。
• 通过 clearable 属性，可以控制输入框是否出现删除按钮，实现清空。

<script setup lang="ts"></script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <XSender loading placeholder="加载中..." />
    <XSender disabled placeholder="禁用" />
    <XSender clearable placeholder="删除按钮" />
  </div>
</template>

Submit Type

enter提交 shiftEnter提交

提交方式

可以通过 submitType 设置输入框的提交方式。

<script setup lang="ts">
import type { XSender } from 'vue-element-plus-x';
import type { XSenderProps } from 'vue-element-plus-x/types/XSender';

const submitType = ref<XSenderProps['submitType']>('enter');
const senderLoading = ref(false);
const senderRef = ref<InstanceType<typeof XSender>>();

function handleSubmit() {
  if (senderLoading.value) return;

  ElMessage.info(`发送中`);
  senderLoading.value = true;

  setTimeout(() => {
    // 可以在控制台 查看打印结果
    console.log('submit-> value：', senderRef.value?.getModelValue());
    senderLoading.value = false;
    ElMessage.success(`发送成功`);
  }, 2000);
}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <el-radio-group v-model="submitType">
      <el-radio-button value="enter"> enter提交 </el-radio-button>
      <el-radio-button value="shiftEnter"> shiftEnter提交 </el-radio-button>
    </el-radio-group>

    <XSender
      ref="senderRef"
      :submit-type="submitType"
      :loading="senderLoading"
      @submit="handleSubmit"
    />
  </div>
</template>

Layout Variant

default updown

输入框布局变体

通过 variant 属性设置输入框的变体。默认 'default' | 上下结构 'updown'

这个属性，将左右结构的 输入框，变成 上下结构的 输入框。上面为 输入框，下面为 内置的 前缀和操作列表栏

<script setup lang="ts">
import type { XSenderProps } from 'vue-element-plus-x/types/XSender';
import { Paperclip, Promotion } from '@element-plus/icons-vue';
import { ref } from 'vue';

const variant = ref<XSenderProps['variant']>('default');
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 20px">
    <el-radio-group v-model="variant">
      <el-radio-button value="default"> default </el-radio-button>
      <el-radio-button value="updown"> updown </el-radio-button>
    </el-radio-group>

    <XSender :variant="variant" clearable />

    <XSender
      :variant="variant"
      placeholder="💌 在这里你可以自定义变体后的 prefix 和 action-list"
    >
      <template #prefix>
        <div
          style="display: flex; align-items: center; gap: 8px; flex-wrap: wrap"
        >
          <el-button round plain color="#626aef">
            <el-icon><Paperclip /></el-icon>
          </el-button>
        </div>
      </template>

      <template #action-list>
        <div style="display: flex; align-items: center; gap: 8px">
          <el-button round color="#626aef">
            <el-icon><Promotion /></el-icon>
          </el-button>
        </div>
      </template>
    </XSender>
  </div>
</template>

Custom Action List

操作列表插槽

通过 #action-list 插槽用于自定义输入框的操作列表内容。

💌 Info

当你使用 #action-list 插槽时，会隐藏内置的输入框的操作按钮。你可以通过和 组件实例方法 相结合，实现更丰富的操作。

<script setup lang="ts">
import type { XSender } from 'vue-element-plus-x';
import { Delete, Promotion } from '@element-plus/icons-vue';

const senderRef = ref<InstanceType<typeof XSender>>();

function handleDelete() {
  senderRef.value?.clear();
}

function handleSubmit() {
  console.log(senderRef.value?.getModelValue());
  handleDelete();
}
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px">
    <XSender ref="senderRef" variant="updown">
      <!-- 自定义 操作列表插槽 -->
      <template #action-list>
        <div style="display: flex; align-items: center">
          <el-button round plain color="#626aef" @click="handleDelete">
            <el-icon><Delete /></el-icon>
          </el-button>
          <el-button round plain color="#626aef" @click="handleSubmit">
            <el-icon><Promotion /></el-icon>
          </el-button>
        </div>
      </template>
    </XSender>
  </div>
</template>

Custom Prefix

前缀插槽

通过 #prefix 插槽用于自定义输入框的前缀内容。

<template>
  <XSender>
    <!-- 自定义 前缀插槽 -->
    <template #prefix>
      <div>
        <el-button>自定义</el-button>
        <el-button>前缀</el-button>
      </div>
    </template>
  </XSender>
</template>

Custom Header

💯 欢迎使用 Element Plus X

🦜 自定义头部内容

头部插槽

通过 #header 插槽用于自定义输入框的头部内容，还可以通过 headerAnimationTimer 属性设置头部动画时间。

<script setup lang="ts">
import { CircleClose } from '@element-plus/icons-vue';

const showHeaderFlog = ref(true);
</script>

<template>
  <XSender :header-animation-timer="300">
    <!-- 自定义 头部插槽 -->
    <template v-if="showHeaderFlog" #header>
      <div class="header-self-wrap">
        <div class="header-self-title">
          <div class="header-left">💯 欢迎使用 Element Plus X</div>
          <div class="header-right">
            <el-button @click.stop="showHeaderFlog = false">
              <el-icon><CircleClose /></el-icon>
              <span>关闭头部</span>
            </el-button>
          </div>
        </div>
        <div class="header-self-content">🦜 自定义头部内容</div>
      </div>
    </template>
    <!-- 自定义 前缀插槽 -->
    <template #prefix>
      <el-button @click="showHeaderFlog = !showHeaderFlog">
        打开/关闭头部
      </el-button>
    </template>
  </XSender>
</template>

<style scoped lang="less">
.header-self-wrap {
  display: flex;
  flex-direction: column;
  padding: 16px;
  height: 200px;
  .header-self-title {
    width: 100%;
    display: flex;
    height: 30px;
    align-items: center;
    justify-content: space-between;
    padding-bottom: 8px;
  }
  .header-self-content {
    flex: 1;
    display: flex;
    align-items: center;
    justify-content: center;
    font-size: 20px;
    color: #626aef;
    font-weight: 600;
  }
}
</style>

Custom Footer

自定义底部内容

底部插槽

通过 #footer 插槽设置输入框 底部内容

<template>
  <XSender>
    <!-- 自定义 底部插槽 -->
    <template #footer>
      <div
        style="
          display: flex;
          align-items: center;
          justify-content: center;
          padding: 12px;
        "
      >
        自定义底部内容
      </div>
    </template>
  </XSender>
</template>

Custom Input Style

自定义输入框样式

通过 customStyle 方便对输入框的样式透传，你可以设置 maxHeight 来限制输入框的高度。这样实现在一定的高度下出现滚动条。

<template>
  <XSender variant="updown" :custom-style="{ maxHeight: '200px' }" />
</template>

Max Length

当前输入长度： / 200

输入长度限制

可以通过 maxLength 来限制输入框的最大输入长度。

💔 Danger

该配置项性能开销较大 非必要情况请别设置（像豆包和文心一言都不对这块做限制不应因小失大）

<script setup lang="ts">
import type { XSender } from 'vue-element-plus-x';
import { ref } from 'vue';

const senderRef = ref<InstanceType<typeof XSender>>();

const maxLength = ref(200);
</script>

<template>
  <div style="margin-bottom: 20px">
    <span
      >当前输入长度：{{ senderRef?.senderState.textLength }} /
      {{ maxLength }}</span
    >
  </div>
  <XSender ref="senderRef" :max-length="maxLength" placeholder="输入长度限制" />
</template>

Advanced Usage

Input

Input

Use setInput to insert an input field for preset values. Use setChatNode to preset template content for the input.

<script setup lang="ts">
import type { XSender } from 'vue-element-plus-x';
import { ref } from 'vue';

const senderRef = ref<InstanceType<typeof XSender>>();

function onSetBasic() {
  senderRef.value?.setInput('job', '请输入职业');
}
function onSetValue() {
  senderRef.value?.setInput('job', '请输入职业', '前端工程师');
}
function onSetModel() {
  senderRef.value?.setChatNode([
    [
      {
        type: 'Write',
        text: '请帮我改写以下内容：'
      },
      {
        type: 'Input',
        key: 'target',
        placeholder: '这里输入要扩写的内容'
      }
    ],
    [
      {
        type: 'Write',
        text: '扩写要求是：'
      },
      {
        type: 'Input',
        key: 'target',
        placeholder: '这里输入要扩写的重点或要求，如扩写的主题、字数要求'
      }
    ]
  ]);
}
</script>

<template>
  <div>
    <div style="margin-bottom: 20px">
      <el-button type="primary" @click="onSetBasic"> 基础插入 </el-button>
      <el-button type="primary" @click="onSetValue"> 定义默认值插入 </el-button>
      <el-button type="primary" @click="onSetModel">
        预设模板内容插入
      </el-button>
    </div>
    <XSender ref="senderRef" variant="updown" />
  </div>
</template>

Tag Selection

Select Picker

Use setSelect to insert a select picker and preset a value. Use showSelect to open the picker dialog anchored to a target element. Use setChatNode to preset the input content template.

<script setup lang="ts">
import type { XSender } from 'vue-element-plus-x';
import { ref } from 'vue';

const senderRef = ref<InstanceType<typeof XSender>>();

const selectConfig = ref([
  {
    dialogTitle: 'Image Style',
    key: 'style',
    options: [
      {
        id: '1',
        name: 'Portrait',
        preview: '/logo.png'
      },
      {
        id: '2',
        name: 'Cinematic',
        preview: '/logo.png'
      },
      {
        id: '3',
        name: 'Chinese Style',
        preview: '/logo.png'
      }
    ],
    multiple: false
  }
]);

function onSetBasic() {
  senderRef.value?.setSelect('style', '1');
}

function openSelectDialog() {
  senderRef.value?.showSelect('style', document.getElementById('target')!);
}

function onSetModel() {
  senderRef.value?.setChatNode([
    [
      {
        type: 'Write',
        text: 'Please generate an image in '
      },
      {
        type: 'Select',
        key: 'style',
        id: '1',
        name: 'Chinese Style'
      },
      {
        type: 'Write',
        text: ' style.'
      }
    ]
  ]);
}
</script>

<template>
  <div>
    <div style="margin-bottom: 20px">
      <el-button type="primary" @click="onSetBasic"> Set via API </el-button>
      <el-button id="target" type="primary" @click="openSelectDialog">
        Open picker (anchored)
      </el-button>
      <el-button type="primary" @click="onSetModel">
        Set template content
      </el-button>
    </div>
    <XSender ref="senderRef" variant="updown" :select-config="selectConfig" />
  </div>
</template>

User Mention

提及用户

默认可以通过 @ 触发提及用户选择弹窗。 可以通过 setMention 插入一个提及用户标签。 使用 setChatNode 可以预设输入框内容（如文案、提及等）。

<script setup lang="ts">
import type { XSender } from 'vue-element-plus-x';
import { ref } from 'vue';

const senderRef = ref<InstanceType<typeof XSender>>();

const mentionConfig = ref({
  dialogTitle: '用户选择',
  callEvery: false,
  options: [
    {
      name: '用户1',
      id: 'user1'
    },
    {
      name: '用户2',
      id: 'user2'
    },
    {
      name: '用户3',
      id: 'user3'
    }
  ]
});

function onSetBasic() {
  senderRef.value?.setMention('user1');
}

function onSetModel() {
  senderRef.value?.setChatNode([
    [
      {
        type: 'Write',
        text: '这些工作任务将由'
      },
      {
        type: 'Mention',
        id: 'user1',
        name: '用户1'
      },
      {
        type: 'Write',
        text: '负责完成。'
      }
    ]
  ]);
}
</script>

<template>
  <div>
    <div style="margin-bottom: 20px">
      <el-button type="primary" @click="onSetBasic"> API插入 </el-button>
      <el-button type="primary" @click="onSetModel">
        预设输入内容插入
      </el-button>
    </div>
    <XSender
      ref="senderRef"
      variant="updown"
      :mention-config="mentionConfig"
      placeholder="敲击 @键 唤起提及用户选择"
    />
  </div>
</template>

Command Trigger

自定义指令

默认可以通过自定义设置触发符触发选择弹窗。 可以通过 setTrigger 插入一个指令标签。 使用 setChatNode 可以预设输入框内容（如文案、指令等）。

<script setup lang="ts">
import type { XSender } from 'vue-element-plus-x';
import { ref } from 'vue';

const senderRef = ref<InstanceType<typeof XSender>>();

const triggerConfig = ref([
  {
    dialogTitle: '技能选择',
    key: '/',
    options: [
      {
        name: '技能1',
        id: 'skill1'
      },
      {
        name: '技能2',
        id: 'skill2'
      },
      {
        name: '技能3',
        id: 'skill3'
      }
    ]
  }
]);

function onSetBasic() {
  senderRef.value?.setTrigger('/', 'skill1');
}

function onSetModel() {
  senderRef.value?.setChatNode([
    [
      {
        type: 'Write',
        text: '用户选择了'
      },
      {
        type: 'Trigger',
        key: '/',
        id: 'skill3',
        name: '技能3'
      },
      {
        type: 'Write',
        text: '模式。'
      }
    ]
  ]);
}
</script>

<template>
  <div>
    <div style="margin-bottom: 20px">
      <el-button type="primary" @click="onSetBasic"> API插入 </el-button>
      <el-button type="primary" @click="onSetModel">
        预设输入内容插入
      </el-button>
    </div>

    <XSender
      ref="senderRef"
      :trigger-config="triggerConfig"
      variant="updown"
      placeholder="敲击 / 唤起技能选择"
    />
  </div>
</template>

Prefix Tip

前置标签状态：

前置提示词

可以通过 showTip 唤起前置提示词。 使用 closeTip 可以关闭前置提示词。

<script setup lang="ts">
import type { XSender } from 'vue-element-plus-x';
import { reactive, ref } from 'vue';

const senderRef = ref<InstanceType<typeof XSender>>();

const tipConfig = reactive({
  offsetTop: 0
});

function onOpen() {
  senderRef.value?.showTip({
    text: '图像生成',
    dialogText: '点击退出技能'
  });
}

function onClose() {
  senderRef.value?.closeTip();
}
</script>

<template>
  <div style="margin-bottom: 20px">
    <el-button type="primary" @click="onOpen"> 打开前置标签 </el-button>
    <el-button type="primary" @click="onClose"> 关闭前置标签 </el-button>
  </div>
  <div style="margin-bottom: 20px">
    <span>前置标签状态：{{ senderRef?.senderState.tipShow }}</span>
  </div>
  <XSender ref="senderRef" :tip-config="tipConfig" />
</template>

Properties

Props

Property	Type	Required	Default	Description
placeholder	string	false	请输入内容	Placeholder text
device	PC | H5 | auto	false	auto	Interaction device
autoFocus	boolean	false	false	Auto focus after render
variant	default | updown	false	default	Layout variant
maxLength	number	false	-1	Input length limit
submitType	enter | shiftEnter	false	enter	Submit type
customStyle	CSSStyleDeclaration	false	{}	Custom input style
loading	boolean	false	false	Loading state
disabled	boolean	false	false	Disabled state
clearable	boolean	false	false	Show clear button
headerAnimationTimer	number	false	300	Header animation duration
mentionConfig	MentionConfig	false	null	User mention config
triggerConfig	TriggerConfig[]	false	null	Command popup config
selectConfig	SelectConfig[]	false	null	Tag selection config
tipConfig	TipConfig | boolean	false	true	Prefix tip config (true enables defaults, false disables, object enables with custom options)
getPlugin	() => typeof XSender	false	null	Custom underlying plugin version

tipConfig is passed through to the underlying x-sender plugin as-is. This component does not merge defaults on its own: booleans act as an on/off switch, and an object provides custom options.

MentionConfig

Property	Type	Required	Default	Description
dialogTitle	string	true	''	Mention popup title
options	<{ id: string, name: string, avatar?: string }>[]	true	[]	Data options
callEvery	boolean	false	false	Enable "mention all" option
everyText	string	false	所有人	"Mention all" option text
asyncMatch	(matchStr: string) => Promise<MentionItem[]>	false	null	Enable async matching mode
emptyText	string	false	暂无数据	Empty result text

TriggerConfig

Property	Type	Required	Default	Description
dialogTitle	string	true	''	Command popup title
key	string	true	null	Trigger key for command selection
options	<{ id: string, name: string }>[]	true	[]	Data options

SelectConfig

Property	Type	Required	Default	Description
dialogTitle	string	true	''	Tag selection popup title
key	string	true	null	Tag selection identifier
options	<{ id: string, name: string, preview?: string }>[]	true	[]	Data options
multiple	boolean	false	false	Enable multiple selection
emptyText	string	false	暂无数据	Empty result text
showSearch	boolean	false	false	Enable search function
placeholder	string	false	输入关键字查询	Search placeholder
searchEmptyText	string	false	暂无数据	Empty search result text

TipConfig

Property	Type	Required	Default	Description
tipTemplate	string	false	''	Prefix tip template
dialogTemplate	string	false	''	Command popup template
closeNames	string[]	false	[]	Key list to close popup
offsetTop	number	false	0	Popup top offset