scoped
textareaコンポーネントは、複数行のテキスト入力に使用されます。ネイティブの textarea 要素は、コンポーネントの内部でレンダリングされます。ネイティブのtextareaを制御することで、textareaコンポーネントのユーザーエクスペリエンスとインタラクティブ性を向上させることができます。
ネイティブのtextarea要素とは異なり、Ionicのtextareaは要素内部のコンテンツからその値を読み込むことをサポートしていません。textareaの値はvalue
属性で設定しなくてはなりません。
textareaコンポーネントはIonicのプロパティに加えて ネイティブのtextareaの属性 に対応します。
Labels should be used to describe the textarea. They can be used visually, and they will also be read out by screen readers when the user is focused on the textarea. This makes it easy for the user to understand the intent of the textarea. Textarea has several ways to assign a label:
label
property: used for plaintext labels
label
slot: used for custom HTML labels (experimental)
aria-label
: used to provide a label for screen readers but adds no visible label
ラベルは、デフォルトでそのコンテンツの幅を占めます。 開発者は labelPlacement
プロパティを使用して、ラベルがどのように配置されるかを制御することができます。
プレーンテキストのラベルは label
プロパティを通して渡されるべきですが、カスタム HTML が必要な場合は、代わりに label
スロットを通して渡すことができます。
この機能は、Web Component slotsのシミュレート版に依存しているため、実験的なものとみなされていることに注意してください。その結果、シミュレートされた動作はネイティブのスロットの動作と完全に一致するとは限りません。
ラベルの表示が必要ない場合でも、開発者はaria-label
を指定して、textareaがスクリーンリーダーにアクセスできるようにすべきです。
Filled Textareas
Material Designでは、テキストエリアの塗りつぶしスタイルが用意されています。アイテムの fill
プロパティは "solid"
または "outline"
のいずれかに設定することができます。
fill
スタイルはテキストエリアのコンテナを視覚的に定義するため、fill
を使用するテキストエリアは ion-item
で使用すべきではありません。
Filled textareas can be used on iOS by setting Textarea's mode
to md
.
Helper & Error Text
ヘルパーテキストとエラーテキストは、helperText
と errorText
プロパティを使って textarea 内で使用することができます。エラーテキストは、ion-invalid
と ion-touched
クラスが ion-textarea
に追加されていない限り表示されません。これにより、ユーザがデータを入力する前にエラーが表示されることはありません。
Angularでは、これはフォームバリデーションによって自動的に行われます。JavaScript、React、Vueでは、独自のバリデーションに基づいてクラスを手動で追加する必要があります。
Textarea Counter
textareaカウンターは、textareaの下に表示されるテキストで、textareaが受け付ける合計文字数のうち、何文字が入力されたかをユーザーに通知します。カウンターを追加する場合、デフォルトの動作は、表示される値を inputLength
/ maxLength
としてフォーマットすることです。この動作は、counterFormatter
プロパティにフォーマッタ関数を渡すことでカスタマイズすることができます。
autoGrow
プロパティがtrue
に設定されている場合、テキストエリアはその内容に基づいて拡大・縮小します。
clearOnEdit
プロパティをtrue
に設定すると、テキストエリアが編集削除された後、再度入力されるとクリアされます。
The start
and end
slots can be used to place icons, buttons, or prefix/suffix text on either side of the textarea.
Note that this feature is considered experimental because it relies on a simulated version of Web Component slots. As a result, the simulated behavior may not exactly match the native slot behavior.
In most cases, Icon components placed in these slots should have aria-hidden="true"
. See the Icon accessibility docs for more information.
If slot content is meant to be interacted with, it should be wrapped in an interactive element such as a Button. This ensures that the content can be tabbed to.
レガシーtextarea構文からの移行
Ionic 7.0では、よりシンプルなtextareaの構文が導入されました。この新しい構文は、textareaを設定するために必要な定型文を減らし、アクセシビリティの問題を解決し、開発者の体験を向上させます。
開発者はこの移行を一度に1つのtextareaで行うことができます。開発者は従来の構文を使い続けることができますが、できるだけ早く移行することをお勧めします。
最新の構文を使うには、3つのステップがあります。
ion-label
を削除して、代わりに ion-textarea
の label
プロパティを使用します。ラベルの配置は ion-textarea
の labelPlacement
プロパティを使用して設定することができる。
- テキストエリア固有のプロパティを
ion-item
から ion-textarea
に移動します。これには、counter
、counterFormatter
、fill
、shape
プロパティが含まれます。
ion-item
の helper
と error
スロットの使用を削除し、代わりに ion-textarea
の helperText
と errorText
プロパティを使用します。
- JavaScript
- Angular
- React
- Vue
<ion-item>
<ion-label position="floating">Label:</ion-label>
<ion-textarea></ion-textarea>
</ion-item>
<ion-item>
<ion-textarea label="Label:" label-placement="floating"></ion-textarea>
</ion-item>
<ion-item fill="outline" shape="round">
<ion-label position="floating">Label:</ion-label>
<ion-textarea></ion-textarea>
</ion-item>
<ion-textarea fill="outline" shape="round" label="Label:" label-placement="floating"></ion-textarea>
<ion-item counter="true">
<ion-label position="floating">Label:</ion-label>
<ion-textarea maxlength="100"></ion-textarea>
<div slot="helper">Enter text</div>
<div slot="error">Please enter text</div>
</ion-item>
<ion-textarea
label="Label:"
counter="true"
maxlength="100"
helper-text="Enter text"
error-text="Please enter text"
></ion-textarea>
<ion-item>
<ion-label position="floating">Label:</ion-label>
<ion-textarea></ion-textarea>
</ion-item>
<ion-item>
<ion-textarea label="Label:" labelPlacement="floating"></ion-textarea>
</ion-item>
<ion-item fill="outline" shape="round">
<ion-label position="floating">Label:</ion-label>
<ion-textarea></ion-textarea>
</ion-item>
<ion-textarea fill="outline" shape="round" label="Label:" labelPlacement="floating"></ion-textarea>
<ion-item [counter]="true">
<ion-label position="floating">Label:</ion-label>
<ion-textarea maxlength="100"></ion-textarea>
<div slot="helper">Enter text</div>
<div slot="error">Please enter text</div>
</ion-item>
<ion-textarea
label="Label:"
[counter]="true"
maxlength="100"
helperText="Enter text"
errorText="Please enter text"
></ion-textarea>
{}
{}
<IonItem>
<IonLabel position="floating">Label:</IonLabel>
<IonTextarea></IonTextarea>
</IonItem>
{}
<IonItem>
<IonTextarea label="Label:" labelPlacement="floating"></IonTextarea>
</IonItem>
{}
{}
<IonItem fill="outline" shape="round">
<IonLabel position="floating">Label:</IonLabel>
<IonTextarea></IonTextarea>
</IonItem>
{}
{}
<IonTextarea fill="outline" shape="round" label="Label:" labelPlacement="floating"></IonTextarea>
{}
{}
<IonItem counter={true}>
<IonLabel position="floating">Label:</IonLabel>
<IonTextarea maxlength="100"></IonTextarea>
<div slot="helper">Enter text</div>
<div slot="error">Please enter text</div>
</IonItem>
{}
{
}
<IonTextarea
label="Label:"
counter={true}
maxlength="100"
helperText="Enter text"
errorText="Please enter text"
></IonTextarea>
<ion-item>
<ion-label position="floating">Label:</ion-label>
<ion-textarea></ion-textarea>
</ion-item>
<ion-item>
<ion-textarea label="Label:" label-placement="floating"></ion-textarea>
</ion-item>
<ion-item fill="outline" shape="round">
<ion-label position="floating">Label:</ion-label>
<ion-textarea></ion-textarea>
</ion-item>
<ion-textarea fill="outline" shape="round" label="Label:" label-placement="floating"></ion-textarea>
<ion-item :counter="true">
<ion-label position="floating">Label:</ion-label>
<ion-textarea maxlength="100"></ion-textarea>
<div slot="helper">Enter text</div>
<div slot="error">Please enter text</div>
</ion-item>
<ion-textarea
label="Label:"
:counter="true"
maxlength="100"
helper-text="Enter text"
error-text="Please enter text"
></ion-textarea>
Ionicは、アプリが最新のtextarea構文を使用しているかどうかをヒューリスティックで検出します。場合によっては、レガシーな構文を使い続けることが望ましいこともあります。開発者は、ion-textarea
のlegacy
プロパティをtrue
に設定することで、そのインスタンスのtextareaがレガシー構文を使用するように強制できます。
TextareaChangeEventDetail
interface TextareaChangeEventDetail {
value?: string | null;
}
TextareaCustomEvent
必須ではありませんが、このコンポーネントから発行される Ionic イベントでより強く型付けを行うために、CustomEvent
インターフェースの代わりにこのインターフェースを使用することが可能です。
interface TextareaCustomEvent extends CustomEvent {
detail: TextareaChangeEventDetail;
target: HTMLIonTextareaElement;
}
Description | If true , the textarea container will grow and shrink based on the contents of the textarea. |
Attribute | auto-grow |
Type | boolean |
Default | false |
Description | Indicates whether and how the text value should be automatically capitalized as it is entered/edited by the user. Available options: "off" , "none" , "on" , "sentences" , "words" , "characters" . |
Attribute | autocapitalize |
Type | string |
Default | 'none' |
Description | Sets the autofocus attribute on the native input element.
This may not be sufficient for the element to be focused on page load. See managing focus for more information. |
Attribute | autofocus |
Type | boolean |
Default | false |
Description | If true , the value will be cleared after focus upon edit. |
Attribute | clear-on-edit |
Type | boolean |
Default | false |
Description | The color to use from your application's color palette. Default options are: "primary" , "secondary" , "tertiary" , "success" , "warning" , "danger" , "light" , "medium" , and "dark" . For more information on colors, see theming. |
Attribute | color |
Type | "danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string | undefined |
Default | undefined |
Description | The visible width of the text control, in average character widths. If it is specified, it must be a positive integer. |
Attribute | cols |
Type | number | undefined |
Default | undefined |
Description | If true , a character counter will display the ratio of characters used and the total character limit. Developers must also set the maxlength property for the counter to be calculated correctly. |
Attribute | counter |
Type | boolean |
Default | false |
Description | Set the amount of time, in milliseconds, to wait to trigger the ionInput event after each keystroke. |
Attribute | debounce |
Type | number | undefined |
Default | undefined |
Description | If true , the user cannot interact with the textarea. |
Attribute | disabled |
Type | boolean |
Default | false |
Description | A hint to the browser for which enter key to display. Possible values: "enter" , "done" , "go" , "next" , "previous" , "search" , and "send" . |
Attribute | enterkeyhint |
Type | "done" | "enter" | "go" | "next" | "previous" | "search" | "send" | undefined |
Default | undefined |
errorText
Description | Text that is placed under the textarea and displayed when an error is detected. |
Attribute | error-text |
Type | string | undefined |
Default | undefined |
Description | The fill for the item. If "solid" the item will have a background. If "outline" the item will be transparent with a border. Only available in md mode. |
Attribute | fill |
Type | "outline" | "solid" | undefined |
Default | undefined |
helperText
Description | Text that is placed under the textarea and displayed when no error is detected. |
Attribute | helper-text |
Type | string | undefined |
Default | undefined |
Description | A hint to the browser for which keyboard to display. Possible values: "none" , "text" , "tel" , "url" , "email" , "numeric" , "decimal" , and "search" . |
Attribute | inputmode |
Type | "decimal" | "email" | "none" | "numeric" | "search" | "tel" | "text" | "url" | undefined |
Default | undefined |
Description | The visible label associated with the textarea.
Use this if you need to render a plaintext label.
The label property will take priority over the label slot if both are used. |
Attribute | label |
Type | string | undefined |
Default | undefined |
Description | Where to place the label relative to the textarea. "start" : The label will appear to the left of the textarea in LTR and to the right in RTL. "end" : The label will appear to the right of the textarea in LTR and to the left in RTL. "floating" : The label will appear smaller and above the textarea when the textarea is focused or it has a value. Otherwise it will appear on top of the textarea. "stacked" : The label will appear smaller and above the textarea regardless even when the textarea is blurred or has no value. "fixed" : The label has the same behavior as "start" except it also has a fixed width. Long text will be truncated with ellipses ("..."). |
Attribute | label-placement |
Type | "end" | "fixed" | "floating" | "stacked" | "start" |
Default | 'start' |
Description | This attribute specifies the maximum number of characters that the user can enter. |
Attribute | maxlength |
Type | number | undefined |
Default | undefined |
Description | This attribute specifies the minimum number of characters that the user can enter. |
Attribute | minlength |
Type | number | undefined |
Default | undefined |
Description | The mode determines which platform styles to use. |
Attribute | mode |
Type | "ios" | "md" |
Default | undefined |
Description | The name of the control, which is submitted with the form data. |
Attribute | name |
Type | string |
Default | this.inputId |
Description | Instructional text that shows before the input has a value. |
Attribute | placeholder |
Type | string | undefined |
Default | undefined |
Description | If true , the user cannot modify the value. |
Attribute | readonly |
Type | boolean |
Default | false |
Description | If true , the user must fill in a value before submitting a form. |
Attribute | required |
Type | boolean |
Default | false |
Description | The number of visible text lines for the control. |
Attribute | rows |
Type | number | undefined |
Default | undefined |
Description | The shape of the textarea. If "round" it will have an increased border radius. |
Attribute | shape |
Type | "round" | undefined |
Default | undefined |
Description | If true , the element will have its spelling and grammar checked. |
Attribute | spellcheck |
Type | boolean |
Default | false |
Description | The value of the textarea. |
Attribute | value |
Type | null | string | undefined |
Default | '' |
Description | Indicates how the control wraps text. |
Attribute | wrap |
Type | "hard" | "off" | "soft" | undefined |
Default | undefined |
Name | Description | Bubbles |
---|
ionBlur | Emitted when the input loses focus. | true |
ionChange | The ionChange event is fired when the user modifies the textarea's value. Unlike the ionInput event, the ionChange event is fired when the element loses focus after its value has been modified.
This event will not emit when programmatically setting the value property. | true |
ionFocus | Emitted when the input has focus. | true |
ionInput | The ionInput event is fired each time the user modifies the textarea's value. Unlike the ionChange event, the ionInput event is fired for each alteration to the textarea's value. This typically happens for each keystroke as the user types.
When clearOnEdit is enabled, the ionInput event will be fired when the user clears the textarea by performing a keydown event. | true |
Description | Returns the native <textarea> element used under the hood. |
Signature | getInputElement() => Promise<HTMLTextAreaElement> |
Description | Sets focus on the native textarea in ion-textarea . Use this method instead of the global textarea.focus() .
See managing focus for more information. |
Signature | setFocus() => Promise<void> |
No CSS shadow parts available for this component.
Name | Description |
---|
--background | Background of the textarea |
--border-color | Color of the border below the textarea when using helper text, error text, or counter |
--border-radius | Border radius of the textarea |
--border-style | Style of the border below the textarea when using helper text, error text, or counter |
--border-width | Width of the border below the textarea when using helper text, error text, or counter |
--color | Color of the text |
--highlight-color-focused | The color of the highlight on the textarea when focused |
--highlight-color-invalid | The color of the highlight on the textarea when invalid |
--highlight-color-valid | The color of the highlight on the textarea when valid |
--highlight-height | The height of the highlight on the textarea. Only applies to md mode. |
--padding-bottom | Bottom padding of the textarea |
--padding-end | Right padding if direction is left-to-right, and left padding if direction is right-to-left of the textarea |
--padding-start | Left padding if direction is left-to-right, and right padding if direction is right-to-left of the textarea |
--padding-top | Top padding of the textarea |
--placeholder-color | Color of the placeholder text |
--placeholder-font-style | Style of the placeholder text |
--placeholder-font-weight | Weight of the placeholder text |
--placeholder-opacity | Opacity of the placeholder text |
Name | Description |
---|
--background | Background of the textarea |
--border-color | Color of the border below the textarea when using helper text, error text, or counter |
--border-radius | Border radius of the textarea |
--border-style | Style of the border below the textarea when using helper text, error text, or counter |
--border-width | Width of the border below the textarea when using helper text, error text, or counter |
--color | Color of the text |
--highlight-color-focused | The color of the highlight on the textarea when focused |
--highlight-color-invalid | The color of the highlight on the textarea when invalid |
--highlight-color-valid | The color of the highlight on the textarea when valid |
--highlight-height | The height of the highlight on the textarea. Only applies to md mode. |
--padding-bottom | Bottom padding of the textarea |
--padding-end | Right padding if direction is left-to-right, and left padding if direction is right-to-left of the textarea |
--padding-start | Left padding if direction is left-to-right, and right padding if direction is right-to-left of the textarea |
--padding-top | Top padding of the textarea |
--placeholder-color | Color of the placeholder text |
--placeholder-font-style | Style of the placeholder text |
--placeholder-font-weight | Weight of the placeholder text |
--placeholder-opacity | Opacity of the placeholder text |
Name | Description |
---|
end | Content to display at the trailing edge of the textarea. (EXPERIMENTAL) |
label | The label text to associate with the textarea. Use the labelPlacement property to control where the label is placed relative to the textarea. Use this if you need to render a label with custom HTML. (EXPERIMENTAL) |
start | Content to display at the leading edge of the textarea. (EXPERIMENTAL) |