Útmutatók

Felület (UI)

A Komod böngészős felülete Blazor komponens(ek), amelyeket a KOFA kliense futás közben tölt be a csomagból. A felület csak megjelenít és parancsot küld; saját portja nincs, az adatot a szerver Komodtól kapja.

Projekt

A felület külön projekt (X.Ui, Microsoft.NET.Sdk.Razor), amely a szerver projekttel közös Package.props-ot használ. A Package.props KomodClientAssemblies tulajdonsága sorolja fel a betöltendő dll-eket. Ezt a kofa-komod és a kofa-komod-quickstart sablon beállítja.

Nézettípusok

A komponenst a [KomodView("<komod id>", ViewKind.X)] attribútum köti a Komodhoz, és a KomodComponentBase-ből származik:

`ViewKind`	Hol jelenik meg
`Widget`	Dashboard csempe.
`Page`	A példány teljes oldala.
`Settings`	Egyedi beállítás-szerkesztő (különben automatikus űrlap).

Egy Komodnak mindháromból lehet egy-egy.

<div style="display:flex;flex-direction:column;gap:6px;font-variant-numeric:tabular-nums">
    <div style="font-size:1.8rem;font-weight:600">
        @(_temperature is { } t ? t.ToString("0.0", CultureInfo.InvariantCulture) + " °C" : "–")
    </div>
    <div style="display:flex;align-items:center;gap:8px">
        <button type="button" @onclick="() => AdjustTargetAsync(-0.5)">−</button>
        <span>cél: @(_target?.ToString("0.0", CultureInfo.InvariantCulture) ?? "–") °C</span>
        <button type="button" @onclick="() => AdjustTargetAsync(+0.5)">+</button>
    </div>
    <div style="font-size:.85rem;opacity:.8">Fűtés: @(_heating ? "BE" : "KI")</div>
    @if (_error is not null)
    {
        <div style="font-size:.8rem;color:#c42b1c">@_error</div>
    }
</div>

Az ős (`KomodComponentBase`) adta tagok

Tag	Jelentés
`InstanceId`, `InstanceLabel`, `KomodId`	A példány azonosítói.
`Kofa` (`IKomodClientContext`)	A szerver elérése: feliratkozás, beállítás, parancs, fájl.
`Port("id")`	`PortRef` a példány egy portjára.
`AssetUrl("x.js")`	A csomag `wwwroot/` fájljának URL-je.
`InjectAsync`, `InvokeCommandAsync`	Rövidítések a bemenet beküldésére és a parancsra.
`Settings`, `SettingsChanged`	Csak `ViewKind.Settings` nézetben: a szerkesztett beállítás és a módosítás jelzése.

Élő adat

A SubscribeAsync<T> aszinkron folyamot ad. Mind kimeneti, mind bemeneti portra feliratkozhatsz; a szerver ritkítja a folyamot (maxRateHz), és csomag-újratöltés után magától újra feliratkozik.

protected override async Task OnInitializedAsync()
{
    _target = ReadTarget(await Kofa.GetSettingsAsync(InstanceId, _cts.Token));

    // Both an input and an output port can be subscribed; the server thins the stream to maxRateHz.
    _loops.Add(Task.Run(async () =>
    {
        await foreach (var message in Kofa.SubscribeAsync<Scalar>(Port("temperature"), maxRateHz: 5, _cts.Token))
        {
            _temperature = message.Value.Value;
            await InvokeAsync(StateHasChanged);
        }
    }));
    _loops.Add(Task.Run(async () =>
    {
        await foreach (var message in Kofa.SubscribeAsync<BoolValue>(Port("heater"), maxRateHz: 5, _cts.Token))
        {
            _heating = message.Value.Value;
            await InvokeAsync(StateHasChanged);
        }
    }));
}

Megjegyzés

A feliratkozó ciklust DisposeAsync-ben állítsd le a CancellationToken-nel (lásd a teljes sablonfájlt), különben az oldal elhagyása után is fut.

Beállítás-szerkesztő

Ha az automatikus űrlap nem elég, írj [KomodView("<id>", ViewKind.Settings)] komponenst. A Settings paraméterben a szerkesztett beállítást kapod (alapértékekkel kitöltve), a módosítást a SettingsChanged callbackkel jelzed. A módosítás a draftba kerül, és az Alkalmaz gomb után él.

Futás közbeni állításhoz (Widget vagy Page nézetből) az IKomodClientContext.GetSettingsAsync / SaveSettingsAsync való: a szerver ellenőriz, élőben alkalmaz (vagy újraindít, ha az OnSettingsChangedAsync false-t ad). Hiba esetén KomodClientException jön magyar üzenettel.

Statikus fájlok és JavaScript

A UI projekt wwwroot/ mappája a csomagba kerül, a szerver a /komods/<id>/<verzió>/wwwroot/ alatt szolgálja ki. A nézetben az AssetUrl adja az URL-t, JS modul így tölthető be:

_module = await JS.InvokeAsync<IJSObjectReference>("import", AssetUrl("remote-input.js"));

A billentyűzet, gamepad, pointer capture és hasonló eseménykezelés a Komod saját JS moduljában maradjon.

Figyelem

A wwwroot/ fájljai bejelentkezés nélkül letölthetők, ezért titkot ne tegyél beléjük. Szerver API-t a nézet ne relatív URL-lel hívjon, hanem az IKomodClientContext metódusaival.

Méret a dashboardon

A csempe magassága állítható. Ha a nézet ki tudja tölteni a helyet (térkép, kép, 3D), a gyökér elem magassága kövesse a --kofa-view-height CSS változót, saját alapértékkel:

<div style="position:relative;height:var(--kofa-view-height, 260px)">…</div>

Stílus

A Komod UI jelenleg nem hoz saját CSS fájlt a kliens oldalra: a stílust a komponensben, inline add meg (a sablon is így csinálja), vagy wwwroot/-ból tölts be egy <link>-et. Az alap betű- és színvilágot a kliens adja; világos és sötét témához kerüld a rögzített színeket.

Korlátok

A kiadott kliens trimmelt, nem minden framework API elérhető. A kofa-pack figyelmeztet.
A UI nem fér hozzá közvetlenül a szerver fájlrendszeréhez; fájl: Fájlok.