Selaimen sisäänrakennettu <textarea>-komponentti mahdollistaa monirivisen tekstisyötteen renderöimisen.

<textarea />

Viite

<textarea>

Näyttääksesi tekstikentän, renderöi selaimen sisäänrakennettu <textarea>-komponentti.

<textarea name="postContent" />

Näe lisää esimerkkejä alla.

Propsit

<textarea> tukee kaikkia yleisten elementtien propseja.

Voit tehdä tekstikentästä kontrolloidun välittämällä value propsin:

  • value: Merkkijono. Kontrolloi tekstikentän tekstiä..

Kun välität value-arvon, sinun täytyy myös välittää onChange-käsittelijä, joka päivittää välitetyn arvon.

Jos <textarea> on kontrolloimaton, voit välittää defaultValue-propsin sen sijaan:

  • defaultValue: Merkkijono. Määrittelee oletusarvon tekstikentälle.

Nämä <textarea>-propsit ovat relevantteja sekä kontrolloimattomille että kontrolloiduille tekstikentille:

  • autoComplete: Joko 'on' tai 'off'. Määrittelee automaattisen täydentämisen käyttäytymistä.
  • autoFocus: Totuusarvo. Jos true, React kohdistaa elementtiin mountatessa.
  • children: <textarea> ei hyväksy lapsia. Oletusarvon asettamiseksi, käytä defaultValue.
  • cols: Numero. Määrittää oletusleveyden keskimääräisinä merkkileveyksinä. Oletuksena arvoltaan 20.
  • disabled: Totuusarvo. Jos true, kenttä ei ole interaktiivinen ja näkyy himmennettynä.
  • form: Merkkijono. Määrittää <form> lomakkeen id :n johon tämä kenttä kuuluu. Jos jätetty pois, se on lähin ylätason lomake.
  • maxLength: Numero. Määrittää tekstin enimmäispituuden.
  • minLength: Numero. Määrittää tekstin vähimmäispituuden.
  • name: Merkkijono. Määrittää nimen tälle kentälle, joka lähetetään lomakkeessa.
  • onChange: Event käsittelijäfunktio. Vaaditaan kontrolloituihin tekstikenttiin. Suoritetaan heti kun käyttäjä muuttaa kentän arvoa (esimerkiksi, suoritetaan jokaisella näppäinpainalluksella). Käyttäytyy kuten selaimen input tapahtuma.
  • onChangeCapture: Versio onChange:sta, joka suoritetaan capture phase.
  • onInput: Event käsittelijäfunktio. Suoritetaan heti kun käyttäjä muuttaa kentän arvoa. Historiallisista syistä, Reactissa on idiomaattista käyttää tämän tilalla onChange, joka toimii samanlaisesti.
  • onInputCapture: Versio onInput:sta joka suoritetaan nappausvaiheessa.
  • onInvalid: Event käsittelijäfunktio. Suoritetaan jos syöte ei läpäise validointia lomaketta lähetettäessä. Toisin kuin selaimen sisäänrakennettu invalid-tapahtuma, Reactin onInvalid-tapahtuma kuplii.
  • onInvalidCapture: Versio onInvalid:sta joka suoritetaan nappausvaiheessa.
  • onSelect: Event käsittelijäfunktio. Suoritetaan kun valinta <textarea>:n sisällä muuttuu. React laajentaa onSelect-tapahtuman myös tyhjälle valinnalle ja muokkauksille (jotka voivat vaikuttaa valintaan).
  • onSelectCapture: Versio onSelect:sta joka suoritetaan nappausvaiheessa.
  • placeholder: Merkkijono. Näytetään himmennetyllä värillä kun kenttä on tyhjä.
  • readOnly: Totuusarvo. Jos true, kenttä ei ole käyttäjän muokattavissa.
  • required: Totuusarvo. Jos true, arvon on oltava lomaketta lähettäessä.
  • rows: Numero. Määrittää oletuskorkeuden keskimääräisinä merkkikorkeuksina. Oletuksena arvoltaan 2.
  • wrap: Joko 'hard', 'soft', tai 'off'. Määrittää miten tekstin tulisi rivittyä lomaketta lähettäessä.

Rajoitukset

  • Lapsien välittäminen kuten <textarea>something</textarea> ei ole sallittua. Käytä defaultValue-arvoa alustukselle.
  • Jos kenttä vastaanottaa merkkijonon value-propsissa, se käsitellään kontrolloituna.
  • Kenttä ei voi olla sekä kontrolloitu että kontrolloimaton samaan aikaan.
  • Kenttä ei voi vaihtaa kontrolloidusta kontrolloimattomaksi elinkaarensa aikana.
  • Jokainen kontrolloitu tekstikenttä tarvitsee onChange-käsittelijän, joka päivittää sen arvon synkronisesti.

Käyttö

Tekstikentän näyttäminen

Renderöi <textarea> näyttääksesi tekstikentän. Voit määritellä sen oletuskoon rows ja cols attribuuteilla, mutta oletuksena käyttäjä voi muuttaa sen kokoa. Voit estää muuttamisen, voit määritellä resize: none CSS:ssä.

export default function NewPost() {
  return (
    <label>
      Kirjoita julkaisusi:
      <textarea name="postContent" rows={4} cols={40} />
    </label>
  );
}

Otsikon tarjoaminen tekstikentälle

Tyypillisesti, asetat jokaisen <textarea>-komponentin <label>-komponentin sisään. Tämä kertoo selaimelle, että tämä otsikko on yhdistetty tähän tekstikenttään. Kun käyttäjä klikkaa otsikkoa, selain kohdistaa tekstikenttään. Tämä on myös tärkeää saavutettavuuden kannalta: ruudunlukija lukee otsikon ääneen, kun käyttäjä kohdistaa tekstikenttään.

Jos et voi sijoittaa <textarea>-komponenttia <label>-komponentin sisään, yhdistä ne välittämällä sama ID <textarea id>:lle ja <label htmlFor>:lle. Välttääksesi konflikteja yhden komponentin instanssien välillä, generoi tällainen ID useId-hookilla.

import { useId } from 'react';

export default function Form() {
  const postTextAreaId = useId();
  return (
    <>
      <label htmlFor={postTextAreaId}>
        Write your post:
      </label>
      <textarea
        id={postTextAreaId}
        name="postContent"
        rows={4}
        cols={40}
      />
    </>
  );
}

Oletusarvon tarjoaminen tekstikentälle

Voit vaihtoehtoisesti määritellä oletusarvon tekstikentälle. Välitä se defaultValue-merkkijonona.

export default function EditPost() {
  return (
    <label>
      Muokkaa julkaisuasi:
      <textarea
        name="postContent"
        defaultValue="Tykkäsin pyöräilystä eilen!"
        rows={4}
        cols={40}
      />
    </label>
  );
}

Sudenkuoppa

Toisin kuin HTML:ssä, oletustekstin välittäminen <textarea>Some content</textarea> ei ole tuettu.

Tekstikentän arvon lukeminen lomaketta lähettäessä

Lisää <form> tekstikentän ympärille, jossa on <button type="submit"> sisällä. Se kutsuu <form onSubmit>-käsittelijää. Oletuksena, selain lähettää lomakkeen datan nykyiseen URL:iin ja päivittää sivun. Voit ohittaa tämän käyttäytymisen kutsumalla e.preventDefault(). Lue lomakkeen data new FormData(e.target) avulla.

export default function EditPost() {
  function handleSubmit(e) {
    // Estä selainta lataamasta sivua uudelleen
    e.preventDefault();

    // Lue lomakkeen data
    const form = e.target;
    const formData = new FormData(form);

    // Voit välittää formData:n suoraan fetchin bodylle:
    fetch('/some-api', { method: form.method, body: formData });

    // Tai voit käsitellä sitä tavallisena oliona:
    const formJson = Object.fromEntries(formData.entries());
    console.log(formJson);
  }

  return (
    <form method="post" onSubmit={handleSubmit}>
      <label>
        Julkaisun otsikko: <input name="postTitle" defaultValue="Pyöräily" />
      </label>
      <label>
        Muokkaa julkaisua:
        <textarea
          name="postContent"
          defaultValue="Tykkäsin pyöräilystä eilen!"
          rows={4}
          cols={40}
        />
      </label>
      <hr />
      <button type="reset">Nollaa muokkaukset</button>
      <button type="submit">Tallenna julkaisu</button>
    </form>
  );
}

Huomaa

Anna <textarea>:lle name, esimerkiksi <textarea name="postContent" />. name-arvoa käytetään avaimena lomakkeen datassa, esimerkiksi { postContent: "Julkaisusi" }.

Sudenkuoppa

Oletuksena, mikä tahansa <form>:n sisällä oleva <button> lähettää sen. Tämä voi olla yllättävää! Jos sinulla on oma Button React-komponentti, harkitse <button type="button"> palauttamista <button>:n sijaan. Sitten, ollaksesi eksplisiittinen, käytä <button type="submit"> painikkeisiin, joiden on tarkoitus lähettää lomake.

Tekstikentän ohjaaminen tilamuuttujalla

Tekstikenttä kuten <textarea /> on kontrolloimaton. Vaikka välittäisit oletusarvon kuten <textarea defaultValue="Alkuteksti" />, JSX määrittelee vain oletusarvon, ei arvoa juuri nyt.

Renderöidäksesi kontrolloidun tekstikentän, välitä value-prop sille. React pakottaa tekstikentän aina sisältämään välittämäsi value-arvon. Tyypillisesti, ohjaat tekstikenttää määrittämällä tilamuuttujan:

function NewPost() {
  const [postContent, setPostContent] = useState(''); // Määrittele tilamuuttuja...
  // ...
  return (
    <textarea
      value={postContent} // ...pakota kentän arvo vastaamaan tilamuuttujaa...
      onChange={e => setPostContent(e.target.value)} // ... ja päivitä tilamuuttuja muutoksissa!
    />
  );
}

Tämä on hyödyllistä, jos haluat renderöidä uudelleen osan käyttöliittymästä jokaisella näppäinpainalluksella.

import { useState } from 'react';
import MarkdownPreview from './MarkdownPreview.js';

export default function MarkdownEditor() {
  const [postContent, setPostContent] = useState('_Hei,_ **Markdown**!');
  return (
    <>
      <label>
        Syötä markdown koodia:
        <textarea
          value={postContent}
          onChange={e => setPostContent(e.target.value)}
        />
      </label>
      <hr />
      <MarkdownPreview markdown={postContent} />
    </>
  );
}

Sudenkuoppa

Jos välität value:n ilman onChange:a, tekstikenttään ei voi kirjoittaa. Kun kontrolloit tekstikenttää välittämällä sille value:n, pakotat sen aina sisältämään välittämäsi arvon. Joten jos välität tilamuuttujan value:ksi mutta unohdat päivittää tilamuuttujaa synkronisesti onChange-käsittelijässä, React palauttaa tekstikentän jokaisen näppäinpainalluksen jälkeen takaisin value:ksi, jonka välitit.

Vianmääritys

Tekstikenttäni ei päivity kun kirjoitan siihen

Jos renderöit tekstikentän value:lla mutta ilman onChange:a, näet virheen konsolissa:

// 🔴 Bugi: kontrolloitu tekstikenttä ilman onChange käsittelijää
<textarea value={something} />
Konsoli
You provided a value prop to a form field without an onChange handler. This will render a read-only field. If the field should be mutable use defaultValue. Otherwise, set either onChange or readOnly.

Kuten virheviesti ehdottaa, jos haluat vain määrittää alkuarvon, välitä defaultValue sen sijaan:

// ✅ Hyvä: kontrolloimaton tekstikenttä oletusarvolla
<textarea defaultValue={something} />

If you want to control this text area with a state variable, specify an onChange handler:

Jos haluat ohjata tätä tekstikenttää tilamuuttujalla, määrittele onChange-käsittelijä:

// ✅ Hyvä: kontrolloitu tekstikenttö onChange:lla
<textarea value={something} onChange={e => setSomething(e.target.value)} />

Jos arvo on tarkoituksella vain-luku -tilassa, lisää readOnly-propsi virheen poistamiseksi:

// ✅ Hyvä: vain-luku tilassa oleva kontrolloitu tekstikenttä ilman muutoksenkäsittelijää
<textarea value={something} readOnly={true} />

Tekstikentän kursori hyppää alkuun jokaisen näppäinpainalluksen yhteydessä

Jos kontrolloit tekstikenttää, sinun täytyy päivittää sen tilamuuttuja tekstikentän arvolla DOM:sta onChange:ssa.

Et voi päivittää sitä joksikin muuksi kuin e.target.value:

function handleChange(e) {
  // 🔴 Bugi: kentän päivittäminen joksikin muuksi kuin e.target.value
  setFirstName(e.target.value.toUpperCase());
}

Et voi päivittää sitä asynkronisesti:

function handleChange(e) {
  // 🔴 Bugi: kentän päivittäminen asynkronisesti
  setTimeout(() => {
    setFirstName(e.target.value);
  }, 100);
}

Korjataksesi koodin, päivitä se synkronisesti e.target.value:lla:

function handleChange(e) {
  // ✅ Kontrolloidun kentän päivittäminen e.target.value:lla synkronisesti
  setFirstName(e.target.value);
}

Jos tämä ei korjaa ongelmaa, on mahdollista, että tekstikenttä poistetaan ja lisätään takaisin DOM:iin jokaisen näppäinpainalluksen yhteydessä. Tämä voi tapahtua jos vahingossa nollaat tilan jokaisen uudelleenrenderöinnin yhteydessä. Esimerkiksi, tämä voi tapahtua jos tekstikenttä tai jokin sen vanhemmista saa aina erilaisen key-attribuutin, tai jos upotat komponenttimäärittelyjä (joka ei ole sallittua Reactissa ja aiheuttaa “sisäisen” komponentin uudelleenmounttauksen jokaisella renderöinnillä).

Saan virheen: “A component is changing an uncontrolled input to be controlled”

Jos tarjoat value:n komponentille, sen täytyy pysyä merkkijonona koko elinkaarensa ajan.

Et voi välittää value={undefined} ensin ja myöhemmin välittää value="some string" koska React ei tiedä haluatko komponentin olevan kontrolloimaton vai kontrolloitu. Kontrolloidun komponentin tulisi aina saada merkkijonona value, ei null tai undefined.

Jos value tulee API:sta tai tilamuuttujasta, se voi olla alustettu null tai undefined. Tässä tapauksessa, joko aseta se tyhjäksi merkkijonoksi ('') aluksi, tai välitä value={someValue ?? ''} varmistaaksesi, että value on merkkijono.

Previous<select>NextAPIt

How do you like these docs?