消息编辑器 composer

AI 对话组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

root / input / submit-trigger 三件缺一不可；Enter 提交、Shift+Enter 换行，清空发生在 submit 派发之后

（还没发过）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhComposerInput,
  XhComposerRoot,
  XhComposerSubmitTrigger,
} from "@xihan-ui/vue";

const value = ref("");
const log = ref("（还没发过）");

function onSubmit(details: { value: string }): void {
  // 这里拿到的是提交那一刻的原文
  log.value = `提交：${details.value}`;
}
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhComposerRoot v-model:value="value" @submit="onSubmit">
      <XhComposerInput placeholder="说点什么…" rows="1" />
      <XhComposerSubmitTrigger>发送</XhComposerSubmitTrigger>
    </XhComposerRoot>
    <span>{{ log }}</span>
  </div>
</template>

流式与停止

run-status 翻成 streaming 后，发送按钮原位变停止：同一个节点、同一个位置，只换 data-mode 与可访问名

run-status：ready · （还没发过）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhComposerInput,
  XhComposerRoot,
  XhComposerSubmitTrigger,
} from "@xihan-ui/vue";

const value = ref("");
const streaming = ref(false);
const log = ref("（还没发过）");

function onSubmit(details: { value: string }): void {
  log.value = `提交：${details.value}`;
  // 运行态的真源在宿主，组件既不猜也不改
  streaming.value = true;
}

function onStop(): void {
  log.value = "已按下停止";
  streaming.value = false;
}
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhComposerRoot
      v-model:value="value"
      :run-status="streaming ? 'streaming' : 'ready'"
      @submit="onSubmit"
      @stop="onStop"
    >
      <XhComposerInput placeholder="发一条，按钮就变成停止" rows="1" />
      <XhComposerSubmitTrigger>
        {{ streaming ? "停止" : "发送" }}
      </XhComposerSubmitTrigger>
    </XhComposerRoot>
    <span>run-status：{{ streaming ? "streaming" : "ready" }} · {{ log }}</span>
  </div>
</template>

Enter 只换行

submit-on-enter 关掉后 Enter 交回浏览器插入换行，发送只剩按钮一条路

（还没发过）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhComposerInput,
  XhComposerRoot,
  XhComposerSubmitTrigger,
} from "@xihan-ui/vue";

const value = ref("");
const log = ref("（还没发过）");
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhComposerRoot
      v-model:value="value"
      :submit-on-enter="false"
      @submit="log = `提交：${$event.value}`"
    >
      <XhComposerInput placeholder="Enter 在这里只换行" rows="2" />
      <XhComposerSubmitTrigger>发送</XhComposerSubmitTrigger>
    </XhComposerRoot>
    <span>{{ log }}</span>
  </div>
</template>

禁用与空值

disabled 罩住整框并走原生 disabled；输入为空或只有空白时发送按钮转灰，但位置留着不收起

这一台是禁用的

<script setup lang="ts">
import { ref } from "vue";
import {
  XhComposerInput,
  XhComposerRoot,
  XhComposerSubmitTrigger,
} from "@xihan-ui/vue";

const value = ref("");
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <!-- 整框禁用 -->
    <XhComposerRoot disabled default-value="这一台是禁用的">
      <XhComposerInput rows="1" />
      <XhComposerSubmitTrigger>发送</XhComposerSubmitTrigger>
    </XhComposerRoot>

    <!-- 空值：按钮转灰，敲进第一个非空白字符就亮 -->
    <XhComposerRoot v-model:value="value">
      <XhComposerInput placeholder="空着时发送按钮是灰的" rows="1" />
      <XhComposerSubmitTrigger>发送</XhComposerSubmitTrigger>
    </XhComposerRoot>
  </div>
</template>

框里的附加按钮

root 里除输入与发送外还能放自己的节点；插槽给出的 value 与 setValue 让清空这类操作就在框内完成

这一台在输入框两侧各放了一颗自己的按钮

（还没发过）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhComposerInput,
  XhComposerRoot,
  XhComposerSubmitTrigger,
} from "@xihan-ui/vue";

const log = ref("（还没发过）");

function onSubmit(details: { value: string }): void {
  log.value = `提交：${details.value}`;
}
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhComposerRoot
      v-slot="{ value, setValue }"
      default-value="这一台在输入框两侧各放了一颗自己的按钮"
      @submit="onSubmit"
    >
      <XhButton variant="ghost" size="sm">附件</XhButton>
      <XhComposerInput placeholder="说点什么…" rows="1" />
      <!-- 有内容才给清空，清空后按钮自己转灰 -->
      <XhButton variant="ghost" size="sm" :disabled="value === ''" @click="setValue('')">
        清空
      </XhButton>
      <XhComposerSubmitTrigger>发送</XhComposerSubmitTrigger>
    </XhComposerRoot>
    <span>{{ log }}</span>
  </div>
</template>

字数与上限

原生属性直接落到输入框上（maxlength 定上限），字数由插槽里的 value 现算

0 / 40

<script setup lang="ts">
import { XhComposerInput, XhComposerRoot, XhComposerSubmitTrigger } from "@xihan-ui/vue";

const max = 40;
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhComposerRoot v-slot="{ value }">
      <XhComposerInput :maxlength="max" placeholder="最多 40 个字" rows="1" />
      <span style="font-size: 13px; white-space: nowrap">{{ value.length }} / {{ max }}</span>
      <XhComposerSubmitTrigger>发送</XhComposerSubmitTrigger>
    </XhComposerRoot>
  </div>
</template>

随内容长高

输入框的高度跟着内容走，rows 定的是起始行数；不手动拖拽，也不写死高度

第一行 第二行 第三行 再多敲几行，框会继续往下长

<script setup lang="ts">
import { XhComposerInput, XhComposerRoot, XhComposerSubmitTrigger } from "@xihan-ui/vue";

const draft = "第一行\n第二行\n第三行\n再多敲几行，框会继续往下长";
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <!-- 起始一行：敲到第二行时框自己变高 -->
    <XhComposerRoot>
      <XhComposerInput placeholder="按 Shift+Enter 换行试试" rows="1" />
      <XhComposerSubmitTrigger>发送</XhComposerSubmitTrigger>
    </XhComposerRoot>

    <!-- 初值就是好几行，挂载时框已经是撑开的 -->
    <XhComposerRoot :default-value="draft">
      <XhComposerInput rows="1" />
      <XhComposerSubmitTrigger>发送</XhComposerSubmitTrigger>
    </XhComposerRoot>
  </div>
</template>

过滤输入

写回这一步由宿主说了算：把不要的字符滤掉再落回去，框里留下的始终是滤过的那一份

0 位

（还没发过）

<script setup lang="ts">
import { ref } from "vue";
import { XhComposerInput, XhComposerRoot, XhComposerSubmitTrigger } from "@xihan-ui/vue";

const log = ref("（还没发过）");

// 只留数字与空格
function digits(text: string): string {
  return text.replace(/[^\d ]/g, "");
}

function onSubmit(details: { value: string }): void {
  log.value = `提交：${details.value}`;
}
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhComposerRoot v-slot="{ value, setValue }" @submit="onSubmit">
      <!-- 输入框自己的写回先跑，这一手紧随其后把值改成滤过的 -->
      <XhComposerInput
        placeholder="敲几个字母试试，只有数字留得下"
        rows="1"
        @input="setValue(digits(($event.target as HTMLTextAreaElement).value))"
      />
      <span style="font-size: 13px; white-space: nowrap">{{ value.length }} 位</span>
      <XhComposerSubmitTrigger>发送</XhComposerSubmitTrigger>
    </XhComposerRoot>
    <span>{{ log }}</span>
  </div>
</template>

聚焦与选中

输入部件渲染出来就是一个 textarea，拿到它的节点就能聚焦、全选、失焦；发完一条把焦点送回去，接着敲下一条

（还没发过）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhComposerInput,
  XhComposerRoot,
  XhComposerSubmitTrigger,
} from "@xihan-ui/vue";

const log = ref("（还没发过）");
const input = ref<HTMLTextAreaElement | null>(null);

// 组件只渲染一个 textarea，实例上的 $el 就是它
function bindInput(instance: unknown): void {
  input.value = (instance as { $el: HTMLTextAreaElement } | null)?.$el ?? null;
}

function onSubmit(details: { value: string }): void {
  log.value = `提交：${details.value}`;
  // 点发送按钮会把焦点留在按钮上，这里送回输入框
  input.value?.focus();
}
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhComposerRoot @submit="onSubmit">
      <XhComposerInput :ref="bindInput" placeholder="发一条，焦点会自己回来" rows="1" />
      <XhComposerSubmitTrigger>发送</XhComposerSubmitTrigger>
    </XhComposerRoot>

    <div style="display: flex; gap: 8px">
      <XhButton variant="outline" size="sm" @click="input?.focus()">聚焦</XhButton>
      <XhButton variant="outline" size="sm" @click="input?.select()">全选</XhButton>
      <XhButton variant="ghost" size="sm" @click="input?.blur()">失焦</XhButton>
    </div>
    <span>{{ log }}</span>
  </div>
</template>

发送失败的错误态

判定谁算出错是宿主的事：属性直接落到真元素上，整框换色靠覆盖公开变量，原因由活区播报

（还没发过）

<script setup lang="ts">
import { ref, useId } from "vue";
import { XhComposerInput, XhComposerRoot, XhComposerSubmitTrigger } from "@xihan-ui/vue";

const reasonId = useId();
const failed = ref(false);
const log = ref("（还没发过）");
let attempt = 0;

// 边框换成危险档，覆盖的是公开变量
const invalidStyle = { "--xh-composer-border": "var(--xh-color-danger-500)" };

function onSubmit(details: { value: string }): void {
  attempt += 1;
  // 头一条故意发不出去，再发一条就成
  failed.value = attempt % 2 === 1;
  log.value = failed.value ? `没发出去：${details.value}` : `提交：${details.value}`;
}
</script>

<template>
  <div style="width: 100%; display: grid; gap: 8px">
    <XhComposerRoot
      :data-invalid="failed || undefined"
      :style="failed ? invalidStyle : undefined"
      @submit="onSubmit"
    >
      <XhComposerInput
        :aria-invalid="failed ? 'true' : 'false'"
        :aria-describedby="failed ? reasonId : undefined"
        placeholder="发一条试试"
        rows="1"
      />
      <XhComposerSubmitTrigger>发送</XhComposerSubmitTrigger>
    </XhComposerRoot>

    <!-- 节点常挂、靠 hidden 显隐：翻出来的那一刻读屏把原因念出来 -->
    <p
      :id="reasonId"
      role="alert"
      :hidden="!failed"
      style="margin: 0; font-size: 13px; color: var(--xh-fg-danger)"
    >
      网络不通，这条没能发出去，再发一次
    </p>
    <span>{{ log }}</span>
  </div>
</template>

产物

层	值
自定义元素	<xh-composer>
Vue 组件	XhComposerInput XhComposerRoot XhComposerSubmitTrigger
组合式函数	useComposer
状态机	无，connect 直接由 props 算属性
皮肤	@xihan-ui/styles/composer.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="composer"：root · input · submit-trigger

Props

属性	类型	必填	说明
value	string		受控值，给了就由宿主写回。
defaultValue	string		非受控初值。
disabled	boolean
runStatus	ComposerRunStatus		宿主传入的运行态。
submitOnEnter	boolean		Enter 直接提交、Shift+Enter 换行，默认 true。
translations	Partial<ComposerTranslations>
onValueChange	(details: ComposerValueChangeDetails) => void
onSubmit	(details: ComposerSubmitDetails) => void
onStop	() => void

状态机

事件：VALUE.SET · KEY.ENTER · COMPOSITION.START · COMPOSITION.END · SUBMIT · STOP · CONTROLLED.DISABLE · CONTROLLED.ENABLE · CONTROLLED.VALUE.EMPTY · CONTROLLED.VALUE.FILLED

判据：canSubmit · isStreaming · isValueEmpty · isNextValueEmpty

connect API

useComposer 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
value	string
isComposing	boolean	是否正在用输入法组合文字。
canSubmit	boolean	当前提交是否会真正发出，在机器守卫之外还额外要求非 disabled。
streaming	boolean
disabled	boolean
setValue	(value: string) => void
submit	() => void
stop	() => void
getRootProps	() => T['element']
getInputProps	() => T['textarea']
getSubmitTriggerProps	() => T['button']

键盘

规格出处：W3C APG

按键	生效条件	行为
Enter	焦点在输入框、未处于 IME 组合态、submitOnEnter 为真且可提交	提交当前输入并清空
Shift+Enter	焦点在输入框	不归组件管：原样放行，浏览器插入换行
Enter	处于 IME 组合态（isComposing 为真）	不提交：交给输入法确认候选词
Space / Enter	焦点在发送/停止按钮上	按 data-mode 触发提交或停止