Inizia a utilizzare gli indicatori Angular

1. Prima di iniziare

Angular Signals introduce tre primitive reattive nell'Angular che conosci e ami, semplificando lo sviluppo e aiutandoti a creare app più veloci per impostazione predefinita.

Cosa creerai

• Scopri le tre primitive reattive introdotte con Angular Signals: signal(), computed() e effect().
• Utilizza Angular Signals per creare un gioco di cifratura Angular. I sistemi di crittografia sono sistemi per criptare e decriptare i dati. In questo gioco, gli utenti possono decodificare un messaggio segreto trascinando gli indizi per risolvere un codice, personalizzare il messaggio e condividere l'URL per inviare messaggi segreti agli amici.

Prerequisiti

• Conoscenza di Angular e TypeScript
• Consigliato: guarda Rethinking Reactivity with Signals per scoprire di più sulla libreria Angular Signals

2. Ottieni il codice

Tutto ciò che ti serve per questo progetto è in StackBlitz. StackBlitz è il metodo consigliato per completare questo codelab. In alternativa, clona il codice e aprilo nel tuo ambiente di sviluppo preferito.

Apri Stackblitz ed esegui l'app

Per iniziare, apri il link di Stackblitz nel tuo browser web preferito:

1. Apri una nuova scheda del browser e vai all'indirizzo https://stackblitz.com/edit/io-signals-codelab-starter?file=src%2Fcipher%2Fservice.cipher.ts,src%2Fsecret-message%2Fservice.message.ts&service.massage.ts
2. Duplica StackBlitz per creare il tuo spazio di lavoro modificabile. Stackblitz dovrebbe eseguire automaticamente l'app e tu sei pronto per iniziare.

Alternativa: clona il repository e pubblica l'app

L'utilizzo di VSCode o di un IDE locale è un metodo alternativo per completare questo codelab:

1. Apri una nuova scheda del browser e vai alla pagina https://github.com/angular/codelabs/tree/signals-get-started.
2. Crea un fork e clona il repository, quindi utilizza il comando cd codelabs/ per spostarti al suo interno.
3. Controlla il ramo del codice iniziale con il comando git checkout signals-get-started.
4. Apri il codice in VSCode o nell'IDE che preferisci.
5. Per installare le dipendenze necessarie per eseguire il server, utilizza il comando npm install.
6. Per eseguire il server, utilizza il comando ng serve.
7. Apri una scheda del browser all'indirizzo http://localhost:4200.

3. Stabilire una base di riferimento

Il tuo punto di partenza è un gioco di cifratura angolare, ma non funziona ancora. Angular Signals alimenterà la funzionalità del gioco.

Per iniziare, esamina la versione finale di ciò che creerai: Angular Signals Cypher.

1. Visualizza il messaggio codificato sullo schermo.
2. Trascina un pulsante con una lettera nel tastierino per risolvere il cifrario e decodificare il messaggio segreto.
3. Se l'operazione va a buon fine, vedrai come il messaggio si aggiorna per decifrare una parte maggiore del messaggio segreto.
4. Fai clic su Personalizza per modificare il mittente e il messaggio, quindi fai clic su Crea e copia URL per visualizzare i valori sullo schermo e la modifica dell'URL.
5. Bonus: copia e incolla l'URL in una nuova scheda o condividilo con un amico e scopri come vengono memorizzati il mittente e il messaggio nell'URL.

4. Definisci il tuo primo indicatore()

Un segnale è un valore che può indicare ad Angular quando cambia. Alcuni indicatori possono essere modificati direttamente, mentre altri calcolano i propri valori a partire dai valori di altri indicatori. Insieme, i segnali creano un grafico diretto delle dipendenze che modella il flusso di dati nella tua app.

Angular può utilizzare le notifiche dei segnali per sapere quali componenti devono essere rilevati per le modifiche o per eseguire le funzioni effect che definisci.

Converti superSecretMessage in un signal()

superSecretMessage è un valore in MessageService che definisce il messaggio segreto che il giocatore decodifica. Al momento, il valore non notifica all'app le modifiche, pertanto il pulsante Personalizza non funziona. Puoi risolvere il problema con un segnale.

Se imposti superSecretMessage come segnale, puoi inviare una notifica alle parti dell'app che dipendono dalla conoscenza del momento in cui il messaggio è stato modificato. Quando personalizzi il messaggio in una finestra di dialogo, imposti il segnale per aggiornare il resto dell'app con il nuovo messaggio.

Per definire il primo segnale, esegui i seguenti passaggi nel commento TODO(1): Define your first signal() in ogni file:

1. Nel file service.message.ts, utilizza la libreria Signals per rendere superSecretMessage reattivo:

src/app/secret-message/service.message.ts

superSecretMessage = signal(
  'Angular Signals are in developer preview in v16 today!'
);

Ti viene chiesto automaticamente di importare signal da @angular/core. Se aggiorni la pagina, è probabile che si verifichino errori nei punti in cui in precedenza facevi riferimento a superSecretMessage. Questo perché hai modificato il tipo di superSecretMessage da string a SettableSignal<string>. Puoi risolvere il problema modificando tutti i riferimenti a superSecretMessage in modo che utilizzino l'API Signals. Ovunque tu legga il valore, chiama il getter del segnale superSecretMessage(). Ovunque scrivi il valore, utilizza l'API .set su SettableSignal per impostare il nuovo valore per il messaggio.

2. Nei file secret-message.ts e service.message.ts, aggiorna tutti i riferimenti a superSecretMessage con superSecretMessage():

src/app/secret-message/secret-message.ts

// Before
this.messages.superSecretMessage
this.messages.superSecretMessage = message;

// After
this.messages.superSecretMessage()
this.messages.superSecretMessage.set(message);

src/app/secret-message/service.message.ts

// Before
this.superSecretMessage

// After
this.superSecretMessage()

Esplora gli altri due indicatori

• Tieni presente che nell'app sono presenti altri due segnali:

src/app/cipher/service.cipher.ts

cipher = signal(this.createNewCipherKey());
decodedCipher = signal<CipherKey[]>([]);

CipherService definisce un segnale cipher, una mappatura generata casualmente di coppie chiave-valore di una lettera dell'alfabeto a una nuova lettera cipher. Lo utilizzi per criptare il messaggio e determinare se il giocatore trova una corrispondenza sulla tastiera.

Hai anche un segnale decodedCipher delle coppie chiave-valore decodificate correttamente che aggiungerai man mano che il giocatore risolve il cifrario.

Un attributo unico e potente della progettazione della libreria Signals di Angular è che puoi introdurre la reattività ovunque. Hai definito i segnali una volta nei servizi dell'app e puoi utilizzarli in un modello, componenti, pipe, altri servizi o ovunque tu possa scrivere codice dell'applicazione. Non sono limitati o vincolati a un ambito di componente.

Verifica le modifiche

• Devi eseguire un altro passaggio prima che l'app funzioni. Per il momento, prova ad aggiungere un console.log() in diverse parti dell'app per vedere come viene impostato il nuovo superSecretMessage.

5. Definisci il tuo primo computed()

In molte situazioni potresti dover derivare lo stato da valori esistenti. È meglio aggiornare lo stato derivato quando cambia il valore dipendente.

Con computed(), puoi esprimere in modo dichiarativo un indicatore che deriva il suo valore da altri indicatori.

Converti solvedMessage in un computed()

solvedMessage traduce il valore secretMessage da codificato a decodificato utilizzando l'indicatore decodedCipher.

Questo è ancora più interessante perché puoi vedere che stai derivando un valore calcolato da un altro valore calcolato, quindi ogni volta che un segnale all'interno di questo contesto reattivo mappato cambia, le dipendenze vengono notificate.

Al momento, solvedMessage non viene aggiornato quando modifichi secretMessage, decodedCipher o superSecretMessage. In questo modo, non vedrai aggiornamenti sullo schermo quando il giocatore risolve il cifrario.

Se rendi solvedMessage un valore calcolato, crei un contesto reattivo in modo che, quando aggiorni il messaggio o risolvi il cifrario, puoi derivare l'aggiornamento dello stato dalle dipendenze monitorate.

Per convertire solvedMessage in computed(), esegui i seguenti passaggi nel commento TODO(2): Define your first computed() di ogni file:

1. Nel file service.message.ts, utilizza la libreria Signals per rendere solvedMessage reattivo:

src/app/secret-message/service.message.ts

solvedMessage = computed(() =>
  this.translateMessage(
    this.secretMessage(), 
    this.cipher.decodedCipher()
  )
);

Ti viene chiesto automaticamente di importare computed da @angular/core. Se aggiorni la pagina, è probabile che si verifichino errori nei punti in cui in precedenza facevi riferimento a solvedMessage. Questo perché hai modificato il tipo di superSecretMessage da string a Signal<string>, una funzione. Puoi risolvere il problema modificando tutti i riferimenti a solvedMessage in solvedMessage().

2. Nel file secret-message.ts, aggiorna tutti i riferimenti a solvedMessage con solvedMessage():

src/app/secret-message/secret-message.ts

// Before
<span *ngFor="let char of this.messages.solvedMessage.split(''); index as i;" [class.unsolved]="this.messages.solvedMessage[i] !== this.messages.superSecretMessage()[i]" >{{ char }}</span>

// After
<span *ngFor="let char of this.messages.solvedMessage().split(''); index as i;" [class.unsolved]="this.messages.solvedMessage()[i] !== this.messages.superSecretMessage()[i]" >{{ char }}</span>

Tieni presente che, a differenza di superSecretMessage, solvedMessage non è un SettableSignal, quindi non puoi modificarne direttamente il valore. Il suo valore viene invece aggiornato ogni volta che uno dei suoi indicatori di dipendenza (secretMessage e decodedCipher) viene aggiornato.

Esplora le altre due computed() funzioni

• Nota che nella tua app sono presenti altri due valori calcolati:

src/app/secret-message/service.message.ts

secretMessage = computed(() => 
  this.translateMessage(
    this.superSecretMessage(),
    this.cipher.cipher()
  )
);

src/app/cipher/service.cipher.ts

unsolvedAlphabet = computed(() =>
  ALPHABET.filter(
    (letter) => !this.decodedCipher().find((guess) => guess.value === letter)
  )
);

MessageService definisce un secretMessage calcolato, il superSecretMessage codificato dal cipher che i giocatori devono risolvere.

CipherService definisce un unsolvedAlphabet calcolato, un elenco di tutte le lettere che il giocatore non ha risolto, derivato dall'elenco delle chiavi di cifratura risolte in decodedCipher.

Verifica le modifiche

Ora che superSecretMessage è un segnale e solvedMessage è un valore calcolato, l'app dovrebbe funzionare. Prova le funzionalità del gioco:

1. Trascina un LetterGuessComponent in un LetterKeyComponent del tuo CipherComponent per risolvere il cifrario e decodificare il messaggio segreto.
2. Scopri come si aggiorna SecretMessageComponent man mano che decodifichi altre parti del messaggio segreto.
3. Fai clic su Personalizza per modificare il mittente e il messaggio, quindi fai clic su Crea e copia URL per visualizzare i valori sullo schermo e la modifica dell'URL.
4. Bonus: copia e incolla l'URL in una nuova scheda o condividilo con un amico e scopri come vengono memorizzati il mittente e il messaggio nell'URL.

6. Aggiungi il tuo primo effetto()

A volte potresti voler che si verifichi qualcosa quando un segnale ha un nuovo valore. Con effect(), puoi pianificare ed eseguire una funzione di gestione in risposta alla modifica dei segnali.

Aggiungere coriandoli quando il cifrario viene risolto

Ora che l'app è funzionante, puoi aggiungere un tocco di divertimento aggiungendo coriandoli quando il codice viene risolto e il messaggio segreto viene decodificato.

Per aggiungere coriandoli, segui questi passaggi nel commento TODO(3): Add your first effect():

1. Nel file cipher.ts, pianifica un effetto per aggiungere coriandoli quando il messaggio viene decodificato:

src/app/cipher/cipher.ts

import * as confetti from 'canvas-confetti';

ngOnInit(): void {
  ...

  effect(() => {
    if (this.messages.superSecretMessage() === this.messages.solvedMessage()) {
      var confettiCanvas = document.getElementById('confetti-canvas');
      confetti.create()(confettiCanvas, { particleCount: 100 });
    }
  });
}

Nota come questo effetto dipende da un segnale e da un valore calcolato: this.messages.superSecretMessage() e this.messages.solvedMessage().

L'effetto ti aiuta a programmare la funzione di coriandoli all'interno di un contesto reattivo per monitorare e rivalutare quando le sue dipendenze vengono aggiornate.

Verifica le modifiche

• Prova a risolvere il codice (suggerimento: puoi modificare il messaggio in modo che sia breve per testarlo più rapidamente). Un popup con coriandoli ti congratulerà per il tuo primo effect().

7. Complimenti!

Il tuo cifrario angolare è ora pronto per decifrare e condividere messaggi segreti. Vuoi inviare un messaggio al team di Angular? Tagga i nostri social media su @Angular per consentirci di decifrarlo. 🎉

Ora hai a disposizione tre nuove primitive reattive nel tuo set di strumenti Angular per semplificare lo sviluppo e creare app più veloci per impostazione predefinita.

Scopri di più

Dai un'occhiata a questi codelab:

• Guida introduttiva ai componenti autonomi
• Building a web application with Angular and Firebase

Leggi questi materiali:

• Angular.io
• Ripensare la reattività con Signals (Google I/O 2023)
• Novità di Angular (Google I/O 2023)