React useActionState Hook'u: Formlar, Hatalar ve Bekleme

Q: useActionState ile useFormState arasındaki fark nedir?

Aynı hook'turlar. React canary sürümlerinde react-dom içinde useFormState olarak geldi, React 19 için useActionState olarak yeniden adlandırılıp react'e taşındı ve aynı anda isPending değerini kazandı.

Q: useActionState'i bir form olmadan kullanabilir miyim?

Evet. Döndürülen action'ı kendin, startTransition içinde çağır; örneğin bir düğmenin onClick'inden. Bir transition olmadan isPending doğru güncellenmez ve React geliştirmede bir hata kaydeder.

useActionState, async bir fonksiyonu (bir action) çalıştıran, ne döndürürse onu state olarak saklayan ve hâlâ çalışıp çalışmadığını söyleyen bir React 19 hook'udur. Onu const [state, formAction, isPending] = useActionState(action, initialState) olarak çağırır ve formAction'ı bir <form>'a aktarırsın.

import { useActionState } from 'react';

function subscribe(email) {
    // Stands in for a real request
    return new Promise((resolve) => setTimeout(resolve, 1000));
}

async function joinList(previousState, formData) {
    const email = formData.get('email');
    if (!email.includes('@')) {
        return { ok: false, message: 'That does not look like an email.' };
    }
    await subscribe(email);
    return { ok: true, message: `Subscribed ${email}.` };
}

export default function App() {
    const [state, formAction, isPending] = useActionState(joinList, { ok: false, message: '' });

    return (
        <form action={formAction}>
            <input name="email" placeholder="you@example.com" />
            <button type="submit" disabled={isPending}>
                {isPending ? 'Subscribing...' : 'Subscribe'}
            </button>
            {state.message && (
                <p style={{ color: state.ok ? 'green' : 'crimson' }}>{state.message}</p>
            )}
        </form>
    );
}

Önce boş formu gönder: action bir hata nesnesi döndürür ve mesaj görünür. Sonra @ içeren bir adres yaz ve yeniden gönder. Bir saniye boyunca düğme "Subscribing..." der ve devre dışıdır.

Sözdizimi

const [state, formAction, isPending] = useActionState(action, initialState, permalink?);

action çalıştırılacak fonksiyondur. React onu action(previousState, ...args) olarak çağırır. Ne döndürürse (ya da async ise neye resolve olursa) yeni state o olur.
initialState, action hiç çalışmadan önceki state'tir. Action'ın döndürdüğü şekli kullan, böylece bileşen ilk render'da da state.message'ı okuyabilir.
state en son sonuçtur.
formAction, action'ının sarılmış bir sürümüdür. Onu <form action>'a ya da <button formAction>'a aktar veya kendin çağır.
isPending, action başladığı andan bitene kadar true'dur.
permalink isteğe bağlıdır ve yalnızca bir framework'teki Server Functions için önemlidir: JavaScript yüklenmeden gönderilirse formun gitmesi gereken URL.

Action önceki state'i ilk argüman olarak alır. Bir formu taşırken en yaygın hata budur: async function save(formData) yazmak sana formData içinde eski state'i verir ve formData.get hata fırlatır.

Formu FormData ile okumak

formAction bir formun action'ı olarak kullanıldığında React action'ını formun FormData'sı ile çağırır. name'i olan her alan onun içindedir. Input'lar için useState'e ya da bir onChange işleyicisine ihtiyacın yoktur ve e.preventDefault() çağırmazsın: gönderme olayını React ele alır.

import { useActionState } from 'react';

async function order(previousState, formData) {
    const entries = Object.fromEntries(formData);
    console.log('form data:', entries);
    return { count: previousState.count + 1, last: entries };
}

export default function App() {
    const [state, formAction] = useActionState(order, { count: 0, last: null });

    return (
        <form action={formAction}>
            <input name="dish" defaultValue="Ramen" />
            <select name="size" defaultValue="large">
                <option value="small">Small</option>
                <option value="large">Large</option>
            </select>
            <label>
                <input type="checkbox" name="spicy" defaultChecked /> Spicy
            </label>
            <button type="submit">Order</button>
            <p>Orders placed: {state.count}</p>
            {state.last && <p>Last: {state.last.size} {state.last.dish}</p>}
        </form>
    );
}

Spicy'nin işaretini kaldır ve yeniden gönder: spicy anahtarı kaydedilen veriden kaybolur, çünkü işaretlenmemiş bir onay kutusu hiçbir şey göndermez. Action ayrıca bir eklemek için previousState.count'u okur; önceki state'in önce gelmesinin nedeni budur.

Doğrulama hatalarını döndürmek

Doğrulama action'a aittir. Hataları state'in parçası olarak döndür ve formun onları geri koyabilmesi için kullanıcının yazdığı değerleri de döndür. Bir form action'ı bittikten sonra React formun kontrolsüz alanlarını sıfırlar, bu yüzden defaultValue={state.values...} olmayan bir alan başarısız bir gönderimden sonra boş gelirdi.

import { useActionState } from 'react';

function createAccount(name) {
    // Stands in for a real request
    return new Promise((resolve) => setTimeout(() => resolve({ id: 7, name }), 800));
}

async function signUp(previousState, formData) {
    const values = { name: formData.get('name'), password: formData.get('password') };
    const errors = {};
    if (values.name.trim().length < 2) errors.name = 'At least 2 characters.';
    if (values.password.length < 8) errors.password = 'At least 8 characters.';
    if (Object.keys(errors).length > 0) {
        return { values, errors, user: null };
    }
    const user = await createAccount(values.name);
    return { values: { name: '', password: '' }, errors: {}, user };
}

const initial = { values: { name: '', password: '' }, errors: {}, user: null };

export default function App() {
    const [state, formAction, isPending] = useActionState(signUp, initial);

    if (state.user) return <p>Welcome, {state.user.name} (account #{state.user.id}).</p>;

    return (
        <form action={formAction} style={{ display: 'grid', gap: 6, maxWidth: 240 }}>
            <input name="name" placeholder="Name" defaultValue={state.values.name} />
            {state.errors.name && <small style={{ color: 'crimson' }}>{state.errors.name}</small>}
            <input name="password" type="password" placeholder="Password" defaultValue={state.values.password} />
            {state.errors.password && <small style={{ color: 'crimson' }}>{state.errors.password}</small>}
            <button type="submit" disabled={isPending}>{isPending ? 'Creating...' : 'Create account'}</button>
        </form>
    );
}

Tek harfli bir ad ve kısa bir parola yaz, sonra gönder. İki hata da görünür ve iki alan da yazdığını korur. defaultValue={state.values.name}'i kaldır ve yeniden gönder: ad alanı hatadan sonra kendini boşaltır.

Gerçek bir uygulamada son hakem olarak sunucuyu tut. İstemci kontrolleri hızlı geri bildirim verir, ama herkes senin formun olmadan bir istek gönderebilir.

Action'ı bir formun dışında çağırmak

formAction bir fonksiyondur, bu yüzden bir düğme ya da bir efekt de onu çağırabilir. Onu kendin çağırdığında çağrıyı startTransition ile sar. Form bunu senin için yapar; düz bir onClick yapmaz ve bir transition olmadan isPending doğru güncellenmez (React geliştirmede bununla ilgili bir hata kaydeder).

import { startTransition, useActionState } from 'react';

function fetchNextPage(page) {
    // Stands in for a real request
    return new Promise((resolve) =>
        setTimeout(() => resolve([`Item ${page * 2 - 1}`, `Item ${page * 2}`]), 700),
    );
}

async function loadMore(previousState) {
    const page = previousState.page + 1;
    const items = await fetchNextPage(page);
    return { page, items: [...previousState.items, ...items] };
}

export default function App() {
    const [state, load, isPending] = useActionState(loadMore, { page: 0, items: [] });

    return (
        <div>
            <ul>
                {state.items.map((item) => (
                    <li key={item}>{item}</li>
                ))}
            </ul>
            <button onClick={() => startTransition(() => load())} disabled={isPending}>
                {isPending ? 'Loading...' : 'Load more'}
            </button>
        </div>
    );
}

Load more'a birkaç kez tıkla. Her çağrı bir öncekinin döndürdüğü state'ten başlar, bu yüzden sayfalar sırayla eklenir. Action hâlâ çalışırken onu yeniden çağırırsan React çağrıyı kuyruğa alır ve mevcut olandan sonra, her birini en son state ile çalıştırır.

useActionState nereden geldi

React 19 yayınlanmadan önce bu hook, canary derlemelerinde react-dom'dan import edilen useFormState olarak mevcuttu. useActionState olarak yeniden adlandırıldı, react'e taşındı ve isPending değerini aldı. Bunun gibi eski bir kod bulursan çözüm import ve addır:

// React canary, before 19
import { useFormState } from 'react-dom';
const [state, formAction] = useFormState(action, initialState);

// React 19
import { useActionState } from 'react';
const [state, formAction, isPending] = useActionState(action, initialState);

Derinde iç içe geçmiş bir gönder düğmesinde bekleme durumu göstermek için react-dom'dan useFormStatus, ebeveyn formun durumunu props olmadan okur. React 19 genel bakışı onu diğer form özellikleriyle birlikte listeliyor.

Hatalar ve ne zaman başka bir şey kullanılmalı

Action hata fırlatırsa React state'i güncellemek yerine en yakın error boundary'yi gösterir. Kullanıcının düzeltebileceği hatalar için, örneğin doğrulama ya da alınmış bir kullanıcı adı, onları kayıt örneğindeki gibi state olarak döndür. Gerçek başarısızlıkların hata fırlatmasına izin ver.

useActionState bir action'ın sonucu içindir. Action çalışırken anında güncellenen bir değer için, örneğin tıklamada artması gereken bir beğeni sayısı, onu useOptimistic ile birleştir. Her tuş vuruşunda değişen ve render sırasında okunan girdi için düz useState ve kontrollü bir input hâlâ doğru araçtır.

Yaygın hatalar

Önceki state parametresini unutmak. async function save(formData), formData içinde önceki state'i alır. Bir form için imza her zaman (previousState, formData)'dır.

name'i olmayan input'lar. FormData yalnızca name özelliği olan alanları içerir. Yalnızca bir id'si olan bir alan formData.get(...)'te yoktur ve bu null döndürür.

Her yerde kontrollü input'lar. Bir form action'ının içinde hâlâ value ve onChange kullanabilirsin, ama zorunda değilsin. name ve defaultValue içeren kontrolsüz alanlar action'lar için daha basit bir eşleşmedir ve React'in gönderim sonrası sıfırlaması yalnızca kontrolsüz alanları etkiler.

Action içinde state okumak. Bileşendeki state, işleyiciyi oluşturan render'daki değerdir. Action'ın içinde, birkaç çağrı kuyruğa alınmış olsa bile her zaman bir önceki çağrının sonucu olan previousState'i kullan.

Beklenen hatalar için hata fırlatmak. Fırlatılan bir hata formu en yakın error boundary ile değiştirir. Yanlış bir parola bir çökme değildir; onu state olarak döndür.

Sıkça Sorulan Sorular

useActionState ne döndürür?

Üç öğeli bir dizi: mevcut state (action'ın en son döndürdüğü değer ya da action hiç çalışmadıysa başlangıç state'i), bir forma aktarmak ya da kendin çağırmak için yeni bir action ve action çalışırken true olan isPending.

Action hangi argümanları alır?

Önce önceki state'i, sonra action neyle çağrıldıysa onu. Bir <form action={formAction}> içinde o ikinci argüman formun FormData'sıdır.

useActionState ile useFormState arasındaki fark nedir?

Aynı hook'turlar. React canary sürümlerinde react-dom içinde useFormState olarak geldi, React 19 için useActionState olarak yeniden adlandırılıp react'e taşındı ve aynı anda isPending değerini kazandı.

useActionState'i bir form olmadan kullanabilir miyim?

Evet. Döndürülen action'ı kendin, startTransition içinde çağır; örneğin bir düğmenin onClick'inden. Bir transition olmadan isPending doğru güncellenmez ve React geliştirmede bir hata kaydeder.

Formum gönderildikten sonra neden temizleniyor?

Bir form action'ı bittikten sonra React, bir tarayıcının normal bir gönderimden sonra yaptığı gibi formun kontrolsüz alanlarını sıfırlar. Bir hatadan sonra bir değeri korumak için onu state'te döndür ve alanın defaultValue'suna aktar.

İlgili kavramlar