文本输入 Input

输入文本。

基础使用

你可以在这里输入文本。传入 modelValue 进入受控模式。不传或者为 undefined 则为非受控模式，此时可以传入 defaultValue 属性作为默认值。 x> 建议使用 null 或者数据类型的空值作为空值。

<template>
	<px-space direction="vertical">
		<px-input placeholder="Please input" v-model="input"></px-input>
		<px-input placeholder="Please input D-mail"></px-input>
		<px-input placeholder="Please input" default-value="El Psy Kongroo"></px-input>
	</px-space>
</template>

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

const input = ref('Steins; Gate')
</script>

<style lang="css" scoped>
.px-input {
	width: 320px;
}
</style>

密码输入

这个组件也可以是密码输入框，只需要把 password 属性设置为 true。

<template>
	<px-input v-model="input" placeholder="Please input password" password></px-input>
</template>

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

const input = ref('')
</script>

<style lang="css" scoped>
.px-input {
	width: 320px;
}
</style>

只读 & 禁用

readonly 设置只读，disabled 设置禁用，此时内部 <input> 都会被设置 disabled。它们之间几乎只有样式不一样。

<template>
	<px-space direction="vertical">
		<px-input readonly placeholder="Please input content"></px-input>
		<px-input disabled default-value="Some text..."></px-input>
	</px-space>
</template>

<style lang="css" scoped>
.px-input {
	width: 320px;
}
</style>

清除文本

clearable 为 true 时，聚焦后展示清除文本的按钮。

<template>
	<px-input placeholder="Please input" v-model="input" clearable></px-input>
</template>

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

const input = ref('Test')
</script>

<style lang="css" scoped>
.px-input {
	width: 320px;
}
</style>

加载状态

loading 设置加载状态，和平常没什么不一样，只是多了一个加载图标。

<template>
	<px-input placeholder="Please input" v-model="input" loading></px-input>
</template>

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

const input = ref('You can enter text as usual')
</script>

<style lang="css" scoped>
.px-input {
	width: 320px;
}
</style>

输入框尺寸

输入框可以有不同的大小。

<template>
	<px-space direction="vertical">
		<px-input placeholder="Please input" size="small"></px-input>
		<px-input placeholder="Please input"></px-input>
		<px-input placeholder="Please input" size="large"></px-input>
	</px-space>
</template>

<style lang="css" scoped>
.px-input {
	width: 320px;
}
</style>

圆角边框

输入框也可以有圆角。

精力和技术力不太充足，自定义圆角还有需要优化的地方，但整体不影响使用。

<template>
	<px-space direction="vertical">
		<px-input placeholder="Please input"></px-input>
		<px-input placeholder="Please input" shape="round"></px-input>
		<px-input placeholder="Please input" :border-radius="[20, 0]"></px-input>
	</px-space>
</template>

<style lang="css" scoped>
.px-input {
	width: 320px;
}
</style>

前缀 & 后缀

在前缀后缀添加附加内容。

<template>
	<px-space direction="vertical">
		<px-input placeholder="Please input">
			<template #prefix>$</template>
		</px-input>
		<px-input placeholder="Please input">
			<template #suffix>km</template>
		</px-input>
	</px-space>
</template>

<style lang="css" scoped>
.px-input {
	width: 320px;
}
</style>

复合输入框

借助 InputGroup 组件，我们可以把各种输入控件和按钮组合起来。

.ini

<template>
	<px-space direction="vertical">
		<px-input-group>
			<px-input-group-label>
				<IconSearch></IconSearch>
			</px-input-group-label>
			<px-input placeholder="Please input"> </px-input>
			<px-button>Search</px-button>
		</px-input-group>
		<px-input-group>
			<px-input placeholder="Please input file name"> </px-input>
			<px-input-group-label> .ini </px-input-group-label>
		</px-input-group>
		<px-input-group>
			<px-input placeholder="Please input"> </px-input>
			<px-input-number placeholder="Please input" :default-value="0"> </px-input-number>
		</px-input-group>
	</px-space>
</template>
<script setup lang="ts">
import { IconSearch } from '@pixelium/web-vue/icon-hn/es'
</script>
<style lang="css" scoped>
.px-input,
.px-input-number {
	width: 320px;
}
</style>

字数统计 & 长度限制

showCount 属性设置展示字数统计，maxLength 设置最大长度。

Input 组件默认使用 str.length 计算长度，对于复合字符会存在计数错误的情况。我们推荐使用 grapheme-splitter 来解决这个问题。countGraphemes 属性用于设置统计长度的函数，sliceGraphemes 用于截取限制长度以内的字串，如果只传入 countGraphemes 而没有 sliceGraphemes，maxLength 的长度限制不会生效。

8 / 20

4 / 20

<template>
	<px-space direction="vertical">
		<px-input placeholder="Please input" default-value="🎺🎸🎹🥁" show-count></px-input>
		<px-input
			placeholder="Please input"
			default-value="🎺🎸🎹🥁"
			show-count
			:max-length="20"
		></px-input>
		<px-input
			placeholder="Please input"
			default-value="🎺🎸🎹🥁"
			show-count
			:max-length="20"
			:countGraphemes="countGraphemes"
			:sliceGraphemes="sliceGraphemes"
		></px-input>
	</px-space>
</template>

<script setup lang="ts">
import GraphemeSplitter from 'grapheme-splitter'

const splitter = new GraphemeSplitter()
const countGraphemes = (val: string) => {
	return splitter.countGraphemes(val)
}
const sliceGraphemes = (val: string, limit: number) => {
	const arr = splitter.splitGraphemes(val)
	return arr.slice(0, limit).join('')
}
</script>

<style lang="css" scoped>
.px-input {
	width: 320px;
}
</style>

手动操作

Input 组件导出了一些操作它本身的函数。

<template>
	<px-space direction="vertical">
		<px-space>
			<px-button theme="info" @click="focusHandler">Focus</px-button>
			<px-button theme="info" @click="blurHandler">Blur</px-button>
			<px-button theme="info" @click="selectHandler">Select</px-button>
			<px-button theme="warning" @click="clearHandler">Clear</px-button>
		</px-space>
		<px-input placeholder="Please input" ref="inputRef"></px-input>
	</px-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Input } from '@pixelium/web-vue'

// If on-demand import
// import { Input } from '@pixelium/web-vue/es'

const inputRef = ref<InstanceType<typeof Input>>(null)

const focusHandler = () => {
	inputRef.value?.focus()
}
const blurHandler = () => {
	inputRef.value?.blur()
}
const clearHandler = () => {
	inputRef.value?.clear()
}
const selectHandler = () => {
	inputRef.value?.select()
}
</script>

<style lang="css" scoped>
.px-input {
	width: 320px;
}
</style>

表单验证状态

输入框支持四种表单验证状态：'normal'（默认）、'success'、'warning'、'error'。

<template>
	<px-space direction="vertical">
		<px-input placeholder="Please input"> </px-input>
		<px-input placeholder="Please input" status="success"> </px-input>
		<px-input placeholder="Please input" status="warning"> </px-input>
		<px-input placeholder="Please input" status="error"> </px-input>
	</px-space>
</template>
<style lang="css" scoped>
.px-input {
	width: 320px;
}
</style>

API

InputProps

属性	类型	可选	默认值	描述	版本
modelValue	`string \| null`	是		文本输入框的值（受控模式），支持 `v-model`。	0.0.2
defaultValue	`string \| null`	是		文本输入框的默认值（非受控模式）。	0.0.2
placeholder	`string`	是		占位符文本。	0.0.2
password	`boolean`	是	`false`	是否为密码输入框。	0.0.2
disabled	`boolean`	是	`false`	是否禁用。	0.0.2
readonly	`boolean`	是	`false`	是否只读。	0.0.2
clearable	`boolean`	是	`false`	是否显示清除按钮。	0.0.2
loading	`boolean`	是	`false`	是否显示加载状态。	0.0.2
size	`'medium' \| 'large' \| 'small'`	是	`'medium'`	输入框尺寸。	0.0.2
shape	`'default' \| 'round'`	是	`'default'`	输入框形状。	0.0.2
borderRadius	`NumberOrPercentage \| NumberOrPercentage[]`	是		圆角半径，优先级高于 `shape`，与 CSS `border-radius` 行为一致；单值或长度为 1 的数组 → 四角同时生效；长度为 2 的数组 → [左上 & 右下, 右上 & 左下]；长度为 3 的数组 → [左上, 右上 & 左下, 右下]；长度为 4 的数组 → 按顺时针顺序依次作用于四角。	0.0.2
maxLength	`number`	是		最大输入长度。	0.0.2
showCount	`boolean`	是	`false`	是否展示字数统计。	0.0.2
countGraphemes	`(value: string) => number`	是		自定义字数统计函数，如果只传入 `countGraphemes` 而没有 `sliceGraphemes`，`maxLength` 的长度限制不会生效。	0.0.2
sliceGraphemes	`(value: string, limit: number) => string`	是		自定义截取长度函数。	0.0.2
status	`'success' \| 'warning' \| 'error' \| 'normal'`	是	`'normal'`	表单验证状态。	0.0.2
autofocus	`boolean`	是	`false`	原生 `<input>` 的 `autofocus` 属性。	0.0.2
nativeType	`'text' \| 'password' \| 'email' \| 'tel' \| 'url' \| 'search'`	是	`'text'`	原生 `<input>` 的 `type` 属性。	0.0.2

InputEvents

事件	参数	描述	版本
input	`value: string, e: Event`	输入框输入时的回调。	0.0.2
update:modelValue	`value: string`	更新 `modelValue` 的回调。	0.0.2
change	`value: string, e: Event \| undefined`	输入内容变化时的回调。	0.0.2
clear	`value: string`	点击清除文本按钮，清除内容时的回调。	0.0.2
blur	`e: FocusEvent`	输入框失焦时的回调。	0.0.2
focus	`e: FocusEvent`	输入框聚焦时的回调。	0.0.2

InputSlots

插槽	参数	描述	版本
prefix		前缀内容。	0.0.2
suffix		后缀内容。	0.0.2
count	`inputValue: number, currentLength: number, maxLength: number`	展示字数统计的插槽。	0.0.2

InputExpose

属性	类型	可选	描述	版本
focus	`() => void`	否	聚焦到当前输入框。	0.0.2
blur	`() => void`	否	取消聚焦当前输入框。	0.0.2
clear	`() => void`	否	清空当前输入框。	0.0.2
select	`() => void`	否	选中当前输入框内容。	0.0.2

NumberOrPercentage

export type NumberOrPercentage = number | `${number}%`

文本输入 Input ​

基础使用 ​

密码输入 ​

只读 & 禁用 ​

清除文本 ​

加载状态 ​

输入框尺寸 ​

圆角边框 ​

前缀 & 后缀 ​

复合输入框 ​

字数统计 & 长度限制 ​

手动操作 ​

表单验证状态 ​

API ​

InputProps ​

InputEvents ​

InputSlots ​

InputExpose ​

NumberOrPercentage ​