API viite
Komponentit

Yleiset komponentit (esim <div>)

Kaikki selaimeen sisäänrakennetut komponentit, kuten <div>, tukevat joitakin yleisiä propseja ja tapahtumia.

Viite

Yleiset komponentit (kuten <div>) 

<div className="wrapper">Jotain sisältöä</div>

Näe lisää esimerkkejä alla.

Propsit

Nämä Reactin erikoispropsit tuetaan kaikissa sisäänrakennetuissa komponenteissa:

  • children: A React noodi (elementti, merkkijono, numero, portaali, tyhjä noodi kuten null, undefined ja totuusarvot, tai taulukko muista React noodeista). Määrittää komponentin sisällön. Kun käytät JSX:ää, määrität children propsin yleensä epäsuorasti upottamalla tageja kuten <div><span /></div>.

  • dangerouslySetInnerHTML: Olio muodossa { __html: '<p>some html</p>' } jossa on raaka HTML merkkijono sisällä. Ohittaa DOM noodin innerHTML ominaisuuden ja näyttää annetun HTML:n sisällä. Tätä tulisi käyttää erityisellä varovaisuudella! Jos HTML sisällä ei ole luotettavaa (esimerkiksi jos se perustuu käyttäjän dataan), riski XSS haavoittuvuuden tuomisesta. Lue lisää dangerouslySetInnerHTML:n käytöstä.

  • ref: Ref olio useRef:sta tai createRef:sta, tai ref kutsufunktio, tai merkkijono vanhoille refseille. Refisi täytetään tämän DOM noodin elementillä. Lue lisää DOM:n manipuloinnista refien avulla.

  • suppressContentEditableWarning: Totuusarvo. Jos true, estää Reactin näyttämästä varoitusta elementeille joilla on sekä children että contentEditable={true} (jotka eivät normaalisti toimi yhdessä). Käytä tätä jos rakennat tekstisyöttökirjastoa joka hallinnoi contentEditable sisältöä manuaalisesti.

  • suppressHydrationWarning: Totuusarvo. Jos käytät palvelimen renderöintiä, normaalisti varoitetaan jos palvelin ja selain renderöivät eri sisältöä. Joissain harvoissa tapauksissa (kuten aikaleimoissa), on hyvin vaikeaa tai mahdotonta taata täsmällistä vastaavuutta. Jos asetat suppressHydrationWarning:n arvoksi true, React ei varoita sinua eroista elementin attribuuteissa ja sisällössä. Se toimii vain yhden tason syvyyteen asti, ja on tarkoitettu käytettäväksi pakotienä. Älä käytä sitä liikaa. Lue lisää hydratointivirheiden estämisestä.

  • style: Olio CSS tyyleistä, esimerkiksi { fontWeight: 'bold', margin: 20 }. Samalla tavalla kuin DOM style ominaisuudessa, CSS ominaisuudet tulee kirjoittaa camelCase muodossa, esimerkiksi fontWeight font-weight:n sijaan. Voit antaa merkkijonoja tai numeroita arvoiksi. Jos annat numeron, kuten width: 100, React lisää automaattisesti px (“pikseliä”) arvon perään ellei kyseessä ole yksikköominaisuus. Suosittelemme käyttämään style:a vain dynaamisissa tyyleissä joissa et tiedä tyylejä etukäteen. Muissa tapauksissa, pelkkien CSS luokkien käyttäminen className:n kanssa on tehokkaampaa. Lue lisää className ja style:sta.

Nämä standardit DOM propsit tuetaan myös kaikissa sisäänrakennetuissa komponenteissa:

Voit myös välittää omia attribuutteja propseina, esimerkiksi mycustomprop="someValue". Tämä voi olla hyödyllistä kun integroit kolmannen osapuolen kirjastojen kanssa. Oma attribuutin nimi tulee olla pienillä kirjaimilla ja ei saa alkaa on:lla. Arvo muutetaan merkkijonoksi. Jos välität null tai undefined, oma attribuutti poistetaan.

Nämä tapahtumat suoritetaan vain <form> elementeille:

Nämä tapahtumat suoritetaan vain <dialog> elementeille. Toisin kuin selaimen tapahtumat, ne kuplivat Reactissa:

Nämä tapahtumat suoritetaan vain <details> elementeille. Toisin kuin selaimen tapahtumat, ne kuplivat Reactissa:

Nämä tapahtumat suoritetaan <img>, <iframe>, <object>, <embed>, <link>, ja SVG <image> elementeille. Toisin kuin selaimen tapahtumat, ne kuplivat Reactissa:

Nämä tapahtumat suoritetaan resursseille kuten <audio> ja <video>. Toisin kuin selaimen tapahtumat, ne kuplivat Reactissa:

Rajoitukset

  • Et voi välittää sekä children että dangerouslySetInnerHTML samaan aikaan.
  • Jotkin tapahtumat (kuten onAbort ja onLoad) eivät kupli selaimessa, mutta kuplivat Reactissa.

ref callback-funktio

Ref olion sijaan (kuten useRef palauttama), voit välittää funktion ref attribuuttiin.

<div ref={(node) => console.log(node)} />

Esimerkki ref callbackin käytöstä.

Kun <div> DOM noodi lisätään näytölle, React kutsuu ref callbackia DOM node argumentilla. Kun <div> DOM noodi poistetaan, React kutsuu ref callbackia null argumentilla.

React kutsuu myös ref callbackia aina kun välität erilaisen ref callbackin. Yllä olevassa esimerkissä, (node) => { ... } on eri funktio joka renderöinnillä. Kun komponenttisi renderöidään uudelleen, edellinen funktio kutsutaan null argumentilla, ja seuraava funktio kutsutaan DOM nodella.

Parametrit

  • node: DOM noodi tai null. React välittää DOM noden kun ref liitetään, ja null kun ref irrotetaan. Ellei välitä samaa funktiota ref callbackiin joka renderöinnillä, callback irrotetaan ja liitetään uudelleen jokaisella komponentin renderöinnillä.

Palautukset

Ei palauta mitään ref callbackista.

React tapahtumaolio

Tapahtumakäsittelijäsi vastaanottaa React tapahtumaolion. Sitä kutsutaan myös joskus “synteettiseksi tapahtumaksi”.

<button onClick={e => {
  console.log(e); // React tapahtumaolio
}} />

Se noudattaa samaa standardia kuin taustalla olevat DOM tapahtumat, mutta korjaa joitain selaimen epäjohdonmukaisuuksia.

Jotkin React tapahtumat eivät mäppäydy suoraan selaimen alkuperäisiin tapahtumiin. Esimerkiksi onMouseLeave, e.nativeEvent osoittaa mouseout tapahtumaan. Tämä mäppäys ei ole osa julkista API:a ja saattaa muuttua tulevaisuudessa. Jos tarvitset taustalla olevan selaimen tapahtuman jostain syystä, lue se e.nativeEvent kautta.

Ominaisuudet

React tapahtumaolio toteuttaa joitain standardin Event ominaisuuksia:

  • bubbles: Totuusarvo. Palauttaa kupliiko tapahtuma DOMin läpi.
  • cancelable: Totuusarvo. Palauttaa voiko tapahtuman peruuttaa.
  • currentTarget: DOM noodi. Palauttaa noodin johon nykyinen käsittelijä on liitetty React puussa.
  • defaultPrevented: Totuusarvo. Palauttaa onko preventDefault kutsuttu.
  • eventPhase: Numero. Palauttaa missä vaiheessa tapahtuma on tällä hetkellä.
  • isTrusted: Totuusarvo. Palauttaa onko tapahtuma käyttäjän aloittama.
  • target: DOM noodi. Palauttaa noodin jossa tapahtuma on tapahtunut (joka voi olla kaukainen lapsi).
  • timeStamp: Numero. Palauttaa ajan jolloin tapahtuma tapahtui.

Lisäksi, React tapahtumaoliot tarjoavat nämä ominaisuudet:

  • nativeEvent: DOM Event. Alkuperäinen selaimen tapahtumaolio.

Metodit

React tapahtumaolio toteuttaa joitain standardin Event metodeista:

Lisäksi, React tapahtumaoliot tarjoavat nämä metodit:

  • isDefaultPrevented(): Palauttaa totuusarvon joka kertoo onko preventDefault kutsuttu.
  • isPropagationStopped(): Palauttaa totuusarvon joka kertoo onko stopPropagation kutsuttu.
  • persist(): Ei käytetä React DOMin kanssa. React Nativella, kutsu tätä lukeaksesi tapahtuman ominaisuudet tapahtuman jälkeen.
  • isPersistent(): Ei käytetä React DOMin kanssa. React Nativella, palauttaa onko persist kutsuttu.

Rajoitukset

  • currentTarget, eventPhase, target, ja type arvot heijastaa arvoja, joita React koodisi olettaa. Taustalla, React liittää tapahtumakäsittelijät juureen, mutta tätä ei heijasteta React tapahtumaolioissa. Esimerkiksi, e.currentTarget ei välttämättä ole sama kuin taustalla oleva e.nativeEvent.currentTarget. Polyfillatuissa tapahtumissa, e.type (React tapahtuman tyyppi) voi erota e.nativeEvent.type (taustalla oleva tyyppi).

AnimationEvent käsittelijäfunktio

Tapahtumakäsittelijätyyppi CSS animaatioiden -tapahtumiin.

<div
  onAnimationStart={e => console.log('onAnimationStart')}
  onAnimationIteration={e => console.log('onAnimationIteration')}
  onAnimationEnd={e => console.log('onAnimationEnd')}
/>

Parametrit

ClipboardEvent käsittelijäfunktio

Tapahtumakäsittelijätyyppi [Clipboard API] tapahtumiin.

<input
  onCopy={e => console.log('onCopy')}
  onCut={e => console.log('onCut')}
  onPaste={e => console.log('onPaste')}
/>

Parametrit

CompositionEvent käsittelijäfunktio

Tapahtumakäsittelijätyyppi syöttömenetelmän editorin (IME) tapahtumiin.

<input
  onCompositionStart={e => console.log('onCompositionStart')}
  onCompositionUpdate={e => console.log('onCompositionUpdate')}
  onCompositionEnd={e => console.log('onCompositionEnd')}
/>

Parametrit

DragEvent käsittelijäfunktio

Tapahtumakäisttelijätyyppi HTML Drag and Drop API tapahtumiin.

<>
  <div
    draggable={true}
    onDragStart={e => console.log('onDragStart')}
    onDragEnd={e => console.log('onDragEnd')}
  >
    Drag lähde
  </div>

  <div
    onDragEnter={e => console.log('onDragEnter')}
    onDragLeave={e => console.log('onDragLeave')}
    onDragOver={e => { e.preventDefault(); console.log('onDragOver'); }}
    onDrop={e => console.log('onDrop')}
  >
    Drop kohde
  </div>
</>

Parametrit

FocusEvent käsittelijäfunktio

Tapahtumakäsittelijätyyppi kohdistumisen tapahtumiin.

<input
  onFocus={e => console.log('onFocus')}
  onBlur={e => console.log('onBlur')}
/>

Katso esimerkki.

Parametrit

Event käsittelijäfunktio

Tapahtumakäsittelijätyyppi yleisiin tapahtumiin.

Parametrit

InputEvent käsittelijäfunktio

Tapahtumakäsittelijätyyppi onBeforeInput tapahtumalle.

<input onBeforeInput={e => console.log('onBeforeInput')} />

Parametrit

KeyboardEvent käsittelijäfunktio

Tapahtumakäsittelijätyyppi näppäimistötapahtumiin.

<input
  onKeyDown={e => console.log('onKeyDown')}
  onKeyUp={e => console.log('onKeyUp')}
/>

Katso esimerkki.

Parametrit

MouseEvent käsittelijäfunktio

Tapahtumakäsittelijätyyppi hiiritapahtumiin.

<div
  onClick={e => console.log('onClick')}
  onMouseEnter={e => console.log('onMouseEnter')}
  onMouseOver={e => console.log('onMouseOver')}
  onMouseDown={e => console.log('onMouseDown')}
  onMouseUp={e => console.log('onMouseUp')}
  onMouseLeave={e => console.log('onMouseLeave')}
/>

Katso esimerkki.

Parametrit

PointerEvent käsittelijäfunktio

Tapahtumakäisttelijätyyppi osoitintapahtumiin.

<div
  onPointerEnter={e => console.log('onPointerEnter')}
  onPointerMove={e => console.log('onPointerMove')}
  onPointerDown={e => console.log('onPointerDown')}
  onPointerUp={e => console.log('onPointerUp')}
  onPointerLeave={e => console.log('onPointerLeave')}
/>

Katso esimerkki.

Parametrit

TouchEvent käsittelijäfunktio

Tapahtumakäsittelijätyyppi kosketustapahtumiin.

<div
  onTouchStart={e => console.log('onTouchStart')}
  onTouchMove={e => console.log('onTouchMove')}
  onTouchEnd={e => console.log('onTouchEnd')}
  onTouchCancel={e => console.log('onTouchCancel')}
/>

Parametrit

TransitionEvent käsittelijäfunktio

Tapahtumakäsittelijätyyppi CSS siirtymätapahtumiin.

<div
  onTransitionEnd={e => console.log('onTransitionEnd')}
/>

Parametrit

UIEvent käsittelijäfunktio

Tapahtumakäsittelijätyyppi yleisiin käyttöliittymätapahtumiin.

<div
  onScroll={e => console.log('onScroll')}
/>

Parametrit

WheelEvent käsittelijäfunktio

Tapahtumakäsittelijätyyppi onWheel tapahtumalle.

<div
  onScroll={e => console.log('onScroll')}
/>

Parametrit

Käyttö

CSS tyylien käyttö

Reactissa, määrität CSS-luokan className:lla. Se toimii kuten class attribuutti HTML:ssä:

<img className="avatar" />

Sitten kirjoitat CSS säännöt sille erillisessä CSS tiedostossa:

/* CSS tiedostossasi */
.avatar {
  border-radius: 50%;
}

React ei määrää miten lisäät CSS tiedostoja. Yksinkertaisimmassa tapauksessa, lisäät <link> tagin HTML:ään. Jos käytät rakennustyökalua tai frameworkkia, tutustu sen dokumentaatioon oppiaksesi miten lisäät CSS tiedoston projektiisi.

Joskus, tyylien arvot riippuvat datasta. Käytä style attribuuttia välittääksesi joitain tyylejä dynaamisesti:

<img
  className="avatar"
  style={{
    width: user.imageSize,
    height: user.imageSize
  }}
/>

Ylläolevassa esimerkissä, style={{}} ei ole erikoissyntaksi, vaan tavallinen {} objekti style={ } JSX aaltosulkeiden sisällä. Suosittelemme käyttämään style attribuuttia vain silloin kun tyylit riippuvat JavaScript muuttujista.

export default function Avatar({ user }) {
  return (
    <img
      src={user.imageUrl}
      alt={'Photo of ' + user.name}
      className="avatar"
      style={{
        width: user.imageSize,
        height: user.imageSize
      }}
    />
  );
}
Syväsukellus

Miten käyttää useita CSS-luokkia ehdollisesti?

Määrittääksesi CSS luokkia ehdollisesti, sinun täytyy tuottaa className merkkijono itse käyttäen JavaScriptiä.

Esimerkiksi, className={'row ' + (isSelected ? 'selected': '')} tuottaa joko className="row" tai className="row selected" riippuen siitä onko isSelected true.

Tehdäksesi tästä luettavamman, voit käyttää pientä apukirjastoa kuten classnames:

import cn from 'classnames';

function Row({ isSelected }) {
  return (
    <div className={cn('row', isSelected && 'selected')}>
      ...
    </div>
  );
}

Se on erityisen kätevää jos sinulla on useita ehdollisia luokkia:

import cn from 'classnames';

function Row({ isSelected, size }) {
  return (
    <div className={cn('row', {
      selected: isSelected,
      large: size === 'large',
      small: size === 'small',
    })}>
      ...
    </div>
  );
}

DOM elemetin manipuolinti refillä

Joskus sinun täytyy saada selaimen DOM noodi joka on yhdistetty JSX tagiin. Esimerkiksi, jos haluat kohdistaa <input>:iin kun painiketta painetaan, sinun täytyy kutsua focus() selaimen <input> DOM noodilla.

To obtain the browser DOM node for a tag, declare a ref and pass it as the ref attribute to that tag:

import { useRef } from 'react';

export default function Form() {
  const inputRef = useRef(null);
  // ...
  return (
    <input ref={inputRef} />
    // ...

React asettaa DOM noodin inputRef.current:iin kun se on renderöity näytölle.

import { useRef } from 'react';

export default function Form() {
  const inputRef = useRef(null);

  function handleClick() {
    inputRef.current.focus();
  }

  return (
    <>
      <input ref={inputRef} />
      <button onClick={handleClick}>
        Focus the input
      </button>
    </>
  );
}

Lue lisää DOM manipuloinnista refien avulla ja katso lisää esimerkkejä.

Kehittyneempiin käyttötapauksiin, ref attribuutti hyväksyy myös takaisinkutsufunktion.

Sisäisen HTML sisällön asettaminen vaarallisesti

Voit välittää raakaa HTML merkkijonoa elementille näin:

const markup = { __html: '<p>some raw html</p>' };
return <div dangerouslySetInnerHTML={markup} />;

Tämä on vaarallista. Kuten DOM:n innerHTML ominaisuudella, sinun täytyy olla erittäin varovainen! Ellei merkintä tule täysin luotettavasta lähteestä, on triviaalia aiheuttaa XSS haavoittuvuus tällä tavalla.

Esimerkiksi, jos käytät Markdown kirjastoa joka muuntaa Markdownia HTML:ksi, luotat että sen parseri ei sisällä bugeja, ja käyttäjä näkee vain oman syötteen, voit näyttää tuloksena olevan HTML:n näin:

import { Remarkable } from 'remarkable';

const md = new Remarkable();

function renderMarkdownToHTML(markdown) {
  // Tämä on turvallista VAIN koska HTML näytetään
  // samalle käyttäjälle, ja koska luotat tämän
  // Markdown parserin oelvan bugivapaa.
  const renderedHTML = md.render(markdown);
  return {__html: renderedHTML};
}

export default function MarkdownPreview({ markdown }) {
  const markup = renderMarkdownToHTML(markdown);
  return <div dangerouslySetInnerHTML={markup} />;
}

Nähdäksesi miksi mielivaltaisen HTML renderöiminen on vaarallista, korvaa ylläoleva koodi tällä:

const post = {
  // Kuvittele tämä sisältö tallennettuna tietokantaan.
  content: `<img src="" onerror='alert("sinut häkkeröitiin")'>`
};

export default function MarkdownPreview() {
  // 🔴 TIETOTURVA-AUKKO: luotettamattoman syötteen välittäminen dangerouslySetInnerHTML:lle
  const markup = { __html: post.content };
  return <div dangerouslySetInnerHTML={markup} />;
}

Koodi upotettuna HTML:ssä suoritetaan. Hakkeri voisi käyttää tätä tietoturva-aukkoa varastaakseen käyttäjän tietoja tai suorittaakseen toimia heidän puolestaan. Käytä dangerouslySetInnerHTML:ää vain luotettavan ja puhdistetun datan kanssa.

Hiiren tapahtumien käsitteleminen

Tämä esimerkki näyttää joitain yleisiä hiiritapahtumia ja milloin ne suoritetaan.

export default function MouseExample() {
  return (
    <div
      onMouseEnter={e => console.log('onMouseEnter (parent)')}
      onMouseLeave={e => console.log('onMouseLeave (parent)')}
    >
      <button
        onClick={e => console.log('onClick (ensimmäinen painike)')}
        onMouseDown={e => console.log('onMouseDown (ensimmäinen painike)')}
        onMouseEnter={e => console.log('onMouseEnter (ensimmäinen painike)')}
        onMouseLeave={e => console.log('onMouseLeave (ensimmäinen painike)')}
        onMouseOver={e => console.log('onMouseOver (ensimmäinen painike)')}
        onMouseUp={e => console.log('onMouseUp (ensimmäinen painike)')}
      >
        Ensimmäinen painike
      </button>
      <button
        onClick={e => console.log('onClick (toinen painike)')}
        onMouseDown={e => console.log('onMouseDown (toinen painike)')}
        onMouseEnter={e => console.log('onMouseEnter (toinen painike)')}
        onMouseLeave={e => console.log('onMouseLeave (toinen painike)')}
        onMouseOver={e => console.log('onMouseOver (toinen painike)')}
        onMouseUp={e => console.log('onMouseUp (toinen painike)')}
      >
        Toinen painike
      </button>
    </div>
  );
}

Osoittimen tapahtumien käsitteleminen

Tämä esimerkki näyttää joitain yleisiä osoitintapahtumia ja milloin ne suoritetaan.

export default function PointerExample() {
  return (
    <div
      onPointerEnter={e => console.log('onPointerEnter (parent)')}
      onPointerLeave={e => console.log('onPointerLeave (parent)')}
      style={{ padding: 20, backgroundColor: '#ddd' }}
    >
      <div
        onPointerDown={e => console.log('onPointerDown (ensimmäinen lapsi)')}
        onPointerEnter={e => console.log('onPointerEnter (ensimmäinen lapsi)')}
        onPointerLeave={e => console.log('onPointerLeave (ensimmäinen lapsi)')}
        onPointerMove={e => console.log('onPointerMove (ensimmäinen lapsi)')}
        onPointerUp={e => console.log('onPointerUp (ensimmäinen lapsi)')}
        style={{ padding: 20, backgroundColor: 'lightyellow' }}
      >
        Ensimmäinen lapsi
      </div>
      <div
        onPointerDown={e => console.log('onPointerDown (toinen lapsi)')}
        onPointerEnter={e => console.log('onPointerEnter (toinen lapsi)')}
        onPointerLeave={e => console.log('onPointerLeave (toinen lapsi)')}
        onPointerMove={e => console.log('onPointerMove (toinen lapsi)')}
        onPointerUp={e => console.log('onPointerUp (toinen lapsi)')}
        style={{ padding: 20, backgroundColor: 'lightblue' }}
      >
        Toinen lapsi
      </div>
    </div>
  );
}

Kohdennustapahtumien käsitteleminen

Reactissa, kohdennustapahtumat kuplivat. Voit käyttää currentTarget ja relatedTarget erottaaksesi onko kohdennus peräisin ulkopuolelta vai ei. Esimerkki näyttää miten havaita lapsen kohdennustapahtuma, vanhemman kohdennustapahtuma, ja miten havaita kohdennuksen tuleminen tai lähteminen koko alipuusta.

export default function FocusExample() {
  return (
    <div
      tabIndex={1}
      onFocus={(e) => {
        if (e.currentTarget === e.target) {
          console.log('focused parent');
        } else {
          console.log('focused child', e.target.name);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // Ei suoritettu kun vaihdetaan kohdennusta lasten välillä
          console.log('focus entered parent');
        }
      }}
      onBlur={(e) => {
        if (e.currentTarget === e.target) {
          console.log('unfocused parent');
        } else {
          console.log('unfocused child', e.target.name);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // Ei suoritettu kun vaihdetaan kohdennusta lasten välillä
          console.log('focus left parent');
        }
      }}
    >
      <label>
        Etunimi:
        <input name="firstName" />
      </label>
      <label>
        Sukunimi:
        <input name="lastName" />
      </label>
    </div>
  );
}

Näppäimistötapahtumien käsitteleminen

Tämä esimerkki näyttää joitain yleisiä näppäimistötapahtumia ja milloin ne suoritetaan.

export default function KeyboardExample() {
  return (
    <label>
      Etunimi:
      <input
        name="firstName"
        onKeyDown={e => console.log('onKeyDown:', e.key, e.code)}
        onKeyUp={e => console.log('onKeyUp:', e.key, e.code)}
      />
    </label>
  );
}
PreviousKomponentitNext<input>

How do you like these docs?