Un componente di notifica per Delphi con toast, casella di notifiche e badge
sgcNavigation, parte di sgcUI, porta alle applicazioni VCL e FireMonkey un set di componenti di notifica per Delphi, tutti guidati da un unico modello di notifica.
sgcNavigation, parte di sgcUI, porta alle applicazioni VCL e FireMonkey un set di componenti di notifica per Delphi, tutti guidati da un unico modello di notifica.
Il modello non disegna nulla ed è indipendente dal framework, quindi un unico modello alimenta le viste VCL e FireMonkey della stessa applicazione.
Un unico modello di notifica guida le notifiche toast, una casella di notifiche raggruppata per giorno, un badge dei non letti e le preferenze per categoria, e un server può inviare nuove notifiche in tempo reale tramite WebSocket, MQTT o server-sent events.
| Componente | Unit | Ruolo |
|---|---|---|
TsgcNotificationModel | sgcNavigation_Notification | Non visuale. Conserva le notifiche, conta quelle non lette, le segna come lette, le chiude e le salva come JSON. |
TsgcVCLToastManager, TsgcFMXToastManager | sgcNavigation_Toast_VCL, sgcNavigation_Toast_FMX | Non visuale. Mostra un toast per ogni nuova notifica non letta del modello, e toast autonomi dal codice. |
TsgcVCLNotificationInbox, TsgcFMXNotificationInbox | sgcNavigation_Inbox_VCL, sgcNavigation_Inbox_FMX | Un controllo che elenca le notifiche per giorno, con le schede Tutte e Non lette e un pulsante Segna tutte come lette. |
TsgcNotificationPreferences | sgcNavigation_NotifyPrefs | Non visuale. I canali (in app, pop-up, e-mail, push) che l'utente vuole per ogni categoria. |
TsgcVCLNotificationPrefsEditor, TsgcFMXNotificationPrefsEditor | sgcNavigation_NotifyPrefs_VCL, sgcNavigation_NotifyPrefs_FMX | Un controllo che mostra le preferenze come una tabella di caselle di controllo, una riga per categoria. |
TsgcToolbarBadgeLink | sgcToolbar_BadgeLink | Non visuale, in sgcToolbar. Mostra il conteggio dei non letti del modello come badge di una voce della barra degli strumenti o della barra multifunzione, 99+ oltre 99. |
TsgcUILiveSource_WebSocket, TsgcUILiveSource_MQTT, TsgcUILiveSource_SSE | Bridge sgcUICoreWS | Passa al modello i messaggi JSON che un server invia su una connessione sgcWebSockets (edizione Registered). |
Un toast è una breve scheda che compare in un angolo del form o dello schermo, conta alla rovescia e si chiude da sola.
Un toast ha un glifo di gravità o un'immagine, un titolo, un corpo fino a tre righe, un pulsante di chiusura e fino a due pulsanti di azione. Il toast manager è un componente non visuale sul form: impila i toast, li conta alla rovescia, li mette in pausa sotto il puntatore, li fa comparire e scomparire in dissolvenza e mette in coda quelli che non entrano.
Position sceglie l'angolo o il bordo, tpsBottomRight per impostazione predefinita, e Anchor del manager VCL impila i toast nel form o nell'area di lavoro dello schermo.Duration è 5000 ms per impostazione predefinita, e StickySeverities mantiene gli errori sullo schermo finché l'utente non li chiude.MaxVisible (3) limita i toast sullo schermo; i successivi attendono in coda.uses
Classes, SysUtils, Forms,
sgcNavigation_Notification, sgcNavigation_Toast, sgcNavigation_Toast_VCL;
procedure TMainForm.FormCreate(Sender: TObject);
begin
FToasts := TsgcVCLToastManager.Create(Self);
// the bottom right corner of the form, two toasts at a time
FToasts.Anchor := tanForm;
FToasts.Position := tpsBottomRight;
FToasts.MaxVisible := 2;
// warnings and errors stay until the user closes them
FToasts.StickySeverities := [nsvWarning, nsvError];
end;
procedure TMainForm.ExportFinished(aRows: Integer);
begin
FToasts.Show('Export finished', IntToStr(aRows) + ' rows written.',
nsvSuccess);
end;
In FireMonkey, TsgcFMXToastManager ha le stesse proprietà senza Anchor. I toast vivono in un overlay dentro il form, che funziona su Windows, macOS, Linux, iOS e Android.
Il modello conserva le notifiche di un utente; i toast, la casella di notifiche e il badge lo seguono senza altro codice.
Una notifica ha un Id, un titolo, un corpo in testo semplice, una gravità (info, success, warning o error), un'ora UTC, uno stato di lettura, una categoria, la sorgente che l'ha generata e pulsanti di azione. Add aggiunge una nuova notifica non letta. Post è un upsert per Id, quindi la chiave di un ordine, di una build o di un ticket mantiene aggiornata una sola notifica invece di aggiungerne una seconda. MarkRead, MarkAllRead e Dismiss cambiano lo stato, e SaveToFile e LoadFromFile conservano le notifiche tra una sessione e l'altra come JSON.
TsgcToolbarBadgeLink mostra il conteggio dei non letti su un pulsante della barra degli strumenti, o su un pulsante della barra multifunzione nell'edizione Registered.OnAction del modello con l'id dell'azione.uses
Classes, SysUtils, Controls, Forms,
sgcNavigation_Notification, sgcNavigation_NotifyPrefs,
sgcNavigation_Toast_VCL, sgcNavigation_Inbox_VCL,
sgcToolbar_VCL, sgcToolbar_BadgeLink;
procedure TMainForm.SetupNotifications(aToolbar: TsgcVCLToolbar);
var
vFile: string;
begin
// the notifications of the user, kept between sessions
FModel := TsgcNotificationModel.Create(Self);
vFile := ExtractFilePath(Application.ExeName) + 'notifications.json';
if FileExists(vFile) then
FModel.LoadFromFile(vFile);
FModel.OnAction := ModelAction;
// orders pop up, news only go to the inbox
FPrefs := TsgcNotificationPreferences.Create(Self);
FPrefs.Categories.Add('orders', 'Orders');
FPrefs.Categories.Add('news', 'News').Defaults := [nchInApp];
// a toast for every new unread notification its category allows
FToasts := TsgcVCLToastManager.Create(Self);
FToasts.Preferences := FPrefs;
FToasts.Model := FModel;
// every notification, newest first, under a header per day
FInbox := TsgcVCLNotificationInbox.Create(Self);
FInbox.Parent := Self;
FInbox.Align := alRight;
FInbox.Width := 360;
FInbox.Model := FModel;
// the unread count as the badge of the first toolbar button
FBadge := TsgcToolbarBadgeLink.Create(Self);
FBadge.Source := FModel;
FBadge.Target := aToolbar;
FBadge.ItemIndex := 0;
end;
procedure TMainForm.OrderShipped(const aOrderId: string);
var
oItem: TsgcNotificationItem;
begin
FModel.BeginUpdate;
try
// an upsert: the same id updates the notification
oItem := FModel.Post('order-' + aOrderId, 'Order ' + aOrderId +
' shipped', 'The parcel left the warehouse.', nsvSuccess, 'orders');
if oItem.Actions.IndexOf('track') < 0 then
oItem.Actions.Add('track', 'Track');
finally
FModel.EndUpdate;
end;
end;
Le modifiche fatte tra BeginUpdate e EndUpdate raggiungono le viste una sola volta, così il toast mostra la notifica completa con i suoi pulsanti. Il modello si usa dal thread principale.
VCL, tema chiaro: la casella di notifiche sopra le preferenze.
FireMonkey, tema chiaro.
Badge di conteggio su Inbox, Tasks e Alerts nella barra laterale.
Un server mantiene aggiornate le notifiche di un utente con messaggi in tempo reale, un oggetto JSON per messaggio.
ApplyMessage applica un messaggio al modello: add, update, remove, read, unread o snapshot. I toast, la casella di notifiche e il badge seguono il modello, quindi un messaggio dal server compare sullo schermo senza altro codice. ApplyMessage non solleva mai eccezioni; restituisce False e lascia il modello invariato quando un messaggio non è destinato a lui.
{"type":"notification","op":"add","notification":{"id":"n2","title":"Build 812 passed","severity":"success","group":"ci"}}
{"type":"notification","op":"update","notification":{"id":"n2","body":"All 1,204 tests passed"}}
{"type":"notification","op":"read","ids":["n1","n2"]}
{"type":"notification","op":"remove","id":"n1"}
Le sorgenti live del bridge sgcUICoreWS prendono i messaggi di un client sgcWebSockets e li passano al modello: TsgcUILiveSource_WebSocket per un TsgcWebSocketClient, TsgcUILiveSource_MQTT per un TsgcWSPClient_MQTT e TsgcUILiveSource_SSE per i server-sent events di un TsgcHTTP1Client. I messaggi che arrivano in un thread del socket vengono messi in coda e applicati nel thread principale.
uses
Classes, SysUtils,
sgcWebSocket, sgcUICoreWS_Live, sgcUICoreWS_Live_WebSocket,
sgcNavigation_Notification;
function BindNotifications(aOwner: TComponent; aClient: TsgcWebSocketClient;
aModel: TsgcNotificationModel): TsgcUILiveSource_WebSocket;
var
oBinding: TsgcUILiveBinding;
begin
Result := TsgcUILiveSource_WebSocket.Create(aOwner);
Result.Client := aClient;
oBinding := Result.Bindings.Add;
oBinding.Target := aModel;
// only the frames of the alerts channel, the live message is in "data":
// {"channel":"alerts","data":{"type":"notification","op":"add",...}}
oBinding.FilterPath := 'channel';
oBinding.FilterValue := 'alerts';
oBinding.MessagePath := 'data';
end;
OnNotification e OnAction del modello e invia il tuo frame tramite lo stesso client.I messaggi live e le sorgenti live fanno parte dell'edizione Registered, e le sorgenti live richiedono sgcWebSockets. Senza un server, l'applicazione chiama Add e Post del modello.
Leggi l'argomento della guida sui messaggi live delle notifiche
Da Delphi 7 a Delphi 13 con VCL, FireMonkey da Delphi XE6, C++Builder e .NET WinForms, WPF e Avalonia.
TsgcVCLToastManager, TsgcVCLNotificationInbox e TsgcVCLNotificationPrefsEditorTsgcFMXToastManager, TsgcFMXNotificationInbox e TsgcFMXNotificationPrefsEditorTsgcWinFormsToastManager, TsgcWpfToastManager e TsgcAvaloniaToastManager, con la casella di notifiche e l'editor delle preferenzeLa demo Realtime della suite sgcUI costruisce una console operativa con una campanella il cui badge è il conteggio dei non letti e la casella di notifiche sopra le preferenze, in VCL, FireMonkey, C++Builder e .NET. Vedi il pacchetto UI Realtime.
I componenti di notifica seguono l'edizione del loro prodotto, sgcNavigation, e il badge link segue sgcToolbar.
| Elemento | Prodotto | .NET Community | Registered |
|---|---|---|---|
| Modello di notifica, toast, casella di notifiche e preferenze | sgcNavigation | Sì | Sì |
| Badge link con una barra degli strumenti | sgcToolbar | Sì | Sì |
| Badge link con una barra multifunzione | sgcToolbar | No | Sì |
| Messaggi di notifica live | sgcNavigation | No | Sì |
| Sorgenti live tramite WebSocket, MQTT e SSE (richiede sgcWebSockets) | sgcUICore | No | Sì |
In Delphi e C++Builder i componenti di notifica sono inclusi in sgcUI Standard, Professional, Enterprise, All-Access e nella versione di prova, e con sgcNavigation e sgcToolbar venduti singolarmente. Li includono anche i pacchetti .NET Community gratuiti. L'edizione Delphi Community include solo sgcGrid. Vedi i prezzi di sgcUI.
Metti un TsgcVCLToastManager sul form, o un TsgcFMXToastManager in FireMonkey, e chiama Show con un titolo, un corpo e una gravità. Il toast compare nell'angolo che scegli, conta alla rovescia per cinque secondi per impostazione predefinita, si mette in pausa mentre il puntatore è sopra e non prende mai il focus. Con il suo Model impostato, il manager mostra anche un toast per ogni nuova notifica non letta.
Crea un TsgcNotificationModel e impostalo come Model di un TsgcVCLNotificationInbox, che elenca le notifiche per giorno con le schede Tutte e Non lette e un pulsante Segna tutte come lette. Poi imposta il modello come Source di un TsgcToolbarBadgeLink con una barra degli strumenti come Target: il conteggio dei non letti compare sul pulsante, come 99+ oltre 99.
Sì, nell'edizione Registered. Il server invia un messaggio JSON per ogni modifica e ApplyMessage lo applica al modello. Le sorgenti live del bridge sgcUICoreWS leggono quei messaggi da un client WebSocket, MQTT o server-sent events di sgcWebSockets e li applicano nel thread principale, così i toast, la casella di notifiche e il badge si aggiornano senza altro codice.
Sì. TsgcFMXToastManager, TsgcFMXNotificationInbox e TsgcFMXNotificationPrefsEditor funzionano da Delphi XE6. I toast FireMonkey vivono in un overlay dentro il form, su Windows, macOS, Linux, iOS e Android. Il modello è indipendente dal framework, quindi lo stesso TsgcNotificationModel alimenta le viste VCL e FireMonkey.
Sì. TsgcNotificationPreferences contiene i canali che l'utente vuole per ogni categoria: in app, pop-up, e-mail e push. L'editor delle preferenze li mostra come una tabella di caselle di controllo. Un toast manager con Preferences impostato non mostra alcun toast per una categoria il cui canale pop-up è disattivato, e la casella di notifiche continua a elencare quelle notifiche.
Sì, quando le salvi. SaveToFile e LoadFromFile del modello conservano le notifiche tra una sessione e l'altra come file JSON, e MaxCount (500 per impostazione predefinita) limita il modello, eliminando per prime le notifiche lette più vecchie.
I pacchetti .NET Community gratuiti includono il modello, i toast, la casella di notifiche e le preferenze. L'edizione Delphi Community include solo sgcGrid, quindi in Delphi e C++Builder i componenti di notifica sono inclusi in sgcNavigation, venduto singolarmente o in sgcUI Standard e superiori. La versione di prova All-Access include ogni prodotto sgcUI per la valutazione.