'use server'

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

Ссылка

'use server'

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

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

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

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

Ограничения

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

Соображения безопасности

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

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

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

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

Вот поддерживаемые типы аргументов Действий сервера:

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

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

• Элементы 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>

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

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

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 возвращённое обещание.