按鈕

按鈕讓使用者透過單次點擊執行動作和做出選擇。

簡介

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 中使用的自訂元件類型指定為非樣式元件的泛型參數。這樣一來，您就可以安全地直接在元件上提供自訂根的屬性

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

相同的原則適用於自訂原始元素特定的屬性

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

Hook

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

useButton Hook 可讓您將 Button 的功能應用於完全自訂的元件。它會傳回要放置在自訂元件上的屬性，以及代表元件內部狀態的欄位。

Hook *不* 支援插槽屬性，但它們支援自訂屬性。

以下示範展示了如何建構與上方元件章節中相同的按鈕，但使用 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.dev.org.tw/">Standard link</Button>
      <Button href="https://mui.dev.org.tw/" 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.dev.org.tw/">Standard link</Button>
      <Button href="https://mui.dev.org.tw/" 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 開始編輯