选择

提供给用户选择的选项列表 - 通过一个按钮触发。

View source Report an issue View in Playground

<Select.Root defaultValue="apple">
	<Select.Trigger />
	<Select.Content>
		<Select.Group>
			<Select.Label>水果</Select.Label>
			<Select.Item value="orange">橘子</Select.Item>
			<Select.Item value="apple">苹果</Select.Item>
			<Select.Item value="grape" disabled>
				葡萄
			</Select.Item>
		</Select.Group>
		<Select.Separator />
		<Select.Group>
			<Select.Label>蔬菜</Select.Label>
			<Select.Item value="carrot">胡萝卜</Select.Item>
			<Select.Item value="potato">土豆</Select.Item>
		</Select.Group>
	</Select.Content>
</Select.Root>

API 参考

Root

包含选择器的所有部分。它从选择基础部分 Root 继承属性。

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

Trigger

用于切换选择器的按钮。该组件从选择基础部分 Trigger 和 Value 继承属性。它支持常见的边距属性。

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 primitive 和 Select.Content primitive 继承属性。

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

Item

包含选择项的组件。它从 Select.Item primitive 部分继承属性。

Group

用于分组多个项。它从 Select.Group primitive 部分继承属性。与 Select.Label 一起使用，以确保通过自动标签实现良好的可访问性。

Label

用于渲染组的标签，无法通过方向键聚焦。它从 Select.Label primitive 部分继承属性。

Separator

用于在选择器中视觉上分隔项。它从 Select.Separator primitive 部分继承属性。

示例

尺寸

使用 size 属性来控制大小。

<Flex gap="3" align="center">
	<Select.Root size="1" defaultValue="apple">
		<Select.Trigger />
		<Select.Content>
			<Select.Item value="apple">苹果</Select.Item>
			<Select.Item value="orange">橘子</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root size="2" defaultValue="apple">
		<Select.Trigger />
		<Select.Content>
			<Select.Item value="apple">苹果</Select.Item>
			<Select.Item value="orange">橘子</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root size="3" defaultValue="apple">
		<Select.Trigger />
		<Select.Content>
			<Select.Item value="apple">苹果</Select.Item>
			<Select.Item value="orange">橘子</Select.Item>
		</Select.Content>
	</Select.Root>
</Flex>

变体

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

<Flex gap="3" align="center">
	<Select.Root defaultValue="apple">
		<Select.Trigger variant="surface" />
		<Select.Content>
			<Select.Item value="apple">苹果</Select.Item>
			<Select.Item value="orange">橘子</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root defaultValue="apple">
		<Select.Trigger variant="classic" />
		<Select.Content>
			<Select.Item value="apple">苹果</Select.Item>
			<Select.Item value="orange">橘子</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root defaultValue="apple">
		<Select.Trigger variant="soft" />
		<Select.Content>
			<Select.Item value="apple">苹果</Select.Item>
			<Select.Item value="orange">橘子</Select.Item>
		</Select.Content>
	</Select.Root>
</Flex>

幽灵

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

<Flex gap="3" align="center">
	<Select.Root defaultValue="apple">
		<Select.Trigger variant="surface" />
		<Select.Content>
			<Select.Item value="apple">苹果</Select.Item>
			<Select.Item value="orange">橘子</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root defaultValue="apple">
		<Select.Trigger variant="ghost" />
		<Select.Content>
			<Select.Item value="apple">苹果</Select.Item>
			<Select.Item value="orange">橘子</Select.Item>
		</Select.Content>
	</Select.Root>
</Flex>

颜色

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

<Flex gap="3">
	<Select.Root defaultValue="apple">
		<Select.Trigger color="indigo" variant="soft" />
		<Select.Content color="indigo">
			<Select.Item value="apple">苹果</Select.Item>
			<Select.Item value="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">苹果</Select.Item>
			<Select.Item value="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">苹果</Select.Item>
			<Select.Item value="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">苹果</Select.Item>
			<Select.Item value="orange">橘子</Select.Item>
		</Select.Content>
	</Select.Root>
</Flex>

高对比

在 Content 上使用 highContrast 属性以增加项的对比度。

<Flex gap="3">
	<Select.Root defaultValue="apple">
		<Select.Trigger color="gray" />
		<Select.Content color="gray" variant="solid">
			<Select.Item value="apple">苹果</Select.Item>
			<Select.Item value="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">苹果</Select.Item>
			<Select.Item value="orange">橘子</Select.Item>
		</Select.Content>
	</Select.Root>
</Flex>

半径

使用 radius 属性来赋予特定的半径值。

<Flex gap="3">
	<Select.Root defaultValue="apple">
		<Select.Trigger radius="none" />
		<Select.Content>
			<Select.Item value="apple">苹果</Select.Item>
			<Select.Item value="orange">橘子</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root defaultValue="apple">
		<Select.Trigger radius="large" />
		<Select.Content>
			<Select.Item value="apple">苹果</Select.Item>
			<Select.Item value="orange">橘子</Select.Item>
		</Select.Content>
	</Select.Root>

	<Select.Root defaultValue="apple">
		<Select.Trigger radius="full" />
		<Select.Content>
			<Select.Item value="apple">苹果</Select.Item>
			<Select.Item value="orange">橘子</Select.Item>
		</Select.Content>
	</Select.Root>
</Flex>

占位符

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

<Select.Root>
	<Select.Trigger placeholder="选择一个水果" />
	<Select.Content>
		<Select.Group>
			<Select.Label>水果</Select.Label>
			<Select.Item value="orange">橘子</Select.Item>
			<Select.Item value="apple">苹果</Select.Item>
			<Select.Item value="grape" disabled>
				葡萄
			</Select.Item>
		</Select.Group>
		<Select.Separator />
		<Select.Group>
			<Select.Label>蔬菜</Select.Label>
			<Select.Item value="carrot">胡萝卜</Select.Item>
			<Select.Item value="potato">土豆</Select.Item>
		</Select.Group>
	</Select.Content>
</Select.Root>

位置

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

<Select.Root defaultValue="apple">
	<Select.Trigger />
	<Select.Content position="popper">
		<Select.Item value="apple">苹果</Select.Item>
		<Select.Item value="orange">橘子</Select.Item>
	</Select.Content>
</Select.Root>

与服务端渲染一起使用

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

() => {
	const data = {
		apple: "苹果",
		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">苹果</Select.Item>
				<Select.Item value="orange">橘子</Select.Item>
			</Select.Content>
		</Select.Root>
	);
};

带图标

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

() => {
	const data = {
		light: { label: "光明", icon: <SunIcon /> },
		dark: { label: "黑暗", 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">光明</Select.Item>
					<Select.Item value="dark">黑暗</Select.Item>
				</Select.Content>
			</Select.Root>
		</Flex>
	);
};

上一篇分段控制 Segmented Control

下一篇分隔线 Separator

在 GitHub 上编辑此页面

概览 Overview

主题 Theme

布局 Layout

排版

组件

通用工具 Utilities

选择

幽灵