按鈕

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

按鈕傳達使用者可以採取的動作。它們通常放置在 UI 各處，例如：

模組化視窗
表單
卡片
工具列

基本按鈕

Button 元件提供三種變體：文字 (預設)、已包含和已外框。

<Button variant="text">Text</Button>
<Button variant="contained">Contained</Button>
<Button variant="outlined">Outlined</Button>

<Button variant="text">Text</Button>
<Button variant="contained">Contained</Button>
<Button variant="outlined">Outlined</Button>

按下 Enter 鍵開始編輯

文字按鈕

文字按鈕通常用於較不明顯的動作，包括位於：對話框、卡片中。在卡片中，文字按鈕有助於保持對卡片內容的強調。

連結

<Button>Primary</Button>
<Button disabled>Disabled</Button>
<Button href="#text-buttons">Link</Button>

<Button>Primary</Button>
<Button disabled>Disabled</Button>
<Button href="#text-buttons">Link</Button>

按下 Enter 鍵開始編輯

已包含按鈕

已包含按鈕是高強調的按鈕，其特點是使用了 elevation 和填滿。它們包含對您的應用程式至關重要的主要動作。

連結

<Button variant="contained">Contained</Button>
<Button variant="contained" disabled>
  Disabled
</Button>
<Button variant="contained" href="#contained-buttons">
  Link
</Button>

<Button variant="contained">Contained</Button>
<Button variant="contained" disabled>
  Disabled
</Button>
<Button variant="contained" href="#contained-buttons">
  Link
</Button>

按下 Enter 鍵開始編輯

您可以使用 disableElevation 屬性移除 elevation。

<Button variant="contained" disableElevation>
  Disable elevation
</Button>

<Button variant="contained" disableElevation>
  Disable elevation
</Button>

按下 Enter 鍵開始編輯

已外框按鈕

已外框按鈕是中等強調的按鈕。它們包含重要的動作，但不是應用程式中的主要動作。

已外框按鈕也是比已包含按鈕較低強調的替代方案，或是比文字按鈕較高強調的替代方案。

連結

<Button variant="outlined">Primary</Button>
<Button variant="outlined" disabled>
  Disabled
</Button>
<Button variant="outlined" href="#outlined-buttons">
  Link
</Button>

<Button variant="outlined">Primary</Button>
<Button variant="outlined" disabled>
  Disabled
</Button>
<Button variant="outlined" href="#outlined-buttons">
  Link
</Button>

按下 Enter 鍵開始編輯

處理點擊

所有元件都接受 onClick 處理函式，該函式會套用至根 DOM 元素。

<Button
  onClick={() => {
    alert('clicked');
  }}
>
  Click me
</Button>

請注意，文件避免在元件的 API 章節中提及原生屬性 (有很多)。

顏色

<Button color="secondary">Secondary</Button>
<Button variant="contained" color="success">
  Success
</Button>
<Button variant="outlined" color="error">
  Error
</Button>

<Button color="secondary">Secondary</Button>
<Button variant="contained" color="success">
  Success
</Button>
<Button variant="outlined" color="error">
  Error
</Button>

按下 Enter 鍵開始編輯

除了使用預設按鈕顏色外，您還可以新增自訂顏色，或停用任何您不需要的顏色。請參閱新增顏色範例以取得更多資訊。

尺寸

若要使用較大或較小的按鈕，請使用 size 屬性。

具有圖示和標籤的按鈕

有時您可能會想要為某些按鈕新增圖示，以增強應用程式的 UX，因為我們比純文字更容易識別標誌。例如，如果您有一個刪除按鈕，您可以使用垃圾桶圖示標記它。

<Button variant="outlined" startIcon={<DeleteIcon />}>
  Delete
</Button>
<Button variant="contained" endIcon={<SendIcon />}>
  Send
</Button>

<Button variant="outlined" startIcon={<DeleteIcon />}>
  Delete
</Button>
<Button variant="contained" endIcon={<SendIcon />}>
  Send
</Button>

按下 Enter 鍵開始編輯

圖示按鈕

圖示按鈕常見於應用程式列和工具列中。

圖示也適用於切換按鈕，這些按鈕允許選取或取消選取單一選項，例如為項目新增或移除星號。

<IconButton aria-label="delete">
  <DeleteIcon />
</IconButton>
<IconButton aria-label="delete" disabled color="primary">
  <DeleteIcon />
</IconButton>
<IconButton color="secondary" aria-label="add an alarm">
  <AlarmIcon />
</IconButton>
<IconButton color="primary" aria-label="add to shopping cart">
  <AddShoppingCartIcon />
</IconButton>

<IconButton aria-label="delete">
  <DeleteIcon />
</IconButton>
<IconButton aria-label="delete" disabled color="primary">
  <DeleteIcon />
</IconButton>
<IconButton color="secondary" aria-label="add an alarm">
  <AlarmIcon />
</IconButton>
<IconButton color="primary" aria-label="add to shopping cart">
  <AddShoppingCartIcon />
</IconButton>

按下 Enter 鍵開始編輯

尺寸

若要使用較大或較小的圖示按鈕，請使用 size 屬性。

<IconButton aria-label="delete" size="small">
  <DeleteIcon fontSize="inherit" />
</IconButton>
<IconButton aria-label="delete" size="small">
  <DeleteIcon fontSize="small" />
</IconButton>
<IconButton aria-label="delete" size="large">
  <DeleteIcon />
</IconButton>
<IconButton aria-label="delete" size="large">
  <DeleteIcon fontSize="inherit" />
</IconButton>

<IconButton aria-label="delete" size="small">
  <DeleteIcon fontSize="inherit" />
</IconButton>
<IconButton aria-label="delete" size="small">
  <DeleteIcon fontSize="small" />
</IconButton>
<IconButton aria-label="delete" size="large">
  <DeleteIcon />
</IconButton>
<IconButton aria-label="delete" size="large">
  <DeleteIcon fontSize="inherit" />
</IconButton>

按下 Enter 鍵開始編輯

顏色

使用 color 屬性將主題色彩調色盤套用至元件。

<IconButton aria-label="fingerprint" color="secondary">
  <Fingerprint />
</IconButton>
<IconButton aria-label="fingerprint" color="success">
  <Fingerprint />
</IconButton>

<IconButton aria-label="fingerprint" color="secondary">
  <Fingerprint />
</IconButton>
<IconButton aria-label="fingerprint" color="success">
  <Fingerprint />
</IconButton>

按下 Enter 鍵開始編輯

載入中

從 v6.4.0 開始，使用 loading 屬性將圖示按鈕設定為載入狀態並停用互動。

<Tooltip title="Click to see loading">
  <IconButton onClick={() => setLoading(true)} loading={loading}>
    <ShoppingCartIcon />
  </IconButton>
</Tooltip>

<Tooltip title="Click to see loading">
  <IconButton onClick={() => setLoading(true)} loading={loading}>
    <ShoppingCartIcon />
  </IconButton>
</Tooltip>

按下 Enter 鍵開始編輯

徽章

您可以使用 Badge 元件將徽章新增至 IconButton。

<IconButton>
  <ShoppingCartIcon fontSize="small" />
  <CartBadge badgeContent={2} color="primary" overlap="circular" />
</IconButton>

<IconButton>
  <ShoppingCartIcon fontSize="small" />
  <CartBadge badgeContent={2} color="primary" overlap="circular" />
</IconButton>

按下 Enter 鍵開始編輯

檔案上傳

若要建立檔案上傳按鈕，請使用 component="label" 將按鈕轉換為標籤，然後建立一個視覺上隱藏的輸入，類型為 file。

上傳檔案

<Button
  component="label"
  role={undefined}
  variant="contained"
  tabIndex={-1}
  startIcon={<CloudUploadIcon />}
>
  Upload files
  <VisuallyHiddenInput
    type="file"
    onChange={(event) => console.log(event.target.files)}
    multiple
  />
</Button>

<Button
  component="label"
  role={undefined}
  variant="contained"
  tabIndex={-1}
  startIcon={<CloudUploadIcon />}
>
  Upload files
  <VisuallyHiddenInput
    type="file"
    onChange={(event) => console.log(event.target.files)}
    multiple
  />
</Button>

按下 Enter 鍵開始編輯

載入中

從 v6.4.0 開始，使用 loading 屬性將按鈕設定為載入狀態並停用互動。

切換載入開關以查看不同狀態之間的轉換。

載入中

當 loading 屬性設定為 boolean 時，載入包裝器會始終存在於 DOM 中，以防止 Google 翻譯崩潰。

loading 值應始終為 null 或 boolean。不建議使用以下模式，因為它可能會導致 Google 翻譯崩潰

<Button {...(isFetching && { loading: true })}> // ❌ Don't do this

自訂

這裡有一些自訂元件的範例。您可以在覆寫文件頁面中了解更多相關資訊。

🎨 如果您正在尋找靈感，可以查看 MUI Treasury 的自訂範例。

複雜按鈕

文字按鈕、已包含按鈕、浮動操作按鈕和圖示按鈕都建立在相同的元件之上：ButtonBase。您可以利用這個較低層級的元件來建立自訂互動。

第三方路由函式庫

一個常見的使用案例是在僅限於用戶端執行導航，而無需 HTTP 往返伺服器。ButtonBase 元件提供 component 屬性來處理此使用案例。這裡有更詳細的指南。

限制

不允許的游標

ButtonBase 元件在已停用的按鈕上設定 pointer-events: none;，這會阻止顯示已停用的游標。

如果您希望使用 not-allowed，您有兩個選項

僅限 CSS。您可以移除 <button> 元素停用狀態的 pointer-events 樣式。

.MuiButtonBase-root:disabled {
  cursor: not-allowed;
  pointer-events: auto;
}

然而

當您需要在已停用的元素上顯示工具提示時，您應該加回 pointer-events: none;。
如果您呈現的不是按鈕元素，例如連結 <a> 元素，則游標不會變更。

DOM 變更。您可以包裝按鈕

<span style={{ cursor: 'not-allowed' }}>
  <Button component={Link} disabled>
    disabled
  </Button>
</span>

這具有支援任何元素的優勢，例如連結 <a> 元素。

無樣式

使用 Base UI Button 完全掌控元件的設計，無需覆寫 Material UI 或 Joy UI 樣式。此元件的無樣式版本是需要大量自訂且套件大小較小的理想選擇。

API

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