18.04.2025

Verificando a Conclusão do Carregamento de Imagem no AngularJS: ng-src e iScroll

Resposta Rápida

No AngularJS, há uma diretiva projetada para rastrear quando uma imagem terminou de carregar usando ng-src. Você precisa vincular o evento load ao elemento img da seguinte maneira:

app.directive('imageOnLoad', function() {
  return {
    restrict: 'A',
    link: function(scope, element) {
      element.on('load', function() {
        // A imagem foi carregada, registre este evento!
        scope.$evalAsync('quandoCarregado()');

        element.on('error', function() {
          // Ocorreu um erro ao carregar a imagem, não é meu dia...
          scope.$evalAsync('erroAoCarregar()');
        });
      });
    }
  };
});

Para usar esta diretiva no HTML, você deve fazer assim:

<img ng-src="{{urlDaImagem}}" image-on-load>

Substitua quandoCarregado() e erroAoCarregar() pelas funções correspondentes que você planeja chamar em caso de carregamento bem-sucedido ou falha no carregamento da imagem.

iScroll - Prevenindo Rolagem Indesejada

Se a imagem estiver localizada dentro de um contêiner rolável, como iScroll, atualizar o scroller logo após a imagem ser carregada proporcionará uma experiência de rolagem suave para os usuários. Isso também ajudará a definir corretamente os limites de rolagem:

app.controller('MeuControlador', function($scope) {
  $scope.quandoCarregado = function() {
    if (iScrollInstance) {
      // Preparação concluída, iScroll pode ser atualizado
      iScrollInstance.refresh();
    }
  };
});

A função iScrollInstance.refresh() é chamada sempre que uma imagem é carregada com sucesso.

E Agora? Lidando com Erros de Carregamento de Imagem

Para garantir que sua diretiva de carregamento de imagem no AngularJS seja robusta, adicione um tratamento de erros para os casos onde as imagens falham ao carregar:

app.directive('imageOnLoad', function() {
  return {
    restrict: 'A',
    link: function(scope, element) {
      element.on('load', function() {
        // Tudo certo, a imagem carregou com sucesso!
        scope.$evalAsync('quandoCarregado()');
      }).on('error', function() {
        // Precisamos resolver o problema de carregamento da imagem
        scope.$evalAsync('erroAoCarregar()');
      });
    }
  };
});

Se a imagem não puder ser carregada, defina uma imagem alternativa ou uma mensagem ao definir a função correspondente erroAoCarregar().

Diretiva Versátil: Uso Avançado

Torne a diretiva mais eficiente permitindo a passagem de funções de callback variáveis:

app.directive('imageOnLoad', function() {
  return {
    scope: {
      quandoCarregado: '&', // Callback dinâmico para carregamento bem-sucedido
      erroAoCarregar: '&' // Callback dinâmico para tratamento de erro
    },
    link: function(scope, element, attrs) {
      element.on('load', function() {
        // Imagem carregada com sucesso!
        scope.quandoCarregado();
      }).on('error', function() {
        // Ocorreu um problema: a imagem não carregou!
        scope.erroAoCarregar();
      });
    }
  };
});

Vincular as funções de callback ao escopo torna a diretiva flexível e permite que diferentes funções sejam atribuídas a diferentes tags <img>:

<img ng-src="{{urlDaImagem}}" image-on-load quando-carregado="imagemCarregada()" erro-ao-carregar="falhaNoCarregamento()">

Visualização

Vamos ilustrar como o carregamento de imagem funciona com uma analogia simples:

🚂 = Imagem  
🛤️ = caminho do ng-src  
🚉 = elemento HTML (o que contém ng-src)

Jornada do Trem:

1. O trem (🚂) viaja pelos trilhos (🛤️) até a estação (🚉).
2. Os passageiros (👀) aguardam sua chegada.
3. Ao chegar do trem (carregamento da imagem concluído), os passageiros iniciam sua jornada (evento é acionado).

No contexto do AngularJS, isso se parece com:

$scope.$watch('urlDaImagem', function (novoValor) {
    if (novoValor) {
        // 🚂 chega ao 🚉 via 🛤️
        // Sinal para os passageiros (evento é acionado)
    }
});

Resumo: Assim que a imagem estiver totalmente carregada (o trem chegou), o evento é acionado (a chegada é anunciada).

Recursos Úteis

1. Documentação da API do AngularJS - Diretiva ngSrc — documentação oficial para a diretiva ngSrc no AngularJS.
2. MDN Web Docs - EventTarget.addEventListener() — guia para usar addEventListener() em JavaScript.
3. CSS-Tricks - Corrigindo .load() no IE para Imagens em Cache — potenciais fraquezas e formas de abordá-las ao trabalhar com eventos de carregamento de imagem no Internet Explorer.
4. Documentação da API do AngularJS - Diretiva ngBind — documentação oficial para a diretiva ngBind no AngularJS.
5. Padrão HTML - img: O elemento de Imagem — especificação HTML explica como o elemento <img> funciona e o comportamento de carregamento relacionado.
6. GitHub - angular/ngImgCrop: Diretiva de Recorte de Imagem para AngularJS — diretiva para recorte de imagem no AngularJS, demonstrando várias capacidades de controle do ng-src.

Video

Navigation