Detalhes do pacotev0.9.11

workmanager_apple

Implementação da plataforma Apple (iOS/macOS) do plugin workmanager.

iOSmacOS

pub.dev Documentação da API Código-fonte

Downloads em 30 dias: 279 mil
Curtidas: 4
Pontos Pub: 150

Instalar pacote

flutter pub add workmanager_apple

Visão geral do pacote

Orientação gerada a partir de informações públicas. Apenas para referência.

O pacote workmanager_apple fornece suporte à plataforma Apple (iOS e macOS) para o plugin workmanager, permitindo a execução de tarefas em segundo plano em aplicativos Flutter. Ele permite que desenvolvedores agendem tarefas periódicas ou únicas que continuam rodando mesmo quando o aplicativo é encerrado, garantindo processamento confiável em segundo plano em dispositivos Apple. Essa implementação integra-se às APIs do sistema iOS e macOS para gerenciar a execução em segundo plano de forma eficiente, respeitando as restrições específicas da plataforma e os recursos de economia de energia.

Casos de uso

Agendamento de sincronização periódica de dados
Atualizações de localização em segundo plano estão sendo executadas
Executando notificações agendadas
Realizando processamento de dados off-line
Manter a continuidade da tarefa em segundo plano

Principais recursos

Manipulação de tarefas em segundo plano específica da plataforma Apple
Integração com APIs do sistema iOS/macOS
Suporte para tarefas periódicas e uma vez
Execução em segundo plano eficiente em energia
Integração contínua com o núcleo do workmanager

Indicado para

Aplicativos Flutter que exigem processamento em segundo plano no iOS
Desenvolvedores direcionados ao macOS com necessidades de fundo
Aplicativos que precisam de agendamento confiável de tarefas em segundo plano
Projetos usando o plugin workmanager em várias plataformas
Aplicações com requisitos de sincronização de dados ou monitoramento

Considerações

Requer configuração adequada nas configurações do projeto no Xcode
Tempo limitado de execução em segundo plano no iOS
Os modos de fundo devem ser habilitados nas capacidades do aplicativo
Não compatível com todos os tipos de tarefa em segundo plano
Pode ser necessário permissão do usuário para certas operações

README original

Snapshot do README original do repositório-fonte vinculado. Consulte o repositório para o conteúdo mais recente.

Flutter Workmanager

Execute Dart code in the background, even when your app is closed (Android and iOS). On macOS, background tasks run while the app is running or backgrounded and the Mac is awake. Perfect for data sync, file uploads, and periodic maintenance tasks.

⚠️ Experimental web support now exists via workmanager_web (Service Worker + Web Worker based background execution). See the Web (experimental) page and the package README for honest limitations and how to test it in Chrome.

📖 Documentation

Get started with background tasks in Flutter:

→ Quick Start Guide - Installation and setup

→ API Documentation - Complete Dart API reference

→ Debugging Guide - Troubleshooting help

→ Troubleshooting Guide - Why tasks stop after app close (OEM battery optimization, constraints, verification)

🎯 Use Cases

Background tasks are perfect for:

Sync data from API - Keep your app's data fresh
Upload files in background - Reliable file uploads
Clean up old data - Remove old files and cache
Fetch notifications - Check for new messages
Database maintenance - Optimize and clean databases

⏱ Long-Running Tasks (Android)

For work that takes longer than the regular background execution window (bulk uploads/downloads, ML processing), Android tasks can run as a foreground service with a persistent notification. Pass a foregroundServiceConfig to registerOneOffTask or registerPeriodicTask:

await Workmanager().registerOneOffTask(
  "upload-task",
  "upload_files",
  foregroundServiceConfig: ForegroundServiceConfig(
    notificationTitle: "Uploading files",
    notificationText: "Your files are being uploaded",
  ),
);

See the Quick Start guide for details and platform caveats.

🛑 Cancelling Running Work (Android)

cancelByUniqueName, cancelByTag and cancelAll stop the WorkManager worker immediately, but the Dart callback that is currently running keeps executing unless it reacts to the stop. Pass an onTaskStopped handler to executeTask inside your callbackDispatcher to be notified when a running task is stopped before it finishes:

@pragma('vm:entry-point')
void callbackDispatcher() {
  Workmanager().executeTask(
    (taskName, inputData) async {
      return true;
    },
    onTaskStopped: (taskName, stopReason) async {
      // Mark the task as cancelled / persist state, then return promptly.
    },
  );
}

The handler receives the task name and the WorkManager stop reason (cancelledByApp, timeout, preempt, ...); on Android < 12 the reason is StopReason.unknown. Android-only — iOS has no way to stop a running task. See the Customization guide for details.