diff --git a/docs/_data/nav_docs.yml b/docs/_data/nav_docs.yml index 2692fe71a83a..737e2c8bd922 100644 --- a/docs/_data/nav_docs.yml +++ b/docs/_data/nav_docs.yml @@ -23,3 +23,10 @@ - id: react-without-jsx title: React Without JSX - title: Reference + items: + - id: reference-react + title: React + - id: reference-react-dom + title: ReactDOM + - id: reference-react-dom-server + title: ReactDOMServer diff --git a/docs/docs-old/ref-01-top-level-api.it-IT.md b/docs/docs-old/ref-01-top-level-api.it-IT.md deleted file mode 100644 index 1b2b15cacc50..000000000000 --- a/docs/docs-old/ref-01-top-level-api.it-IT.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -id: top-level-api-it-IT -title: API di Livello Elevato -permalink: docs-old/top-level-api-it-IT.html -next: component-api-it-IT.html -redirect_from: "/docs/reference.html" ---- - -## React - -`React` è il punto di ingresso alla libreria React. Se stai usando uno dei pacchetti precompilati, è disponibile come variabile globale; se stai usando i moduli CommonJS puoi richiederlo con `require()`. - - -### React.Component - -```javascript -class Component -``` - -Questa è la classe base per i componenti React quando sono definiti usando le classi ES6. Vedi [Componenti Riutilizzabili](/react/docs/reusable-components.html#es6-classes) per usare le classi ES6 con React. Per i metodi forniti dalla classe base, vedi la [API dei Componenti](/react/docs/component-api.html). - - -### React.createClass - -```javascript -ReactClass createClass(object specification) -``` - -Crea la classe di un componente, data una specifica. Un componente implementa un metodo `render` che restituisce **un singolo** figlio. Tale figlio può avere una struttura di fogli arbitrariamente profonda. Una cosa che rende i componenti diversi dalle classi prototipiche standard è che non hai bisogno di chiamare `new` su di esse. Sono delle convenienti astrazioni che costruiscono (attraverso `new`) istanze dietro le quinte per te. - -Per maggiori informazioni sull'oggetto specifica, vedi [Specifiche dei Componenti e Ciclo di Vita](/react/docs/component-specs.html). - - -### React.createElement - -```javascript -ReactElement createElement( - string/ReactClass type, - [object props], - [children ...] -) -``` - -Crea e restituisce un nuovo `ReactElement` del tipo desiderato. L'argomento `type` può essere una stringa contenente il nome di un tag HTML (ad es. 'div', 'span', etc), oppure una `ReactClass` (creata attraverso `React.createClass`). - - -### React.cloneElement - -``` -ReactElement cloneElement( - ReactElement element, - [object props], - [children ...] -) -``` - -Clona e restituisce un nuovo `ReactElement` usando `element` come punto di partenza. L'elemento risultante avrà le proprietà dell'elemento originale, con le nuove proprietà unite in maniera superficiale. I figli esistenti sono sostituiti dai figli passati come `children`. Diversamente da `React.addons.cloneWithProps`, `key` e `ref` dell'elemento originale saranno preservati. Non esiste alcun comportamento speciale per riunire le proprietà (diversamente da `cloneWithProps`). Vedi l'[articolo del blog sulla v0.13 RC2](/react/blog/2015/03/03/react-v0.13-rc2.html) per maggiori dettagli. - - -### React.createFactory - -```javascript -factoryFunction createFactory( - string/ReactClass type -) -``` - -Restituisce una funzione che produce ReactElements di un tipo desiderato. Come `React.createElement`, -l'argomento `type` può essere sia la stringa contenente il nome di un tag HTML (ad es. 'div', 'span', etc), oppure una -`ReactClass`. - - -### ReactDOM.render - -```javascript -ReactComponent render( - ReactElement element, - DOMElement container, - [function callback] -) -``` - -Effettua il rendering di un ReactElement nel DOM all'interno dell'elemento `container` fornito e restituisce un [riferimento](/react/docs/more-about-refs-it-IT.html) al componente (oppure restituisce `null` per i [componenti privi di stato](/react/docs/reusable-components-it-IT.html#stateless-functions)). - -Se il rendering del ReactElement è stato precedentemente effettuato all'interno di `container`, questa operazione effettuerà un aggiornamento su di esso e modificherà il DOM in modo necessario a riflettere il più recente componente React. - -Se la callback opzionale è fornita, sarà eseguita dopo che il rendering o l'aggiornamento del componente sono stati effettuati. - -> Nota: -> -> `ReactDOM.render()` controlla i contenuti del nodo contenitore che viene passato come argomento `container`. Gli elementi DOM -> esistenti al suo interno sono sostituiti quando viene chiamata la prima volta. Le chiamate successive usano l'algoritmo di -> differenza di React per aggiornamenti efficienti. -> -> `ReactDOM.render()` non modifica il nodo contenitore (modifica soltanto i figli del contenitore). In -> futuro potrebbe essere possibile inserire un componente in un nodo DOM esistente senza sovrascrivere i figli esistenti. - - -### ReactDOM.unmountComponentAtNode - -```javascript -boolean unmountComponentAtNode(DOMElement container) -``` - -Rimuove un componente React montato nel DOM e ripulisce i suoi gestori di evento e lo stato. Se nessun componente è stato montato nel contenitore `container`, chiamare questa funzione non ha alcun effetto. Restituisce `true` se il componente è stato smontato e `false` se non è stato trovato un componente da smontare. - - -### ReactDOM.renderToString - -```javascript -string renderToString(ReactElement element) -``` - -Effettua il rendering di un ReactElement come il suo HTML iniziale. Questo dovrebe essere utilizzato soltanto lato server. React restituirà una stringa di HTML. Puoi usare questo metodo per generare HTML sul server e inviare il markup come risposta alla richiesta iniziale per un più rapido caricamento della pagina, e permettere ai motori di ricerca di effettuare il crawling della tua pagina per ottimizzazione SEO. - -Se chiami `ReactDOM.render()` su un nodo che possiede già questo markup generato lato server, React lo preserverà e vi attaccherà soltanto i gestori di eventi, permettendoti di avere una esperienza di primo caricamento altamente efficiente. - - -### ReactDOM.renderToStaticMarkup - -```javascript -string renderToStaticMarkup(ReactElement element) -``` - -Simile a `renderToString`, eccetto che non crea attributi DOM aggiuntivi come `data-react-id`, che React utilizza internamente. Questo è utile se vuoi usare React come un semplice generatore di pagine statiche, in quanto eliminare gli attributi aggiuntivi può risparmiare parecchi byte. - - -### ReactDOM.isValidElement - -```javascript -boolean isValidElement(* object) -``` - -Verifica che `object` sia un ReactElement. - - -### ReactDOM.findDOMNode - -```javascript -DOMElement findDOMNode(ReactComponent component) -``` -Se questo componente è stato montato nel DOM, restituisce il corrispondente elemento DOM nativo del browser. Questo metodo è utile per leggere i valori dal DOM, come i valori dei campi dei moduli ed effettuare misure sul DOM. Quando `render` restituisce `null` o `false`, `findDOMNode` restituisce `null`. - -> Nota: -> -> `findDOMNode()` è una via di fuga usata per accedere al nodo DOM sottostante. Nella maggior parte dei casi, l'uso di questa via di fuga è scoraggiato perché viola l'astrazione del componente. Tuttavia, esistono delle situazioni in cui questo è necessario (ad esempio, potresti aver bisogno di trovare un nodo DOM per posizionarlo in maniera assoluta oppure determinarne la larghezza visualizzata misurata in pixel). - -> -> `findDOMNode()` funziona soltanto su componenti montati (cioè, componenti che sono stati posizionati nel DOM). Se provi a chiamarlo su un componente che non è stato ancora montato (come chiamare `findDOMNode()` in `render()` su un componente che deve ancora essere creato) lancerà un'eccezione. - -### React.DOM - -`React.DOM` fornisce convenienti utilità che espongono `React.createElement` per componenti del DOM. Questi dovrebbero essere usate soltanto quando non si utilizza JSX. Ad esempio, `React.DOM.div(null, 'Ciao Mondo!')` - - -### React.PropTypes - -`React.PropTypes` include tipi che possono essere usati con l'oggetto `propTypes` di un componente per validare le proprietà passate ai tuoi componenti. Per maggiori informazioni su `propTypes`, vedi [Componenti Riutilizzabili](/react/docs/reusable-components.html). - - -### React.Children - -`React.Children` fornisce utilitià per gestire la struttura dati opaca `this.props.children`. - -#### React.Children.map - -```javascript -object React.Children.map(object children, function fn [, object thisArg]) -``` - -Invoca `fn` su ciascuno dei diretti discendenti contenuti in `children`, con `this` impostato a `thisArg`. Se `children` è un oggetto annidato o un array, esso verrà attraversato: ad `fn` non saranno mai passati gli oggetti contenitori. Se `children` è `null` o `undefined` restituisce `null` o `undefined` anziché un oggetto vuoto. - -#### React.Children.forEach - -```javascript -React.Children.forEach(object children, function fn [, object thisArg]) -``` - -Come `React.Children.map()` con la differenza che non restituisce un oggetto. - -#### React.Children.count - -```javascript -number React.Children.count(object children) -``` - -Restituisce il numero totale di componenti in `children`, uguale al numero di volte che una callback passata a `map` o `forEach` verrebbe invocata. - -#### React.Children.only - -```javascript -object React.Children.only(object children) -``` - -Restituisce il figlio unico contenuto in `children`, altrimenti lancia un'eccezione. diff --git a/docs/docs-old/ref-01-top-level-api.ja-JP.md b/docs/docs-old/ref-01-top-level-api.ja-JP.md deleted file mode 100644 index dca48c8e61d2..000000000000 --- a/docs/docs-old/ref-01-top-level-api.ja-JP.md +++ /dev/null @@ -1,172 +0,0 @@ ---- -id: top-level-api-ja-JP -title: Top-Level API -permalink: docs-old/top-level-api-ja-JP.html -next: component-api-ja-JP.html -redirect_from: "/docs/reference-ja-JP.html" ---- - -## React - -`React` はReactのライブラリに対するエントリーポイントです。事前にビルドされたパッケージを使用する場合は、グローバルで使用可能です。CommonJSのモジュールを使用する場合は、 `require()` できます。 - - -### React.Component - -```javascript -class Component -``` - -これは、ES6のクラスを使用して定義されている場合の、Reactコンポーネントに対する基底クラスです。ReactでES6のクラスを使用する方法については、[再利用可能なコンポーネント](/react/docs/reusable-components-ja-JP.html#es6-classes)をご覧ください。基底クラスからどのメソッドが実際に提供されるかについては、[コンポーネントAPI](/react/docs/component-api-ja-JP.html)をご覧ください。 - -### React.createClass - -```javascript -ReactClass createClass(object specification) -``` - -与えられた仕様に基づいてコンポーネントクラスを作成します。コンポーネントは **ある単一の** 子要素を返す `render` メソッドを実行します。その子要素は勝手に深い子要素の構造を保持しています。コンポーネントが標準的なプロトタイプのクラスと異なっている部分は、newを呼ぶ必要がないということです。それらは内部で（newを行う）インスタンスを構築する便利なラッパーです。 - -specificationオブジェクトについての情報は、[コンポーネントのスペックとライフサイクル](/react/docs/component-specs-ja-JP.html)をご覧ください。 - -### React.createElement - -```javascript -ReactElement createElement( - string/ReactClass type, - [object props], - [children ...] -) -``` - -与えられた型の `ReactElement` を作成し、返します。type引数はhtmlタグ名（例えば、'div'、'span'など）の文字列にも`ReactClass`（`React.createClass` によって作成される）にもなり得ます。 - -### React.cloneElement - -``` -ReactElement cloneElement( - ReactElement element, - [object props], - [children ...] -) -``` - -`element` をスターティングポイントとして使用する新しい `ReactElement` をクローンして返します。 -結果として生まれる要素はオリジナルの要素のpropsと新しいpropsを暗にマージしたものを保持しています。新しい子要素は現存する子要素を置き換えます。 `React.addons.cloneWithProps` と異なり、オリジナルの要素から得られた `key` と `ref` は保存されます。（`cloneWithProps` とは異なり）propsをマージする際に特別な動きは行いません。詳細については、[v0.13 RC2 blog記事](/react/blog/2015/03/03/react-v0.13-rc2.html)をご覧ください。 - -### React.createFactory - -```javascript -factoryFunction createFactory( - string/ReactClass type -) -``` - -与えられた型のReactElementsを生成する関数を返します。 `React.createElement` と同様に、type引数はhtmlタグ名（例えば、'div'、'span'など）の文字列にも`ReactClass` にもなり得ます。 - -### React.render - -```javascript -ReactComponent render( - ReactElement element, - DOMElement container, - [function callback] -) -``` - -与えられた `container` によってReactElementをDOMにレンダリングし、コンポーネントへの参照を返します。 - -もしReactElementが事前に `container` にレンダリングされていた場合は、更新を行い、DOMが最新のReactのコンポーネントを表すように変化させます。 - -オプションのコールバックが与えられた場合は、コンポーネントがレンダリングされたり、更新された後に実行されます。 - -> 注意: -> `React.render()` は渡されたコンテナーノードの内容を制御します。内部に存在するDOM要素は最初に呼ばれた際に置き換えられます。その後に呼ばれた場合は、ReactのDOMの差分アルゴリズムを使用して、効率的に更新されます。 -> -> `React.render()` はコンテナーノードの変更は行いません（コンテナの子要素のみ変更を行います）。今後、存在する子要素を上書きすることなく、存在するDOMノードにコンポーネントを挿入することが可能になるでしょう。 - -### React.unmountComponentAtNode - -```javascript -boolean unmountComponentAtNode(DOMElement container) -``` - -マウントされたReactのコンポーネントをDOMから削除し、そのイベントハンドラとstateをクリーンアップします。コンテナにコンポーネントがマウントされていない場合は、この関数を呼んでも何も行われません。コンポーネントがアンマウントされた場合は `true` を返し、アンマウントするコンポーネントが存在しない場合は `false` を返します。 - -### React.renderToString - -```javascript -string renderToString(ReactElement element) -``` - -ReactElementを最初にHTMLにレンダリングします。これはサーバでのみ使用されるべきです。ReactはHTML文字列を返します。このメソッドを、サーバでHTMLを生成し、最初のリクエストに対してマークアップを送るのに使用することができます。そうすることで、ページロードが速くなり、サーチエンジンはSEOの目的でページをクロールします。 - -既にサーバでレンダリングされたマークアップを保持しているノードで `React.render()` を呼んだ場合は、Reactはそれを保護し、イベントハンドラを加えます。そうすることで、最初のローディングのパフォーマンスがとても良くなります。 - -### React.renderToStaticMarkup - -```javascript -string renderToStaticMarkup(ReactElement element) -``` - -`renderToString` に似ていますが、Reactが内部で使用する `data-react-id` のような外部のDOM属性を作成しません。Reactを、単純な静的なページを生成するために使用したい場合は有用です。外部の属性を取り除くことでメモリを節約することができます。 - -### React.isValidElement - -```javascript -boolean isValidElement(* object) -``` - -オブジェクトがReactElementであるかどうか調査します。 - -### React.findDOMNode - -```javascript -DOMElement findDOMNode(ReactComponent component) -``` - -このコンポーネントがDOMにマウントされた場合は、対応するネイティブブラウザのDOM要素を返します。このメソッドはDOMの外の値を読み込む場合に有用です。例えば、formフィールドの値やDOMの測定を行う場合があります。 `render` が `null` や `false` を返した場合は、 `findDOMNode` は `null` を返します。 - -### React.DOM - -`React.DOM` はDOMコンポーネントのための `React.createElement` の周りの便利なラッパーを提供します。JSXを使用しない場合にのみ使用すべきです。例えば、 `React.DOM.div(null, 'Hello World!')` のように。 - -### React.PropTypes - -`React.PropTypes` はコンポーネントに与えられたpropsをバリデーションするためにコンポーネントの `propTypes` と使用できる型を含んでいます。 `propTypes` についての更なる情報は、[再利用可能なコンポーネント](/react/docs/reusable-components-ja-JP.html)をご覧ください。 - -### React.Children - -`React.Children` は `this.props.children` の不透明なデータ構造を扱うユーティリティを提供します。 - -#### React.Children.map - -```javascript -object React.Children.map(object children, function fn [, object thisArg]) -``` - -全ての `children` を含む子要素に対して、 `fn` を実行します。 `this` は `thisArg` にセットされます。 `children` がネストしたオブジェクトや配列だった場合は、実行されません。 `fn` はコンテナのオブジェクトから渡されません。子要素が `null` か `undefined` だった場合は、空のオブジェクトではなく `null` か `undefined` を返します。 - -#### React.Children.forEach - -```javascript -React.Children.forEach(object children, function fn [, object thisArg]) -``` - -`React.Children.map()` に似ていますが、オブジェクトを返しはしません。 - -#### React.Children.count - -```javascript -number React.Children.count(object children) -``` - -`children` の中のコンポーネントの合計数を返します。 `map` や `forEach` に渡されるコールバックが実行される数と等しくなります。 - -#### React.Children.only - -```javascript -object React.Children.only(object children) -``` - -`children` の単一の子要素を返します。それ以外の場合は例外をスローします。 diff --git a/docs/docs-old/ref-01-top-level-api.ko-KR.md b/docs/docs-old/ref-01-top-level-api.ko-KR.md deleted file mode 100644 index 3ebb9224af64..000000000000 --- a/docs/docs-old/ref-01-top-level-api.ko-KR.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -id: top-level-api-ko-KR -title: 최상위 API -permalink: docs-old/top-level-api-ko-KR.html -next: component-api-ko-KR.html -redirect_from: "/docs/reference-ko-KR.html" ---- - -## React - -`React`는 React 라이브러리의 진입점입니다. 미리 빌드된 패키지를 사용하는 경우 전역 변수로 접근할 수 있습니다. CommonJS 모듈을 사용하는 경우에는 `require()`로 불러올 수 있습니다. - - -### React.Component - -```javascript -class Component -``` - -ES6 클래스 구문을 사용해 React 컴포넌트를 정의했을 때 기본 클래스가 되는 부분입니다. 어떻게 ES6 클래스 구문을 사용해 React를 다루는지는 [재사용가능한 컴포넌트](/react/docs/reusable-components-ko-KR.html#es6-클래스)를 확인하세요. 기본 클래스에서 실제 제공되는 메소드들에는 어떤것이 있는지 알아보려면 [컴포넌트 API](/react/docs/component-api-ko-KR.html)를 확인하세요. - - -### React.createClass - -```javascript -ReactClass createClass(object specification) -``` - -주어진 명세에 따라 컴포넌트 클래스를 만듭니다. 컴포넌트는 단 하나의 자식만을 리턴하는 `render` 메소드를 구현합니다. 그 자식은 임의 깊이의 자식 구조를 가질 수 있습니다. 컴포넌트가 일반적인 프로토타입 기반의 클래스와 다른 점은 생성할 때 `new` 연산자를 사용하지 않아도 된다는 것입니다. 컴포넌트는 (`new` 연산자를 통해) 내부 인스턴스를 만들어 주는 편의 래퍼(wrapper)입니다. - -명세 객체에 대한 자세한 정보는 [컴포넌트 명세와 생명주기](/react/docs/component-specs-ko-KR.html)를 참고하세요. - - -### React.createElement - -```javascript -ReactElement createElement( - string/ReactClass type, - [object props], - [children ...] -) -``` - -주어진 타입의 새 `ReactElement`를 만들고 리턴합니다. `type` 인자는 HTML 태그명 문자열 (예: 'div', 'span' 등) 또는 (`React.createClass`로 만든) `ReactClass`입니다. - - -### React.cloneElement - -``` -ReactElement cloneElement( - ReactElement element, - [object props], - [children ...] -) -``` - -`element`를 시작점으로 새로운 `ReactElement`를 클론해 반환합니다. 반환된 엘리먼트에는 원본의 props와 새로운 props가 얕게 병합됩니다. 새 자식은 존재하는 자식을 교체할 것입니다. `React.addons.cloneWithProps`와는 다르게, 원본 엘리먼트의 `key`와 `ref`는 보존될 것입니다. `cloneWithProps`와는 달리 props이 병합되는데는 어떠한 특별한 동작도 없습니다. [v0.13 RC2 블로그 포스트](/react/blog/2015/03/03/react-v0.13-rc2.html)에서 추가적인 내용을 확인하세요. - - -### React.createFactory - -```javascript -factoryFunction createFactory( - string/ReactClass type -) -``` - -주어진 타입의 ReactElement를 만들어주는 함수를 리턴합니다. `React.createElement`와 마찬가지로 `type` 인자는 HTML 태그명 문자열 (예: 'div', 'span' 등) 또는 `ReactClass`입니다. - - -### React.isValidElement - -```javascript -boolean isValidElement(* object) -``` - -주어진 객체가 ReactElement인지 확인합니다. - - -### React.DOM - -`React.DOM`은 DOM 컴포넌트에 대해 `React.createElement`의 편의 래퍼(wrapper)를 제공합니다. JSX를 사용하지 않는 경우에만 사용하십시오. 예를 들어, `React.DOM.div(null, 'Hello World!')`와 같이 사용할 수 있습니다. - - -### React.PropTypes - -`React.PropTypes`는 컴포넌트에 넘어오는 props가 올바른지 검사할 수 있는 컴포넌트의 `propTypes` 객체에 들어가는 타입을 가집니다. `propTypes`에 대한 자세한 정보는 [재사용 가능한 컴포넌트](/react/docs/reusable-components-ko-KR.html)를 참고하세요. - - -### React.Children - -`React.Children`은 불투명한 자료 구조인 `this.props.children`를 다룰 수 있는 유틸리티를 제공합니다. - -#### React.Children.map - -```javascript -array React.Children.map(object children, function fn [, object thisArg]) -``` - -`children`의 바로 밑에 있는 모든 자식에 `fn`을 호출합니다. 이 때 `this`는 `thisArg`로 설정됩니다. `children`이 중첩된 객체나 배열일 경우 그 안의 값을 순회합니다. 따라서 `fn`에 컨테이너 객체가 넘어가는 일은 일어나지 않습니다. `children`이 `null`이거나 `undefined`면 배열 대신 `null` 또는 `undefined`를 리턴합니다. - -#### React.Children.forEach - -```javascript -React.Children.forEach(object children, function fn [, object thisArg]) -``` - -`React.Children.map()`과 비슷하지만 배열을 리턴하지 않습니다. - -#### React.Children.count - -```javascript -number React.Children.count(object children) -``` - -`children`에 들어있는 컴포넌트의 총 갯수를 리턴합니다. 이 갯수는 `map`이나 `forEach`에 넘긴 콜백이 호출되는 횟수와 동일합니다. - -#### React.Children.only - -```javascript -object React.Children.only(object children) -``` - -`children`에 단 하나의 자식이 있을 때 그 자식을 리턴합니다. 그 밖의 경우에는 예외를 발생시킵니다. - -#### React.Children.toArray - -```javascript -array React.Children.toArray(object children) -``` - -불투명한 자료구조인 `children`를 개별 자식마다 키를 할당해 평면 배열로 리턴합니다. 이는 render 메소드 내에서 자식의 컬렉션을 조작할 때, 특히 `this.props.children`을 넘기기 전에 재정렬하거나 재단할 때 유용합니다. - -## ReactDOM - -`react-dom` 패키지는 앱의 최상위 레벨에서 사용될 DOM 고유의 메소드를 제공하며, 원한다면 리액트 외부모델을 위한 출구로 사용될 수 있습니다. 대부분의 컴포넌트는 이 모듈을 사용할 필요가 없습니다. - -### ReactDOM.render - -```javascript -ReactComponent render( - ReactElement element, - DOMElement container, - [function callback] -) -``` - -주어진 ReactElement를 `container` 인자에 넘어온 DOM 안에 렌더링하고 컴포넌트의 [레퍼런스](/react/docs/more-about-refs-ko-KR.html)를 컴포넌트에 리턴합니다. [상태가 없는 컴포넌트](/react/docs/reusable-components-ko-KR.html#상태를-가지지-않는-함수)에서는 `null`을 리턴합니다. - -어떤 ReactElement가 이미 `container`에 렌더링 된 적이 있다면, 그것을 업데이트한 뒤 React 컴포넌트의 최신 상태를 반영하기 위해 꼭 필요한 만큼만 DOM을 변경합니다. - -콜백 인자를 넘기면 컴포넌트가 렌더링되거나 업데이트 된 다음 호출됩니다. - -> 주의: -> -> `ReactDOM.render()`는 넘어온 컨테이너 노드의 내용을 교체합니다. 안에 있는 DOM 엘리먼트는 첫 호출을 할 때 교체됩니다. 그 후의 호출에는 효율석으로 업데이트하기 위해 React의 DOM diff 알고리즘을 사용합니다. -> -> `ReactDOM.render()`는 컨테이너 노드를 수정하지 않습니다. (컨테이너의 자식만 수정함) 추후에 기존 자식들을 덮어쓰지 않고 이미 있는 DOM 노드에 컴포넌트를 삽입하는 것도 지원할 가능성이 있습니다. - - -### ReactDOM.unmountComponentAtNode - -```javascript -boolean unmountComponentAtNode(DOMElement container) -``` - -DOM에 마운트된 React 컴포넌트를 제거하고 이벤트 핸들러 및 state를 정리합니다. 컨테이너에 마운트된 컴포넌트가 없는 경우에는 호출해도 아무 동작을 하지 않습니다. 컴포넌트가 마운트 해제된 경우 `true`를, 마운트 해제할 컴포넌트가 없으면 `false`를 리턴합니다. - - -### ReactDOM.findDOMNode - -```javascript -DOMElement findDOMNode(ReactComponent component) -``` -이 컴포넌트가 DOM에 마운트된 경우 해당하는 네이티브 브라우저 DOM 엘리먼트를 리턴합니다. 이 메소드는 폼 필드의 값이나 DOM의 크기/위치 등 DOM에서 정보를 읽을 때 유용합니다. **대부분의 경우, DOM 노드에 ref를 쓸 수 있으며 `findDOMNode`를 사욯할 필요는 없습니다.** `render`가 `null`이나 `false`를 리턴할 때 `findDOMNode()`는 `null`을 리턴합니다. - -> 주의: -> -> `findDOMNode()`는 기본 DOM 노드에 접근하기 위한 출구입니다. 컴포넌트 추상화를 파괴하기 때문에 대부분의 경우 이것의 사용은 권장되지 않습니다. -> -> `findDOMNode()`는 마운트된 컴포넌트에서만 작동합니다. 이는 컴포넌트가 DOM에 위치해야 함을 뜻합니다. 만약 아직 생성되기전의 컴포넌트에서 `render()`에서 `findDOMNode()`를 호출하는 등 컴포넌트가 마운트 되기 이전에 이를 호출한다면, 예외가 던져질 것입니다. -> -> `findDOMNode()`는 상태가없는 컴포넌트에서 쓸 수 없습니다. - -## ReactDOMServer - -`react-dom/server` 패키지는 서버단에서 컴포넌트를 렌더할 수 있도록 해 줍니다. - -### ReactDOMServer.renderToString - -```javascript -string renderToString(ReactElement element) -``` - -주어진 ReactElement의 최초 HTML을 렌더링합니다. 이 함수는 서버에서만 사용해야 합니다. React가 HTML 문자열을 리턴합니다. HTML을 서버에서 생성하고 마크업을 최초 요청에 내려보내서, 페이지 로딩을 빠르게 하거나 검색 엔진이 크롤링할 수 있도록 하는 SEO 목적으로 이 메소드를 사용할 수 있습니다. - -또한 이 메소드로 서버에서 렌더링한 마크업을 포함한 노드에 `ReactDOM.render()`를 호출하면, React는 마크업을 보존하고 이벤트 핸들러만 붙이므로 최초 로딩을 매우 빠르게 느껴지게 할 수 있습니다. - - -### ReactDOMServer.renderToStaticMarkup - -```javascript -string renderToStaticMarkup(ReactElement element) -``` - -`renderToString`와 비슷하지만 `data-react-id`처럼 React에서 내부적으로 사용하는 추가적인 DOM 어트리뷰트를 만들지 않습니다. 추가적인 어트리뷰트를 제거하면 생성되는 마크업의 용량을 줄일 수 있기 때문에 React를 단순한 정적 페이지 생성기로 사용할 때 유용합니다. diff --git a/docs/docs-old/ref-01-top-level-api.md b/docs/docs-old/ref-01-top-level-api.md deleted file mode 100644 index 42e9b7f15278..000000000000 --- a/docs/docs-old/ref-01-top-level-api.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -id: top-level-api -title: Top-Level API -permalink: docs-old/top-level-api.html -next: component-api.html -redirect_from: "/docs/reference.html" ---- - -## React - -`React` is the entry point to the React library. If you're using one of the prebuilt packages it's available as a global; if you're using CommonJS modules you can `require()` it. - - -### React.Component - -```javascript -class Component -``` - -This is the base class for React Components when they're defined using ES6 classes. See [Reusable Components](/react/docs/reusable-components.html#es6-classes) for how to use ES6 classes with React. For what methods are actually provided by the base class, see the [Component API](/react/docs/component-api.html). - - -### React.createClass - -```javascript -ReactClass createClass(object specification) -``` - -Create a component class, given a specification. A component implements a `render` method which returns **one single** child. That child may have an arbitrarily deep child structure. One thing that makes components different than standard prototypal classes is that you don't need to call new on them. They are convenience wrappers that construct backing instances (via new) for you. - -For more information about the specification object, see [Component Specs and Lifecycle](/react/docs/component-specs.html). - - -### React.createElement - -```javascript -ReactElement createElement( - string/ReactClass type, - [object props], - [children ...] -) -``` - -Create and return a new `ReactElement` of the given type. The type argument can be either an -html tag name string (eg. 'div', 'span', etc), or a `ReactClass` (created via `React.createClass`). - - -### React.cloneElement - -``` -ReactElement cloneElement( - ReactElement element, - [object props], - [children ...] -) -``` - -Clone and return a new `ReactElement` using `element` as the starting point. The resulting element will have the original element's props with the new props merged in shallowly. New children will replace existing children. Unlike `React.addons.cloneWithProps`, `key` and `ref` from the original element will be preserved. There is no special behavior for merging any props (unlike `cloneWithProps`). See the [v0.13 RC2 blog post](/react/blog/2015/03/03/react-v0.13-rc2.html) for additional details. - - -### React.createFactory - -```javascript -factoryFunction createFactory( - string/ReactClass type -) -``` - -Return a function that produces ReactElements of a given type. Like `React.createElement`, the type argument can be either an html tag name string (eg. 'div', 'span', etc), or a `ReactClass`. - - -### React.isValidElement - -```javascript -boolean isValidElement(* object) -``` - -Verifies the object is a ReactElement. - - -### React.DOM - -`React.DOM` provides convenience wrappers around `React.createElement` for DOM components. These should only be used when not using JSX. For example, `React.DOM.div(null, 'Hello World!')` - - -### React.PropTypes - -`React.PropTypes` includes types that can be used with a component's `propTypes` object to validate props being passed to your components. For more information about `propTypes`, see [Reusable Components](/react/docs/reusable-components.html). - - -### React.Children - -`React.Children` provides utilities for dealing with the `this.props.children` opaque data structure. - -#### React.Children.map - -```javascript -array React.Children.map(object children, function fn [, object thisArg]) -``` - -Invoke `fn` on every immediate child contained within `children` with `this` set to `thisArg`. If `children` is a [keyed fragment](/react/docs/create-fragment.html) or array it will be traversed: `fn` will never be passed the container objects. If children is `null` or `undefined` returns `null` or `undefined` rather than an array. - -#### React.Children.forEach - -```javascript -React.Children.forEach(object children, function fn [, object thisArg]) -``` - -Like `React.Children.map()` but does not return an array. - -#### React.Children.count - -```javascript -number React.Children.count(object children) -``` - -Return the total number of components in `children`, equal to the number of times that a callback passed to `map` or `forEach` would be invoked. - -#### React.Children.only - -```javascript -object React.Children.only(object children) -``` - -Return the only child in `children`. Throws otherwise. - -#### React.Children.toArray - -```javascript -array React.Children.toArray(object children) -``` - -Return the `children` opaque data structure as a flat array with keys assigned to each child. Useful if you want to manipulate collections of children in your render methods, especially if you want to reorder or slice `this.props.children` before passing it down. - -> Note: -> -> `React.Children.toArray()` changes keys to preserve the semantics of nested arrays when flattening lists of children. That is, `toArray` prefixes each key in the returned array so that each element's key is scoped to the input array containing it. - -## ReactDOM - -The `react-dom` package provides DOM-specific methods that can be used at the top level of your app and as an escape hatch to get outside of the React model if you need to. Most of your components should not need to use this module. - -### ReactDOM.render - -```javascript -render( - ReactElement element, - DOMElement container, - [function callback] -) -``` - -Render a ReactElement into the DOM in the supplied `container` and return a [reference](/react/docs/more-about-refs.html) to the component (or returns `null` for [stateless components](/react/docs/reusable-components.html#stateless-functions)). - -If the ReactElement was previously rendered into `container`, this will perform an update on it and only mutate the DOM as necessary to reflect the latest React component. - -If the optional callback is provided, it will be executed after the component is rendered or updated. - -> Note: -> -> `ReactDOM.render()` controls the contents of the container node you pass in. Any existing DOM elements -> inside are replaced when first called. Later calls use React’s DOM diffing algorithm for efficient -> updates. -> -> `ReactDOM.render()` does not modify the container node (only modifies the children of the container). In -> the future, it may be possible to insert a component to an existing DOM node without overwriting -> the existing children. -> -> `ReactDOM.render()` currently returns a reference to the root `ReactComponent` instance. However, using this return value is legacy -> and should be avoided because future versions of React may render components asynchronously in some cases. If you need a reference to the root `ReactComponent` instance, the preferred solution is to attach a -> [callback ref](/react/docs/more-about-refs.html#the-ref-callback-attribute) to the root element. - - -### ReactDOM.unmountComponentAtNode - -```javascript -boolean unmountComponentAtNode(DOMElement container) -``` - -Remove a mounted React component from the DOM and clean up its event handlers and state. If no component was mounted in the container, calling this function does nothing. Returns `true` if a component was unmounted and `false` if there was no component to unmount. - - -### ReactDOM.findDOMNode - -```javascript -DOMElement findDOMNode(ReactComponent component) -``` -If this component has been mounted into the DOM, this returns the corresponding native browser DOM element. This method is useful for reading values out of the DOM, such as form field values and performing DOM measurements. **In most cases, you can attach a ref to the DOM node and avoid using `findDOMNode` at all.** When `render` returns `null` or `false`, `findDOMNode` returns `null`. - -> Note: -> -> `findDOMNode()` is an escape hatch used to access the underlying DOM node. In most cases, use of this escape hatch is discouraged because it pierces the component abstraction. -> -> `findDOMNode()` only works on mounted components (that is, components that have been placed in the DOM). If you try to call this on a component that has not been mounted yet (like calling `findDOMNode()` in `render()` on a component that has yet to be created) an exception will be thrown. -> -> `findDOMNode()` cannot be used on stateless components. - -## ReactDOMServer - -The `react-dom/server` package allows you to render your components on the server. - -### ReactDOMServer.renderToString - -```javascript -string renderToString(ReactElement element) -``` - -Render a ReactElement to its initial HTML. This should only be used on the server. React will return an HTML string. You can use this method to generate HTML on the server and send the markup down on the initial request for faster page loads and to allow search engines to crawl your pages for SEO purposes. - -If you call `ReactDOM.render()` on a node that already has this server-rendered markup, React will preserve it and only attach event handlers, allowing you to have a very performant first-load experience. - - -### ReactDOMServer.renderToStaticMarkup - -```javascript -string renderToStaticMarkup(ReactElement element) -``` - -Similar to `renderToString`, except this doesn't create extra DOM attributes such as `data-react-id`, that React uses internally. This is useful if you want to use React as a simple static page generator, as stripping away the extra attributes can save lots of bytes. diff --git a/docs/docs-old/ref-01-top-level-api.zh-CN.md b/docs/docs-old/ref-01-top-level-api.zh-CN.md deleted file mode 100644 index b62d4f4182b0..000000000000 --- a/docs/docs-old/ref-01-top-level-api.zh-CN.md +++ /dev/null @@ -1,211 +0,0 @@ ---- -id: top-level-api-zh-CN -title: Top-Level API -permalink: docs-old/top-level-api-zh-CN.html -next: component-api-zh-CN.html -redirect_from: "/docs/reference-zh-CN.html" ---- - -## React - -`React` 是 React 库的入口点。如果你使用预编译包中的一个，则 `React` 为全局变量；如果你使用 CommonJS 模块，你可以 `require()` 它。 - - -### React.Component - -```javascript -class Component -``` - -当使用ES6 类定义时，React.Component是 React 组件的基类。如何在React中使用 ES6 class 请参见 [可重用组件](/react/docs/reusable-components-zh-CN.html#es6-classes)。基类实际提供了哪些方法 请参见 [组件 API](/react/docs/component-api-zh-CN.html). - - -### React.createClass - -```javascript -ReactClass createClass(object specification) -``` - -给定一份规格（specification），创建一个组件类。组件通常要实现一个 `render()` 方法，它返回 **单个的** 子级。该子级可能包含任意深度的子级结构。组件与标准原型类的不同之处在于，你不需要对它们调用 new。 它们是为你在后台构造实例（通过 new）的便利的包装器。 - -更多关于规格对象（specification object）的信息，请见 [组件规格和生命周期](/react/docs/component-specs-zh-CN.html) 。 - - -### React.createElement - -```javascript -ReactElement createElement( - string/ReactClass type, - [object props], - [children ...] -) -``` - -创建并返回一个新的给定类型的 `ReactElement`。type 参数既可以是一个 html 标签名字符串（例如. “div”，“span”，等等），也可以是一个 `ReactClass` （用 `React.createClass` 创建的）。 - - - -### React.cloneElement - -``` -ReactElement cloneElement( - ReactElement element, - [object props], - [children ...] -) -``` - -使用 `element` 作为起点，克隆并返回一个新的 `ReactElement` 。生成的 element 将会拥有原始 element 的 props 与新的 props 的浅合并。新的子级将会替换现存的子级。 不同于 `React.addons.cloneWithProps`，来自原始 element 的 `key` 和 `ref` 将会保留。对于合并任何 props 没有特别的行为（不同于 `cloneWithProps`）。更多细节详见[v0.13 RC2 blog post](/react/blog/2015/03/03/react-v0.13-rc2.html) 。 - - -### React.createFactory - -```javascript -factoryFunction createFactory( - string/ReactClass type -) -``` - -返回一个生成给定类型的 ReactElements 的函数。如同 `React.createElement`，type 参数既可以是一个 html 标签名字符串（例如. “div”，“span”，等等），也可以是一个 `ReactClass` 。 - - -### React.isValidElement - -```javascript -boolean isValidElement(* object) -``` - -验证对象是否是一个 ReactElement。 - - -### React.DOM - -`React.DOM` 用 `React.createElement` 为 DOM 组件提供了便利的包装器。该方式应该只在不使用 JSX 的时使用。例如，`React.DOM.div(null, 'Hello World!')`。 - - -### React.PropTypes - -`React.PropTypes` 包含了能与 组件的`propTypes` 对象一起使用的类型，用以验证传入你的组件的 props。更多有关 `propTypes` 的信息，请见 [可重用组件](/react/docs/reusable-components-zh-CN.html)。 - - -### React.Children - -`React.Children` 为处理 `this.props.children` 这个不透明的数据结构提供了工具。 - -#### React.Children.map - -```javascript -array React.Children.map(object children, function fn [, object thisArg]) -``` - -在每一个包含在 `children` 中的直接子级上调用 `fn` ，`fn`中的 `this` 设置为 `thisArg`。如果 `children` 是一个嵌套的对象或者数组，它将被遍历：不会传入容器对象到 `fn` 中。如果 children 是 `null` 或者 `undefined`，则返回 `null` 或者 `undefined` 而不是一个空数组。 - -#### React.Children.forEach - -```javascript -React.Children.forEach(object children, function fn [, object thisArg]) -``` - -类似 `React.Children.map()`，但是不返回数组。 - -#### React.Children.count - -```javascript -number React.Children.count(object children) -``` - -返回 `children` 中的组件总数，相等于传递给 `map` 或者 `forEach` 的回调函数应被调用次数。 - -#### React.Children.only - -```javascript -object React.Children.only(object children) -``` - -返回 `children` 中仅有的子级。否则抛出异常。 - -#### React.Children.toArray - -```javascript -array React.Children.toArray(object children) -``` - -以赋key给每个child的平坦的数组形式,返回不透明的 `children` 数据结构.如果你想操纵你的渲染方法的子级的合集这很有用,尤其如果你想在 `this.props.children` 传下之前渲染或者切割. - -## ReactDOM - -`react-dom` 包提供了 具体的DOM方法,这些方法可以在你的app的顶层作为一个你需要时脱离React模式的安全舱口 被使用.你的大多数组件不需要使用这个模块. - -### ReactDOM.render - -```javascript -ReactComponent render( - ReactElement element, - DOMElement container, - [function callback] -) -``` - -渲染一个 ReactElement 到 DOM 里提供的 `容器（container）`中，并返回一个对 组件(或者返回 `null` 对于 [无状态组件](/react/docs/reusable-components-zh-CN.html#无状态函数)) 的[引用](/react/docs/more-about-refs.html) - -如果 ReactElement 之前被渲染到了 `container` 中，这将对它执行一次更新，并仅变动需要变动的 DOM 来反映最新的 React 组件。 - -如果提供了可选的回调函数，则该函数将会在组件渲染或者更新之后被执行。 - -> 注意: -> -> `ReactDOM.render()` 控制你传入的 container 节点的内容。 -> 当初次调用时，任何现存于内的 DOM 元素将被替换。 -> 其后的调用使用 React的 diffing 算法来有效率的更新。 -> -> `ReactDOM.render()` 不会修改 container 节点（只修改 container 的子级）。 -> 将来，也许能够直接插入一个组件到已经存在的 DOM 节点而不覆盖 -> 现有的子级。 - - -### ReactDOM.unmountComponentAtNode - -```javascript -boolean unmountComponentAtNode(DOMElement container) -``` - -从 DOM 中移除已经挂载的 React 组件，并清除它的事件处理器和 state。如果在 container 中没有组件被挂载，调用此函数将什么都不做。如果组件被卸载返回 `true`，如果没有组件被卸载返回 `false`。 - - -### ReactDOM.findDOMNode - -```javascript -DOMElement findDOMNode(ReactComponent component) -``` -如果这个组件已经被挂载到了 DOM，它返回相应的浏览器原生的 DOM 元素。这个方法对于读取 DOM 的值很有用，比如表单域的值和执行 DOM 的测量。**在大多数情况下,你可以连接一个ref到DOM节点上,并避免使用 `findDOMNode`** 如果 `render` 返回 `null` 或者 `false`， `findDOMNode` 返回 `null`. - -> 注意: -> -> `findDOMNode()` 是一个用来访问底层DOM节点的安全舱口.大多数情况下,使用这个安全舱口是不被鼓励的,因为它穿破了组件的抽象. -> -> `findDOMNode()` 只在已挂载的组件上工作(即是,已经被放置到DOM里的组件).如果你尝试在没有被挂载的组件上调用这个方法(比如在 一个没有被创建的组件的`render()`里 调用 `findDOMNode()` )会抛出一个异常. -> -> `findDOMNode()` 不能用在无状态组件. - -## ReactDOMServer - -`react-dom/server` 允许你在服务器上渲染你的组件. - -### ReactDOMServer.renderToString - -```javascript -string renderToString(ReactElement element) -``` - -把 ReactElement 渲染为它原始的 HTML 。这应该仅在服务器端使用。React 将会返回一个 HTML 字符串。你可以用这种方法在服务器端生成 HTML，然后在初始请求下传这些标记，以获得更快的页面加载速度及允许搜索引擎抓取页面（便于 SEO）。 - -如果在一个在已经有了这种服务器预渲染标记的节点上面调用 `ReactDOM.render()`，React 将会维护该节点，仅绑定事件处理器，让你有一个非常高效的初次加载体验。 - - -### ReactDOMServer.renderToStaticMarkup - -```javascript -string renderToStaticMarkup(ReactElement element) -``` - -类似于 `renderToString` ，除了不创建额外的 DOM 属性，比如 `data-react-id`，这仅在 React 内部使用的属性。如果你想用 React 做一个简单的静态页面生成器，这是很有用的，因为去除额外的属性能够节省很多字节。 diff --git a/docs/docs/reference-react-dom-server.md b/docs/docs/reference-react-dom-server.md new file mode 100644 index 000000000000..96be5cd997cf --- /dev/null +++ b/docs/docs/reference-react-dom-server.md @@ -0,0 +1,32 @@ +--- +id: reference-react-dom-server +title: ReactDOMServer +permalink: docs/reference-react-dom-server.html +next: reference-react-dom-server.html +redirect_from: "/docs/reference.html" +--- + +The `react-dom/server` package allows you to render your components on the server. + + - [`renderToString()`](#renderToString) + - [`renderToStaticMarkup()`](#renderToStaticMarkup) + +## Reference + +### `renderToString()` + +```javascript +ReactDOMServer.renderToString(element) +``` + +Render a React element to its initial HTML. This should only be used on the server. React will return an HTML string. You can use this method to generate HTML on the server and send the markup down on the initial request for faster page loads and to allow search engines to crawl your pages for SEO purposes. + +If you call [`ReactDOM.render()`](/react/docs/reference-react-dom.html#render) on a node that already has this server-rendered markup, React will preserve it and only attach event handlers, allowing you to have a very performant first-load experience. + +### `renderToStaticMarkup()` + +```javascript +ReactDOMServer.renderToStaticMarkup(element) +``` + +Similar to [`renderToString`](#rendertostring), except this doesn't create extra DOM attributes such as `data-react-id`, that React uses internally. This is useful if you want to use React as a simple static page generator, as stripping away the extra attributes can save lots of bytes. diff --git a/docs/docs/reference-react-dom.md b/docs/docs/reference-react-dom.md new file mode 100644 index 000000000000..38a683cb35b3 --- /dev/null +++ b/docs/docs/reference-react-dom.md @@ -0,0 +1,66 @@ +--- +id: reference-react-dom +title: ReactDOM +permalink: docs/reference-react-dom.html +next: reference-react-dom-server.html +redirect_from: "/docs/reference.html" +--- + +The `react-dom` package provides DOM-specific methods that can be used at the top level of your app and as an escape hatch to get outside of the React model if you need to. Most of your components should not need to use this module. + + - [`render()`](#render) + - [`unmountComponentAtNode()`](#unmountComponentAtNode) + - [`findDOMNode()`](#findDOMNode) + +## Reference + +### `render()` + +```javascript +ReactDOM.render( + element, + container, + [callback] +) +``` + +Render a React element into the DOM in the supplied `container` and return a [reference](/react/docs/more-about-refs.html) to the component (or returns `null` for [stateless components](/react/docs/components-and-props.html#functional-and-class-components). + +If the React element was previously rendered into `container`, this will perform an update on it and only mutate the DOM as necessary to reflect the latest React element. + +If the optional callback is provided, it will be executed after the component is rendered or updated. + +> Note: +> +> `ReactDOM.render()` controls the contents of the container node you pass in. Any existing DOM elements inside are replaced when first called. Later calls use React’s DOM diffing algorithm for efficient updates. +> +> `ReactDOM.render()` does not modify the container node (only modifies the children of the container). It may be possible to insert a component to an existing DOM node without overwriting the existing children. +> +> `ReactDOM.render()` currently returns a reference to the root `ReactComponent` instance. However, using this return value is legacy +> and should be avoided because future versions of React may render components asynchronously in some cases. If you need a reference to the root `ReactComponent` instance, the preferred solution is to attach a +> [callback ref](/react/docs/more-about-refs.html#the-ref-callback-attribute) to the root element. + + +### `unmountComponentAtNode()` + +```javascript +ReactDOM.unmountComponentAtNode(container) +``` + +Remove a mounted React component from the DOM and clean up its event handlers and state. If no component was mounted in the container, calling this function does nothing. Returns `true` if a component was unmounted and `false` if there was no component to unmount. + + +### `findDOMNode(component)` + +```javascript +ReactDOM.findDOMNode(component) +``` +If this component has been mounted into the DOM, this returns the corresponding native browser DOM element. This method is useful for reading values out of the DOM, such as form field values and performing DOM measurements. **In most cases, you can attach a ref to the DOM node and avoid using `findDOMNode` at all.** When `render` returns `null` or `false`, `findDOMNode` returns `null`. + +> Note: +> +> `findDOMNode` is an escape hatch used to access the underlying DOM node. In most cases, use of this escape hatch is discouraged because it pierces the component abstraction. +> +> `findDOMNode` only works on mounted components (that is, components that have been placed in the DOM). If you try to call this on a component that has not been mounted yet (like calling `findDOMNode()` in `render()` on a component that has yet to be created) an exception will be thrown. +> +> `findDOMNode` cannot be used on functional components. diff --git a/docs/docs/reference-react.md b/docs/docs/reference-react.md new file mode 100644 index 000000000000..853a555af192 --- /dev/null +++ b/docs/docs/reference-react.md @@ -0,0 +1,149 @@ +--- +id: reference-react +title: React Top-Level API +permalink: docs/reference-react.html +next: reference-react-dom.html +redirect_from: "/docs/reference.html" +--- + +`React` is the entry point to the React library. + +## Reference + + - [`React.Component`](#react.component) + - [`createClass()`](#createclass) + - [`createElement()`](#createlement) + - [`cloneElement()`](#cloneelement) + - [`createFactory()`](#createfactory) + - [`isValidElement()`](#isvalidelement) + - [`PropTypes`](#proptypes) + - [`Children`](#children) + +### `React.Component` + +```javascript +class Greeting extends React.Component { + render() { + return

Hello, {this.props.name}

; + } +} +``` + +`React.Component` is the base class for React components when they are defined using ES6 classes. See the [React.Component API Reference](/react/docs/reference-react-component.html) for a list of methods related to the base `React.Component` class. + +### `createClass()` + +```javascript +React.createClass(specification) +``` + +If you don't use ES6 yet, you may use the `React.createClass` helper instead to create a component class. See [Using React without ES6](/react/docs/react-without-es6.html) for more information. + +### `createElement()` + +```javascript +React.createElement( + type, + [props], + [...children] +) +``` + +Create and return a new React element of the given type. The type argument can be either an +html tag name string (eg. 'div', 'span', etc), or a React class (created via `React.createClass`). + +Code written with JSX will be converted to use `React.createElement`. You will not typically invoke `React.createElement` directly if you are using JSX. See [React Without JSX](/react/docs/react-without-jsx.html) to learn more. + +Convenience wrappers around `React.createElement` for DOM components are provided by `React.DOM`. For example, `React.DOM.a(...)` is a convenience wrapper for `React.createElement('a', ...)`. + +### `cloneElement()` + +``` +React.cloneElement( + element, + [props], + [...children] +) +``` + +Clone and return a new React element using `element` as the starting point. The resulting element will have the original element's props with the new props merged in shallowly. New children will replace existing children. `key` and `ref` from the original element will be preserved. + +`React.cloneElement` is almost equivalent to: + +```js +{children} +``` + +However, it also preserves `ref`s. This means that if you get a child with a `ref` on it, you won't accidentally steal it from your ancestor. You will get the same `ref` attached to your new element. + +This API was introduced as a replacement of the deprecated `React.addons.cloneWithProps`. + +### `createFactory()` + +```javascript +React.createFactory(type) +``` + +Return a function that produces React elements of a given type. Like [`React.createElement`](#createElement), the type argument can be either an html tag name string (eg. 'div', 'span', etc), or a React class. + +You will not typically invoke `React.createFactory` directly if you are using JSX. See [React Without JSX](/react/docs/react-without-jsx.html) to learn more. + +### `isValidElement()` + +```javascript +React.isValidElement(object) +``` + +Verifies the object is a React element. Returns `true` or `false`. + +### `PropTypes` + +`React.PropTypes` includes types that can be used with a component's `propTypes` object to validate props being passed to your components. For more information about `propTypes`, see [Typechecking with PropTypes](/react/docs/typechecking-with-proptypes.html). + +### `Children` + +`React.Children` provides utilities for dealing with the `this.props.children` opaque data structure. + +#### `Children.map` + +```javascript +React.Children.map(children, function[(thisArg)]) +``` + +Invoke a function on every immediate child contained within `children` with `this` set to `thisArg`. If `children` is a keyed fragment or array it will be traversed: the function will never be passed the container objects. If children is `null` or `undefined`, returns `null` or `undefined` rather than an array. + +#### `Children.forEach` + +```javascript +React.Children.forEach(children, function[(thisArg)]) +``` + +Like `React.Children.map()` but does not return an array. + +#### `Children.count` + +```javascript +Children.count(children) +``` + +Return the total number of components in `children`, equal to the number of times that a callback passed to `map` or `forEach` would be invoked. + +#### `Children.only` + +```javascript +React.Children.only(children) +``` + +Return the only child in `children`. Throws otherwise. + +#### `Children.toArray` + +```javascript +React.Children.toArray(children) +``` + +Return the `children` opaque data structure as a flat array with keys assigned to each child. Useful if you want to manipulate collections of children in your render methods, especially if you want to reorder or slice `this.props.children` before passing it down. + +> Note: +> +> `React.Children.toArray()` changes keys to preserve the semantics of nested arrays when flattening lists of children. That is, `toArray` prefixes each key in the returned array so that each element's key is scoped to the input array containing it.