API viite
Komponentit

Common components (e.g. <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ö

In React, you specify a CSS class with className. It works like the class attribute in HTML:

<img className="avatar" />

Then you write the CSS rules for it in a separate CSS file:

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

React does not prescribe how you add CSS files. In the simplest case, you’ll add a <link> tag to your HTML. If you use a build tool or a framework, consult its documentation to learn how to add a CSS file to your project.

Sometimes, the style values depend on data. Use the style attribute to pass some styles dynamically:

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

In the above example, style={{}} is not a special syntax, but a regular {} object inside the style={ } JSX curly braces. We recommend only using the style attribute when your styles depend on JavaScript variables.

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?

To apply CSS classes conditionally, you need to produce the className string yourself using JavaScript.

For example, className={'row ' + (isSelected ? 'selected': '')} will produce either className="row" or className="row selected" depending on whether isSelected is true.

To make this more readable, you can use a tiny helper library like classnames:

import cn from 'classnames';

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

It is especially convenient if you have multiple conditional classes:

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ä

Sometimes, you’ll need to get the browser DOM node associated with a tag in JSX. For example, if you want to focus an <input> when a button is clicked, you need to call focus() on the browser <input> DOM node.

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 will put the DOM node into inputRef.current after it’s been rendered to the screen.

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>
    </>
  );
}

Read more about manipulating DOM with refs and check out more examples.

For more advanced use cases, the ref attribute also accepts a callback function.

Sisäisen HTML sisällön asettaminen vaarallisesti

You can pass a raw HTML string to an element like so:

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

This is dangerous. As with the underlying DOM innerHTML property, you must exercise extreme caution! Unless the markup is coming from a completely trusted source, it is trivial to introduce an XSS vulnerability this way.

For example, if you use a Markdown library that converts Markdown to HTML, you trust that its parser doesn’t contain bugs, and the user only sees their own input, you can display the resulting HTML like this:

import { Remarkable } from 'remarkable';

const md = new Remarkable();

function renderMarkdownToHTML(markdown) {
  // This is ONLY safe because the output HTML
  // is shown to the same user, and because you
  // trust this Markdown parser to not have bugs.
  const renderedHTML = md.render(markdown);
  return {__html: renderedHTML};
}

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

To see why rendering arbitrary HTML is dangerous, replace the code above with this:

const post = {
  // Imagine this content is stored in the database.
  content: `<img src="" onerror='alert("you were hacked")'>`
};

export default function MarkdownPreview() {
  // 🔴 SECURITY HOLE: passing untrusted input to dangerouslySetInnerHTML
  const markup = { __html: post.content };
  return <div dangerouslySetInnerHTML={markup} />;
}

The code embedded in the HTML will run. A hacker could use this security hole to steal user information or to perform actions on their behalf. Only use dangerouslySetInnerHTML with trusted and sanitized data.

Hiiren tapahtumien käsitteleminen

This example shows some common mouse events and when they fire.

export default function MouseExample() {
  return (
    <div
      onMouseEnter={e => console.log('onMouseEnter (parent)')}
      onMouseLeave={e => console.log('onMouseLeave (parent)')}
    >
      <button
        onClick={e => console.log('onClick (first button)')}
        onMouseDown={e => console.log('onMouseDown (first button)')}
        onMouseEnter={e => console.log('onMouseEnter (first button)')}
        onMouseLeave={e => console.log('onMouseLeave (first button)')}
        onMouseOver={e => console.log('onMouseOver (first button)')}
        onMouseUp={e => console.log('onMouseUp (first button)')}
      >
        First button
      </button>
      <button
        onClick={e => console.log('onClick (second button)')}
        onMouseDown={e => console.log('onMouseDown (second button)')}
        onMouseEnter={e => console.log('onMouseEnter (second button)')}
        onMouseLeave={e => console.log('onMouseLeave (second button)')}
        onMouseOver={e => console.log('onMouseOver (second button)')}
        onMouseUp={e => console.log('onMouseUp (second button)')}
      >
        Second button
      </button>
    </div>
  );
}

Osoittimen tapahtumien käsitteleminen

This example shows some common pointer events and when they fire.

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 (first child)')}
        onPointerEnter={e => console.log('onPointerEnter (first child)')}
        onPointerLeave={e => console.log('onPointerLeave (first child)')}
        onPointerMove={e => console.log('onPointerMove (first child)')}
        onPointerUp={e => console.log('onPointerUp (first child)')}
        style={{ padding: 20, backgroundColor: 'lightyellow' }}
      >
        First child
      </div>
      <div
        onPointerDown={e => console.log('onPointerDown (second child)')}
        onPointerEnter={e => console.log('onPointerEnter (second child)')}
        onPointerLeave={e => console.log('onPointerLeave (second child)')}
        onPointerMove={e => console.log('onPointerMove (second child)')}
        onPointerUp={e => console.log('onPointerUp (second child)')}
        style={{ padding: 20, backgroundColor: 'lightblue' }}
      >
        Second child
      </div>
    </div>
  );
}

Kohdennustapahtumien käsitteleminen

In React, focus events bubble. You can use the currentTarget and relatedTarget to differentiate if the focusing or blurring events originated from outside of the parent element. The example shows how to detect focusing a child, focusing the parent element, and how to detect focus entering or leaving the whole subtree.

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)) {
          // Not triggered when swapping focus between children
          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)) {
          // Not triggered when swapping focus between children
          console.log('focus left parent');
        }
      }}
    >
      <label>
        First name:
        <input name="firstName" />
      </label>
      <label>
        Last name:
        <input name="lastName" />
      </label>
    </div>
  );
}

Näppäimistötapahtumien käsitteleminen

This example shows some common keyboard events and when they fire.

export default function KeyboardExample() {
  return (
    <label>
      First name:
      <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?