feat(sender): add speech custom icon support (#374)

kieranwv · wzc520pyfm · web-flow · commit 7ded91547c3d · 2025-06-28T22:40:49.000+08:00
* feat(sender): add speech custom icon support and docs demo

* docs enhance SenderProps with audio icon customization options

* chore: remove console

* feat(sender): use the allowSpeech field to customize the icon

* fix: fix SenderProps types

* fix(sender): fix allow-speech type

---------

Co-authored-by: wzc520pyfm &lt;1528857653@qq.com&gt;
diff --git a/docs/component/sender.md b/docs/component/sender.md
@@ -1,4 +1,3 @@
-
 # Sender 输入框
 
 用于聊天的输入框组件。
@@ -45,6 +44,18 @@ sender/speech
 
 </ClientOnly>
 
+### 语音输入图标
+
+<ClientOnly>
+
+:::demo 调整语音输入显示的图标，包含正在录音的图标。
+
+sender/speechIcon
+
+:::
+
+</ClientOnly>
+
 ### 自定义语音输入
 
 <ClientOnly>
@@ -143,35 +154,38 @@ sender/focus
 
 ### SenderProps
 
-| 属性 | 说明 | 类型 | 默认值 | 版本 |
-| --- | --- | --- | --- | --- |
-| actions | 自定义按钮，当不需要默认操作按钮时，可以设为 `actions={false}` | VNode \| (oriNode, info: \{ components: ActionsComponents \}) => VNode | - | - |
-| allowSpeech | 是否允许语音输入 | boolean \| SpeechConfig | false | - |
-| classNames | 样式类名 | [见下](#semantic-dom) | - | - |
-| components | 自定义组件 | Record<'input', ComponentType> | - | - |
-| defaultValue | 输入框默认值 | string | - | - |
-| disabled | 是否禁用 | boolean | false | - |
-| loading | 是否加载中 | boolean | false | - |
-| header | 头部面板 | VNode \| () => VNode | - | - |
-| prefix | 前缀内容 | VNode \| () => VNode | - | - |
-| footer | 底部内容 | ReactNode \| (info: \{ components: ActionsComponents \}) => ReactNode | - | - |
-| readOnly | 是否让输入框只读 | boolean | false | - |
-| rootClassName | 根元素样式类 | string | - | - |
-| styles | 语义化定义样式 | [见下](#semantic-dom) | - | - |
-| submitType | 提交模式 | SubmitType | `enter` \| `shiftEnter` | - |
-| value(v-model) | 输入框值 | string | - | - |
-| onSubmit | 点击发送按钮的回调 | (message: string) => void | - | - |
-| onChange | 输入框值改变的回调 | (value: string, event?: FormEvent \| ChangeEvent ) => void | - | - |
-| onCancel | 点击取消按钮的回调 | () => void | - | - |
-| onPasteFile | 黏贴文件的回调 | (firstFile: File, files: FileList) => void | - | - |
-| autoSize | 自适应内容高度，可设置为 true \| false 或对象：\{ minRows: 2, maxRows: 6 \} | boolean \| \{ minRows?: number; maxRows?: number \} | \{ maxRows: 8 \} | - |
+| 属性           | 说明                                                                        | 类型                                                                   | 默认值                  | 版本 |
+| -------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------- | ---- |
+| actions        | 自定义按钮，当不需要默认操作按钮时，可以设为 `actions={false}`              | VNode \| (oriNode, info: \{ components: ActionsComponents \}) => VNode | -                       | -    |
+| allowSpeech    | 是否允许语音输入                                                            | boolean \| SpeechConfig                                                | false                   | -    |
+| classNames     | 样式类名                                                                    | [见下](#semantic-dom)                                                  | -                       | -    |
+| components     | 自定义组件                                                                  | Record<'input', ComponentType>                                         | -                       | -    |
+| defaultValue   | 输入框默认值                                                                | string                                                                 | -                       | -    |
+| disabled       | 是否禁用                                                                    | boolean                                                                | false                   | -    |
+| loading        | 是否加载中                                                                  | boolean                                                                | false                   | -    |
+| header         | 头部面板                                                                    | VNode \| () => VNode                                                   | -                       | -    |
+| prefix         | 前缀内容                                                                    | VNode \| () => VNode                                                   | -                       | -    |
+| footer         | 底部内容                                                                    | ReactNode \| (info: \{ components: ActionsComponents \}) => ReactNode  | -                       | -    |
+| readOnly       | 是否让输入框只读                                                            | boolean                                                                | false                   | -    |
+| rootClassName  | 根元素样式类                                                                | string                                                                 | -                       | -    |
+| styles         | 语义化定义样式                                                              | [见下](#semantic-dom)                                                  | -                       | -    |
+| submitType     | 提交模式                                                                    | SubmitType                                                             | `enter` \| `shiftEnter` | -    |
+| value(v-model) | 输入框值                                                                    | string                                                                 | -                       | -    |
+| onSubmit       | 点击发送按钮的回调                                                          | (message: string) => void                                              | -                       | -    |
+| onChange       | 输入框值改变的回调                                                          | (value: string, event?: FormEvent \| ChangeEvent ) => void             | -                       | -    |
+| onCancel       | 点击取消按钮的回调                                                          | () => void                                                             | -                       | -    |
+| onPasteFile    | 黏贴文件的回调                                                              | (firstFile: File, files: FileList) => void                             | -                       | -    |
+| autoSize       | 自适应内容高度，可设置为 true \| false 或对象：\{ minRows: 2, maxRows: 6 \} | boolean \| \{ minRows?: number; maxRows?: number \}                    | \{ maxRows: 8 \}        | -    |
 
 ```typescript | pure
 type SpeechConfig = {
   // 当设置 `recording` 时，内置的语音输入功能将会被禁用。
   // 交由开发者实现三方语音输入的功能。
   recording?: boolean;
   onRecordingChange?: (recording: boolean) => void;
+  audioIcon?: ButtonProps['icon'] | VNode;
+  audioDisabledIcon?: ButtonProps['icon'] | VNode;
+  audioRecordingIcon?: ButtonProps['icon'] | VNode;
 };
 ```
 
@@ -186,31 +200,31 @@ type ActionsComponents = {
 
 ### Sender Slots
 
-| 插槽名   | 说明    | 类型 |
-| ------- | ------ | ---- |
-| header  | 头部面板 | -   |
-| prefix  | 前缀内容 | _   |
+| 插槽名  | 说明     | 类型                                                                                                                                                                                                  |
+| ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| header  | 头部面板 | -                                                                                                                                                                                                     |
+| prefix  | 前缀内容 | _                                                                                                                                                                                                     |
 | actions | 操作按钮 | \{ ori: VNode; info: \{ components: \{ SendButton: InstanceType\<Button\>; ClearButton: InstanceType\<Button\>; LoadingButton: InstanceType\<Button\>; SpeechButton: InstanceType\<Button\>; \} \} \} |
-| footer  | 底部内容 | \{ info: \{ components: \{ SendButton: InstanceType\<Button\>; ClearButton: InstanceType\<Button\>; LoadingButton: InstanceType\<Button\>; SpeechButton: InstanceType\<Button\>; \} \} \}              |
+| footer  | 底部内容 | \{ info: \{ components: \{ SendButton: InstanceType\<Button\>; ClearButton: InstanceType\<Button\>; LoadingButton: InstanceType\<Button\>; SpeechButton: InstanceType\<Button\>; \} \} \}             |
 
 #### Sender Ref
 
-| 属性 | 说明 | 类型 | 默认值 | 版本 |
-| --- | --- | --- | --- | --- |
-| nativeElement | 外层容器 | `HTMLDivElement` | - | - |
-| focus | 获取焦点 | (option?: { preventScroll?: boolean, cursor?: 'start' \| 'end' \| 'all' }) | - | - |
-| blur | 取消焦点 | () => void | - | - |
+| 属性          | 说明     | 类型                                                                       | 默认值 | 版本 |
+| ------------- | -------- | -------------------------------------------------------------------------- | ------ | ---- |
+| nativeElement | 外层容器 | `HTMLDivElement`                                                           | -      | -    |
+| focus         | 获取焦点 | (option?: { preventScroll?: boolean, cursor?: 'start' \| 'end' \| 'all' }) | -      | -    |
+| blur          | 取消焦点 | () => void                                                                 | -      | -    |
 
 ### Sender.Header
 
-| 属性 | 说明 | 类型 | 默认值 | 版本 |
-| --- | --- | --- | --- | --- |
-| children | 面板内容 | VNode | - | - |
-| closable | 是否可关闭 | boolean | true | - |
-| forceRender | 强制渲染，在初始化便需要 ref 内部元素时使用 | boolean | false | - |
-| open | 是否展开 | boolean | - | - |
-| title | 标题 | VNode | - | - |
-| onOpenChange | 展开状态改变的回调 | (open: boolean) => void | - | - |
+| 属性         | 说明                                        | 类型                    | 默认值 | 版本 |
+| ------------ | ------------------------------------------- | ----------------------- | ------ | ---- |
+| children     | 面板内容                                    | VNode                   | -      | -    |
+| closable     | 是否可关闭                                  | boolean                 | true   | -    |
+| forceRender  | 强制渲染，在初始化便需要 ref 内部元素时使用 | boolean                 | false  | -    |
+| open         | 是否展开                                    | boolean                 | -      | -    |
+| title        | 标题                                        | VNode                   | -      | -    |
+| onOpenChange | 展开状态改变的回调                          | (open: boolean) => void | -      | -    |
 
 ## Semantic DOM
 
diff --git a/docs/examples-setup/sender/speechIcon.vue b/docs/examples-setup/sender/speechIcon.vue
@@ -0,0 +1,27 @@
+<script setup lang="ts">
+import { h } from 'vue';
+import { App, message } from 'ant-design-vue';
+import { Sender } from 'ant-design-x-vue';
+import { SoundOutlined, EllipsisOutlined } from '@ant-design/icons-vue';
+
+defineOptions({ name: 'AXSenderSpeechIconSetup' });
+
+const [messageApi, contextHolder] = message.useMessage();
+
+const submit = () => {
+  messageApi.success('Send message successfully!');
+};
+</script>
+<template>
+  <App>
+    <context-holder />
+    <Sender
+      :allow-speech="{
+        audioIcon: h(SoundOutlined),
+        audioDisabledIcon: h(SoundOutlined, { style: { color: 'gray' } }),
+        audioRecordingIcon: h(EllipsisOutlined)
+      }"
+      :on-submit="submit"
+    />
+  </App>
+</template>
diff --git a/docs/examples/sender/speechIcon.vue b/docs/examples/sender/speechIcon.vue
@@ -0,0 +1,34 @@
+<script setup lang="tsx">
+import { h } from 'vue';
+import { App } from 'ant-design-vue';
+import { Sender } from 'ant-design-x-vue';
+import { SoundOutlined, EllipsisOutlined } from '@ant-design/icons-vue';
+
+defineOptions({ name: 'AXSenderSpeechIcon' });
+
+const Demo = () => {
+  const { message } = App.useApp();
+
+  return (
+    <Sender
+      allowSpeech={{
+        audioIcon: h(SoundOutlined),
+        audioDisabledIcon: h(SoundOutlined, { style: { color: 'gray' } }),
+        audioRecordingIcon: h(EllipsisOutlined)
+      }}
+      onSubmit={() => {
+        message.success('Send message successfully!');
+      }}
+    />
+  );
+};
+
+defineRender(() => {
+  return (
+    <App>
+      <Demo />
+    </App>
+  )
+});
+
+</script>
diff --git a/src/sender/Sender.vue b/src/sender/Sender.vue
@@ -245,7 +245,17 @@ const onContentMouseDown: MouseEventHandler = (e) => {
 const actionNode = computed(() => {
   let _actionNode: VNode | false = (
     <Flex class={`${actionListCls.value}-presets`}>
-      {allowSpeech && <SpeechButton />}
+      {allowSpeech && (
+        <SpeechButton
+          {...(typeof allowSpeech === 'object' ? 
+            { 
+              audioIcon: allowSpeech.audioIcon, 
+              audioDisabledIcon: allowSpeech.audioDisabledIcon, 
+              audioRecordingIcon: allowSpeech.audioRecordingIcon 
+            } : {}
+          )}
+        />
+      )}
       {/* Loading or Send */}
       {loading ? <LoadingButton /> : <SendButton />}
     </Flex>
diff --git a/src/sender/components/SpeechButton/index.vue b/src/sender/components/SpeechButton/index.vue
@@ -4,29 +4,36 @@ import { AudioMutedOutlined, AudioOutlined } from '@ant-design/icons-vue';
 import type { AntdButtonProps } from '../../interface';
 import ActionButton from '../ActionButton/index.vue';
 import { useActionButtonContextInject } from '../ActionButton/context';
-
 import RecordingIcon from './RecordingIcon.vue';
 import { computed } from 'vue';
 
 defineOptions({ name: 'AXSenderSpeechButton' });
 
-const { type = 'text', disabled = undefined, ...restProps} = defineProps<AntdButtonProps>();
+const { type = 'text',
+  disabled = undefined,
+  audioIcon = (<AudioOutlined />),
+  audioDisabledIcon = (<AudioMutedOutlined />),
+  audioRecordingIcon = undefined,
+  ...restProps
+} = defineProps<AntdButtonProps>();
 
 const context = useActionButtonContextInject();
+
 const { token } = theme.useToken();
 
 const speechRecording = computed(() => context.value.speechRecording);
+
 const prefixCls = computed(() => context.value.prefixCls);
 
 const icon = computed(() => {
 
   let myIcon;
   if (speechRecording.value) {
-    myIcon = <RecordingIcon className={`${prefixCls.value}-recording-icon`} />;
+    myIcon = audioRecordingIcon ? (audioRecordingIcon) : (<RecordingIcon className={`${prefixCls.value}-recording-icon`} />)
   } else if (context.value.onSpeechDisabled) {
-    myIcon = <AudioMutedOutlined />;
+    myIcon = audioDisabledIcon
   } else {
-    myIcon = <AudioOutlined />;
+    myIcon = audioIcon
   }
   return myIcon
 })
diff --git a/src/sender/interface.ts b/src/sender/interface.ts
@@ -17,7 +17,7 @@ export type ClipboardEventHandler = (e: ClipboardEvent) => void;
 
 export type ChangeEvent = Event & {
   target: {
-      value?: string | undefined;
+    value?: string | undefined;
   };
 }
 
@@ -118,6 +118,9 @@ export interface SenderHeaderProps {
 
 export interface RecordingIconProps {
   className?: string;
+  audioIcon?: ButtonProps['icon'];
+  audioDisabledIcon?: ButtonProps['icon'];
+  audioRecordingIcon?: ButtonProps['icon'];
 }
 
 export interface ActionButtonContextProps {
@@ -152,6 +155,9 @@ export interface AntdButtonProps {
   title?: ButtonProps['title'];
   onClick?: ButtonProps['onClick'];
   onMousedown?: ButtonProps['onMousedown'];
+  audioIcon?: ButtonProps['icon'] | VNode;
+  audioDisabledIcon?: ButtonProps['icon'] | VNode
+  audioRecordingIcon?: ButtonProps['icon'] | VNode;
 }
 
 export interface ActionButtonProps extends AntdButtonProps {
diff --git a/src/sender/useSpeech.ts b/src/sender/useSpeech.ts
@@ -1,3 +1,4 @@
+import { ButtonProps } from 'ant-design-vue';
 import useMergedState from '../_util/hooks/useMergedState';
 import { computed, ref, watchEffect, type MaybeRefOrGetter, toValue, onWatcherCleanup, type ComputedRef, type Ref } from 'vue';
 
@@ -10,7 +11,10 @@ if (!SpeechRecognition && typeof window !== 'undefined') {
 
 export type ControlledSpeechConfig = {
   recording?: boolean;
-  onRecordingChange: (recording: boolean) => void;
+  onRecordingChange?: (recording: boolean) => void;
+  audioIcon?: ButtonProps['icon'];
+  audioDisabledIcon?: ButtonProps['icon']
+  audioRecordingIcon?: ButtonProps['icon'];
 };
 
 export type AllowSpeech = boolean | ControlledSpeechConfig;
