按钮

按钮让用户通过单击执行操作和做出选择。

简介

按钮用于传达用户可以执行的操作。Joy UI 按钮组件取代了原生的 HTML <button> 元素，并为样式和可访问性提供了扩展选项。

基础

import Button from '@mui/joy/Button';

Joy UI 按钮的行为类似于原生的 HTML <button>，因此它会包裹显示在其表面的文本。

下面的演示展示了按钮可用的三种基本状态：默认、禁用和加载中。

<Button>Button</Button>
<Button disabled>Disabled</Button>
<Button loading>Loading</Button>

<Button>Button</Button>
<Button disabled>Disabled</Button>
<Button loading>Loading</Button>

按 Enter 开始编辑

禁用

使用 disabled 属性来禁用交互和焦点

<Button disabled variant="solid" startDecorator={<Add />}>
  Solid
</Button>
<Button disabled color="neutral" variant="soft" startDecorator={<Add />}>
  Soft
</Button>
<Button disabled color="success" variant="outlined" startDecorator={<Add />}>
  Outlined
</Button>
<Button disabled color="danger" variant="plain" startDecorator={<Add />}>
  Plain
</Button>

<Button disabled variant="solid" startDecorator={<Add />}>
  Solid
</Button>
<Button disabled color="neutral" variant="soft" startDecorator={<Add />}>
  Soft
</Button>
<Button disabled color="success" variant="outlined" startDecorator={<Add />}>
  Outlined
</Button>
<Button disabled color="danger" variant="plain" startDecorator={<Add />}>
  Plain
</Button>

按 Enter 开始编辑

加载中

添加 loading 属性以显示按钮的加载状态。只要按钮处于加载状态，它就会被禁用。有关自定义选项，请参阅加载指示器和加载位置。

<Button loading variant="solid">
  Solid
</Button>
<Button loading variant="soft">
  Soft
</Button>
<Button loading variant="outlined">
  Outlined
</Button>
<Button loading variant="plain">
  Plain
</Button>

<Button loading variant="solid">
  Solid
</Button>
<Button loading variant="soft">
  Soft
</Button>
<Button loading variant="outlined">
  Outlined
</Button>
<Button loading variant="plain">
  Plain
</Button>

按 Enter 开始编辑

自定义

变体

按钮组件支持 Joy UI 的四种全局变体：solid（默认）、soft、outlined 和 plain。

<Button variant="solid">Solid</Button>
<Button variant="soft">Soft</Button>
<Button variant="outlined">Outlined</Button>
<Button variant="plain">Plain</Button>

<Button variant="solid">Solid</Button>
<Button variant="soft">Soft</Button>
<Button variant="outlined">Outlined</Button>
<Button variant="plain">Plain</Button>

按 Enter 开始编辑

尺寸

按钮组件提供三种尺寸：sm、md（默认）和 lg。

<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

按 Enter 开始编辑

颜色

主题中包含的每个调色板都可以通过 color 属性使用。尝试将不同的颜色与不同的变体结合使用。

变体

SolidSoftOutlinedPlain

装饰器

使用 startDecorator 和 endDecorator 属性将操作和图标附加到按钮的任一侧

<Button startDecorator={<Add />}>Add to cart</Button>
<Button endDecorator={<KeyboardArrowRight />} color="success">
  Go to checkout
</Button>

<Button startDecorator={<Add />}>Add to cart</Button>
<Button endDecorator={<KeyboardArrowRight />} color="success">
  Go to checkout
</Button>

按 Enter 开始编辑

加载指示器

默认加载指示器使用圆形进度条组件。使用 loadingIndicator 属性将其替换为自定义指示器，如下所示

<Button loading>Default</Button>
<Button loading loadingIndicator="Loading…">
  Custom
</Button>

<Button loading>Default</Button>
<Button loading loadingIndicator="Loading…">
  Custom
</Button>

按 Enter 开始编辑

加载位置

loadingPosition 属性设置按钮加载指示器的位置。它支持三个值

center（默认）：加载指示器嵌套在 loadingIndicatorCenter 插槽内，并在加载状态下替换按钮的内容。
start：当按钮处于加载状态时，加载指示器替换起始装饰器。
end：当按钮处于加载状态时，加载指示器替换结束装饰器。

<Button loading loadingPosition="start">
  Start
</Button>
<Button loading loadingPosition="end" endDecorator={<SendIcon />}>
  End
</Button>

<Button loading loadingPosition="start">
  Start
</Button>
<Button loading loadingPosition="end" endDecorator={<SendIcon />}>
  End
</Button>

按 Enter 开始编辑

链接按钮

按钮让用户执行操作，但如果该操作是导航到新页面，那么通常锚标签比按钮标签更可取。

如果您需要按钮的样式和链接的功能，那么您可以使用 component 属性将默认的 <button> 替换为 <a>，如下所示

在新标签页中打开

<Button component="a" href="#as-link" startDecorator={<OpenInNew />}>
  Open in new tab
</Button>
<IconButton aria-label="Open in new tab" component="a" href="#as-link">
  <OpenInNew />
</IconButton>

<Button component="a" href="#as-link" startDecorator={<OpenInNew />}>
  Open in new tab
</Button>
<IconButton aria-label="Open in new tab" component="a" href="#as-link">
  <OpenInNew />
</IconButton>

按 Enter 开始编辑

文件上传

要创建文件上传按钮，请使用 component="label" 将按钮转换为标签，然后创建一个视觉上隐藏的 file 类型的 input。

上传文件

图标按钮

import IconButton from '@mui/joy/IconButton';

使用图标按钮组件创建一个正方形按钮，用于容纳没有文本内容的图标。

禁用

CSS 变量游乐场

试用按钮和图标按钮组件可用的 CSS 变量，看看设计如何变化。您可以使用这些通过 sx 属性和主题自定义组件。

按钮

<Button
  startDecorator={<FavoriteBorder />}
>

CSS 变量

--Button-gap

图标按钮

<IconButton
>
  <FavoriteBorder />
</IconButton>

CSS 变量

--IconButton-size

无障碍

所有按钮都必须具有有意义的 aria-label，以便需要辅助技术的用户可以理解其用途。

对于图标按钮来说，这一点尤其重要，因为它们不包含任何文本。例如，显示 <FavoriteBorder /> 图标的图标按钮可能具有如下标签

<IconButton aria-label="Add to favorites">
  <FavoriteBorder />
</IconButton>

解剖结构

按钮组件由单个根 <button> 元素组成，该元素包裹其内容

<button class="MuiButton-root" type="button">
  <!-- Button contents -->
</button>

API

请参阅下面的文档，以获取此处提及的组件的所有可用属性和类的完整参考。