Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizzare elenchi di dati

Recuperare un riferimento a un database

Per leggere o scrivere dati dal database, è necessaria un'istanza di DatabaseReference:

DatabaseReference ref = FirebaseDatabase.instance.ref();

Lettura e scrittura di elenchi

Aggiunta a un elenco di dati

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, pertanto 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 del publisher secondario o imposta i dati per quest'ultimo. La 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 ulteriori informazioni, 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 secondari

Gli eventi secondari vengono attivati in risposta a operazioni specifiche che si verificano per i figli di un nodo da un'operazione, ad esempio un nuovo figlio aggiunto tramite il metodo push() o un figlio aggiornato tramite il metodo update().

Evento	Utilizzo tipico
`onChildAdded`	Recupera elenchi di elementi o ascolta le aggiunte a un elenco di elementi. Questo evento viene attivato una volta per ogni account figlio esistente e poi di nuovo ogni volta che viene aggiunto un nuovo asset secondario al percorso specificato. All'ascoltatore viene fornito uno snapshot contenente i dati del nuovo bambino.
`onChildChanged`	Rileva le modifiche agli elementi di un elenco. Questo evento viene attivato ogni volta che un nodo secondario viene modificato. Sono inclusi eventuali modifiche ai discendenti del nodo figlio. Snapshot trasmesso al listener di eventi contiene i dati aggiornati per il file secondario.
`onChildRemoved`	Ascolta gli elementi che vengono rimossi da un elenco. Questo evento viene attivato quando viene rimosso un elemento figlio immediato. Lo snapshot passato al blocco di callback contiene i dati dell'elemento figlio rimosso.
`onChildMoved`	Rileva le modifiche all'ordine degli elementi in un elenco ordinato. Gli eventi onChildMoving seguono sempre Evento onChildChanged che ha attivato l'ordine dell'articolo modificare (in base al metodo di ordinamento corrente).

Ciascuno di questi elementi insieme può essere utile per ascoltare le modifiche a una specifica in 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 secondari sia il modo consigliato per leggere gli elenchi di dati, in alcune situazioni è utile ascoltare gli eventi di valore in un riferimento elenco.

Se colleghi un ascoltatore value a un elenco di dati, verrà restituito l'intero elenco di dati come un'unica istantanea, che potrai poi eseguire in loop per accedere ai singoli elementi secondari.

Anche quando esiste una sola corrispondenza per la query, lo snapshot è comunque una list; 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é ascoltare altri eventi di aggiunta di elementi secondari.

Ordinare e filtrare i dati

Puoi utilizzare la classe Query per recuperare i dati ordinati per chiave, valore o 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 e i relativi valori.

Ordinare i dati

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

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

Puoi utilizzare un solo metodo di ordine 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 migliori 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");

Questa definisce una query che, se combinata con un listener secondario, consente di sincronizzare il client con i post dell'utente dal percorso nel database in base al relativo ID utente, ordinati in base al numero di stelle ricevute da ciascun post. Questa tecnica che utilizza gli ID come chiavi indice è chiamata "Data fan-out", ovvero per saperne di più Strutturare il database.

La chiamata al metodo orderByChild() specifica la chiave figlio per ordinare risultati. In questo caso, i post vengono ordinati in base al valore rispettivo "starCount" figlio. Le query possono essere ordinate anche per secondari, nel caso in cui si disponessero di dati 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 sotto metrics specificando il percorso relativo dell'elemento secondario nidificato nel nostro Chiamata orderByChild().

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

Per ulteriori informazioni sull'ordinamento di altri tipi di dati, consulta Come vengono ordinati i dati delle query.

Filtrare i dati

Per filtrare i dati, puoi combinare qualsiasi metodo basato su limite o intervallo con una al momento di creare una query.

Metodo	Utilizzo
`limitToFirst()`	Imposta il numero massimo di elementi da restituire dall'inizio del un elenco ordinato di risultati.
`limitToLast()`	Imposta il numero massimo di elementi da restituire dalla fine dell'elenco ordinato dei risultati.
`startAt()`	Restituisci elementi maggiori o uguali alla chiave o al valore specificato, a seconda del metodo di ordine scelto.
`startAfter()`	Restituisci elementi maggiori della chiave o del valore specificato a seconda del metodo di ordine scelto.
`endAt()`	Restituisci elementi minori o uguali alla chiave o al valore specificato, a seconda del metodo di ordine scelto.
`endBefore()`	Restituisci elementi di importo inferiore alla chiave o al valore specificato a seconda del metodo di ordine scelto.
`equalTo()`	Restituisci gli elementi uguali alla chiave o al valore specificato, a seconda del in base al metodo 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 hai meno di 100 elementi archiviati nel tuo Database Firebase, viene attivato un evento onChildAdded per ogni elemento.

Quando gli elementi cambiano, ricevi eventi onChildAdded per gli elementi che entrano nella query ed eventi onChildRemoved per quelli che ne escono, in modo che il numero totale rimanga 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 è necessario avere un listener collegato.

Filtra per chiave o valore

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

Come vengono ordinati i dati delle query

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

`orderByChild`

Quando utilizzi orderByChild(), i dati contenenti la chiave secondaria specificata vengono ordinate come segue:

Gli elementi secondari con un valore null per la chiave figlio specificata per prima cosa.
Gli elementi secondari con un valore false per la chiave secondaria specificata vengono visualizzati successivamente. Se più elementi secondari hanno un valore false, vengono ordinati in ordine alfabetico in base alla chiave.
Elementi secondari con un valore true per la chiave figlio specificata viene dopo. Se più elementi secondari hanno un valore true, vengono e ordinate lessicograficamente per chiave.
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 in base alla chiave.
Le stringhe vengono dopo i numeri e sono ordinate lessicograficamente in ordine crescente ordine. Se più elementi secondari hanno lo stesso valore per l'elemento secondario specificato nodo, sono ordinate lessicograficamente per chiave.
Gli oggetti sono gli ultimi e vengono ordinati lessicograficamente per chiave in ordine crescente.

`orderByKey`

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

I figli con una chiave che può essere analizzata come numero intero a 32 bit vengono visualizzati per primi, in ordine crescente.
Figli con un valore stringa come chiave successivo, ordinati lessicograficamente in ordine crescente.

`orderByValue`

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

Scollega listener

I callback vengono rimossi chiamando il metodo off() sul tuo Riferimento database Firebase.

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

La chiamata a off() su un ascoltatore principale nonrimuove automaticamente gli ascoltatori registrati sui relativi nodi secondari.off() deve essere chiamato anche su tutti gli ascoltatori secondari per rimuovere il callback.