Select

这是一个常见的选择器，使用下拉菜单展示并选择内容。

基础使用

传入 modelValue 进入受控模式。不传或者为 undefined 则为非受控模式，此时可以传入 defaultValue 属性作为默认值。

Vue

<template>
	<px-space direction="vertical">
		<px-select v-model="value" :options="options" placeholder="Please Select"></px-select>
		<px-select :defaultValue="'vue'" :options="options" placeholder="Please Select"></px-select>
	</px-space>
</template>

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

const value = ref('vue')
const options = [
	{ label: 'Vue', value: 'vue' },
	{ label: 'React', value: 'react' },
	{ label: 'Angular', value: 'angular' }
]
</script>

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

禁用选项

options 中，选项置 disabled 为 true 可禁用选项。

Vue

Vanilla

<template>
	<px-space direction="vertical">
		<px-select v-model="value" :options="options" placeholder="Please Select"></px-select>
		<px-select
			:defaultValue="'vanilla'"
			:options="options"
			placeholder="Please Select"
		></px-select>
	</px-space>
</template>

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

const value = ref('vue')
const options = [
	{ label: 'Vanilla', value: 'vanilla', disabled: true },
	{ label: 'Vue', value: 'vue' },
	{ label: 'React', value: 'react' },
	{ label: 'Angular', value: 'angular' }
]
</script>

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

分组

options 中，也支持传入选项组。

Vue

<template>
	<px-space>
		<px-select v-model="value" :options="options" placeholder="Please Select"></px-select>
	</px-space>
</template>

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

const value = ref('vue')
const options = [
	{
		label: 'JS Framework',
		key: 'JS Framework',
		type: 'group',
		children: [
			{ label: 'Vanilla', value: 'vanilla', disabled: true },
			{ label: 'Vue', value: 'vue' },
			{ label: 'React', value: 'react' },
			{ label: 'Angular', value: 'angular' }
		]
	},
	{
		label: 'CSS Preprocessor',
		key: 'CSS Preprocessor',
		type: 'group',
		children: [
			{ label: 'Less', value: 'less' },
			{ label: 'Sass', value: 'sass' }
		]
	}
]
</script>

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

远程加载

设置 loading 属性和监听 focus 事件，实现加载搜索时的 UI 变化。

Please Select

<template>
	<px-select
		v-model="value"
		:options="options"
		placeholder="Please Select"
		@focus="focusHandler"
		:loading="loading"
	></px-select>
</template>

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

const value = ref(null)

const options = ref<string[]>([])
const loading = ref(false)

const list = ['Ready to work', 'Work, work', 'Work completed']

const focusHandler = () => {
	options.value = []
	loading.value = true
	setTimeout(() => {
		options.value = list
		loading.value = false
	}, 5000)
}
</script>

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

多选

设置 multiple 属性开启多选模式。

Please Select

<template>
	<px-select
		v-model="value"
		:options="options"
		placeholder="Please Select"
		multiple
	></px-select>
</template>

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

const value = ref<string[]>([])

const options = ref<string[]>(['Ready for action', 'Locked and loaded', 'I await your command'])
</script>

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

折叠标签

多选时，设置 collapseTags 属性可开启折叠标签（默认为 false），maxDisplayTags 属性设置最大展示标签，collapseTagsPopover 设置折叠后是否通过弹出框展示被折叠的标签（默认为 true）。

Please select

<template>
	<px-space direction="vertical">
		<px-select
			placeholder="Please select"
			v-model="value"
			collapse-tags
			:max-display-tags="3"
			multiple
			:options="options"
		></px-select>
		<px-select
			placeholder="Please select"
			v-model="value"
			collapse-tags
			:max-display-tags="3"
			:collapse-tags-popover="false"
			multiple
			:options="options"
		></px-select>
	</px-space>
</template>

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

const value = ref<string[]>([])
const options = [
	{ label: 'Vue', value: 'vue' },
	{ label: 'React', value: 'react' },
	{ label: 'Angular', value: 'angular' },
	{ label: 'Svelte', value: 'svelte' },
	{ label: 'Preact', value: 'Preact' },
	{ label: 'Next', value: 'next' },
	{ label: 'Nuxt', value: 'nuxt' },
	{ label: 'Astro', value: 'astro' }
]
</script>

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

搜索选项

设置 filterable 属性可开启搜索选项。

对于搜索的输入，传入 inputValue 进入受控模式。不传或者为 undefined 则为非受控模式，此时可以传入 defaultInputValue 属性作为默认值。

inputValue:

Please select

<template>
	<px-space direction="vertical">
		<div>inputValue: {{ inputValue }}</div>
		<px-select
			placeholder="Please select"
			v-model="value"
			:options="options"
			v-model:input-value="inputValue"
			filterable
		></px-select>
		<px-select
			placeholder="Please select"
			v-model="multiValue"
			default-input-value="Nest"
			multiple
			:options="options"
			filterable
		></px-select>
	</px-space>
</template>

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

const multiValue = ref<string[]>([])
const value = ref<string | null>(null)
const inputValue = ref<string>()
const options = [
	{ label: 'Express', value: 'express' },
	{ label: 'Koa', value: 'koa' },
	{ label: 'Nest', value: 'nest' },
	{ label: 'Fastify', value: 'fastify' }
]
</script>

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

添加选项

设置 creatable 属性可添加选项，添加的选项类型为 string，注意要开启 filterable。

Please select

<template>
	<px-space direction="vertical">
		<px-select
			placeholder="Please select"
			v-model="value"
			:options="options"
			filterable
			creatable
		></px-select>
		<px-select
			placeholder="Please select"
			v-model="multiValue"
			multiple
			:options="options"
			filterable
			creatable
		></px-select>
	</px-space>
</template>

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

const multiValue = ref<string[]>([])
const value = ref<string | null>(null)
const options = [
	{ label: 'Morning Mood', value: 'music1' },
	{ label: 'The Death of Åse', value: 'music2' },
	{ label: "Anitra's Dance", value: 'music3' },
	{ label: 'In the Hall of the Mountain King', value: 'music4' }
]
</script>

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

更多配置

选择器 Select 还拥有 Input、InputTag、AutoComplete 组件的部分功能。

Disabled, Readonly, Loading & Clearable

Please input

Shape

Please input

Size

Please input

Slot

prefix

Please input

suffix

Please input

Composite

Please input

Status

Please input

Expose

Please input

Tag Render

Please input

Option Render

Please input

<template>
	<px-space direction="vertical">
		<h4>Disabled, Readonly, Loading & Clearable</h4>
		<px-space>
			<px-select placeholder="Please input" disabled :options="options"></px-select>
			<px-select placeholder="Please input" readonly :options="options"></px-select>
			<px-select placeholder="Please input" loading :options="options"></px-select>
			<px-select placeholder="Please input" clearable :options="options"></px-select>
		</px-space>
		<h4>Shape</h4>
		<px-space>
			<px-select placeholder="Please input" shape="round" :options="options"></px-select>
			<px-select placeholder="Please input" :options="options"></px-select>
		</px-space>
		<h4>Size</h4>
		<px-space>
			<px-select placeholder="Please input" size="small" :options="options"></px-select>
			<px-select placeholder="Please input" :options="options"></px-select>
			<px-select placeholder="Please input" size="large" :options="options"></px-select>
		</px-space>
		<h4>Slot</h4>
		<px-space>
			<px-select placeholder="Please input" :options="options">
				<template #prefix>prefix</template>
				<template #suffix>suffix</template>
			</px-select>
			<px-select placeholder="Please input" :options="options">
				<template #prepend>
					<IconBolt></IconBolt>
				</template>
			</px-select>
			<px-select placeholder="Please input" :options="options">
				<template #append>
					<IconBolt></IconBolt>
				</template>
			</px-select>
		</px-space>
		<h4>Composite</h4>
		<px-space>
			<px-input-group>
				<px-input-group-label>
					<IconBolt></IconBolt>
				</px-input-group-label>
				<px-select placeholder="Please input" :options="options"> </px-select>
				<px-button>Confirm</px-button>
			</px-input-group>
		</px-space>
		<h4>Status</h4>
		<px-space>
			<px-select placeholder="Please input" :options="options"> </px-select>
			<px-select placeholder="Please input" :options="options" status="success"> </px-select>
			<px-select placeholder="Please input" :options="options" status="warning"> </px-select>
			<px-select placeholder="Please input" :options="options" status="error"> </px-select>
		</px-space>
		<h4>Expose</h4>
		<px-space direction="vertical">
			<px-space>
				<px-button theme="info" @click="focusHandler">Focus & Blur after 5s</px-button>
				<px-button theme="warning" @click="clearHandler">Clear</px-button>
			</px-space>
			<px-select placeholder="Please input" :options="options" ref="selectRef"></px-select>
		</px-space>
		<h4>Tag Render</h4>
		<px-select placeholder="Please input" multiple :options="options">
			<template #tag="{ label }">
				<div style="display: flex; align-items: center">
					<IconBolt style="margin-right: 4px"></IconBolt> {{ label }}
				</div>
			</template>
		</px-select>
		<h4>Option Render</h4>
		<px-select placeholder="Please input" v-model="input" :options="options">
			<template #group-label="{ option }">
				{{ option.label }}
				<div
					style="margin-left: 12px; color: red; font-size: 16px"
					v-if="option.label === 'citrus fruits'"
				>
					HOT!
				</div>
			</template>
			<template #option="{ option }">
				{{ option.label }}
				<px-tag style="margin-left: 12px" v-if="option.value === 'orange'">NEW!</px-tag>
			</template>
		</px-select>
	</px-space>
</template>

<script setup lang="ts">
import { IconBolt } from '@pixelium/web-vue/icon-hn/es'
import { ref } from 'vue'
import { Select } from '@pixelium/web-vue'

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

const selectRef = ref<InstanceType<typeof Select>>(null)

const focusHandler = () => {
	setTimeout(() => {
		selectRef.value?.focus()
		setTimeout(() => {
			selectRef.value?.blur()
		}, 5000)
	}, 50)
}
const clearHandler = () => {
	selectRef.value?.clear()
}

const options = ref([
	{
		type: 'group',
		label: 'citrus fruits',
		children: [
			{ label: 'orange', value: 'orange' },
			{ label: 'lemon', value: 'lemon' },
			{ label: 'lime', value: 'lime' },
			{ label: 'grapefruit', value: 'grapefruit' },
			{ label: 'tangerine', value: 'tangerine' }
		]
	},
	{
		type: 'group',
		label: 'tropical fruits',
		children: [
			{ label: 'mango', value: 'mango' },
			{ label: 'pineapple', value: 'pineapple' },
			{ label: 'papaya', value: 'papaya' },
			{ label: 'dragon fruit', value: 'dragon fruit' },
			{ label: 'durian', value: 'durian' },
			{ label: 'lychee', value: 'lychee' },
			{ label: 'longan', value: 'longan' }
		]
	}
])
</script>

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

API

SelectProps

属性	类型	可选	默认值	描述	版本
modelValue	`any`	是		选择器的值（受控模式），支持 `v-model`。	0.0.2
defaultValue	`any`	是		选择器的默认值（非受控模式）。	0.0.2
options	`string`	是		选项列表。	0.0.2
placeholder	`string`	是		占位符文本。	0.0.2
disabled	`boolean`	是	`false`	是否禁用。	0.0.2
readonly	`boolean`	是	`false`	是否只读。	0.0.2
clearable	`boolean`	是	`false`	是否显示清除按钮。	0.0.2
multiple	`boolean`	是	`false`		0.0.2
loading	`boolean`	是	`false`	是否显示加载状态。	0.0.2
inputValue	`string \| null`	是		搜索选项输入的文本值（受控模式），支持 `v-model`。	0.0.2
defaultInputValue	`string \| null`	是		搜索选项输入的默认文本值（非受控模式）。	0.0.2
filterable	`boolean`	是	`false`	可否搜索选项。	0.0.2
shouldShowPopover	`(value: string, optionsFiltered: (string \| SelectOption \| SelectGroupOption)[]) => boolean`	是		是否展示弹出框的函数。	0.0.2
filter	`(keyword: string, options: (string \| SelectOption \| SelectGroupOption)[]) => (string \| SelectOption \| SelectGroupOption)[]`	是		筛选选项的函数。	0.0.2
creatable	`boolean`	是	`false`	可否创建选项，需要开启 `filterable`。	0.0.2
collapseTags	`boolean`	是	`false`	是否开启折叠标签。	0.0.2
collapseTags	`number`	是		是否开启折叠标签。	0.0.2
collapseTagsPopover	`boolean`	是	`true`	是否在弹出框中展示被折叠的标签，开启 `collapseTags` 后生效。	0.0.2
tagTheme	`'primary' \| 'sakura' \| 'success' \| 'warning' \| 'danger' \| 'info'`	是	`'info'`	标签的 `theme` 属性，设置标签主题颜色。	0.0.2
tagVariant	`'primary' \| 'plain' \| 'outline'`	是	`'plain'`	标签的 `variant` 属性，设置标签样式变体。	0.0.2
tagColor	`string`	是		标签的 `color` 属性，自定义标签颜色。	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
status	`'success' \| 'warning' \| 'error' \| 'normal'`	是	`'normal'`	表单验证状态。	0.0.2

SelectEvents

事件	参数	描述	版本
input	`value: string, e: Event`	搜索选项输入时的回调。	0.0.2
update:modelValue	`value: any`	更新 `modelValue` 的回调。	0.0.2
update:inputValue	`value: string`	更新 `inputValue` 的回调。	0.0.2
change	`value: any`	选择器内容变化时的回调。	0.0.2
change	`value: string, e: Event \| undefined`	选择器内容变化时的回调。	0.0.2
clear	`value: any`	点击清除文本按钮，清除内容时的回调。	0.0.2
blur		失焦时的回调。	0.0.2
focus		聚焦时的回调。	0.0.2
select	`value: any, e: MouseEvent`	选中选项的回调。	0.0.2
tagClose	`value: any, e: MouseEvent`	关闭标签时的回调。	0.0.2

SelectSlots

插槽	参数	描述	版本
prefix		前缀内容。	0.0.2
suffix		后缀内容。	0.0.2
option	`option: string \| SelectOption`	选项内容。	0.0.2
group-label	`option: SelectGroupOption`	选项组的标签名。	0.0.2
tag	`value: any, label: string, index: number`	标签内容。	0.0.2

SelectExpose

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

Select ​

基础使用 ​

禁用选项 ​

分组 ​

远程加载 ​

多选 ​

折叠标签 ​

搜索选项 ​

添加选项 ​

更多配置 ​

Disabled, Readonly, Loading & Clearable

Shape

Size

Slot

Composite

Status

Expose

Tag Render

Option Render

API ​

SelectProps ​

SelectEvents ​

SelectSlots ​

SelectExpose ​

Select

基础使用

禁用选项

分组

远程加载

多选

折叠标签

搜索选项

添加选项

更多配置

API

SelectProps

SelectEvents

SelectSlots

SelectExpose