按钮

按钮允许用户通过单击进行操作和选择。

简介

Button 组件替换了原生的 HTML <button> 元素，并为样式和可访问性提供了扩展选项。

组件

import { Button } from '@mui/base/Button';

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

以下演示展示了如何创建和样式化两个基本按钮。请注意，由于 disabled 属性，第二个按钮无法点击

<Button>Button</Button>
<Button disabled>Disabled</Button>

<Button>Button</Button>
<Button disabled>Disabled</Button>

按 Enter 开始编辑

解剖结构

Button 组件由一个根 <button> 插槽组成，没有内部插槽

<button class="base-Button-root">
  <!-- button text goes here -->
</button>

自定义结构

使用 slots.root 属性来使用自定义元素覆盖根插槽

<Button slots={{ root: 'div' }} />

如果您提供非交互元素（例如 <span>），Button 组件将自动添加必要的辅助功能属性。

将此演示中的 <span> 上的属性与前一个演示中的 Button 进行比较——尝试使用浏览器的开发者工具检查它们

按钮禁用

<Button slots={{ root: 'span' }}>Button</Button>
<Button slots={{ root: 'span' }} disabled>
  Disabled
</Button>

<Button slots={{ root: 'span' }}>Button</Button>
<Button slots={{ root: 'span' }} disabled>
  Disabled
</Button>

按 Enter 开始编辑

与 TypeScript 一起使用

在 TypeScript 中，您可以将 slots.root 中使用的自定义组件类型指定为非样式化组件的泛型参数。这样，您可以安全地直接在组件上提供自定义根的 props

<Button<typeof CustomComponent> slots={{ root: CustomComponent }} customProp />

相同的道理也适用于特定于自定义原始元素的 props

<Button<'img'> slots={{ root: 'img' }} src="button.png" />

Hook

import { useButton } from '@mui/base/useButton';

useButton hook 允许您将 Button 的功能应用于完全自定义的组件。它返回要放置在自定义组件上的 props，以及表示组件内部状态的字段。

Hook 不支持 插槽 props，但它们支持自定义 props。

以下演示展示了如何构建与上面的组件部分中相同的按钮，但使用 useButton hook

import * as React from 'react';
import clsx from 'clsx';
import { styled } from '@mui/system';
import Stack from '@mui/material/Stack';
import { useButton } from '@mui/base/useButton';
import { ButtonProps } from '@mui/base/Button';

const CustomButton = React.forwardRef(function CustomButton(
  props: ButtonProps,
  ref: React.ForwardedRef<any>,
) {
  const { children, disabled } = props;
  const { active, focusVisible, getRootProps } = useButton({
    ...props,
    rootRef: ref,
  });

  return (
    <CustomButtonRoot
      {...getRootProps()}
      className={clsx({
        active,
        disabled,
        focusVisible,
      })}
    >
      {children}
    </CustomButtonRoot>
  );
});

export default function UseButton() {
  return (
    <Stack spacing={2} direction="row">
      <CustomButton onClick={() => console.log('click!')}>Button</CustomButton>
      <CustomButton disabled>Disabled</CustomButton>
    </Stack>
  );
}

const blue = {
  200: '#99CCFF',
  300: '#66B2FF',
  400: '#3399FF',
  500: '#007FFF',
  600: '#0072E5',
  700: '#0066CC',
};

const grey = {
  50: '#F3F6F9',
  100: '#E5EAF2',
  200: '#DAE2ED',
  300: '#C7D0DD',
  400: '#B0B8C4',
  500: '#9DA8B7',
  600: '#6B7A90',
  700: '#434D5B',
  800: '#303740',
  900: '#1C2025',
};

const CustomButtonRoot = styled('button')(
  ({ theme }) => `
  font-family: 'IBM Plex Sans', sans-serif;
  font-weight: 600;
  font-size: 0.875rem;
  line-height: 1.5;
  background-color: ${blue[500]};
  padding: 8px 16px;
  border-radius: 8px;
  color: white;
  transition: all 150ms ease;
  cursor: pointer;
  border: 1px solid ${blue[500]};
  box-shadow: 0 2px 1px ${
    theme.palette.mode === 'dark' ? 'rgba(0, 0, 0, 0.5)' : 'rgba(45, 45, 60, 0.2)'
  }, inset 0 1.5px 1px ${blue[400]}, inset 0 -2px 1px ${blue[600]};

  &:hover {
    background-color: ${blue[600]};
  }

  &.active {
    background-color: ${blue[700]};
    box-shadow: none;
    transform: scale(0.99);
  }

  &.focusVisible {
    box-shadow: 0 0 0 4px ${theme.palette.mode === 'dark' ? blue[300] : blue[200]};
    outline: none;
  }

  &.disabled {
    background-color: ${theme.palette.mode === 'dark' ? grey[700] : grey[200]};
    color: ${theme.palette.mode === 'dark' ? grey[200] : grey[700]};
    border: 0;
    cursor: default;
    box-shadow: none;
    transform: scale(1);
  }
`,
);

import * as React from 'react';
import clsx from 'clsx';
import { styled } from '@mui/system';
import Stack from '@mui/material/Stack';
import { useButton } from '@mui/base/useButton';
import { ButtonProps } from '@mui/base/Button';

const CustomButton = React.forwardRef(function CustomButton(
  props: ButtonProps,
  ref: React.ForwardedRef<any>,
) {
  const { children, disabled } = props;
  const { active, focusVisible, getRootProps } = useButton({
    ...props,
    rootRef: ref,
  });

  return (
    <CustomButtonRoot
      {...getRootProps()}
      className={clsx({
        active,
        disabled,
        focusVisible,
      })}
    >
      {children}
    </CustomButtonRoot>
  );
});

export default function UseButton() {
  return (
    <Stack spacing={2} direction="row">
      <CustomButton onClick={() => console.log('click!')}>Button</CustomButton>
      <CustomButton disabled>Disabled</CustomButton>
    </Stack>
  );
}

const blue = {
  200: '#99CCFF',
  300: '#66B2FF',
  400: '#3399FF',
  500: '#007FFF',
  600: '#0072E5',
  700: '#0066CC',
};

const grey = {
  50: '#F3F6F9',
  100: '#E5EAF2',
  200: '#DAE2ED',
  300: '#C7D0DD',
  400: '#B0B8C4',
  500: '#9DA8B7',
  600: '#6B7A90',
  700: '#434D5B',
  800: '#303740',
  900: '#1C2025',
};

const CustomButtonRoot = styled('button')(
  ({ theme }) => `
  font-family: 'IBM Plex Sans', sans-serif;
  font-weight: 600;
  font-size: 0.875rem;
  line-height: 1.5;
  background-color: ${blue[500]};
  padding: 8px 16px;
  border-radius: 8px;
  color: white;
  transition: all 150ms ease;
  cursor: pointer;
  border: 1px solid ${blue[500]};
  box-shadow: 0 2px 1px ${
    theme.palette.mode === 'dark' ? 'rgba(0, 0, 0, 0.5)' : 'rgba(45, 45, 60, 0.2)'
  }, inset 0 1.5px 1px ${blue[400]}, inset 0 -2px 1px ${blue[600]};

  &:hover {
    background-color: ${blue[600]};
  }

  &.active {
    background-color: ${blue[700]};
    box-shadow: none;
    transform: scale(0.99);
  }

  &.focusVisible {
    box-shadow: 0 0 0 4px ${theme.palette.mode === 'dark' ? blue[300] : blue[200]};
    outline: none;
  }

  &.disabled {
    background-color: ${theme.palette.mode === 'dark' ? grey[700] : grey[200]};
    color: ${theme.palette.mode === 'dark' ? grey[200] : grey[700]};
    border: 0;
    cursor: default;
    box-shadow: none;
    transform: scale(1);
  }
`,
);

按 Enter 开始编辑

如果您使用 ref 来存储对按钮的引用，请将其传递给 useButton 的 ref 参数，如上面的演示所示。它将与 hook 内部使用的 ref 合并。

自定义

自定义元素

Button 接受超出 HTML 元素的各种自定义元素。您甚至可以使用 SVG，如下面的演示所示

与链接一起使用

以下演示说明了如何将 Button 用作链接，无论是使用 MUI Base Button 本身作为 href，还是使用 Next.js Link 组件

标准链接 Next.js 链接

import * as React from 'react';
import { Button as BaseButton, buttonClasses } from '@mui/base/Button';
import { prepareForSlot } from '@mui/base/utils';
import { styled } from '@mui/system';
import Stack from '@mui/material/Stack';
import Link from 'next/link';

const LinkSlot = prepareForSlot(Link);

export default function UnstyledLinkButton() {
  return (
    <Stack spacing={2} direction="row">
      <Button href="https://mui.org.cn/">Standard link</Button>
      <Button href="https://mui.org.cn/" slots={{ root: LinkSlot }}>
        Next.js link
      </Button>
    </Stack>
  );
}

const blue = {
  200: '#99CCFF',
  300: '#66B2FF',
  400: '#3399FF',
  500: '#007FFF',
  600: '#0072E5',
  700: '#0066CC',
};

const grey = {
  50: '#F3F6F9',
  100: '#E5EAF2',
  200: '#DAE2ED',
  300: '#C7D0DD',
  400: '#B0B8C4',
  500: '#9DA8B7',
  600: '#6B7A90',
  700: '#434D5B',
  800: '#303740',
  900: '#1C2025',
};

const Button = styled(BaseButton)(
  ({ theme }) => `
  font-family: 'IBM Plex Sans', sans-serif;
  font-weight: 600;
  font-size: 0.875rem;
  line-height: 1.5;
  text-decoration: none;
  background-color: ${blue[500]};
  padding: 8px 16px;
  border-radius: 8px;
  color: white;
  transition: all 150ms ease;
  cursor: pointer;
  border: 1px solid ${blue[500]};
  box-shadow: 0 2px 1px ${
    theme.palette.mode === 'dark' ? 'rgba(0, 0, 0, 0.5)' : 'rgba(45, 45, 60, 0.2)'
  }, inset 0 1.5px 1px ${blue[400]}, inset 0 -2px 1px ${blue[600]};

  &:hover {
    background-color: ${blue[600]};
  }

  &.${buttonClasses.active} {
    background-color: ${blue[700]};
    box-shadow: none;
    transform: scale(0.99);
  }

  &.${buttonClasses.focusVisible} {
    box-shadow: 0 0 0 4px ${theme.palette.mode === 'dark' ? blue[300] : blue[200]};
    outline: none;
  }

  &.${buttonClasses.disabled} {
    background-color: ${theme.palette.mode === 'dark' ? grey[700] : grey[200]};
    color: ${theme.palette.mode === 'dark' ? grey[200] : grey[700]};
    border: 0;
    cursor: default;
    box-shadow: none;
    transform: scale(1);
  }
  `,
);

import * as React from 'react';
import { Button as BaseButton, buttonClasses } from '@mui/base/Button';
import { prepareForSlot } from '@mui/base/utils';
import { styled } from '@mui/system';
import Stack from '@mui/material/Stack';
import Link from 'next/link';

const LinkSlot = prepareForSlot(Link);

export default function UnstyledLinkButton() {
  return (
    <Stack spacing={2} direction="row">
      <Button href="https://mui.org.cn/">Standard link</Button>
      <Button href="https://mui.org.cn/" slots={{ root: LinkSlot }}>
        Next.js link
      </Button>
    </Stack>
  );
}

const blue = {
  200: '#99CCFF',
  300: '#66B2FF',
  400: '#3399FF',
  500: '#007FFF',
  600: '#0072E5',
  700: '#0066CC',
};

const grey = {
  50: '#F3F6F9',
  100: '#E5EAF2',
  200: '#DAE2ED',
  300: '#C7D0DD',
  400: '#B0B8C4',
  500: '#9DA8B7',
  600: '#6B7A90',
  700: '#434D5B',
  800: '#303740',
  900: '#1C2025',
};

const Button = styled(BaseButton)(
  ({ theme }) => `
  font-family: 'IBM Plex Sans', sans-serif;
  font-weight: 600;
  font-size: 0.875rem;
  line-height: 1.5;
  text-decoration: none;
  background-color: ${blue[500]};
  padding: 8px 16px;
  border-radius: 8px;
  color: white;
  transition: all 150ms ease;
  cursor: pointer;
  border: 1px solid ${blue[500]};
  box-shadow: 0 2px 1px ${
    theme.palette.mode === 'dark' ? 'rgba(0, 0, 0, 0.5)' : 'rgba(45, 45, 60, 0.2)'
  }, inset 0 1.5px 1px ${blue[400]}, inset 0 -2px 1px ${blue[600]};

  &:hover {
    background-color: ${blue[600]};
  }

  &.${buttonClasses.active} {
    background-color: ${blue[700]};
    box-shadow: none;
    transform: scale(0.99);
  }

  &.${buttonClasses.focusVisible} {
    box-shadow: 0 0 0 4px ${theme.palette.mode === 'dark' ? blue[300] : blue[200]};
    outline: none;
  }

  &.${buttonClasses.disabled} {
    background-color: ${theme.palette.mode === 'dark' ? grey[700] : grey[200]};
    color: ${theme.palette.mode === 'dark' ? grey[200] : grey[700]};
    border: 0;
    cursor: default;
    box-shadow: none;
    transform: scale(1);
  }
  `,
);

按 Enter 开始编辑

禁用按钮上的焦点

与原生的 HTML <button> 元素类似，Button 组件在禁用时无法接收焦点。这可能会降低其可访问性，因为屏幕阅读器将无法宣布按钮的存在和状态。

focusableWhenDisabled 属性允许您更改此行为。当设置此属性时，底层 Button 不会设置 disabled 属性。而是使用 aria-disabled，这使得 Button 可聚焦。

每当需要屏幕阅读器读取禁用的 Button 时，都应使用此属性。

MUI Base 在菜单项中内部使用此属性，从而可以使用键盘导航到禁用的项目（符合 ARIA 指南）。

以下演示展示了 focusableWhenDisabled 属性的工作方式——使用 Tab 键在此文档中导航，以查看只有第二个 Button 接受焦点

<Button disabled>{'focusableWhenDisabled = false'}</Button>
<Button disabled focusableWhenDisabled>
  {'focusableWhenDisabled = true'}
</Button>

<Button disabled>{'focusableWhenDisabled = false'}</Button>
<Button disabled focusableWhenDisabled>
  {'focusableWhenDisabled = true'}
</Button>

按 Enter 开始编辑

当根插槽被自定义时，focusableWhenDisabled 属性的工作方式相同，不同之处在于 aria-disabled 属性始终会被使用，无论属性的状态如何。接收焦点的能力由 tabindex 属性在内部控制。

focusableWhenDisabled = falsefocusableWhenDisabled = true

<Button slots={{ root: 'span' }} disabled>
  {'focusableWhenDisabled = false'}
</Button>
<Button slots={{ root: 'span' }} disabled focusableWhenDisabled>
  {'focusableWhenDisabled = true'}
</Button>

<Button slots={{ root: 'span' }} disabled>
  {'focusableWhenDisabled = false'}
</Button>
<Button slots={{ root: 'span' }} disabled focusableWhenDisabled>
  {'focusableWhenDisabled = true'}
</Button>

按 Enter 开始编辑