'use server'

React Server Components

• Справочник
  • 'use server'
  • Учёт мер безопасности
  • Сериализуемые аргументы и возвращаемые значения
• Использование
  • Функции сервера в формах
  • Вызов функции сервера вне <form>

Справочник

'use server'

Добавьте 'use server' в начале тела асинхронной функции, чтобы отметить функцию как вызываемую клиентом. Мы называем эти функции Функциями сервера.

async function addToCart(data) {
  'use server';
  // ...
}

При вызове функции сервера на клиенте будет отправлен сетевой запрос на сервер, включающий сериализованную копию любых переданных аргументов. Если функция сервера возвращает значение, это значение будет сериализовано и возвращено клиенту.

Вместо отдельной маркировки функций с 'use server', вы можете добавить директиву в начало файла, чтобы отметить все экспорты в этом файле как функции сервера, которые можно использовать в любом месте, включая импорт в клиентский код.

Ограничения

• 'use server' должны быть в самом начале функции или модуля; выше любого другого кода, включая импорты (комментарии выше директив допустимы). Они должны быть написаны с одинарными или двойными кавычками, а не обратными апострофами.
• 'use server' могут использоваться только в файлах на стороне сервера. Результирующие функции сервера могут передаваться клиентским компонентам через свойства. Смотрите поддерживаемые типы для сериализации.
• Для импорта функций сервера из клиентского кода, директива должна использоваться на уровне модуля.
• Поскольку основанные сетевые вызовы всегда асинхронны, 'use server' может использоваться только с асинхронными функциями.
• Всегда рассматривайте аргументы функций сервера как ненадёжные входные данные и авторизуйте любые изменения. Смотрите учёт мер безопасности.
• Функции сервера должны вызываться в Transition. Функции сервера, переданные в <form action> или formAction, автоматически будут вызваны в рамках транзакции.
• Функции сервера предназначены для изменений, обновляющих состояние на стороне сервера; они не рекомендуются для получения данных. Соответственно, фреймворки, реализующие функции сервера, обычно обрабатывают одно действие за раз и не имеют способа кэширования возвращаемого значения.

Учёт мер безопасности

Аргументы функций сервера полностью контролируются клиентом. Для обеспечения безопасности всегда рассматривайте их как ненадёжные входные данные и убедитесь, что аргументы валидированы и экранированы должным образом.

В любой функции сервера убедитесь, что вошедший пользователь имеет право выполнить это действие.

Сериализуемые аргументы и возвращаемые значения

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

Вот поддерживаемые типы аргументов для функций сервера:

• Примитивы
  • строка
  • число
  • bigint
  • булево
  • неопределено
  • null
  • символ, только символы, зарегистрированные в глобальной базе символов Symbol через Symbol.for
• Итерируемые объекты, содержащие сериализуемые значения
  • Строка
  • Массив
  • Map
  • Множество
  • TypedArray и ArrayBuffer
• Дата
• FormData
• Простые объекты: созданные с помощью инициализаторов объектов, с сериализуемыми свойствами
• Функции, являющиеся функциями сервера
• Promises

Следующие типы не поддерживаются:

• Элементы React или JSX
• Функции, включая функции компонентов или любые другие функции, которые не являются функциями сервера
• Классы
• Объекты, которые являются экземплярами любого класса (кроме встроенных), или объекты с null прототипом
• Символы, не зарегистрированные глобально, например Symbol('my new symbol')
• События из обработчиков событий

Поддерживаемые сериализуемые возвращаемые значения идентичны сериализуемым свойствам для граничного клиентского компонента.

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

Функции сервера в формах

Наиболее распространённый случай использования функций сервера — вызов функций, изменяющих данные. В браузере элемент формы HTML традиционно используется для отправки пользователем мутации. В React Server Components React вводит первоклассную поддержку функций сервера в качестве действий в формах .

Вот форма, которая позволяет пользователю запросить имя пользователя.

// App.js

async function requestUsername(formData) {
  'use server';
  const username = formData.get('username');
  // ...
}

export default function App() {
  return (
    <form action={requestUsername}>
      <input type="text" name="username" />
      <button type="submit">Request</button>
    </form>
  );
}

В этом примере requestUsername — функция сервера, переданная в <form>. Когда пользователь отправляет эту форму, происходит сетевой запрос к функции сервера requestUsername. При вызове функции сервера в форме React предоставляет форму FormData в качестве первого аргумента функции сервера.

Передавая функцию сервера в форму action, React может постепенно улучшать форму. Это означает, что формы можно отправлять до загрузки JavaScript-пакета.

Обработка возвращаемых значений в формах

В форме запроса имени пользователя может возникнуть случай, когда имя пользователя недоступно. requestUsername должен сообщить об успехе или неудаче.

Для обновления пользовательского интерфейса на основе результата функции сервера с поддержкой постепенного улучшения используйте useActionState.

// requestUsername.js
'use server';

export default async function requestUsername(formData) {
  const username = formData.get('username');
  if (canRequest(username)) {
    // ...
    return 'successful';
  }
  return 'failed';
}

// UsernameForm.js
'use client';

import { useActionState } from 'react';
import requestUsername from './requestUsername';

function UsernameForm() {
  const [state, action] = useActionState(requestUsername, null, 'n/a');

  return (
    <>
      <form action={action}>
        <input type="text" name="username" />
        <button type="submit">Request</button>
      </form>
      <p>Last submission request returned: {state}</p>
    </>
  );
}

Обратите внимание, что, как и большинство хуков, useActionState может быть вызван только в клиентском коде.

Вызов функции сервера вне <form>

Функции сервера предоставляются как серверные точки доступа и могут вызываться в любом месте клиентского кода.

При использовании функции сервера вне формы форма, вызовите функцию сервера в Transition, что позволяет отображать индикатор загрузки, показывать оптимистические обновления состояния и обрабатывать непредвиденные ошибки. Формы автоматически оборачивают функции сервера в переходы.

import incrementLike from './actions';
import { useState, useTransition } from 'react';

function LikeButton() {
  const [isPending, startTransition] = useTransition();
  const [likeCount, setLikeCount] = useState(0);

  const onClick = () => {
    startTransition(async () => {
      const currentCount = await incrementLike();
      setLikeCount(currentCount);
    });
  };

  return (
    <>
      <p>Total Likes: {likeCount}</p>
      <button onClick={onClick} disabled={isPending}>Like</button>;
    </>
  );
}

// actions.js
'use server';

let likeCount = 0;
export default async function incrementLike() {
  likeCount++;
  return likeCount;
}

Чтобы прочитать возвращаемое значение функции сервера, вам необходимо await вернуть promise.