بیاموزید که چگونه همگام سازی بلادرنگ را به برنامه React Flow اضافه کنید

سلام به همگی 👋🏼

آموزش امروز شما را از طریق افزودن همگام سازی بلادرنگ به برنامه React Flow با استفاده از SuperViz راهنمایی می کند. همگام‌سازی بلادرنگ یک ویژگی کلیدی برای برنامه‌های مشترک است که به چندین کاربر اجازه می‌دهد به طور همزمان با محتوای اشتراک‌گذاری شده تعامل داشته باشند و تغییرات یکدیگر را در حین وقوع ببینند. با React Flow و SuperViz، می‌توانید فلوچارت‌های تعاملی بسازید که به‌طور زنده به‌روزرسانی می‌شوند و یک تجربه مشترک یکپارچه را ارائه می‌کنند.

ما نشان خواهیم داد که چگونه نظرات متنی و نشانگرهای ماوس را در یک برنامه React Flow ادغام کنیم و به کاربران امکان می‌دهد با به‌روزرسانی‌های بلادرنگ در نمودارهای جریانی همکاری کنند. این تنظیمات به چندین شرکت‌کننده اجازه می‌دهد تا گره‌ها را اضافه کنند، اتصالات ایجاد کنند و عناصر را در فلوچارت بکشند، با تغییراتی که فوراً برای همه کاربران جلسه قابل مشاهده است.

بیایید شروع کنیم!

پیش نیاز

برای دنبال کردن این آموزش، به یک حساب SuperViz و یک توکن توسعه دهنده نیاز دارید. اگر قبلا یک حساب کاربری و یک توکن توسعه دهنده دارید، می توانید به مرحله بعدی بروید.

یک حساب کاربری ایجاد کنید

برای ایجاد یک حساب کاربری، به https://dashboard.superviz.com/register بروید و یک حساب کاربری با استفاده از Google یا ایمیل/رمز عبور ایجاد کنید. توجه به این نکته مهم است که هنگام استفاده از ایمیل/گذرواژه، یک پیوند تأیید دریافت خواهید کرد که برای تأیید حساب خود باید روی آن کلیک کنید.

بازیابی توکن توسعه دهنده

برای استفاده از SDK، باید یک توکن توسعه دهنده ارائه دهید، زیرا این توکن برای مرتبط کردن درخواست های SDK با حساب شما ضروری است. شما می توانید توکن های توسعه و تولید SuperViz را از داشبورد بازیابی کنید.

توکن توسعه دهنده را کپی و ذخیره کنید، زیرا در مراحل بعدی این آموزش به آن نیاز خواهید داشت.

مرحله 1: برنامه React خود را راه اندازی کنید

برای شروع، باید یک پروژه React جدید راه اندازی کنید که در آن React Flow و SuperViz SDK را برای همکاری بلادرنگ یکپارچه کنیم.

1. یک پروژه React جدید ایجاد کنید

ابتدا با استفاده از Create React App با TypeScript یک برنامه React جدید ایجاد کنید.

npx create-react-app realtime-react-flow --template typescript
cd realtime-react-flow

2. کتابخانه های مورد نیاز را نصب کنید

در مرحله بعد، کتابخانه های لازم برای پروژه خود را نصب کنید:

npm install @superviz/react-sdk reactflow uuid

• @superviz/react-sdk: SuperViz SDK برای یکپارچه سازی ویژگی های همکاری بلادرنگ.
• جریان واکنش: کتابخانه ای برای ساخت فلوچارت ها و نمودارهای تعاملی.
• uuid: کتابخانه ای برای تولید شناسه های منحصر به فرد، مفید برای ایجاد شناسه های منحصر به فرد شرکت کنندگان.

3. tailwind را پیکربندی کنید

در این آموزش از فریم ورک Tailwind css استفاده می کنیم. ابتدا پکیج tailwind را نصب کنید.

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

سپس باید مسیر قالب را پیکربندی کنیم. باز کنید tailwind.config.js در ریشه پروژه و کد زیر را وارد کنید.

/** @type  {import('tailwindcss').Config} */
export  default  {
content:  [
"./index.html",
"./src/**/*.{js,ts,jsx,tsx}",
],
theme:  {
extend:  {},
},
plugins:  [],
}

سپس باید دستورات tailwind را به فایل CSS جهانی اضافه کنیم. (src/index.css)

@tailwind base;
@tailwind components;
@tailwind utilities;

4. تنظیم متغیرهای محیطی

ایجاد یک .env در ریشه پروژه خود فایل کنید و کلید توسعه دهنده SuperViz خود را اضافه کنید. این کلید برای احراز هویت برنامه شما با خدمات SuperViz استفاده می شود.

VITE_SUPERVIZ_API_KEY=YOUR_SUPERVIZ_DEVELOPER_KEY

مرحله 2: برنامه اصلی را پیاده سازی کنید

در این مرحله، منطق برنامه اصلی را برای مقداردهی اولیه SuperViz و مدیریت همگام سازی بلادرنگ در یک برنامه React Flow پیاده سازی می کنیم.

1. App Component را پیاده سازی کنید

باز کنید src/App.tsx و کامپوننت اصلی برنامه را با استفاده از SuperVizRoomProvider برای مدیریت محیط مشارکتی

import { SuperVizRoomProvider } from '@superviz/react-sdk'; 
import { v4 as generateId } from 'uuid'; 
import Room from './Room'; 
import { ReactFlowProvider } from 'reactflow'; 

const developerKey = import.meta.env.VITE_SUPERVIZ_API_KEY; 
const participantId = generateId(); 

export default function App() { 
    return ( 
        <SuperVizRoomProvider 
            developerKey={developerKey} 
            group={{ 
                id: 'react-flow-tutorial', 
                name: 'react-flow-tutorial', 
            }} 
            participant={{ 
            id: participantId, 
            name: 'Participant', 
            }} 
            roomId='react-flow-tutorial' 
        > 
            <ReactFlowProvider> 
                <Room participantId={participantId} /> 
            </ReactFlowProvider> 
        </SuperVizRoomProvider> 
    ); 
}

توضیح:

• SuperVizRoomProvider: این مؤلفه برنامه را می‌پیچد تا ویژگی‌های بلادرنگ را فعال کند و پیکربندی را برای جزئیات گروه و شرکت‌کننده فراهم می‌کند.
• توسعه دهنده کلید: کلید توسعه دهنده را از متغیرهای محیطی برای احراز هویت با SuperViz بازیابی می کند.
• ReactFlowProvider: مولفه Room را برای ارائه زمینه React Flow که وضعیت فلوچارت را مدیریت می کند، می پیچد.
• اجزای اتاق: شامل منطق ارائه فلوچارت و مدیریت تعاملات بلادرنگ است.

مرحله 3: کامپوننت اتاق را ایجاد کنید

کامپوننت Room مسئول ادغام React Flow با SuperViz خواهد بود که به کاربران امکان می دهد در زمان واقعی بر روی فلوچارت همکاری کنند.

تجزیه گام به گام جزء اتاق

بیایید مولفه Room را گام به گام تجزیه کنیم تا بفهمیم چگونه با استفاده از React Flow و SuperViz همکاری بلادرنگ را ممکن می‌سازد.

1. وارد کردن ماژول های ضروری

ابتدا ماژول ها و اجزای مورد نیاز را از هر دو وارد کنید reactflow و @superviz/react-sdk.

import  { useCallback, useEffect, MouseEvent, useRef }  from  "react";
import ReactFlow,  {
      useNodesState,
      Controls,
      Background,
      ConnectionLineType,
      addEdge,
      useEdgesState,
      ConnectionMode,
      Connection,
      useViewport,
      Node,
}  from  "reactflow";
import  "reactflow/dist/style.css";
import  {
     Comments,
     MousePointers,
     Realtime,
     useComments,
     useHTMLPin,
     useMouse,
     useRealtime,
     WhoIsOnline,
}  from  "@superviz/react-sdk";

توضیح:

• واردات ReactFlow: اجزاء و ابزارهای فلوچارت را برای ایجاد نمودارهای تعاملی ارائه دهید.
• واردات SDK SuperViz: شامل ابزارهایی برای همکاری در زمان واقعی، مانند نظرات، اشاره گرهای ماوس، و همگام سازی است.

2. گره ها و لبه های اولیه را تعریف کنید

وضعیت اولیه گره ها و لبه ها را برای فلوچارت تعریف کنید.

const initialNodes = [ 
    { id: "1", position: { x: 381, y: 265 }, data: { label: "Start" } }, 
    { id: "2", position: { x: 556, y: 335 }, data: { label: "Action" } }, 
    { id: "3", position: { x: 701, y: 220 }, data: { label: "Process" } }, 
    { id: "4", position: { x: 823, y: 333 }, data: { label: "End" } }, 
]; 

const initialEdges = [ 
    { 
        id: "e1-2", 
        source: "1", 
        target: "2", 
        type: ConnectionLineType.SmoothStep, 
        animated: true, 
    }, 
    { 
        id: "e2-3", 
        source: "2", 
        target: "3", 
        type: ConnectionLineType.SmoothStep, 
        animated: true, 
    }, 
    { 
        id: "e3-4", 
        source: "3", 
        target: "4", 
        type: ConnectionLineType.SmoothStep, 
        animated: true, 
    }, 
];

توضیح:

• گره های اولیه: آرایه ای از اشیاء که موقعیت و برچسب هر گره را در فلوچارت مشخص می کند.
• لبه های اولیه: آرایه ای از اشیاء که اتصالات بین گره ها را با استفاده از یک خط اتصال گام صاف با انیمیشن تعریف می کنند.

3. مولفه اتاق را تعریف کنید

ایجاد کنید Room جزء با خواص برای مدیریت شناسه شرکت کننده.

type  Props  =  {
     participantId:  string;
};

export  default  function  Room({ participantId }: Props)  {
    const subscribed =  useRef(false);

توضیح:

• نوع لوازم جانبی: خصوصیات مورد انتظار را برای Room جزء، از جمله participantId.
• مرجع مشترک: مرجعی برای ردیابی اینکه آیا مؤلفه در رویدادهای بلادرنگ مشترک شده است یا خیر، و اطمینان حاصل می کند که فقط یک بار مشترک می شود.

4. قلاب ها و ابزارهای بلادرنگ را تنظیم کنید

برای مدیریت نظرات، به‌روزرسانی‌های بی‌درنگ و تبدیل‌های ماوس، قلاب‌ها و ابزارهای SuperViz را راه‌اندازی کنید.

// Managing comments 
const { openThreads, closeThreads } = useComments(); 

// Managing real-time updates 
const { isReady, subscribe, unsubscribe, publish } = useRealtime("default"); 

// Managing mouse pointers 
const { transform } = useMouse(); 

// Pinning functionality for comments 
const { pin } = useHTMLPin({ 
    containerId: "react-flow-container", 
    dataAttributeName: "data-id", 
    dataAttributeValueFilters: [/.*null-(target|source)$/], 
});

توضیح:

• استفاده از نظرات: توابعی برای باز کردن و بستن موضوعات نظرات ارائه می دهد.
• useRealtime: روش‌های مدیریت رویداد در زمان واقعی مانند subscribe، unsubscribe، و publish.
• استفاده از ماوس: اجازه می دهد تا تغییرات بر اساس حرکات ماوس.
• استفاده از HTMLPin: پین کردن نظرات به عناصر خاص HTML در برنامه را فعال می کند.

5. حالت اولیه را برای گره ها و لبه ها تنظیم کنید

با استفاده از هوک های React Flow وضعیت گره ها و لبه ها را مدیریت کنید.

const  { x, y, zoom }  =  useViewport();
const  [nodes, setNodes, onNodesChange]  =  useNodesState(initialNodes);
const  [edges, setEdges, onEdgesChange]  =  useEdgesState(initialEdges);

توضیح:

• useViewport: وضعیت نمای فعلی، از جمله x و y ترجمه و zoom سطح
• useNodesState: وضعیت گره ها را با مقادیر اولیه مدیریت می کند و تغییرات را کنترل می کند.
• useEdgesState: وضعیت لبه ها را با مقادیر اولیه مدیریت می کند و تغییرات را کنترل می کند.

6. اتصالات لبه را کنترل کنید

یک تابع فراخوانی برای مدیریت اتصالات لبه جدید در فلوچارت تعریف کنید.

const onConnect = useCallback( 
    (connection: Connection) => { 
        const edge = { 
            ...connection, 
            type: ConnectionLineType.SmoothStep, 
            animated: true, 
        }; 

        setEdges((eds) => addEdge(edge, eds)); 

        publish("new-edge", { 
            edge, 
        }); 
    }, 
    [setEdges, publish] 
);

توضیح:

• onConnect: ایجاد لبه‌های جدید، به‌روزرسانی وضعیت و انتشار تغییرات برای همه شرکت‌کنندگان را مدیریت می‌کند.
• addEdge: یک لبه جدید به وضعیت فعلی اضافه می کند.

7. کشیدن گره را کنترل کنید

برای مدیریت رویدادهای کشیدن گره، یک تماس پاسخ ایجاد کنید و تغییرات را منتشر کنید.

const onNodeDrag =  useCallback(
    (_: MouseEvent, node: Node)  =>  {
        publish("node-drag",  { node });
    },
    [publish]
);

توضیح:

• onNodeDrag: به‌روزرسانی‌های موقعیت گره را هنگام کشیده شدن منتشر می‌کند و به سایر شرکت‌کنندگان اجازه می‌دهد تغییرات را ببینند.

8. Drag Over Events را مدیریت کنید

برای فعال کردن تعاملات کشیدن سفارشی، از رفتار پیش‌فرض برای رویدادهای کشیدن بر روی جلوگیری کنید.

const onDragOver =  useCallback(
    (event: React.DragEvent<HTMLButtonElement | HTMLDivElement>)  =>  {
        event.preventDefault();
        event.dataTransfer.dropEffect =  "move";
    },
    []
);

توضیح:

• onDragOver: برای ارائه بازخورد بصری در حین عملیات کشیدن، جلوه کشیدن را روی “حرکت” تنظیم می کند.

9. Viewport را در Mouse Movement به روز کنید

درگاه دید را بر اساس حرکات ماوس تنظیم کنید تا فلوچارت در یک راستا باشد.

useEffect(()  =>  {
    transform({
        translate:  {
            x: x,
            y: y,
        },
        scale: zoom,
    });
},  [x, y, zoom, transform]);

توضیح:

• useEffect: موقعیت و مقیاس درگاه دید را هنگام حرکت ماوس تغییر می‌دهد و اطمینان حاصل می‌کند که همه شرکت‌کنندگان یک نمای همگام دارند.

10. مشخصه داده را برای پین کردن SuperViz تنظیم کنید

برای پین کردن SuperViz یک ویژگی داده به ظرف React Flow اختصاص دهید.

useEffect(()  =>  {
    const element = document.querySelector(".react-flow__pane");

    if  (!element)  return;

    element.setAttribute("data-superviz-id",  "plane");
},  []);

توضیح:

• data-superviz-id: به SuperViz اجازه می‌دهد تا عناصری را که می‌توانند پین‌هایی را به آن‌ها متصل کنند، شناسایی کند و ویژگی‌های نظر را تسهیل کند.

11. مشترک شدن در رویدادهای زمان واقعی

اشتراک ها را برای گوش دادن به رویدادهای زمان واقعی و همگام سازی تغییرات وضعیت تنظیم کنید.

useEffect(() => { 
    if (subscribed.current) return; 

    const centerNodes = () => { 
        const centerButton = document.querySelector( 
            ".react-flow__controls-fitview" 
        ) as HTMLButtonElement; 
        centerButton?.click(); 
    }; 

    centerNodes(); 

    // Subscribe to new-edge events 
    subscribe("new-edge", ({ data, participantId: senderId }) => { 
        if (senderId === participantId) return; 

        setEdges((eds) => addEdge(data.edge, eds)); 
    }); 


    // Subscribe to node-drag events 
    subscribe( 
        "node-drag", 
        ({ 
            data, 
            participantId: senderId,
        }: { 
            data: { node: Node }; 
            participantId: string; 
        }) => { 
            if (senderId === participantId) return; 

            setNodes((nds) => 
                nds.map((node) => 
                    node.id === data.node.id ? { ...node, ...data.node } : node 
                ) 
            ); 
        } 
    ); 

    subscribed.current = true; 
}, [isReady, setEdges, setNodes, unsubscribe, subscribe, participantId]);

توضیح:

• اشتراک: به رویدادهای خاص گوش می دهد (new-edge، node-drag) و وضعیت محلی را بر اساس داده های دریافتی به روز می کند.
• لغو اشتراک: اشتراک ها را در صورت عدم نیاز پاک کنید.

12. کامپوننت اتاق را رندر کنید

در نهایت کامپوننت Room را با ویژگی های React Flow و SuperViz رندر کنید.

return ( 
    <div className="w-full h-full bg-gray-200 flex items-center justify-center flex-col">
        <header className="w-full p-5 bg-purple-400 flex items-center justify-between"> 
            <h1 className="text-white text-2xl font-bold">React Flow + SuperViz</h1> 
            <div id="comments" className="flex gap-2"></div> 
        </header> 
        <main className="flex-1 w-full h-full"> 
            <div id="react-flow-container" className="w-full h-full"> 
                <ReactFlow 
                    nodes={nodes} 
                    onNodeDrag={onNodeDrag} 
                    edges={edges} 
                    onConnect={onConnect} 
                    onNodesChange={onNodesChange} 
                    onEdgesChange={onEdgesChange} 
                    onDragOver={onDragOver} 
                    connectionMode={ConnectionMode.Loose} 
                > 
                    <Controls showFitView={false} /> 
                    <Background /> 
                </ReactFlow> 
            </div> 

            {/* SuperViz Components */} 
            <Realtime /> 
            <WhoIsOnline position="comments" /> 
            <Comments 
                pin={pin} 
                position="left" 
                buttonLocation="comments" 
                onPinActive={openThreads} 
                onPinInactive={closeThreads} 
            /> 
            <MousePointers elementId="react-flow-container" /> 
        </main> 
    </div>  
);

توضیح:

• ReactFlow: فلوچارت را با گره ها، لبه ها و کنترل کننده های تعامل نمایش می دهد.
• زمان واقعی: هماهنگ‌سازی بی‌درنگ وضعیت بین شرکت‌کنندگان را مدیریت می‌کند.
• WhoIsOnline: لیستی از شرکت کنندگان آنلاین در جلسه را نشان می دهد.
• نظرات: امکان افزودن و مشاهده نظرات متنی را فراهم می کند.
• ماوس اشاره گر: نشانگرهای ماوس را در زمان واقعی برای همه شرکت کنندگان نمایش می دهد.

مرحله 4: اجرای برنامه

1. برنامه React را اجرا کنید

برای اجرای برنامه خود، از دستور زیر در فهرست پروژه خود استفاده کنید:

npm run dev

این دستور سرور توسعه را راه اندازی می کند و برنامه شما را در مرورگر وب پیش فرض باز می کند. می‌توانید با فلوچارت تعامل داشته باشید و به‌روزرسانی‌ها را در زمان واقعی در بین چندین شرکت‌کننده مشاهده کنید.

2. برنامه را تست کنید

• فلوچارت مشارکتی: برنامه را در چندین پنجره مرورگر یا برگه باز کنید تا چندین شرکت کننده را شبیه سازی کنید و بررسی کنید که تغییرات ایجاد شده توسط یک شرکت کننده در زمان واقعی برای دیگران منعکس می شود.
• به روز رسانی در زمان واقعی: پاسخگویی برنامه را آزمایش کنید تا ببینید آیا به درستی با اقدامات انجام شده توسط سایر کاربران همگام می شود یا خیر.

خلاصه

در این آموزش، ما یک برنامه فلوچارت مشترک با استفاده از React Flow و SuperViz برای همگام سازی بلادرنگ ساختیم. ما یک برنامه React را پیکربندی کردیم تا تعاملات نود و لبه را مدیریت کند و چندین کاربر را قادر می‌سازد تا به طور یکپارچه در یک نمودار مشترک با یکدیگر همکاری کنند. این راه‌اندازی را می‌توان برای تناسب با سناریوهای مختلف که در آن به همکاری بلادرنگ و تجسم گردش کار نیاز است، گسترش داد و سفارشی کرد.

برای جزئیات بیشتر می توانید کد کامل و نمونه های بیشتر را در مخزن GitHub بررسی کنید.

به ما بپیوندید: SuperViz Hackathon 2.0: AI با RealTime ملاقات می کند

برای شرکت در Super Hackathon 2.0 ما در اکتبر امسال آماده شوید تا راه حل های نوآورانه ارتباط هوش مصنوعی خود را در زمان واقعی به نمایش بگذارید! به میزبانی SuperViz و با جوایز 5000 دلاری، ما شما را به چالش می‌کشیم تا هوش مصنوعی را با پلتفرم بلادرنگ SuperViz ادغام کنید و مرزهای ارتباطات تعاملی را جابجا کنید.

آماده پیوستن هستید؟ برای ثبت نام و به روز ماندن به وب سایت Super Hackathon 2.0 مراجعه کنید.