按鈕

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

簡介

按鈕傳達使用者可以執行的動作。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 的視覺隱藏輸入。

上傳檔案

圖示按鈕

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

請參閱以下文件，以取得此處提及之元件的所有屬性和類別的完整參考。