Menu Docs

Abrir um Realm sincronizado — Flutter SDK

Esta página descreve como abrir um domínio sincronizado usando o Device Sync. Para saber como abrir e configurar domínios não sincronizados, consulte Abrir e fechar um domínio.

Antes de abrir um Realm com o Flexible Sync em uma aplicação do Flutter:

  1. Configure a Flexible Sync no backend. Você deve configurar o Flexible Sync no backend antes de poder usá-lo com seu aplicação cliente.

  2. Inicialize a aplicação do cliente.

  3. Autenticar um usuário em seu projeto de cliente.

Para abrir um Realm sincronizado, passe um usuário conectado, uma lista de esquemas de Objeto de Realm e argumentos nomeados opcionais adicionais para o arquivo Configuration.flexibleSync() construtor. Este construtor retorna uma FlexibleSyncConfiguration. Em seguida, passe o FlexibleSyncConfiguration para Realm() para abrir uma instância do Realm. Os dados são sincronizados com o App Services em segundo plano depois que você abre o Realm.

final currentUser = await app.logIn(credentials);
final config = Configuration.flexibleSync(currentUser, [Tricycle.schema],
path: 'flex.realm');
final realm = Realm(config);

Depois de abrir um Realm sincronizado, configure e managed as assinaturas de sincronização.

Para sincronizar todos os dados com o Atlas App Services quando você abre um domínio, use o método assíncrono Realm.open(). A operação sincroniza todos os dados disponíveis antes de retornar ao domínio.

Na primeira abertura, o Realm.open() baixa todos os dados que correspondem às suas assinaturas de sincronização. As aberturas subsequentes baixam apenas as alterações mais recentes. Dependendo do tamanho inicial do Realm e das atualizações do conjunto de dados enquanto o dispositivo não está sincronizando, o desempenho pode ser mais lento na primeira abertura e mais rápido nas aberturas subsequentes.

Se o aplicativo cliente estiver offline, Realm.open() não será resolvido. Você deve verificar se o dispositivo está conectado à internet antes de usar o Realm.open(). Se o dispositivo não estiver conectado à Internet, você ainda poderá usar Realm() para abrir um Realm imediatamente e sincronizar os dados em segundo plano quando uma conexão com a Internet estiver disponível.

// Helper function to check if device is connected to the internet.
Future<bool> isDeviceOnline() async {
// ...logic to check if device is online
}
final config = Configuration.flexibleSync(currentUser, [Tricycle.schema]);
// Only use asynchronous open if app is online.
late Realm realm;
if (await isDeviceOnline()) {
// If the device is online, download changes and then open the realm.
realm = await Realm.open(config);
} else {
// If the device is offline, open the realm immediately
// and automatically sync changes in the background when the device is online.
realm = Realm(config);
}

Para rastrear o estado da sincronização, passe uma ProgressCallback ao argumento opcional nomeado onProgressCallback.

double progressEstimate = -1;
final realm = await Realm.open(config, onProgressCallback: (syncProgress) {
progressEstimate = syncProgress.progressEstimate;
print('Sync progress: ${progressEstimate * 100}% complete.');
if (progressEstimate == 1.0) {
// Transfer is complete
}
});

Dica

Se você deseja configurar notificações de progresso depois de abrir um Realm, use SyncSession.getProgressStream.

Para cancelar uma sincronização em andamento, passe um CancellationToken instância para o argumento nomeado opcional cancellationToken. Chame CancellationToken.cancel() para cancelar a sincronização.

final token = CancellationToken();
// Cancel the open operation after 30 seconds.
// Alternatively, you could display a loading dialog and bind the cancellation
// to a button the user can click to stop the wait.
Future<void>.delayed(
const Duration(seconds: 30),
() => token.cancel(CancelledException(
cancellationReason: "Realm took too long to open")));
// If realm does not open after 30 seconds with asynchronous Realm.open(),
// open realm immediately with Realm() and try to sync data in the background.
late Realm realm;
try {
realm = await Realm.open(config, cancellationToken: token);
} on CancelledException catch (err) {
print(err.cancellationReason); // prints "Realm took too long to open"
realm = Realm(config);
}

Exemplo

Realm() vs. Realm.open()

Esta seção compara exemplos de cenários em que você pode querer usar Realm() versus Realm.open() para abrir um Realm em uma aplicação.

Considere um aplicativo que permita aos usuários gravar e salvar suas receitas favoritas. Talvez você queira dar ao usuário a opção de criar uma nova receita sem esperar para baixar as atualizações, ou mesmo se estiver offline. Neste caso, Realm() é preferível. O usuário pode operar offline, mas o aplicativo sincroniza suas receitas da próxima vez que tiver uma conexão de rede.

Considere um aplicativo de jogo com uma versão para tablete e telefone. Um usuário joga o jogo em uma tabela e em um telefone. O usuário progride três níveis no comprimido. Mais tarde, o usuário abre o jogo em um telefone. Neste caso, Realm.open() é a melhor maneira de abrir o Realm. Como o Realm.open() sincroniza os dados antes de retornar o Realm, ele garante que o progresso do usuário seja sincronizado no telefone antes que ele comece a usar o aplicativo, mesmo que o tempo de carregamento inicial seja mais lento.

Para obter mais informações sobre as opções gerais de configuração do Realm, consulte Configurar um Realm.

Para lidar com erros no seu Realm sincronizado usando propriedade de configuração adicionais, consulte Lidar com erros de sincronização.

Quando terminar de trabalhar com um Realm sincronizado, feche-o para evitar vazamentos de memória.

realm.close();