API 參考

此頁面提供所有已匯出的函式的快速概觀。

元件

元件是一個基礎類別，可以延伸它來建立有狀態的 Preact 元件。

元件並非直接實例化，而是由渲染器管理並根據需要建立。

import { Component } from 'preact';

class MyComponent extends Component {
  // (see below)
}

Component.render(props, state)

所有元件都必須提供一個 render() 函式。render 函式會傳入元件目前的 props 和狀態，並應該回傳一個虛擬 DOM 元素（通常是 JSX「元素」）、一個陣列，或 null。

import { Component } from 'preact';

class MyComponent extends Component {
    render(props, state) {
        // props is the same as this.props
        // state is the same as this.state

        return <h1>Hello, {props.name}!</h1>;
    }
}

若要進一步了解元件以及如何使用元件，請查看元件文件。

render()

render(virtualDom, containerNode, [replaceNode])

將虛擬 DOM 元素渲染到父 DOM 元素 containerNode。不會回傳任何東西。

// DOM tree before render:
// <div id="container"></div>

import { render } from 'preact';

const Foo = () => <div>foo</div>;

render(<Foo />, document.getElementById('container'));

// After render:
// <div id="container">
//  <div>foo</div>
// </div>

在 REPL 中執行

如果提供了選用的 replaceNode 參數，它必須是 containerNode 的子節點。Preact 除了推論從哪裡開始渲染之外，還會使用其 diffing 演算法來更新或取代傳遞的元素。

⚠️ replaceNode 參數會在 Preact v11 中移除。它引入了太多需要在 Preact 其他原始碼中考量的邊緣案例和錯誤。我們保留此區段是基於歷史原因，但我們不建議任何人使用第三個 replaceNode 參數。

// DOM tree before render:
// <div id="container">
//   <div>bar</div>
//   <div id="target">foo</div>
// </div>

import { render } from 'preact';

const Foo = () => <div id="target">BAR</div>;

render(
  <Foo />,
  document.getElementById('container'),
  document.getElementById('target')
);

// After render:
// <div id="container">
//   <div>bar</div>
//   <div id="target">BAR</div>
// </div>

第一個參數必須是有效的虛擬 DOM 元素，它代表元件或元素。在傳遞元件時，讓 Preact 執行實例化，而不是直接呼叫元件非常重要，否則會以意外的方式中斷

const App = () => <div>foo</div>;

// DON'T: Invoking components directly breaks hooks and update ordering:
render(App(), rootElement); // ERROR
render(App, rootElement); // ERROR

// DO: Passing components using h() or JSX allows Preact to render correctly:
render(h(App), rootElement); // success
render(<App />, rootElement); // success

hydrate()

如果您已經預先渲染或伺服器端渲染您的應用程式為 HTML，Preact 可以在瀏覽器中載入時略過大部分渲染工作。這可以透過從 render() 切換到 hydrate() 來啟用，它會略過大部分 diffing，同時仍附加事件監聽器並設定元件樹。這僅在與預先渲染或伺服器端渲染結合使用時才有效。

import { hydrate } from 'preact';

const Foo = () => <div>foo</div>;
hydrate(<Foo />, document.getElementById('container'));

在 REPL 中執行

h() / createElement()

h(type, props, ...children)

回傳一個具有給定 props 的虛擬 DOM 元素。虛擬 DOM 元素是應用程式 UI 層級中節點的輕量級描述，基本上是 { type, props } 形式的物件。

在 type 和 props 之後，任何剩餘的參數都會收集到 children 屬性中。子項可以是下列任何一種

標量值（字串、數字、布林值、null、undefined 等）
巢狀虛擬 DOM 元素
上述的無限巢狀陣列

import { h } from 'preact';

h('div', { id: 'foo' }, 'Hello!');
// <div id="foo">Hello!</div>

h('div', { id: 'foo' }, 'Hello', null, ['Preact!']);
// <div id="foo">Hello Preact!</div>

h(
    'div',
    { id: 'foo' },
    h('span', null, 'Hello!')
);
// <div id="foo"><span>Hello!</span></div>

toChildArray

此輔助函式會將 props.children 值轉換為扁平陣列，而不管其結構或巢狀。如果 props.children 已經是陣列，則會傳回一個副本。此函式在 props.children 可能不是陣列的情況下很有用，這可能會發生在 JSX 中靜態和動態表達式的某些組合中。

對於具有單一子項的虛擬 DOM 元素，props.children 是對子項的參考。當有多個子項時，props.children 永遠都是陣列。toChildArray 輔助函式提供了一種一致處理所有情況的方法。

import { toChildArray } from 'preact';

function Foo(props) {
  const count = toChildArray(props.children).length;
  return <div>I have {count} children</div>;
}

// props.children is "bar"
render(
  <Foo>bar</Foo>,
  container
);

// props.children is [<p>A</p>, <p>B</p>]
render(
  <Foo>
    <p>A</p>
    <p>B</p>
  </Foo>,
  container
);

cloneElement

cloneElement(virtualElement, props, ...children)

此函式允許您建立虛擬 DOM 元素的淺層副本。它通常用於新增或覆寫元素的 props

function Linkout(props) {
  // add target="_blank" to the link:
  return cloneElement(props.children, { target: '_blank' });
}
render(<Linkout><a href="/">home</a></Linkout>);
// <a href="/" target="_blank">home</a>

createContext

請參閱 Context 文件中的章節。

createRef

提供一種方法，可以在元素或元件呈現後參考它。

請參閱 References 文件以取得更多詳細資訊。

Fragment

一種特殊類型的元件，可以有子項，但不會呈現為 DOM 元素。片段可以傳回多個同層子項，而不需要將它們包在 DOM 容器中

import { Fragment, render } from 'preact';

render(
  <Fragment>
    <div>A</div>
    <div>B</div>
    <div>C</div>
  </Fragment>,
  document.getElementById('container')
);
// Renders:
// <div id="container>
//   <div>A</div>
//   <div>B</div>
//   <div>C</div>
// </div>

在 REPL 中執行