文档演练博客

选择

显示一个选项列表，供用户选择 - 由按钮触发。

View source Report an issue View in Playground

<Select.Root defaultValue="apple">
	<Select.Trigger />
	<Select.Content>
		<Select.Group>
			<Select.Label>Fruits</Select.Label>
			<Select.Item value="orange">Orange</Select.Item>
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="grape" disabled>
				Grape
			</Select.Item>
		</Select.Group>
		<Select.Separator />
		<Select.Group>
			<Select.Label>Vegetables</Select.Label>
			<Select.Item value="carrot">Carrot</Select.Item>
			<Select.Item value="potato">Potato</Select.Item>
		</Select.Group>
	</Select.Content>
</Select.Root>

API 参考

¥API Reference

根

¥Root

包含选择框的所有部分。它继承了 Select 基元根部分的 props。

¥Contains all the parts of a select. It inherits props from the Select primitive Root part.

Prop	Type	Default
`size`	`Responsive<"1" \| "2" \| "3">`	`"2"`

触发器

¥Trigger

切换选择按钮。此组件继承了 Select 基础组件触发器和值部件的属性。支持常用边距属性。

¥The button that toggles the select. This component inherits props from the Select primitive Trigger and Value parts. It supports common margin props.

Prop	Type	Default
`variant`	`"classic" \| "surface" \| "soft" \| "ghost"`	`"surface"`
`color`	`enum`	No default value
`radius`	`"none" \| "small" \| "medium" \| "large" \| "full"`	No default value
`placeholder`	`string`	No default value

内容

¥Content

选择框打开时弹出的组件。它继承了 Select.Portal 基础组件和 Select.Content 基础组件部分的 props。

¥The component that pops out when the select is open. It inherits props from the Select.Portal primitive and Select.Content primitive parts.

Prop	Type	Default
`variant`	`"solid" \| "soft"`	`"solid"`
`color`	`enum`	No default value
`highContrast`	`boolean`	No default value

项目

¥Item

包含选择项的组件。它继承了 Select.Item 基础组件部分的 props。

¥The component that contains the select items. It inherits props from the Select.Item primitive part.

组

¥Group

用于对多个项目进行分组。它继承了 Select.Group 基础组件部分的 props。与 Select.Label 结合使用，通过自动标记确保良好的可访问性。

¥Used to group multiple items. It inherits props from the Select.Group primitive part. Use in conjunction with Select.Label to ensure good accessibility via automatic labelling.

分隔符

¥Separator

用于在选择菜单中以视觉方式分隔项目。它继承了 Select.Separator 基础组件部分的 props。

¥Used to visually separate items in the Select. It inherits props from the Select.Separator primitive part.

示例

¥Examples

尺寸

¥Size

使用 size 属性控制大小。

¥Use the size prop to control the size.

<Flex gap="3" align="center">
	<Select.Root size="1" defaultValue="apple">
		<Select.Trigger />
		<Select.Content>
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="orange">Orange</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root size="2" defaultValue="apple">
		<Select.Trigger />
		<Select.Content>
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="orange">Orange</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root size="3" defaultValue="apple">
		<Select.Trigger />
		<Select.Content>
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="orange">Orange</Select.Item>
		</Select.Content>
	</Select.Root>
</Flex>

变体

¥Variant

在 Trigger 和 Content 上使用 variant 属性来自定义视觉样式。

¥Use the variant prop on Trigger and Content to customize the visual style.

<Flex gap="3" align="center">
	<Select.Root defaultValue="apple">
		<Select.Trigger variant="surface" />
		<Select.Content>
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="orange">Orange</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root defaultValue="apple">
		<Select.Trigger variant="classic" />
		<Select.Content>
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="orange">Orange</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root defaultValue="apple">
		<Select.Trigger variant="soft" />
		<Select.Content>
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="orange">Orange</Select.Item>
		</Select.Content>
	</Select.Root>
</Flex>

幽灵

¥Ghost

使用 ghost 触发器变体渲染触发器，使其不包含视觉包含元素。幽灵触发器在布局中的行为有所不同，因为它们使用负边距使其与兄弟按钮在视觉上对齐，同时在活动和悬停状态下保持填充。

¥Use the ghost trigger variant to render the trigger without a visually containing element. Ghost triggers behave differently in layout as they use a negative margin to optically align themselves against their siblings while maintaining their padded active and hover states.

<Flex gap="3" align="center">
	<Select.Root defaultValue="apple">
		<Select.Trigger variant="surface" />
		<Select.Content>
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="orange">Orange</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root defaultValue="apple">
		<Select.Trigger variant="ghost" />
		<Select.Content>
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="orange">Orange</Select.Item>
		</Select.Content>
	</Select.Root>
</Flex>

颜色

¥Color

在 Trigger 和 Content 上使用 color 属性来分配特定的颜色值。

¥Use the color prop on Trigger and Content to assign a specific color value.

<Flex gap="3">
	<Select.Root defaultValue="apple">
		<Select.Trigger color="indigo" variant="soft" />
		<Select.Content color="indigo">
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="orange">Orange</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root defaultValue="apple">
		<Select.Trigger color="cyan" variant="soft" />
		<Select.Content color="cyan">
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="orange">Orange</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root defaultValue="apple">
		<Select.Trigger color="orange" variant="soft" />
		<Select.Content color="orange">
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="orange">Orange</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root defaultValue="apple">
		<Select.Trigger color="crimson" variant="soft" />
		<Select.Content color="crimson">
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="orange">Orange</Select.Item>
		</Select.Content>
	</Select.Root>
</Flex>

高对比度

¥High-contrast

在 Content 上使用 highContrast 属性来增加项目对比度。

¥Use the highContrast prop on Content to increase item contrast.

<Flex gap="3">
	<Select.Root defaultValue="apple">
		<Select.Trigger color="gray" />
		<Select.Content color="gray" variant="solid">
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="orange">Orange</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root defaultValue="apple">
		<Select.Trigger color="gray" />
		<Select.Content color="gray" variant="solid" highContrast>
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="orange">Orange</Select.Item>
		</Select.Content>
	</Select.Root>
</Flex>

圆角

¥Radius

使用 radius 属性指定特定的圆角值。

¥Use the radius prop to assign a specific radius value.

<Flex gap="3">
	<Select.Root defaultValue="apple">
		<Select.Trigger radius="none" />
		<Select.Content>
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="orange">Orange</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root defaultValue="apple">
		<Select.Trigger radius="large" />
		<Select.Content>
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="orange">Orange</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root defaultValue="apple">
		<Select.Trigger radius="full" />
		<Select.Content>
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="orange">Orange</Select.Item>
		</Select.Content>
	</Select.Root>
</Flex>

占位符

¥Placeholder

使用 placeholder 属性创建不需要初始值的 Trigger。

¥Use the placeholder prop to create a Trigger that doesn’t need an initial value.

<Select.Root>
	<Select.Trigger placeholder="Pick a fruit" />
	<Select.Content>
		<Select.Group>
			<Select.Label>Fruits</Select.Label>
			<Select.Item value="orange">Orange</Select.Item>
			<Select.Item value="apple">Apple</Select.Item>
			<Select.Item value="grape" disabled>
				Grape
			</Select.Item>
		</Select.Group>
		<Select.Separator />
		<Select.Group>
			<Select.Label>Vegetables</Select.Label>
			<Select.Item value="carrot">Carrot</Select.Item>
			<Select.Item value="potato">Potato</Select.Item>
		</Select.Group>
	</Select.Content>
</Select.Root>

位置

¥Position

设置 position="popper" 属性，将选择菜单置于触发器下方。

¥Set position="popper" prop to position the select menu below the trigger.

<Select.Root defaultValue="apple">
	<Select.Trigger />
	<Select.Content position="popper">
		<Select.Item value="apple">Apple</Select.Item>
		<Select.Item value="orange">Orange</Select.Item>
	</Select.Content>
</Select.Root>

使用服务器端渲染

¥With SSR

使用服务器端渲染时，你可能会注意到水合后布局发生变化。这是因为触发器执行客户端代码来显示所选项目的文本。为避免布局偏移，你可以通过映射值手动渲染。

¥When using server-side rendering, you might notice a layout shift after hydration. This is because Trigger executes client-side code to display the selected item’s text. To avoid that layout shift, you can render it manually by mapping values.

() => {
	const data = {
		apple: "Apple",
		orange: "Orange",
	};
	const [value, setValue] = React.useState("apple");
	return (
		<Select.Root value={value} onValueChange={setValue}>
			<Select.Trigger>{data[value]}</Select.Trigger>
			<Select.Content>
				<Select.Item value="apple">Apple</Select.Item>
				<Select.Item value="orange">Orange</Select.Item>
			</Select.Content>
		</Select.Root>
	);
};

使用图标

¥With an icon

你可以通过手动控制触发器的子项来自定义触发器如何呈现值。例如，你可以在所选项目的文本旁边渲染一个图标。

¥You can customise how Trigger renders the value by controlling its children manually. For example, you can render an icon next to the selected item’s text.

() => {
	const data = {
		light: { label: "Light", icon: <SunIcon /> },
		dark: { label: "Dark", icon: <MoonIcon /> },
	};
	const [value, setValue] = React.useState("light");
	return (
		<Flex direction="column" maxWidth="160px">
			<Select.Root value={value} onValueChange={setValue}>
				<Select.Trigger>
					<Flex as="span" align="center" gap="2">
						{data[value].icon}
						{data[value].label}
					</Flex>
				</Select.Trigger>
				<Select.Content position="popper">
					<Select.Item value="light">Light</Select.Item>
					<Select.Item value="dark">Dark</Select.Item>
				</Select.Content>
			</Select.Root>
		</Flex>
	);
};

Previous分段控件

Next分隔符

概览

主题

布局

排版

组件

实用工具

选择

幽灵