Útmutató: Közönségfunkciók használata a Dinamikus keretrendszer

Cikk
10/24/2023

Ebben az oktatóanyagban megismerheti, hogyan használhatja a Dinamikus keretrendszer célközönséget a React használatával a tárolóhoz csatlakozó felhasználók vizuális bemutatójának létrehozásához. A célközönség objektum a tárolóhoz csatlakoztatott összes felhasználóval kapcsolatos információkat tartalmazza. Ebben a példában az Azure-ügyfélkódtár használatával hozza létre a tárolót és a célközönséget.

Az alábbi képen az azonosítógombok és a tárolóazonosító beviteli mezője látható. Ha üresen hagyja a tárolóazonosító mezőt, és a felhasználóazonosító gombra kattint, új tárolót hoz létre, és a kiválasztott felhasználóként csatlakozik. Másik lehetőségként a végfelhasználó megadhat egy tárolóazonosítót, és kiválaszthat egy felhasználói azonosítót egy meglévő tárolóhoz kiválasztott felhasználóként való csatlakozáshoz.

A screenshot of a browser with buttons for selecting a user.

A következő képen több felhasználó látható, aki egy dobozok által ábrázolt tárolóhoz csatlakozik. A kék színnel tagolt mező azt a felhasználót jelöli, aki megtekinti az ügyfelet, míg a fekete színnel tagolt mezők a többi csatlakoztatott felhasználót jelölik. Ahogy az új felhasználók egyedi azonosítóval csatlakoznak a tárolóhoz, a dobozok száma nőni fog.

A screenshot of a browser showing information for four different container users.

Feljegyzés

Ez az oktatóanyag feltételezi, hogy ismeri a Dinamikus keretrendszer Áttekintést, és elvégezte a rövid útmutatót. Ismernie kell a React alapjait, a React-projektek létrehozását és a React Hooks használatát is.

A projekt létrehozása

Nyisson meg egy parancssort, és lépjen arra a szülőmappára, ahol létre szeretné hozni a projektet; pl. C:\My Fluid Projects.
Futtassa a következő parancsot a parancssorban. (Vegye figyelembe, hogy a parancssori felület npx, nem npm. A Node.js telepítésekor lett telepítve.)
```
npx create-react-app fluid-audience-tutorial
```
A projekt egy almappában fluid-audience-tutorialjön létre. Lépjen rá a paranccsal cd fluid-audience-tutorial.

A projekt a következő Fluid-kódtárakat használja:

Könyvtár	Leírás
`fluid-framework`	A SharedMap elosztott adatstruktúrát tartalmazza, amely szinkronizálja az adatokat az ügyfelek között.
`@fluidframework/azure-client`	Meghatározza a fluidszolgáltatás-kiszolgálóhoz való kapcsolatot, és meghatározza a Fluid-tároló kiindulási sémáját.
`@fluidframework/test-client-utils`	Meghatározza a Fluid Service-kapcsolat létrehozásához szükséges InsecureTokenProvidert .

Futtassa a következő parancsot a kódtárak telepítéséhez.

npm install @fluidframework/azure-client @fluidframework/test-client-utils fluid-framework

A projekt kódolása

Állapotváltozók és összetevőnézet beállítása

Nyissa meg a fájlt \src\App.js a kódszerkesztőben. Törölje az összes alapértelmezett import utasítást. Ezután törölje az összes korrektúrát az return utasításból. Ezután adja hozzá az összetevőkre és a React-horgokra vonatkozó importálási utasításokat. Vegye figyelembe, hogy a későbbi lépésekben implementáljuk az importált AudienceDisplay és UserIdSelection összetevőket. A fájlnak a következőképpen kell kinéznie:
```
    import { useState, useCallback } from "react";
    import { AudienceDisplay } from "./AudienceDisplay";
    import { UserIdSelection } from "./UserIdSelection";

    export const App = () => {
    // TODO 1: Define state variables to handle view changes and user input
    return (
    // TODO 2: Return view components
    );
    }
```
Írja felül a TODO 1 értékét az alábbi kóddal. Ez a kód inicializálja az alkalmazásban használt helyi állapotváltozókat. Az displayAudience érték határozza meg, hogy az AudienceDisplay összetevőt vagy a UserIdSelection összetevőt jelenítjük-e meg (lásd TODO 2). Az userId érték az a felhasználói azonosító, amellyel csatlakozni szeretne a tárolóhoz, és az containerId érték a betöltendő tároló. handleContainerNotFound A handleSelectUser rendszer visszahívásként adja át a függvényeket a két nézetnek, és kezeli az állapotváltásokat. handleSelectUser a rendszer meghívja a tároló létrehozásakor/betöltésekor. handleContainerNotFound a rendszer meghívja, ha egy tároló létrehozása/betöltése meghiúsul.

Vegye figyelembe, hogy a userId és a containerId értékek a UserIdSelection összetevőből származnak a handleSelectUser függvényen keresztül.
```
    const [displayAudience, setDisplayAudience] = useState(false);
    const [userId, setUserId] = useState();
    const [containerId, setContainerId] = useState();

    const handleSelectUser = useCallback((userId, containerId) => {
    setDisplayAudience(true)
    setUserId(userId);
    setContainerId(containerId);
    }, [displayAudience, userId, containerId]);

    const handleContainerNotFound = useCallback(() => {
    setDisplayAudience(false)
    }, [setDisplayAudience]);
```
Írja felül a TODO 2 értékét az alábbi kóddal. A fent leírtaknak megfelelően a displayAudience változó határozza meg, hogy az AudienceDisplay összetevőt vagy a UserIdSelection összetevőt jelenítjük-e meg. Emellett az állapotváltozók frissítésére szolgáló függvények tulajdonságokként lesznek átadva az összetevőknek.
```
    (displayAudience) ?
    <AudienceDisplay userId={userId} containerId={containerId} onContainerNotFound={handleContainerNotFound}/> :
    <UserIdSelection onSelectUser={handleSelectUser}/>
```

Az AudienceDisplay összetevő beállítása

Hozzon létre és nyisson meg egy fájlt \src\AudienceDisplay.js a kódszerkesztőben. Adja hozzá a következő import-utasításokat:
```
    import { useEffect, useState } from "react";
    import { SharedMap } from "fluid-framework";
    import { AzureClient } from "@fluidframework/azure-client";
    import { InsecureTokenProvider } from "@fluidframework/test-client-utils";
```
Vegye figyelembe, hogy a felhasználók és tárolók definiálásához a Dinamikus keretrendszer tárból importált objektumokra van szükség. A következő lépésekben az AzureClient és az InsecureTokenProvider használatával konfigurálja az ügyfélszolgáltatást (lásd TODO 1), míg a megosztotttérképet a tároló létrehozásához szükséges konfiguráláshoz containerSchema használja (lásd TODO 2).

Adja hozzá a következő funkcionális összetevőket és segédfüggvényeket:

    const tryGetAudienceObject = async (userId, userName, containerId) => {
    // TODO 1: Create container and return audience object
    }

    export const AudienceDisplay = (props) => {
    //TODO 2: Configure user ID, user name, and state variables
    //TODO 3: Set state variables and set event listener on component mount
    //TODO 4: Return list view
    }

    const AudienceList = (data) => {
    //TODO 5: Append view elements to list array for each member
    //TODO 6: Return list of member elements
    }

Vegye figyelembe, hogy az AudienceDisplay és az AudienceList funkcionális összetevők, amelyek kezelik a célközönség adatainak lekérését és renderelését, míg a tryGetAudienceObject metódus kezeli a tároló- és közönségszolgáltatások létrehozását.

Tároló és célközönség lekérése

Segédfüggvény használatával lekérheti a Fluid-adatokat a Célközönség objektumból a nézetrétegbe (a React állapotba). A tryGetAudienceObject metódus akkor lesz meghívva, ha a nézetösszetevő betöltődik egy felhasználói azonosító kiválasztása után. A visszaadott érték egy React állapottulajdonsághoz van rendelve.

Írja felül a TODO 1 értékét az alábbi kóddal. Vegye figyelembe, hogy a rendszer userIduserNamecontainerId az alkalmazásösszetevőből adja át az értékeket. Ha nincs containerId, létrejön egy új tároló. Azt is vegye figyelembe, hogy a rendszer az containerId URL-kivonaton tárolja a fájlokat. Az új böngészőből munkamenetet beíró felhasználó átmásolhatja az URL-címet egy meglévő munkamenet-böngészőből, vagy navigálhat a tárolóazonosítóhoz localhost:3000 , és manuálisan is beírhatja azt. Ezzel az implementációval a hívást egy próbafogásba szeretnénk csomagolni getContainer abban az esetben, ha a felhasználó olyan tárolóazonosítót ad meg, amely nem létezik. További információért tekintse meg a Tárolók dokumentációját.

    const userConfig = {
        id: userId,
        name: userName,
        additionalDetails: {
            email: userName.replace(/\s/g, "") + "@example.com",
            date: new Date().toLocaleDateString("en-US"),
        },
    };

    const serviceConfig = {
        connection: {
            type: "local",
            tokenProvider: new InsecureTokenProvider("", userConfig),
            endpoint: "http://localhost:7070",
        },
    };

    const client = new AzureClient(serviceConfig);

    const containerSchema = {
        initialObjects: { myMap: SharedMap },
    };

    let container;
    let services;
    if (!containerId) {
        ({ container, services } = await client.createContainer(containerSchema));
        const id = await container.attach();
        location.hash = id;
    } else {
        try {
            ({ container, services } = await client.getContainer(containerId, containerSchema));
        } catch (e) {
            return;
        }
    }
    return services.audience;

A célközönség csatlakoztatása az összetevő csatlakoztatásához

Most, hogy meghatároztuk, hogyan szerezheti be a Fluid célközönséget, meg kell adnunk a Reactnek, hogy hívja tryGetAudienceObject meg a Célközönség megjelenítése összetevő csatlakoztatását.

Írja felül a TODO 2 értékét az alábbi kóddal. Vegye figyelembe, hogy a felhasználói azonosító a szülő összetevőből származik vagy user1user2random. Ha az azonosítót random véletlenszerű szám létrehozására használjuk Math.random() azonosítóként. Emellett a rendszer leképez egy nevet a felhasználóhoz a megadott userNameListazonosítójuk alapján. Végül meghatározzuk azokat az állapotváltozókat, amelyek a csatlakoztatott tagokat és az aktuális felhasználót is tárolják. fluidMembers a tárolóhoz csatlakoztatott összes tag listáját tárolja, míg currentMember a böngészőkörnyezetet megtekintő aktuális felhasználót képviselő tagobjektumot.
```
    const userId = props.userId == "random" ? Math.random() : props.userId;
    const userNameList = {
    "user1" : "User One",
    "user2" : "User Two",
    "random" : "Random User"
    };
    const userName = userNameList[props.userId];

    const [fluidMembers, setFluidMembers] = useState();
    const [currentMember, setCurrentMember] = useState();
```
Írja felül a TODO 3 értékét az alábbi kóddal. Ez meghívja az tryGetAudienceObject összetevő csatlakoztatásának időpontjára, és beállítja a visszaadott közönségtagokat a következőre fluidMembers : és currentMember. Vegye figyelembe, hogy a rendszer ellenőrzi, hogy a rendszer visszaad-e egy célközönségobjektumot, ha egy felhasználó olyan tárolóazonosítót ad meg, amely nem létezik, és vissza kell adnunk őket a UserIdSelection nézethez (props.onContainerNotFound() ez fogja kezelni a nézetváltást). Az eseménykezelők regisztrációját akkor is érdemes megszüntetni, ha a React-összetevő a visszatéréssel leválasztja audience.offa elemet.
```
    useEffect(() => {
    tryGetAudienceObject(userId, userName, props.containerId).then(audience => {
        if(!audience) {
        props.onContainerNotFound();
        alert("error: container id not found.");
        return;
        }

        const updateMembers = () => {
        setFluidMembers(audience.getMembers());
        setCurrentMember(audience.getMyself());
        }

        updateMembers();

        audience.on("membersChanged", updateMembers);

        return () => { audience.off("membersChanged", updateMembers) };
    });
    }, []);
```
Írja felül a TODO 4 értékét az alábbi kóddal. Vegye figyelembe, hogy ha a fluidMembers képernyő inicializálva van, vagy currentMember nincs inicializálva, a képernyő üres lesz. Az AudienceList összetevő stílussal jeleníti meg a tagadatokat (a következő szakaszban implementálandó).
```
    if (!fluidMembers || !currentMember) return (<div/>);

    return (
        <AudienceList fluidMembers={fluidMembers} currentMember={currentMember}/>
    )
```
Feljegyzés

Csatlakozás áttűnések rövid időablakokat eredményezhetnek, ahol getMyself a visszatérési undefinedidő . Ennek az az oka, hogy az aktuális ügyfélkapcsolat még nem lett hozzáadva a célközönséghez, ezért nem található egyező kapcsolatazonosító. Ha meg szeretné akadályozni, hogy a React közönségtagok nélkül jelenítsen membersChangedmeg egy lapot, hozzáadunk egy figyelőt a híváshozupdateMembers. Ez azért működik, mert a szolgáltatás célközönsége eseményt membersChanged bocsát ki a tároló csatlakoztatásakor.

A nézet létrehozása

Írja felül a TODO 5 értékét az alábbi kóddal. Vegye figyelembe, hogy az AudienceDisplay összetevőből átadott minden taghoz megjelenítünk egy listaösszetevőt . Minden tag esetében először az adott tag isSelfellenőrzéséhez currentMember.userId hasonlítjuk összemember.userId. Így megkülönböztethetjük az ügyfélfelhasználót a többi felhasználótól, és más színnel jeleníthetjük meg az összetevőt. Ezután leküldjük a listaösszetevőt egy list tömbbe. Minden összetevő megjeleníti a tagadatokat, például userIduserName és additionalDetails.

    const currentMember = data.currentMember;
    const fluidMembers = data.fluidMembers;

    const list = [];
    fluidMembers.forEach((member, key) => {
        const isSelf = (member.userId === currentMember.userId);
        const outlineColor = isSelf ? 'blue' : 'black';

        list.push(
        <div style={{
            padding: '1rem',
            margin: '1rem',
            display: 'flex',
            outline: 'solid',
            flexDirection: 'column',
            maxWidth: '25%',
            outlineColor
        }} key={key}>
            <div style={{fontWeight: 'bold'}}>Name</div>
            <div>
                {member.userName}
            </div>
            <div style={{fontWeight: 'bold'}}>ID</div>
            <div>
                {member.userId}
            </div>
            <div style={{fontWeight: 'bold'}}>Connections</div>
            {
                member.connections.map((data, key) => {
                    return (<div key={key}>{data.id}</div>);
                })
            }
            <div style={{fontWeight: 'bold'}}>Additional Details</div>
            { JSON.stringify(member.additionalDetails, null, '\t') }
        </div>
        );
    });

Írja felül a TODO 6 értékét az alábbi kóddal. Ez megjeleníti a tömbbe list leküldött összes tagelemet.
```
    return (
        <div>
            {list}
        </div>
    );
```

A UserIdSelection összetevő beállítása

Hozzon létre és nyisson meg egy fájlt \src\UserIdSelection.js a kódszerkesztőben. Ez az összetevő felhasználói azonosító gombokat és tárolóazonosító beviteli mezőket tartalmaz, amelyek lehetővé teszik a végfelhasználók számára a felhasználói azonosító és az együttműködési munkamenet kiválasztását. Adja hozzá a következő import utasításokat és funkcionális összetevőket:
```
import { useState } from 'react';

export const UserIdSelection = (props) => {
    // TODO 1: Define styles and handle user inputs
    return (
    // TODO 2: Return view components
    );
}
```
Írja felül a TODO 1 értékét az alábbi kóddal. Vegye figyelembe, hogy a onSelectUser függvény frissíti az állapotváltozókat a szülőalkalmazás-összetevőben, és kérni fogja a nézet módosítását. A handleSubmit metódust gombelemek aktiválják, amelyek a következőben TODO 2lesznek implementálva: . Emellett a metódus az handleChange állapotváltozó frissítésére containerId is használható. Ezt a metódust egy bemeneti elem eseményfigyelője hívja meg, amely a következőben TODO 2implementálva van: . Azt is vegye figyelembe, hogy frissítjük az containerId értéket egy HTML-elemből a (megadott) TODO 2azonosítóval containerIdInput .
```
    const selectionStyle = {
    marginTop: '2rem',
    marginRight: '2rem',
    width: '150px',
    height: '30px',
    };

    const [containerId, setContainerId] = (location.hash.substring(1));

    const handleSubmit = (userId) => {
    props.onSelectUser(userId, containerId);
    }

    const handleChange = () => {
    setContainerId(document.getElementById("containerIdInput").value);
    };
```

Írja felül a TODO 2 értékét az alábbi kóddal. Ez megjeleníti a felhasználói azonosító gombjait és a tárolóazonosító beviteli mezőjét.

    <div style={{display: 'flex', flexDirection:'column'}}>
    <div style={{marginBottom: '2rem'}}>
        Enter Container Id:
        <input type="text" id="containerIdInput" value={containerId} onChange={() => handleChange()} style={{marginLeft: '2rem'}}></input>
    </div>
    {
        (containerId) ?
        (<div style={{}}>Select a User to join container ID: {containerId} as the user</div>)
        : (<div style={{}}>Select a User to create a new container and join as the selected user</div>)
    }
    <nav>
        <button type="submit" style={selectionStyle} onClick={() => handleSubmit("user1")}>User 1</button>
        <button type="submit" style={selectionStyle} onClick={() => handleSubmit("user2")}>User 2</button>
        <button type="submit" style={selectionStyle} onClick={() => handleSubmit("random")}>Random User</button>
    </nav>
    </div>

Indítsa el a Fluid-kiszolgálót, és futtassa az alkalmazást

Feljegyzés

A jelen útmutató többi részével való egyeztetéshez ez a szakasz egy Fluid-kiszolgáló elindításához és npm parancsaihoz használja npx a parancsokat. A cikkben szereplő kód azonban egy Azure Fluid Relay-kiszolgálón is futtatható. További információ: Az Azure Fluid Relay szolgáltatás üzembe helyezése és az Azure Fluid Relay szolgáltatás Csatlakozás

A Parancssorban futtassa a következő parancsot a Fluid szolgáltatás elindításához.

npx @fluidframework/azure-local-service@latest

Nyisson meg egy új parancssort, és keresse meg a projekt gyökerét; például C:/My Fluid Projects/fluid-audience-tutorial. Indítsa el az alkalmazáskiszolgálót a következő paranccsal. Az alkalmazás megnyílik a böngészőben. Ez eltarthat néhány percig.

npm run start

localhost:3000 Lépjen a böngészőlapra a futó alkalmazás megtekintéséhez. Új tároló létrehozásához válasszon egy felhasználói azonosító gombot, miközben üresen hagyja a tárolóazonosító bemenetét. A tároló munkamenethez csatlakozó új felhasználó szimulálásához nyisson meg egy új böngészőlapot, és lépjen a következőre localhost:3000: . Ezúttal adja meg a tárolóazonosító értékét, amely az első böngészőlap URL-címének eljárásából http://localhost:3000/#található.

Feljegyzés

Előfordulhat, hogy további függőséget kell telepítenie ahhoz, hogy ez a bemutató kompatibilis legyen a Webpack 5-kel. Ha "puffer" vagy "URL" csomaghoz kapcsolódó fordítási hibát kap, futtassa npm install -D buffer url és próbálkozzon újra. Ez a Dinamikus keretrendszer egy későbbi kiadásában lesz megoldva.

Következő lépések

Próbálja kiterjeszteni a bemutatót több kulcs/érték párral a mezőbenuserConfig.additionalDetails
Fontolja meg a célközönség integrálását egy olyan együttműködési alkalmazásba, amely elosztott adatstruktúrákat, például SharedMap-et vagy SharedString-et használ.
További információ a célközönségről.

Tipp.

Amikor módosítja a kódot, a projekt automatikusan újraépíti a projektet, és az alkalmazáskiszolgáló újra betöltődik. Ha azonban módosítja a tárolósémát, azok csak akkor lépnek érvénybe, ha bezárja és újraindítja az alkalmazáskiszolgálót. Ehhez koncentráljon a parancssorra, és nyomja le kétszer a Ctrl-C billentyűkombinációt. Ezután futtassa npm run start újra.

Megosztás a következőn keresztül:

Útmutató: Közönségfunkciók használata a Dinamikus keretrendszer

A projekt létrehozása

A projekt kódolása

Állapotváltozók és összetevőnézet beállítása

Az AudienceDisplay összetevő beállítása

Tároló és célközönség lekérése

A célközönség csatlakoztatása az összetevő csatlakoztatásához

A nézet létrehozása

A UserIdSelection összetevő beállítása

Indítsa el a Fluid-kiszolgálót, és futtassa az alkalmazást

Következő lépések

További források