Textarea

Textarea 元件為您提供一個 textarea HTML 元素，該元素會自動調整其高度以符合內容的長度。

簡介

Joy UI 的 textarea 元件建立在 MUI Base TextareaAutoSize 元件之上。

元件

在安裝之後，您可以使用以下基本元素開始建構此元件

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

export default function MyApp() {
  return <Textarea placeholder="Type anything…" />;
}

變體

textarea 元件支援四種全域變體：solid（預設）、soft、outlined 和 plain。

<Textarea name="Solid" placeholder="Type in here…" variant="solid" />
<Textarea name="Soft" placeholder="Type in here…" variant="soft" />
<Textarea name="Outlined" placeholder="Type in here…" variant="outlined" />
<Textarea name="Plain" placeholder="Type in here…" variant="plain" />

<Textarea name="Solid" placeholder="Type in here…" variant="solid" />
<Textarea name="Soft" placeholder="Type in here…" variant="soft" />
<Textarea name="Outlined" placeholder="Type in here…" variant="outlined" />
<Textarea name="Plain" placeholder="Type in here…" variant="plain" />

按下 Enter 開始編輯

尺寸

textarea 元件預設提供三種尺寸：sm、md（預設）和 lg。

<Textarea size="sm" name="Size" placeholder="Small" />
<Textarea size="md" name="Size" placeholder="Medium" />
<Textarea size="lg" name="Size" placeholder="Large" />

<Textarea size="sm" name="Size" placeholder="Small" />
<Textarea size="md" name="Size" placeholder="Medium" />
<Textarea size="lg" name="Size" placeholder="Large" />

按下 Enter 開始編輯

顏色

使用 color 屬性切換用於為文字欄位著色的調色盤。

表單屬性

支援標準表單屬性，例如 required、disabled 等。

<form
  onSubmit={(event) => {
    event.preventDefault();
  }}
>
  <Textarea
    placeholder="Try to submit with no text!"
    required
    sx={{ mb: 1 }}
  />
  <Textarea placeholder="It is disabled" disabled sx={{ mb: 1 }} />
  <Button type="submit">Submit</Button>
</form>

<form
  onSubmit={(event) => {
    event.preventDefault();
  }}
>
  <Textarea
    placeholder="Try to submit with no text!"
    required
    sx={{ mb: 1 }}
  />
  <Textarea placeholder="It is disabled" disabled sx={{ mb: 1 }} />
  <Button type="submit">Submit</Button>
</form>

按下 Enter 開始編輯

聚焦環

提供這些 CSS 變數給 sx 屬性以控制聚焦環的外觀

--Textarea-focusedInset：聚焦環的位置，在 Textarea 的內部 (inset) 或外部 (var(--any, ))。
--Textarea-focusedThickness：聚焦環的大小。
--Textarea-focusedHighlight：聚焦環的顏色。

<Textarea
  placeholder="Bootstrap"
  minRows={2}
  sx={{
    '--Textarea-focusedInset': 'var(--any, )',
    '--Textarea-focusedThickness': '0.25rem',
    '--Textarea-focusedHighlight': 'rgba(13,110,253,.25)',
    '&::before': {
      transition: 'box-shadow .15s ease-in-out',
    },
    '&:focus-within': {
      borderColor: '#86b7fe',
    },
  }}
/>

<Textarea
  placeholder="Bootstrap"
  minRows={2}
  sx={{
    '--Textarea-focusedInset': 'var(--any, )',
    '--Textarea-focusedThickness': '0.25rem',
    '--Textarea-focusedHighlight': 'rgba(13,110,253,.25)',
    '&::before': {
      transition: 'box-shadow .15s ease-in-out',
    },
    '&:focus-within': {
      borderColor: '#86b7fe',
    },
  }}
/>

按下 Enter 開始編輯

若要完全控制聚焦環，請直接自訂 ::before 虛擬元素的 box-shadow

<Textarea sx={{ '&:focus-within::before': { boxShadow: '...your custom value' } }} />

偵錯聚焦環

若要透過模擬使用者焦點來顯示 Textarea 的聚焦環，請檢查 Textarea 元素並切換虛擬狀態面板。

如果您檢查 Textarea 的根元素，帶有 .MuiTextarea-root 類別，則必須開啟 :focus-within 狀態。
如果您檢查 <input> 元素，則必須開啟 :focus 狀態。

觸發聚焦環

若要以程式設計方式觸發聚焦環，請設定 CSS 變數 --Textarea-focused: 1。

<Textarea
  placeholder="Looks like I'm focused but no"
  sx={{ '--Textarea-focused': 1 }}
/>

<Textarea
  placeholder="Looks like I'm focused but no"
  sx={{ '--Textarea-focused': 1 }}
/>

按下 Enter 開始編輯

驗證

若要切換錯誤狀態，請使用 error 屬性。

<Textarea
  placeholder="Type in here…"
  error
  defaultValue="Oh no! Something is definitely wrong."
/>

<Textarea
  placeholder="Type in here…"
  error
  defaultValue="Oh no! Something is definitely wrong."
/>

按下 Enter 開始編輯

請注意，使用 color 屬性並將 danger 作為值會得到相同的結果

<Textarea color="danger" />

行數

使用 minRows 設定要顯示的最小行數，並使用 maxRows 限制使用者將看到的行數。

<Textarea
  placeholder="Type in here…"
  defaultValue="Try to put text longer than 4 lines."
  minRows={2}
  maxRows={4}
/>

<Textarea
  placeholder="Type in here…"
  defaultValue="Try to put text longer than 4 lines."
  minRows={2}
  maxRows={4}
/>

按下 Enter 開始編輯

裝飾器

使用 startDecorator 和/或 endDecorator 屬性將支援圖示或元素新增至 textarea。在 textarea 元件的頂部和底部使用裝飾器通常更常見。

0字元

HTML textarea ref

使用 slotProps.textarea 屬性將 props 傳遞到 ref 和其他支援的 HTML 屬性到 textarea 元素。

<Textarea
  placeholder="Placeholder"
  slotProps={{ textarea: { ref: textareaRef } }}
/>
<Button onClick={handleTextareaFocus}>Focus textarea element</Button>

<Textarea
  placeholder="Placeholder"
  slotProps={{ textarea: { ref: textareaRef } }}
/>
<Button onClick={handleTextareaFocus}>Focus textarea element</Button>

按下 Enter 開始編輯

無障礙功能

為了使 textarea 具有無障礙功能，它應該連結到標籤。

FormControl 自動產生一個唯一的 id，將 textarea 與 FormLabel 元件連結起來

標籤

這是一個輔助文字。

<FormControl>
  <FormLabel>Label</FormLabel>
  <Textarea placeholder="Placeholder" minRows={2} />
  <FormHelperText>This is a helper text.</FormHelperText>
</FormControl>

<FormControl>
  <FormLabel>Label</FormLabel>
  <Textarea placeholder="Placeholder" minRows={2} />
  <FormHelperText>This is a helper text.</FormHelperText>
</FormControl>

按下 Enter 開始編輯

或者，您可以透過鎖定 textarea slot 手動執行此操作

<label htmlFor="unique-id">Label</label>
<Textarea
  slotProps={{
    textarea: {
      id: 'unique-id',
    }
  }}
/>

常見範例

聚焦外框

此範例示範如何使用 CSS 外框取代預設的聚焦環外觀。

<Textarea
  placeholder="Type in here…"
  minRows={2}
  sx={{
    '&::before': {
      display: 'none',
    },
    '&:focus-within': {
      outline: '2px solid var(--Textarea-focusedHighlight)',
      outlineOffset: '2px',
    },
  }}
/>

<Textarea
  placeholder="Type in here…"
  minRows={2}
  sx={{
    '&::before': {
      display: 'none',
    },
    '&:focus-within': {
      outline: '2px solid var(--Textarea-focusedHighlight)',
      outlineOffset: '2px',
    },
  }}
/>

按下 Enter 開始編輯

浮動標籤

若要建立浮動標籤 textarea，需要自訂元件（<textarea> 和 <label> 的組合）來取代預設的 textarea slot。

標籤

<Textarea
  slots={{ textarea: InnerTextarea }}
  slotProps={{ textarea: { placeholder: 'A placeholder' } }}
  sx={{ borderRadius: '6px' }}
/>

<Textarea
  slots={{ textarea: InnerTextarea }}
  slotProps={{ textarea: { placeholder: 'A placeholder' } }}
  sx={{ borderRadius: '6px' }}
/>

按下 Enter 開始編輯

底線輸入框

留言框

您的留言

API

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

<Textarea />

Textarea

Playground

偵錯聚焦環