Utilizzare elenchi di dati

Ottieni un riferimento al database

Per leggere o scrivere dati dal database, devi avere un'istanza di DatabaseReference:

DatabaseReference ref = FirebaseDatabase.instance.ref();

Lettura e scrittura di elenchi

Aggiungere dati a un elenco

Utilizza il metodo push() per aggiungere dati a un elenco nelle applicazioni multiutente. Il metodo push() genera una chiave univoca ogni volta che viene aggiunto un nuovo elemento secondario al riferimento Firebase specificato. Utilizzando queste chiavi generate automaticamente per ogni nuovo elemento dell'elenco, più client possono aggiungere elementi secondari alla stessa posizione contemporaneamente senza conflitti di scrittura. La chiave univoca generata da push() si basa su un timestamp, quindi gli elementi dell'elenco vengono ordinati automaticamente in ordine cronologico.

Puoi utilizzare il riferimento ai nuovi dati restituiti dal metodo push() per ottenere il valore della chiave generata automaticamente dell'elemento secondario o impostare i dati per l'elemento secondario. La proprietà .key di un riferimento push() contiene la chiave generata automaticamente.

Puoi utilizzare queste chiavi generate automaticamente per semplificare l'appiattimento della struttura dei dati. Per saperne di più, consulta l'esempio di fan-out dei dati.

Ad esempio, push() potrebbe essere utilizzato per aggiungere un nuovo post a un elenco di post in un'applicazione social:

DatabaseReference postListRef = FirebaseDatabase.instance.ref("posts");
DatabaseReference newPostRef = postListRef.push();
newPostRef.set({
  // ...
});

Ascolta gli eventi figlio

Gli eventi figlio vengono attivati in risposta a operazioni specifiche che si verificano sugli elementi figlio di un nodo, ad esempio l'aggiunta di un nuovo elemento figlio tramite il metodo push() o l'aggiornamento di un elemento figlio tramite il metodo update().

Evento Utilizzo tipico
onChildAdded Recuperare elenchi di elementi o ascoltare le aggiunte a un elenco di elementi. Questo evento viene attivato una volta per ogni elemento secondario esistente e poi di nuovo ogni volta che viene aggiunto un nuovo elemento secondario al percorso specificato. Al listener viene passato uno snapshot contenente i dati del nuovo elemento secondario.
onChildChanged Ascolta le modifiche agli elementi di un elenco. Questo evento viene attivato ogni volta che un nodo secondario viene modificato. Sono incluse eventuali modifiche ai discendenti del nodo secondario. Lo snapshot passato al listener di eventi contiene i dati aggiornati per l'elemento secondario.
onChildRemoved Ascolta quando gli elementi vengono rimossi da un elenco. Questo evento viene attivato quando viene rimosso un elemento secondario immediato.L'istantanea passata al blocco di callback contiene i dati dell'elemento secondario rimosso.
onChildMoved Ascolta le modifiche all'ordine degli elementi in un elenco ordinato. Gli eventi onChildMoved seguono sempre l'evento onChildChanged che ha causato la modifica dell'ordine dell'elemento (in base al metodo di ordinamento corrente).

Ognuno di questi elementi può essere utile per ascoltare le modifiche a un nodo specifico di un database. Ad esempio, un'app di social blogging potrebbe utilizzare questi metodi insieme per monitorare l'attività nei commenti di un post, come mostrato di seguito:

final commentsRef = FirebaseDatabase.instance.ref("post-comments/$postId");
commentsRef.onChildAdded.listen((event) {
  // A new comment has been added, so add it to the displayed list.
});
commentsRef.onChildChanged.listen((event) {
  // A comment has changed; use the key to determine if we are displaying this
  // comment and if so displayed the changed comment.
});
commentsRef.onChildRemoved.listen((event) {
  // A comment has been removed; use the key to determine if we are displaying
  // this comment and if so remove it.
});

Ascolta gli eventi di valore

Sebbene l'ascolto degli eventi figlio sia il modo consigliato per leggere gli elenchi di dati, in alcune situazioni è utile l'ascolto degli eventi di valore su un riferimento di elenco.

Se colleghi un listener value a un elenco di dati, verrà restituito l'intero elenco di dati sotto forma di un singolo snapshot, su cui puoi eseguire un loop per accedere ai singoli elementi secondari.

Anche se esiste una sola corrispondenza per la query, lo snapshot è comunque un elenco, ma contiene un solo elemento. Per accedere all'elemento, devi eseguire un loop sul risultato:

myTopPostsQuery.onValue.listen((event) {
  for (final child in event.snapshot.children) {
    // Handle the post.
  }
}, onError: (error) {
  // Error.
});

Questo pattern può essere utile quando vuoi recuperare tutti gli elementi secondari di un elenco in un'unica operazione, anziché rimanere in ascolto di altri eventi di aggiunta di elementi secondari.

Ordinamento e filtro dei dati

Puoi utilizzare la classe Query per recuperare i dati ordinati per chiave, per valore o per valore di un elemento secondario. Puoi anche filtrare il risultato ordinato in base a un numero specifico di risultati o a un intervallo di chiavi o valori.

Ordina i dati

Per recuperare i dati ordinati, inizia specificando uno dei metodi di ordinamento per determinare l'ordine dei risultati:

Metodo Utilizzo
orderByChild() Ordina i risultati in base al valore di una chiave secondaria o di un percorso secondario nidificato specificati.
orderByKey() Ordina i risultati in base alle chiavi secondarie.
orderByValue() Ordina i risultati in base ai valori secondari.

Puoi utilizzare un solo metodo di ordinamento alla volta. La chiamata di un metodo di ordinamento più volte nella stessa query genera un errore.

L'esempio seguente mostra come recuperare un elenco dei post principali di un utente ordinati in base al numero di stelle:

final myUserId = FirebaseAuth.instance.currentUser?.uid;
final topUserPostsRef = FirebaseDatabase.instance
    .ref("user-posts/$myUserId")
    .orderByChild("starCount");

In questo modo viene definita una query che, se combinata con un listener secondario, sincronizza il client con i post dell'utente dal percorso nel database in base al suo ID utente, ordinati in base al numero di stelle ricevute da ciascun post. Questa tecnica di utilizzo degli ID come chiavi di indice è chiamata fan out dei dati. Per saperne di più, consulta Struttura il tuo database.

La chiamata al metodo orderByChild() specifica la chiave secondaria in base alla quale ordinare i risultati. In questo caso, i post vengono ordinati in base al valore del rispettivo elemento secondario "starCount". Le query possono anche essere ordinate in base ai nodi secondari nidificati, nel caso in cui i dati siano simili ai seguenti:

"posts": {
  "ts-functions": {
    "metrics": {
      "views" : 1200000,
      "likes" : 251000,
      "shares": 1200,
    },
    "title" : "Why you should use TypeScript for writing Cloud Functions",
    "author": "Doug",
  },
  "android-arch-3": {
    "metrics": {
      "views" : 900000,
      "likes" : 117000,
      "shares": 144,
    },
    "title" : "Using Android Architecture Components with Firebase Realtime Database (Part 3)",
    "author": "Doug",
  }
},

In questo caso, possiamo ordinare gli elementi dell'elenco in base ai valori nidificati nella chiave metrics specificando il percorso relativo dell'elemento secondario nidificato nella nostra chiamata orderByChild().

final mostViewedPosts =
    FirebaseDatabase.instance.ref('posts').orderByChild('metrics/views');

Per saperne di più su come vengono ordinati gli altri tipi di dati, consulta Come vengono ordinati i dati delle query.

Filtrare i dati

Per filtrare i dati, puoi combinare uno qualsiasi dei metodi di limite o intervallo con un metodo di ordinamento durante la creazione di una query.

Metodo Utilizzo
limitToFirst() Imposta il numero massimo di elementi da restituire dall'inizio dell'elenco ordinato dei risultati.
limitToLast() Imposta il numero massimo di elementi da restituire dalla fine dell'elenco ordinato dei risultati.
startAt() Restituisce gli elementi maggiori o uguali alla chiave o al valore specificati, a seconda del metodo di ordinamento scelto.
startAfter() Restituisce gli elementi maggiori della chiave o del valore specificati, a seconda del metodo di ordinamento scelto.
endAt() Restituisce gli elementi minori o uguali alla chiave o al valore specificati, a seconda del metodo di ordinamento scelto.
endBefore() Restituisce gli elementi inferiori alla chiave o al valore specificati, a seconda del metodo di ordinamento scelto.
equalTo() Restituisce gli elementi uguali alla chiave o al valore specificato, a seconda del metodo di ordinamento scelto.

A differenza dei metodi di ordinamento, puoi combinare più funzioni di limite o intervallo. Ad esempio, puoi combinare i metodi startAt() e endAt() per limitare i risultati a un intervallo di valori specificato.

Limita il numero di risultati

Puoi utilizzare i metodi limitToFirst() e limitToLast() per impostare un numero massimo di elementi secondari da sincronizzare per un determinato evento. Ad esempio, se utilizzi limitToFirst() per impostare un limite di 100, inizialmente riceverai solo fino a 100 eventi onChildAdded. Se nel tuo database Firebase sono archiviati meno di 100 elementi, viene attivato un evento onChildAdded per ogni elemento.

Man mano che gli elementi cambiano, ricevi eventi onChildAdded per gli elementi che entrano nella query ed eventi onChildRemoved per gli elementi che ne escono, in modo che il numero totale rimanga pari a 100.

L'esempio seguente mostra come l'app di blogging di esempio definisce una query per recuperare un elenco dei 100 post più recenti di tutti gli utenti:

final recentPostsRef = FirebaseDatabase.instance.ref('posts').limitToLast(100);

Questo esempio definisce solo una query. Per sincronizzare effettivamente i dati, deve avere un listener collegato.

Filtra per chiave o valore

Puoi utilizzare startAt(), startAfter(),endAt(), endBefore() e equalTo() per scegliere punti di inizio, fine ed equivalenza arbitrari per le query. Questo può essere utile per impaginare i dati o trovare elementi con elementi secondari che hanno un valore specifico.

Come vengono ordinati i dati delle query

Questa sezione spiega come i dati vengono ordinati in base a ciascuno dei metodi di ordinamento nella classe Query.

orderByChild

Quando utilizzi orderByChild(), i dati che contengono la chiave secondaria specificata vengono ordinati come segue:

  1. I nodi secondari con un valore null per la chiave secondaria specificata vengono visualizzati per primi.
  2. Seguono gli elementi secondari con un valore false per la chiave secondaria specificata. Se più elementi secondari hanno un valore false, vengono ordinati lessicograficamente in base alla chiave.
  3. Seguono gli elementi secondari con un valore true per la chiave secondaria specificata. Se più elementi secondari hanno un valore true, vengono ordinati lessicograficamente per chiave.
  4. Seguono gli elementi secondari con un valore numerico, ordinati in ordine crescente. Se più elementi secondari hanno lo stesso valore numerico per il nodo secondario specificato, vengono ordinati per chiave.
  5. Le stringhe vengono dopo i numeri e sono ordinate lessicograficamente in ordine crescente. Se più elementi secondari hanno lo stesso valore per il nodo secondario specificato, vengono ordinati in ordine lessicografico per chiave.
  6. Gli oggetti vengono visualizzati per ultimi e sono ordinati lessicograficamente per chiave in ordine crescente.

orderByKey

Quando utilizzi orderByKey() per ordinare i dati, questi vengono restituiti in ordine crescente per chiave.

  1. I nodi secondari con una chiave che può essere analizzata come un numero intero a 32 bit vengono visualizzati per primi, ordinati in ordine crescente.
  2. Seguono i nodi secondari con un valore di stringa come chiave, ordinati lessicograficamente in ordine crescente.

orderByValue

Quando utilizzi orderByValue(), i nodi secondari vengono ordinati in base al loro valore. I criteri di ordinamento sono gli stessi di orderByChild(), ad eccezione del fatto che viene utilizzato il valore del nodo anziché il valore di una chiave secondaria specificata.

Scollega i listener

I callback vengono rimossi chiamando il metodo off() sul riferimento al database Firebase.

Puoi rimuovere un singolo listener passandolo come parametro a off(). La chiamata di off() nella posizione senza argomenti rimuove tutti i listener in quella posizione.

La chiamata di off() su un listener principale non rimuove automaticamente i listener registrati sui relativi nodi secondari; off() deve essere chiamato anche su tutti i listener secondari per rimuovere il callback.

Passaggi successivi