操作

React 应用中的一个常见用例是执行数据突变，然后更新响应状态。例如，当用户提交表单以更改其姓名时，您将发出 API 请求，然后处理响应。过去，您需要手动处理待处理状态、错误、乐观更新和顺序请求。

例如，你可以在 `useState` 中处理待处理和错误状态：

// Before Actions
function UpdateName({}) {
  const [name, setName] = useState("");
  const [error, setError] = useState(null);
  const [isPending, setIsPending] = useState(false);

  const handleSubmit = async () => {
    setIsPending(true);
    const error = await updateName(name);
    setIsPending(false);
    if (error) {
      setError(error);
      return;
    } 
    redirect("/path");
  };

  return (
    

       setName(event.target.value)} />
      
        Update
      
      {error && 
{error}
}
    
  );
}

在 React 19 中，我们添加了在转换中使用异步函数的支持，以自动处理待处理状态、错误、表单和乐观更新。

例如，您可以使用 `useTransition` 来处理待处理状态：

// Using pending state from Actions
function UpdateName({}) {
  const [name, setName] = useState("");
  const [error, setError] = useState(null);
  const [isPending, startTransition] = useTransition();

  const handleSubmit = () => {
    startTransition(async () => {
      const error = await updateName(name);
      if (error) {
        setError(error);
        return;
      } 
      redirect("/path");
    })
  };

  return (
    

       setName(event.target.value)} />
      
        Update
      
      {error && 
{error}
}
    
  );
}

异步转换将立即将“isPending”状态设置为 true，发出异步请求，并在任何转换后将“isPending”切换为 false。这允许您在数据发生变化时保持当前 UI 响应和交互。

笔记

按照惯例，使用异步转换的功能称为“动作”。

操作会自动为您管理提交数据：

待处理状态：操作提供待处理状态，该状态从请求开始时开始，并在提交最终状态更新时自动重置。

乐观更新：操作支持新的“useOptimistic”钩子，因此您可以在提交请求时向用户显示即时反馈。

错误处理：操作提供错误处理，以便您可以在请求失败时显示错误边界，并自动将乐观更新恢复为其原始值。

形式：` ` 元素现在支持将函数传递给 `action` 和 `formAction` 属性。将函数传递给 `action` 属性默认使用 Actions，并在提交后自动重置表单。

在 Actions 的基础上，React 19 引入了 `useOptimistic` 来管理乐观更新，并引入了新的钩子 `React.useActionState` 来处理 Actions 的常见情况。在 `react-dom` 中，我们添加了 ``Actions 来自动管理表单，并添加了 `useFormStatus` 来支持表单中 Actions 的常见情况。

在 React 19 中，上面的例子可以简化为：

// Using 
 Actions and useActionState
function ChangeName({ name, setName }) {
  const [error, submitAction, isPending] = useActionState(
    async (previousState, formData) => {
      const error = await updateName(formData.get("name"));
      if (error) {
        return error;
      }
      redirect("/path");
      return null;
    },
    null,
  );

  return (
    
      
      Update
      {error && 
{error}
}
    
  );
}

在下一部分中，我们将分解 React 19 中的每个新 Action 功能。

新钩子：useActionState

为了使 Actions 更容易处理常见情况，我们添加了一个名为“useActionState”的新钩子：

const [error, submitAction, isPending] = useActionState(
  async (previousState, newName) => {
    const error = await updateName(newName);
    if (error) {
      // You can return any result of the action.
      // Here, we return only the error.
      return error;
    }

    // handle success
    return null;
  },
  null,
);

`useActionState` 接受一个函数（“Action”），并返回一个要调用的包装的 Action。这是因为 Actions 是组合而成的。当调用包装的 Action 时，`useActionState` 将返回 Action 的最后结果作为 `data`，并将 Action 的待处理状态作为 `pending`。

笔记

React.useActionState 以前在 Canary 版本中被称为 ReactDOM.useFormState，但我们已将其重命名并弃用了 useFormState。

请参阅#28491 以了解更多信息。

有关更多信息，请参阅“useActionState”文档。

React DOM：操作

Actions 还与 React 19 的 ``react-dom`` 新功能集成。我们添加了将函数作为 ``、`` 的 ``action`` 和 ``formAction`` 属性传递的支持。`，和 `` 元素使用以下操作自动提交表单：

当 `` Action 成功执行时，React 会自动重置不受控组件的表单。如果需要手动重置 ``，可以调用新的 ``requestFormReset`` React DOM API。

有关详细信息，请参阅 `react-dom` 文档中的 ``, ``，和 ``。

React DOM：新钩子：useFormStatus

在设计系统中，编写需要访问其所在位置信息的设计组件很常见，而无需深入研究组件的 props。这可以通过 Context 完成，但为了使常见情况更容易，我们添加了一个新的钩子 `useFormStatus`：

import {useFormStatus} from 'react-dom';

function DesignButton() {
  const {pending} = useFormStatus();
  return 
}

`useFormStatus` 读取父级的状态，就好像表单是一个上下文提供程序一样。

欲了解更多信息，请参阅 `react-dom` 文档中的 `useFormStatus`。

新的钩子：useOptimistic

执行数据变异时的另一个常见 UI 模式是在异步请求进行时乐观地显示最终状态。在 React 19 中，我们添加了一个名为“useOptimistic”的新钩子以使此操作更容易：

function ChangeName({currentName, onUpdateName}) {
  const [optimisticName, setOptimisticName] = useOptimistic(currentName);

  const submitAction = async formData => {
    const newName = formData.get("name");
    setOptimisticName(newName);
    const updatedName = await updateName(newName);
    onUpdateName(updatedName);
  };

  return (
    
      
Your name is: {optimisticName}
      

        Change Name:
        
      
    
  );
}

`useOptimistic` 钩子将在 `updateName` 请求进行时立即渲染 `optimisticName`。当更新完成或出错时，React 将自动切换回 `currentName` 值。

有关更多信息，请参阅“useOptimistic”的文档。

新 API：使用

在 React 19 中，我们引入了一个新的 API 来读取渲染中的资源：“use”。

例如，你可以使用 `use` 读取一个承诺，React 将会暂停直到该承诺解决：

import {use} from 'react';

function Comments({commentsPromise}) {
  // `use` will suspend until the promise resolves.
  const comments = use(commentsPromise);
  return comments.map(comment => 
{comment}
);
}

function Page({commentsPromise}) {
  // When `use` suspends in Comments,
  // this Suspense boundary will be shown.
  return (
    Loading...