Input 输入框

用于单行文本输入，并提供搜索、密码和组合输入等扩展形态。

基础用法

vue

<template>
  <x-input v-model="value" placeholder="请输入" allow-clear />
</template>

<script setup lang="ts">
import { ref } from 'vue';

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

前缀与后缀

https://.com

vue

<template>
  <x-input v-model="value" placeholder="请输入">
    <template #prefix>https://</template>
    <template #suffix>.com</template>
  </x-input>
</template>

<script setup lang="ts">
import { ref } from 'vue';

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

尺寸

vue

<template>
  <x-input v-model="value" size="mini" />
  <x-input v-model="value" size="small" />
  <x-input v-model="value" size="medium" />
  <x-input v-model="value" size="large" />
</template>

<script setup lang="ts">
import { ref } from 'vue';
const value = ref('当前内容');
</script>

禁用、只读和错误

vue

<template>
  <x-input v-model="value" disabled allow-clear aria-label="禁用输入" />
  <x-input v-model="value" readonly allow-clear aria-label="只读输入" />
  <x-input v-model="value" error allow-clear aria-label="错误输入" />
</template>

<script setup lang="ts">
import { ref } from 'vue';
const value = ref('当前内容');
</script>

字数限制

0/1215/12

vue

<template>
  <x-input v-model="value" :max-length="12" show-word-limit allow-clear />
  <x-input v-model="overflow" :max-length="{ length: 12, errorOnly: true }" show-word-limit allow-clear />
</template>

<script setup lang="ts">
import { ref } from 'vue';
const value = ref('');
const overflow = ref('超长内容只提示错误，不会被截断');
</script>

errorOnly 允许输入超过限制，并展示错误状态。Input 默认按 JavaScript 字符串长度计数；需要自定义计数时，同时提供 wordLength 和 wordSlice。

搜索、加载和禁用

禁用搜索

加载中

点击搜索按钮查看回调

vue

<template>
  <x-checkbox v-model="disabled">禁用搜索</x-checkbox>
  <x-checkbox v-model="loading">加载中</x-checkbox>
  <x-input-search v-model="value" :disabled="disabled" :loading="loading" allow-clear @search="handleSearch" />
  <x-input-search v-model="value" :disabled="disabled" :loading="loading" search-button button-text="搜索" @search="handleSearch" />
  <p role="status">{{ result }}</p>
</template>

<script setup lang="ts">
import { ref } from 'vue';
const value = ref('');
const disabled = ref(false);
const loading = ref(false);
const result = ref('等待搜索');
const handleSearch = (value: string) => { result.value = `搜索：${value || '空内容'}`; };
</script>

search 在点击搜索按钮时触发。需要回车搜索时，可监听继承自 Input 的 press-enter，用当前 v-model 值执行搜索。禁用状态同时约束输入和搜索按钮，并可继承 Form 的禁用状态与尺寸。

输入和提交事件

等待输入

vue

<template>
  <x-input v-model="value" allow-clear
    @input="(next) => result = `input：${next}`"
    @change="(next) => result = `change：${next || '空内容'}`"
    @press-enter="result = `press-enter：${value}`"
    @clear="result = 'clear：已清空'"
  />
  <p role="status">{{ result }}</p>
</template>

<script setup lang="ts">
import { ref } from 'vue';
const value = ref('');
const result = ref('等待输入');
</script>

input 表示键入，change 在值有变化时由失焦、回车或清空触发。清空会通知 Form 的 input 校验通道，公开事件仍通过 clear 表示按钮操作。

前置与后置标签

https://.com

vue

<template>
  <x-input v-model="value" placeholder="请输入域名">
    <template #prepend>https://</template>
    <template #append>.com</template>
  </x-input>
</template>

<script setup lang="ts">
import { ref } from 'vue';

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

在 Form 中校验

x-input 接入 x-form 后会自动继承尺寸与禁用状态，并按 validateTrigger 触发校验。默认 change 表示文本输入在失焦时校验；需要每次输入即校验时设置 validateTrigger="input"。

vue

<template>
  <x-form ref="formRef" :model="form" :rules="formRules">
    <x-form-item field="email" label="邮箱">
      <x-input v-model="form.email" placeholder="请输入邮箱" allow-clear />
    </x-form-item>
    <!-- validate-trigger 是 FormItem 的 prop：每次输入即触发校验 -->
    <x-form-item field="code" label="验证码" validate-trigger="input">
      <x-input v-model="form.code" placeholder="请输入验证码" />
    </x-form-item>
    <x-form-item>
      <x-button type="primary" @click="onSubmit">提交</x-button>
    </x-form-item>
  </x-form>
  <p role="status">{{ formResult }}</p>
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue';
import type { FormInstance, FieldRule } from 'x-next';

const form = reactive({ email: '', code: '' });
const formRules: Record<string, FieldRule[]> = {
  email: [
    { required: true, message: '请输入邮箱' },
    { type: 'email', message: '邮箱格式不正确' },
  ],
  code: [{ required: true, message: '请输入验证码' }],
};
const formRef = ref<FormInstance>();
const formResult = ref('');

const onSubmit = async () => {
  const errors = await formRef.value!.validate();
  formResult.value = errors ? '校验失败，请检查表单' : '校验通过，已提交';
};
</script>

关联组件

vue

<template>
  <x-input-search placeholder="搜索" />
  <x-input-password placeholder="密码" />
  <x-input-group>
    <x-input placeholder="省" />
    <x-input placeholder="市" />
  </x-input-group>
</template>

密码可见性

当前：密码已隐藏

vue

<template>
  <x-input-password
    v-model="password"
    v-model:visibility="visible"
    placeholder="请输入密码"
  />
  <span>{{ visible ? '明文可见' : '密码已隐藏' }}</span>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const password = ref('x-next-password');
const visible = ref(false);
</script>

visibility=true 表示显示明文，false 表示使用密码遮蔽。显隐按钮会触发 visibility-change 和 update:visibility。

非受控密码默认 defaultVisibility=true。需要默认遮蔽时设置 :default-visibility="false"；禁用时显隐按钮也不可操作。

id、name、aria-label、aria-labelledby、aria-describedby、inputmode 等原生属性会传给内部 input；class / style 保留在组件根节点。也可以通过 inputAttrs 集中传入原生属性。

按需导入

import { Input, InputSearch, InputPassword, InputGroup } from 'x-next';

样式按需引入（base.css 为共享基础层，多个组件只需引入一次）：

import 'x-next/style/base.css';
import 'x-next/style/form-input.css';

Input Props

参数	说明	类型	默认值
`modelValue`	绑定值	`string`	`-`
`defaultValue`	默认值，非受控模式	`string`	`''`
`size`	输入框尺寸	`'mini' \| 'small' \| 'medium' \| 'large'`	跟随全局配置
`allowClear`	是否允许清空	`boolean`	`false`
`disabled`	是否禁用	`boolean`	`false`
`readonly`	是否只读	`boolean`	`false`
`error`	是否为错误状态	`boolean`	`false`
`placeholder`	占位提示	`string`	`-`
`maxLength`	最大长度，支持仅提示错误	`number \| { length: number; errorOnly?: boolean }`	`0`
`showWordLimit`	是否显示字数统计	`boolean`	`false`
`wordLength`	字符长度计算方法	`(value: string) => number`	`-`
`wordSlice`	超长时的截取方法	`(value: string, maxLength: number) => string`	`-`
`inputAttrs`	内部 input 元素属性	`object`	`-`

Input Events

事件名	说明	回调参数
`update:modelValue`	值更新时触发	`value`
`input`	用户输入时触发	`value, event`
`change`	失焦或按下回车且值变化时触发	`value, event`
`press-enter`	按下回车时触发	`event`
`clear`	点击清除按钮时触发	`event`
`focus`	获取焦点时触发	`event`
`blur`	失去焦点时触发	`event`

InputPassword Props

除 Input 的属性外，InputPassword 还支持：

参数	说明	类型	默认值
`visibility`	密码是否以明文显示，受控属性	`boolean`	`-`
`defaultVisibility`	非受控模式下默认是否显示明文	`boolean`	`true`
`invisibleButton`	是否显示密码显隐按钮	`boolean`	`true`
`disabled`	禁用输入和显隐按钮，继承 Form	`boolean`	`false`

InputSearch Props

除 Input 的属性外，InputSearch 还支持：

参数	说明	类型	默认值
`searchButton`	使用后置搜索按钮	`boolean`	`false`
`loading`	搜索加载状态	`boolean`	`false`
`disabled`	禁用输入和搜索按钮	`boolean`	`false`
`size`	尺寸，继承 Form / 全局配置	`'mini' \| 'small' \| 'medium' \| 'large'`	跟随全局配置
`buttonText`	搜索按钮文字	`string`	`-`
`buttonProps`	搜索按钮属性	`ButtonProps`	`-`

InputSearch Events

事件名	说明	回调参数
`search`	点击可用搜索按钮时触发	`value: string, event: MouseEvent`

InputSearch Slots

支持 Input 的四个插槽，以及按钮模式下的 button-default（按钮内容）、button-icon（按钮图标）。

InputPassword Events

事件名	说明	回调参数
`visibility-change`	密码可见性变化时触发	`visible: boolean`
`update:visibility`	用于 `v-model:visibility` 同步	`visible: boolean`

Input Slots

插槽名	说明
`prefix`	前缀内容
`suffix`	后缀内容
`prepend`	前置标签
`append`	后置标签

Input Methods

方法	说明
`focus`	使输入框获取焦点
`blur`	使输入框失去焦点

Input 输入框 ​

基础用法 ​

前缀与后缀 ​

尺寸 ​

禁用、只读和错误 ​

字数限制 ​

搜索、加载和禁用 ​

输入和提交事件 ​

前置与后置标签 ​

在 Form 中校验 ​

关联组件 ​

密码可见性 ​

按需导入 ​

Input Props ​

Input Events ​

InputPassword Props ​

InputSearch Props ​

InputSearch Events ​

InputSearch Slots ​

InputPassword Events ​

Input Slots ​

Input Methods ​