الخطافات المخصصة في React: كيف تكتب خطافك الخاص مع أمثلة

الخطاف المخصص دالة يبدأ اسمها بـ use وتستدعي خطافات أخرى. تكتب واحدًا عندما يحتاج مكوّنان إلى المنطق ذي الحالة نفسه: انقل استدعاءات useState وuseEffect إلى الدالة، وأرجع ما يحتاجه المكوّن، واستدعِها من كل مكوّن.

import { useState } from 'react';

function useToggle(initial = false) {
    const [on, setOn] = useState(initial);
    const toggle = () => setOn((v) => !v);
    return [on, toggle];
}

function Spoiler({ title, children }) {
    const [open, toggle] = useToggle();
    return (
        <div style={{ marginBottom: 8 }}>
            <button onClick={toggle}>{open ? 'Hide' : 'Show'} {title}</button>
            {open && <p>{children}</p>}
        </div>
    );
}

export default function App() {
    return (
        <div>
            <Spoiler title="ending">The butler did it.</Spoiler>
            <Spoiler title="sequel">The butler did it again.</Spoiler>
        </div>
    );
}

يستدعي كلا عنصري الإخفاء useToggle، وفتح أحدهما يترك الآخر مغلقًا. كل استدعاء يشغّل useState الخاص به، فيحصل كل مكوّن على قيمته الخاصة. الخطاف المخصص يشارك المنطق لا الحالة.

قواعد كتابة خطاف

• يبدأ الاسم بـ use يليها حرف كبير: useToggle وuseOnlineStatus. تستخدم قاعدة الفحص الخاصة بالخطافات البادئة لتجد استدعاءات الخطافات وتفحصها.
• يستدعي خطافًا واحدًا على الأقل. الدالة المساعدة التي لا تستدعي أي خطاف دالة عادية؛ سمّها formatDate لا useFormatDate، ليمكن استدعاؤها في أي مكان، بما في ذلك داخل الشروط.
• يتبع قواعد الخطافات: يستدعي الخطافات في مستواه الأعلى، ولا يُستدعى إلا من مكوّنات أو من خطافات مخصصة أخرى.
• يُرجع كل ما هو مفيد. المصفوفة ([on, toggle]) مفيدة عندما يعيد المستدعون تسمية القيم؛ والكائن ({ data, loading, error }) أوضح لثلاث قيم أو أكثر.

useLocalStorage: حالة تبقى بعد إعادة التحميل

ينسى useState كل شيء عند إعادة التحميل. يقرأ هذا الخطاف القيمة الابتدائية من localStorage ويكتب كل تغيير فيه.

import { useState, useEffect } from 'react';

function readStored(key, fallback) {
    try {
        const raw = window.localStorage.getItem(key);
        return raw === null ? fallback : JSON.parse(raw);
    } catch {
        console.warn('localStorage is not available, keeping the value in memory');
        return fallback;
    }
}

function useLocalStorage(key, initial) {
    const [value, setValue] = useState(() => readStored(key, initial));

    useEffect(() => {
        try {
            window.localStorage.setItem(key, JSON.stringify(value));
        } catch {
            // Storage blocked or full: the value still works for this visit
        }
    }, [key, value]);

    return [value, setValue];
}

export default function App() {
    const [name, setName] = useLocalStorage('demo-name', '');
    return (
        <div>
            <input value={name} onChange={(e) => setName(e.target.value)} placeholder="Your name" />
            <p>Hello, {name || 'stranger'}.</p>
        </div>
    );
}

تعمل المعاينة في إطار معزول يحظر فيه المتصفح localStorage، لذا سترى هنا التحذير في Console ويعود الخطاف إلى حالة عادية. أما في صفحة عادية فيبقى الاسم بعد إعادة التحميل. وكتلة try/catch ليست لهذه المعاينة فقط: أوضاع التصفح الخاص وملفات تعريف الارتباط المحظورة والحصة الممتلئة كلها تجعل التخزين يرمي خطأ في التطبيقات الحقيقية أيضًا. وتمرير دالة إلى useState يعني أن التخزين يُقرأ مرة واحدة، في العرض الأول.

useDebounce: انتظر حتى يتوقف المستخدم عن الكتابة

ينبغي ألا يطلق مربع البحث طلبًا مع كل ضغطة مفتاح. يُرجع useDebounce نسخة من قيمة لا تتحدث إلا بعد أن تتوقف عن التغير لمهلة محددة.

import { useState, useEffect } from 'react';

function useDebounce(value, delay) {
    const [debounced, setDebounced] = useState(value);

    useEffect(() => {
        const id = setTimeout(() => setDebounced(value), delay);
        return () => clearTimeout(id);
    }, [value, delay]);

    return debounced;
}

export default function App() {
    const [text, setText] = useState('');
    const query = useDebounce(text, 500);

    useEffect(() => {
        if (query) console.log('search for:', query);
    }, [query]);

    return (
        <div>
            <input value={text} onChange={(e) => setText(e.target.value)} placeholder="Search" />
            <p>Typed: {text}</p>
            <p>Debounced: {query}</p>
        </div>
    );
}

اكتب كلمة بسرعة: يتبع Typed كل مفتاح، ويلحق Debounced بعد نصف ثانية من توقفك، وتسجّل Console بحثًا واحدًا. كل ضغطة مفتاح تغيّر value، فتشغّل React دالة التنظيف (clearTimeout) قبل بدء مؤقت جديد. غيّر 500 إلى 0 فتسجّل كل ضغطة مفتاح بحثها الخاص.

useWindowWidth: اشترك مع التنظيف

الخطاف الذي يستمع إلى المتصفح يجب أن يزيل مستمعه عندما يزول المكوّن، وإلا ترك كل تركيب مستمعًا خلفه.

import { useState, useEffect } from 'react';

function useWindowWidth() {
    const [width, setWidth] = useState(window.innerWidth);

    useEffect(() => {
        const onResize = () => setWidth(window.innerWidth);
        window.addEventListener('resize', onResize);
        console.log('resize listener added');
        return () => {
            window.removeEventListener('resize', onResize);
            console.log('resize listener removed');
        };
    }, []);

    return width;
}

function WidthBadge() {
    const width = useWindowWidth();
    return <p>This frame is {width}px wide: {width < 500 ? 'narrow' : 'wide'} layout.</p>;
}

export default function App() {
    const [show, setShow] = useState(true);
    return (
        <div>
            <button onClick={() => setShow(!show)}>{show ? 'Unmount' : 'Mount'} badge</button>
            {show && <WidthBadge />}
        </div>
    );
}

غيّر حجم نافذة المتصفح فيتبعه الرقم. انقر الزر فتُظهر Console إزالة المستمع. احذف return من التأثير، ثم ركّب وأزل بضع مرات: تحصل على سطر added في كل مرة ولا سطر removed، فتتراكم المستمعات القديمة. ولقيم المتصفح مثل هذه، useSyncExternalStore هو الخطاف الذي بنته React لهذه المهمة، ومن الجيد استدعاؤه داخل خطاف مخصص.

المنطق مشترك، والحالة ليست كذلك

مكوّنان يستدعيان الخطاف نفسه يحصلان على نسختين منفصلتين من كل ما بداخله. وهذا يفاجئ من يتوقعون أن يعمل الخطاف كمتغير عام.

import { useState } from 'react';

function useCounter() {
    const [count, setCount] = useState(0);
    return [count, () => setCount((c) => c + 1)];
}

function Counter({ name }) {
    const [count, increment] = useCounter();
    return (
        <p>
            {name}: {count} <button onClick={increment}>+1</button>
        </p>
    );
}

export default function App() {
    return (
        <div>
            <Counter name="First" />
            <Counter name="Second" />
        </div>
    );
}

انقر أي زر فلا يتحرك إلا ذلك العدّاد. إذا كان ينبغي أن يُظهر الاثنان الرقم نفسه، فانقل الحالة إلى App ومررها إلى الأسفل، أو ضعها في سياق. يمكن لخطاف مخصص أن يغلّف تلك الحالة المشتركة للتسهيل (useCart() يقرأ CartContext)، لكن المشاركة تأتي من السياق لا من الخطاف.

متى تكتب خطافًا مخصصًا

استخرج خطافًا عندما تظهر المجموعة نفسها من استدعاءات الخطافات في مكوّنين، أو عندما يطول منطق التأثير في مكوّن واحد بحيث يشرحه اسم بشكل أفضل (useOnlineStatus() أوضح من عشرين سطرًا من المستمعات). لا تغلّف استدعاء useState واحدًا في خطاف لمجرد إعادة تسميته، ولا تكتب خطافات لا تفعل سوى استدعاء useEffect لضبط الحالة من props؛ بل احسب تلك القيمة أثناء العرض.