Серверные функции

Серверные компоненты React

Когда серверная функция определяется с помощью директивы "use server", ваш фреймворк автоматически создаст ссылку на серверную функцию и передаст эту ссылку клиентскому компоненту. Когда функция вызывается на клиенте, React отправит запрос на сервер для выполнения функции и вернёт результат.

Серверные функции можно создавать в серверных компонентах и передавать клиентским компонентам через свойства, либо импортировать и использовать в клиентских компонентах.

Использование

Создание серверной функции в серверном компоненте

Серверные компоненты могут определять серверные функции с помощью директивы "use server":

// Server Component
import Button from './Button';

function EmptyNote () {
  async function createNoteAction() {
    // Server Function
    'use server';
    
    await db.notes.create();
  }

  return <Button onClick={createNoteAction}/>;
}

Когда React отрисовывает серверный компонент EmptyNote, он создаёт ссылку на функцию createNoteAction и передаёт её клиентскому компоненту Button. Когда пользователь нажимает кнопку, React отправляет запрос на сервер, чтобы выполнить функцию createNoteAction с указанной ссылкой:

"use client";

export default function Button({onClick}) { 
  console.log(onClick); 
  // {$$typeof: Symbol.for("react.server.reference"), $$id: 'createNoteAction'}
  return <button onClick={() => onClick()}>Create Empty Note</button>
}

Подробнее см. документацию по "use server".

Импорт серверных функций в клиентские компоненты

Клиентские компоненты могут импортировать серверные функции из файлов, использующих директиву "use server":

"use server";

export async function createNote() {
  await db.notes.create();
}

Когда сборщик создаёт клиентский компонент EmptyNote, он создаёт в сборке ссылку на функцию createNote. Когда пользователь нажимает button, React отправляет запрос на сервер, чтобы выполнить функцию createNote с указанной ссылкой:

"use client";
import {createNote} from './actions';

function EmptyNote() {
  console.log(createNote);
  // {$$typeof: Symbol.for("react.server.reference"), $$id: 'createNote'}
  <button onClick={() => createNote()} />
}

Подробнее см. документацию по "use server".

Серверные функции в действиях

Серверные функции можно вызывать из действий на клиенте:

"use server";

export async function updateName(name) {
  if (!name) {
    return {error: 'Name is required'};
  }
  await db.users.updateName(name);
}

"use client";

import {updateName} from './actions';

function UpdateName() {
  const [name, setName] = useState('');
  const [error, setError] = useState(null);

  const [isPending, startTransition] = useTransition();

  const submitAction = async () => {
    startTransition(async () => {
      const {error} = await updateName(name);
      if (error) {
        setError(error);
      } else {
        setName('');
      }
    })
  }
  
  return (
    <form action={submitAction}>
      <input type="text" name="name" disabled={isPending}/>
      {error && <span>Failed: {error}</span>}
    </form>
  )
}

Это позволяет получить доступ к состоянию isPending серверной функции, обернув её в действие на клиенте.

Подробнее см. документацию о том, как вызывать серверную функцию вне <form>

Серверные функции в действиях формы

Серверные функции работают с новыми возможностями форм в React 19.

Вы можете передать серверную функцию форме, чтобы автоматически отправлять её на сервер:

"use client";

import {updateName} from './actions';

function UpdateName() {
  return (
    <form action={updateName}>
      <input type="text" name="name" />
    </form>
  )
}

Если отправка формы прошла успешно, React автоматически сбросит её. Добавьте useActionState, чтобы получить доступ к состоянию ожидания, последнему ответу или обеспечить постепенное улучшение.

Подробнее см. документацию о серверных функциях в формах.

Серверные функции с useActionState

Вы можете вызывать серверные функции с помощью useActionState — это удобно, когда нужен доступ только к состоянию ожидания действия и последнему возвращённому ответу:

"use client";

import {updateName} from './actions';

function UpdateName() {
  const [state, submitAction, isPending] = useActionState(updateName, {error: null});

  return (
    <form action={submitAction}>
      <input type="text" name="name" disabled={isPending}/>
      {state.error && <span>Failed: {state.error}</span>}
    </form>
  );
}

При использовании useActionState с серверными функциями React также автоматически повторно отправит формы, отправленные до завершения гидратации. Это позволяет пользователям взаимодействовать с приложением ещё до завершения гидратации.

Подробнее см. документацию по useActionState.

Постепенное улучшение с помощью useActionState

Серверные функции также поддерживают постепенное улучшение при использовании третьего аргумента useActionState.

"use client";

import {updateName} from './actions';

function UpdateName() {
  const [, submitAction] = useActionState(updateName, null, `/name/update`);

  return (
    <form action={submitAction}>
      ...
    </form>
  );
}

Если для useActionState указан URL-адрес перенаправления, React перенаправит пользователя на этот URL, если форма отправлена до загрузки JavaScript-бандла.

Подробнее см. документацию по useActionState.