Diretivas personalizadas do AngularJS: Modelos, Escopo e Transclusão
James Hartmann
⚡ Resumo Inteligente
As diretivas personalizadas no AngularJS estendem o HTML com comportamentos reutilizáveis que você define. Uma fábrica de diretivas retorna um objeto de definição, e o AngularJS aplica esse comportamento sempre que o elemento, atributo, classe ou comentário correspondente aparecer na marcação.
O que é uma diretiva personalizada no AngularJS?
A Diretiva Aduaneira Em AngularJS, `@index` é uma diretiva definida pelo usuário que estende o HTML com comportamentos que você mesmo escreve. Ela é registrada em um arquivo HTML. módulo Utilizando a função "diretiva", o AngularJS a anexa onde quer que o elemento ou atributo correspondente apareça na página. Embora o AngularJS possua muitas funcionalidades poderosas, ele ainda oferece recursos avançados. diretivas integradas pronto para usar, como por exemplo ng-repetirÀs vezes, são necessárias diretivas personalizadas.
⚠️ Correção: O texto original dizia que uma diretiva personalizada "substitui o elemento para o qual é usada". Por padrão, isso não acontece: template está inserido dentro o elemento correspondente. Necessidade de substituição replace: true, obsoleto desde o AngularJS 1.3.
⚠️ Aviso de suporte: AngularJS alcançou fim da vida em 31 de dezembro de 2021 e não recebe mais patches ou correções de segurança. Tudo abaixo permanece válido para a manutenção do código AngularJS 1.x existente; no Angular moderno, os equivalentes são componentes e diretivas de atributo.
O motivo para usar uma diretiva personalizada é a repetição. Quando a mesma marcação ou estrutura DOM aparece em várias telas, uma diretiva a transforma em uma única tag nomeada.
Como criar uma diretiva personalizada?
Vejamos um exemplo de como podemos criar uma diretiva personalizada em AngularJS.
A diretiva personalizada, em nosso caso, simplesmente irá inserir uma tag div com o texto “Angular JS Tutorial” em nossa página quando a diretiva for chamada.
A captura de tela anotada abaixo numera as quatro partes da listagem explicadas a seguir.
<!DOCTYPE html> <html> <head> <meta chrset="UTF 8"> <title>Event Registration</title> </head> <body> <script src="https://code.angularjs.org/1.6.9/angular-route.js"></script> <script src="https://code.angularjs.org/1.6.9/angular.js"></script> <script src="https://code.angularjs.org/1.6.9/angular.min.js"></script> <script src="https://code.jquery.com/jquery-3.3.1.min.js"></script> <h1> Guru99 Global Event</h1> <div ng-app="DemoApp"> <div ng-guru=""></div> </div> <script type="text/javascript"> var app = angular.module('DemoApp',[]); app.directive('ngGuru',function(){ return { template: '<div>Angular JS Tutorial</div>' } }); </script> </body> </html>
⚠️ Atenção — defeitos preservados neste anúncio: O código foi reproduzido exatamente como publicado. Três falhas se repetem em todas as listagens aqui: chrset="UTF 8" deveria estar charset="UTF-8"; angular.js e angular.min.js ambos carregam, então o AngularJS carrega duas vezes; e angular-route.js Carrega antes do arquivo do qual depende.
Code Explicação
- Estamos primeiro criando um módulo Para nossa aplicação AngularJS. Isso é necessário para criar uma diretiva personalizada, pois a diretiva será criada usando este módulo.
- Estamos criando uma diretiva personalizada chamada “ng”Guru"e definindo uma função de fábrica que conterá o código personalizado para nossa diretiva."
- Estamos usando o parâmetro `template`, que é um parâmetro definido pelo AngularJS para diretivas personalizadas. Nele, definimos que, sempre que essa diretiva for usada, basta utilizar o valor do template e injetá-lo no código que a chama.
- Aqui estamos utilizando nossa diretiva personalizada “ng-guru”. Ao fazer isso, o valor que definimos para nosso modelo,
<div>Angular JS Tutorial</div>, será injetado aqui agora.
Diretivas de nomenclatura e normalização
A incompatibilidade de nomes entre o JavaA linguagem de script e HTML confunde a maioria dos iniciantes. AngularJS normaliza cada elemento e nome de atributo antes da correspondência: remove qualquer x- or data- prefixo e, em seguida, converte um nome delimitado por -, : or _ para camelCase. É por isso. ngGuru fósforos ng-guru, e porque data-ng-guru Também funciona. O formato camelCase é o nome real; kebab-case é simplesmente a forma como é escrito em HTML.
⚠️ Correção: O texto original dizia que o nome de uma diretiva personalizada “deveria começar com as letras 'ng'”. Documentação oficial do AngularJS aconselha o oposto: nunca prefixe suas próprias diretivas com ngou podem entrar em conflito com um recurso integrado futuro. Use seu próprio prefixo, como g99Guru escrito como g99-guru.
Se o código for executado com sucesso, esta saída será exibida.
Saída:
O resultado mostra claramente que nossa diretiva ng-guru personalizada, que possui o modelo definido para exibir um texto personalizado, é exibida no navegador. O próximo passo é inserir algo que possa ser reutilizado dentro desse modelo.
Como criar diretivas reutilizáveis
Já vimos o poder das diretivas personalizadas, mas podemos levar isso para o próximo nível criando as nossas próprias diretivas reutilizáveis.
Vamos supor, por exemplo, que quiséssemos inserir um código que sempre exibisse as tags HTML abaixo em várias telas, que basicamente são apenas campos para inserir o “Nome” e a “Idade” do usuário.
Para reutilizar esse fragmento em várias telas sem precisar codificá-lo todas as vezes, criamos um controle mestre, ou diretiva, no AngularJS para conter esses dois controles.
Agora, em vez de repetir essa marcação em todas as telas, nós a incorporamos em uma diretiva e chamamos a diretiva. A captura de tela abaixo mostra a única linha que muda.
<!DOCTYPE html> <html> <head> <meta chrset="UTF 8"> <title>Event Registration</title> </head> <body> <script src="https://code.angularjs.org/1.6.9/angular-route.js"></script> <script src="https://code.angularjs.org/1.6.9/angular.js"></script> <script src="https://code.angularjs.org/1.6.9/angular.min.js"></script> <script src="https://code.jquery.com/jquery-3.3.1.min.js"></script> <h1> Guru99 Global Event</h1> <div ng-app="DemoApp"> <div ng-guru=""></div> </div> <script type="text/javascript"> var app = angular.module('DemoApp',[]); app.directive('ngGuru',function(){ return { template: ' Name <input type="text"><br><br> Age<input type="text">' }; }); </script> </body> </html>
Code Explicação
- Em nosso trecho de código para uma diretiva personalizada, o que muda é apenas o valor fornecido ao parâmetro do modelo. Em vez de uma tag simples ou uma linha de texto, estamos inserindo o fragmento completo de dois controles de entrada para "Nome" e "Idade" que precisam ser exibidos em nossa página.
💡 Dica: Um modelo tão longo assim deve estar em um arquivo separado. Trocar. template pela templateUrl: 'name-age.html'.
Se o código for executado com sucesso, esta saída será exibida.
Saída:
A partir da saída acima, podemos ver que o trecho de código do modelo da diretiva personalizada é adicionado à página. O modelo ainda é estático, então o próximo passo é alimentá-lo com dados.
Diretivas e Escopos do AngularJS
O escopo É definida como a cola que liga o controlador à visualização, gerenciando os dados entre a visualização e o controlador.
Ao criar diretivas personalizadas do AngularJS, elas terão, por padrão, acesso ao objeto de escopo no controlador pai. Trata-se do mesmo objeto de escopo, não de uma cópia.
Dessa forma, fica fácil para a diretiva customizada fazer uso dos dados que estão sendo passados para o controlador principal.
Vejamos um exemplo de como podemos usar o escopo de um controlador pai em nossa diretiva personalizada. A captura de tela abaixo numera as quatro etapas.
<!DOCTYPE html> <html> <head> <meta chrset="UTF 8"> <title>Event Registration</title> </head> <body> <script src="https://code.angularjs.org/1.6.9/angular-route.js"></script> <script src="https://code.angularjs.org/1.6.9/angular.js"></script> <script src="https://code.angularjs.org/1.6.9/angular.min.js"></script> <script src="https://code.jquery.com/jquery-3.3.1.min.js"></script> <h1> Guru99 Global Event</h1> <div ng-app="DemoApp" ng-controller="DemoController"> <div ng-guru=""></div> </div> <script type="text/javascript"> var app = angular.module('DemoApp',[]); app.controller('DemoController',function($scope) { $scope.tutorialName = "Angular JS"; }); app.directive('ngGuru',function(){ return { template: '<div>{{tutorialName}}</div>' } }); </script> </body> </html>
Code Explicação
- Primeiro, criamos um controlador chamado “DemoController”. Nele, definimos uma variável chamada tutorialName e a associamos ao objeto de escopo em uma única instrução:
$scope.tutorialName = "Angular JS". - Em nossa diretiva customizada, podemos chamar a variável “tutorialName” usando uma expressão. Esta variável seria acessível porque está definida no controlador “DemoController”, que se tornaria o pai desta diretiva.
- Fazemos referência ao controlador em uma tag div, que atuará como nossa tag div pai. Observe que isso precisa ser feito primeiro para que nossa diretiva personalizada acesse a variável tutorialName.
- Finalmente, apenas anexamos nossa diretiva personalizada “ng-guru” à nossa tag div.
Se o código for executado com sucesso, esta saída será exibida.
Saída:
O resultado acima mostra claramente que nossa diretiva personalizada “ng-guru” utiliza a variável de escopo tutorialName no controlador pai. Compartilhar o escopo pai é conveniente, mas nem sempre é o que se deseja.
Usando controladores com diretivas
O AngularJS oferece a possibilidade de acessar a variável de membro do controlador diretamente das diretivas personalizadas sem a necessidade do objeto de escopo.
Isso se torna necessário em alguns casos porque um aplicativo pode ter vários objetos de escopo pertencentes a vários controladores, portanto, há uma grande chance de acessar o objeto de escopo do controlador errado por engano.
Nesse cenário, existe uma maneira de dizer especificamente "Eu quero acessar este controlador" a partir da minha diretiva.
Vejamos um exemplo de como podemos alcançar isso. A captura de tela numera os quatro passos.
<!DOCTYPE html> <html> <head> <meta chrset="UTF 8"> <title>Event Registration</title> </head> <body> <script src="https://code.angularjs.org/1.6.9/angular-route.js"></script> <script src="https://code.angularjs.org/1.6.9/angular.js"></script> <script src="https://code.angularjs.org/1.6.9/angular.min.js"></script> <script src="https://code.jquery.com/jquery-3.3.1.min.js"></script> <h1> Guru99 Global Event</h1> <div ng-app="DemoApp" ng-controller="DemoController"> <div ng-guru99=""></div> </div> <script type="text/javascript"> var app = angular.module('DemoApp',[]); app.controller('DemoController',function() { this.tutorialName = "Angular"; }); app.directive('ngGuru99',function(){ return { controller: 'DemoController', controllerAs: 'ctrl', template: '{{ctrl.tutorialName}}' }; }); </script> </body> </html>
Code Explicação
- Primeiro, criamos um controlador chamado “DemoController”. Nele, definiremos uma variável chamada “tutorialName” e, desta vez, em vez de associá-la ao objeto de escopo, a associaremos diretamente ao controlador.
- Em nossa diretiva customizada, mencionamos especificamente que queremos usar o controlador “DemoController” usando a palavra-chave do parâmetro do controlador.
- Criamos uma referência ao controlador usando o parâmetro “controllerAs”. Este parâmetro é definido pelo AngularJS e é a forma de referenciar o controlador por meio de um alias.
- Finalmente, em nosso modelo, estamos usando a referência criada na etapa 3 e a variável de membro que foi anexada diretamente ao controlador na etapa 1.
Observação: É possível acessar múltiplos controladores em uma diretiva especificando os respectivos blocos do controlador, `controllerAs` e instruções de modelo. Para alcançar um principal Em vez disso, use o controlador da diretiva. require.
Se o código for executado com sucesso, esta saída será exibida.
Saída:
O resultado mostra claramente que a diretiva personalizada está acessando o DemoController e a variável membro tutorialName associada a ele, e exibe o texto “Angular”. Ambas as abordagens ainda leem de um escopo compartilhado, o que um escopo isolado impede.
Como as associações @, =, & e < diferem em um escopo isolado
Uma diretiva que compartilha o escopo do controlador pai só pode ser usada uma vez por controlador, pois duas cópias entrariam em conflito pelas mesmas variáveis. scope objeto cria um escopo de isolamentoA diretiva não vê nada fora do escopo, exceto as propriedades que você lista. Cada entrada usa um símbolo de prefixo que declara como seu valor é transmitido.
| Símbolo | Direção | Valor recebido | Use para |
|---|---|---|---|
| @ | Sentido único | O atributo como uma string interpolada | Rótulos, títulos, qualquer texto simples |
| = | Nos dois sentidos | O objeto ou valor vivo em si | Modelos para os quais a diretiva escreve de volta. |
| & | Chamada externa | Uma função que avalia uma expressão no escopo externo. | Funções de retorno de chamada, como ao fechar ou ao salvar. |
| < | Sentido único | O valor avaliado, nunca escrito para cima. | Dados somente leitura, adicionados no AngularJS 1.5. |
💡 Dica: Alcance para < antes =A vinculação unidirecional é mais barata de monitorar e impede que um componente altere silenciosamente os dados de seu chamador. A próxima seção usa @.
Diretivas e componentes do AngularJS: ng-transclude
Como mencionamos anteriormente, o AngularJS tem como objetivo estender a funcionalidade de HTML. E já vimos como podemos ter injeção de código usando diretivas reutilizáveis personalizadas.
Mas no desenvolvimento moderno de aplicações web, existe também o conceito de desenvolvimento.ping Componentes web, que basicamente significam criar nossas próprias tags HTML que podem ser usadas como componentes em nosso código.
Assim, o AngularJS oferece um nível adicional de poder para estender as tags HTML, permitindo envolver qualquer marcação que o usuário insira dentro da tag.
Isto é feito pelo “ng-transcluirA diretiva “custom-tag”, que instrui o AngularJS a capturar tudo o que for inserido dentro da tag personalizada na marcação e a inseri-lo no modelo nesse ponto.
Vejamos um exemplo de como podemos alcançar isso. A captura de tela numera os cinco pontos a seguir.
<!DOCTYPE html> <html> <head> <meta chrset="UTF 8"> <title>Event Registration</title> </head> <body> <script src="https://code.angularjs.org/1.6.9/angular-route.js"></script> <script src="https://code.angularjs.org/1.6.9/angular.js"></script> <script src="https://code.angularjs.org/1.6.9/angular.min.js"></script> <script src="https://code.jquery.com/jquery-3.3.1.min.js"></script> <h1> Guru99 Global Event</h1> <div ng-app="DemoApp"> <pane title="{{title}}">Angular JS</pane> </div> <script type="text/javascript"> var app = angular.module('DemoApp',[]); app.directive('pane',function(){ return { transclude:true, scope :{title:'@'}, template: '<div style="border: 1px solid black;"> '+ '<ng-transclude></ng-transclude>'+ '</div>' }; }); </script> </body> </html>
Code Explicação
- Estamos usando a diretiva para definir uma tag HTML personalizada chamada “pane”, com uma função de fábrica que fornece seu código. Na saída, a tag “pane” exibe o texto “Angular JS” em um retângulo com uma borda preta sólida.
- A propriedade “transclude” precisa ser definida como verdadeira, o que instrui o AngularJS a manter a marcação interna original e torná-la disponível para o usuário.
ng-transclude. - No objeto de escopo, estamos declarando uma associação de título. Os atributos são normalmente escritos como pares nome/valor, como
name="value"No nosso caso, o atributo na tag do painel é "title", e o símbolo "@" pede ao AngularJS para copiar esse atributo como uma string interpolada. - O modelo desenha a borda preta sólida para o nosso controle e marca o local onde a marcação transcluída é inserida.
- Finalmente, estamos chamando nossa tag HTML personalizada juntamente com o atributo de título que foi definido.
⚠️ Correção: O texto original descrevia “@” como “um requisito do Angular”. Não é uma formalidade: @ é um dos quatro símbolos de ligação de escopo isolado na tabela acima e sempre produz uma string. Este modelo também nunca renderiza {{title}}e nenhum controlador define titleAssim, apenas o texto transcluído fica visível.
Se o código for executado com sucesso, esta saída será exibida.
Saída:
- O resultado mostra o elemento de painel personalizado renderizado como uma caixa com borda contendo o texto transcluído “Angular JS”.
Uma diretiva também pode conter outras diretivas, que é como componentes maiores são montados.
Diretivas Aninhadas
Diretivas em AngularJS podem ser aninhadas. Assim como módulos internos ou funções em qualquer outro tipo de linguagem. linguagem de programação, talvez seja necessário incorporar diretivas umas nas outras.
Você pode entender melhor isso vendo o exemplo abaixo.
Neste exemplo, estamos criando 2 diretivas chamadas “externas” e “internas”.
- A diretiva interna exibe um texto chamado “Inner”.
- Enquanto a diretiva externa na verdade faz uma chamada para a diretiva interna para exibir o texto chamado “Inner”.
A captura de tela abaixo mostra as duas definições de diretiva e o ponto em que uma chama a outra.
</head> <body> <script src="https://code.angularjs.org/1.6.9/angular-route.js"></script> <script src="https://code.angularjs.org/1.6.9/angular.js"></script> <script src="https://code.angularjs.org/1.6.9/angular.min.js"></script> <script src="https://code.jquery.com/jquery-3.3.1.min.js"></script> <h1> Guru99 Global Event</h1> <div ng-app="DemoApp"> <outer></outer> </div> <script type="text/javascript"> var app = angular.module('DemoApp',[]); app.directive('outer',function(){ return { restrict:'E', template: '<div><h1>Outer</h1><inner></inner></div>', }}); app.directive('inner',function(){ return { restrict:'E', template: '<div><h1>Inner</h1></div>', } }); </script> </body> </html>
⚠️ Atenção — defeito preservado neste anúncio: A lista publicada começa em </head>, perdendo sua inauguração <!DOCTYPE html>, <html> e <head> linhas. Adicione-as antes de executar o programa.
Code Explicação
- Estamos criando uma diretiva chamada “externa” que se comportará como nossa diretiva pai. Esta directiva fará então um apelo à directiva “interna”.
- O
restrict:'E'Essa opção instrui o AngularJS a corresponder a cada diretiva por elemento nome, razão pela qual podem ser escritos como tags<outer>e<inner>A letra 'E' é a abreviação da palavra 'Elemento'. - Aqui estamos criando a diretiva inner que exibe o texto “Inner” em uma tag div.
- No modelo da diretiva externa, estamos chamando a diretiva interna. Portanto, aqui estamos injetando o modelo da diretiva interna na diretiva externa.
- Finalmente, estamos a invocar directamente a directiva externa.
⚠️ Correção: O texto original afirmava restrict:'E' É necessário “garantir que os dados da diretiva interna estejam disponíveis para a diretiva externa”. Isso não acontece; apenas controla. como Uma diretiva pode ser escrita. O aninhamento funciona porque o compilador continua percorrendo o modelo que acabou de inserir. Para compartilhar dados, use require e controller.
Se o código for executado com sucesso, esta saída será exibida.
Saída:
Da saída,
- É possível observar que ambas as diretivas, externa e interna, foram chamadas e o texto em ambas as tags div é exibido.
Renderizar a marcação é apenas metade do que uma diretiva faz; a outra metade é reagir ao usuário.
Tratamento de eventos em uma diretiva
Eventos Ações como cliques do mouse ou de botões podem ser tratadas diretamente pelas diretivas. Isso é feito usando a função `link`. A função `link` permite que a diretiva se conecte aos elementos DOM em uma página HTML.
Sintaxe:
A sintaxe da função de ligação é mostrada abaixo.
link: function ($scope, element, attrs)
A função de link normalmente aceita 3 parâmetros: o escopo, o elemento ao qual a diretiva está associada e os atributos do elemento de destino. Mais dois parâmetros, um controlador obrigatório e uma função de transclusão, são adicionados quando aplicáveis.
Fase de compilação versus fase de ligação
O AngularJS processa uma diretiva em duas etapas, e saber qual é qual indica a qual local seu código deve ser inserido.
- Compilar Executa uma única vez no elemento de modelo, antes que qualquer escopo exista. É adequado para edições estruturais compartilhadas por todos os clones.
- de vidrio Executa uma vez por instância, após o modelo ser clonado e um escopo ser anexado. Os listeners do DOM e as leituras de escopo pertencem a este local.
Como o método `compile` não possui escopo, tudo que precisa de dados pertence ao método `link`, e é por isso que o exemplo abaixo define... link sozinho.
Vejamos um exemplo de como podemos realizar isso. A captura de tela numera os quatro pontos abaixo.
<!DOCTYPE html> <html> <head> <meta chrset="UTF 8"> <title>Event Registration</title> </head> <body> <script src="https://code.angularjs.org/1.6.9/angular-route.js"></script> <script src="https://code.angularjs.org/1.6.9/angular.js"></script> <script src="https://code.angularjs.org/1.6.9/angular.min.js"></script> <script src="https://code.jquery.com/jquery-3.3.1.min.js"></script> <h1> Guru99 Global Event</h1> <div ng-app="DemoApp"> <div ng-guru="">Click Me</div> </div> <script type="text/javascript"> var app = angular.module('DemoApp',[]); app.directive('ngGuru',function(){ return { link:function($scope,element,attrs) { element.bind('click',function () { element.html('You clicked me'); });} }}); </script> </body> </html>
Code Explicação
- Estamos utilizando a função link, conforme definida no AngularJS, para permitir que a diretiva acesse eventos no DOM HTML.
- Estamos usando a palavra-chave 'element' porque queremos responder a um evento de um elemento DOM HTML, que em nosso caso é o elemento "div". Em seguida, usamos a função "bind" para adicionar funcionalidades personalizadas ao evento de clique do elemento. A palavra 'click' é usada para denotar o evento de clique de qualquer controle HTML.
- Aqui estamos dizendo que queremos substituir o HTML interno do elemento, no nosso caso o elemento div, pelo texto 'Você clicou em mim'.
- Aqui estamos definindo nossa tag div para usar a diretiva personalizada ng-guru.
💡 Dica: Uma diretiva deve limpar seus próprios erros. Remova qualquer ouvinte que sobreviva ao elemento interno. element.on('$destroy', ...)ou a página apresenta vazamento de memória.
Se o código for executado com sucesso, esta saída será exibida.
Saída:
- Inicialmente, o texto 'Clique aqui' é exibido ao usuário, pois foi isso que foi definido dentro da tag div. Ao clicar na tag div, o conteúdo abaixo é exibido em vez disso.
Cada exemplo acima utilizou uma ou duas propriedades do mesmo objeto de definição. Vale a pena manter o conjunto completo.ping à mão.
Definição de diretiva Propriedades do objeto Referência
O objeto retornado por uma fábrica de diretivas é o Objeto de Definição de DiretivaCada propriedade responde a uma pergunta sobre como a diretiva se comporta.
| Propriedade | Padrão | O que ele faz |
|---|---|---|
| restringir | 'EA' | Quais formas correspondem: elemento E, atributo A, classe C, comentário M |
| modelo | Nenhum | Marcação embutida inserida no elemento correspondente |
| URL do modelo | Nenhum | Caminho do arquivo de modelo, obtido uma vez e armazenado em cache. |
| escopo | falso | `false` compartilha o escopo do pai, `true` cria um filho, um objeto isola. |
| controlador | Nenhum | Construtor que expõe uma API que outras diretivas podem exigir |
| controladorComo | Nenhum | Alias para o controlador dentro do modelo |
| requerer | Nenhum | Controlador de outra diretiva para injetar; ^ busca os pais, ^^ ignora a si mesmo, ? opcional |
| link | Nenhum | Função por instância: escopo, elemento, atributos, controlador, transcludeFn |
| compilar | Nenhum | Executa uma vez no modelo antes que qualquer escopo exista. |
| transcluir | falso | Preserva a marcação interna original para ng-transclude |
| prioridade | 0 | A ordem de compilação em um elemento compartilhado é definida da seguinte forma: o elemento de ordem superior é executado primeiro. |
| terminal | falso | Impede a execução de diretivas de menor prioridade nesse elemento. |
| substituir | falso | Troca o elemento pelo modelo. Obsoleto desde a versão 1.3. |
💡 Dica: Começar com restrict, template e link. Adicionar, acrescentar scope para reutilização, controller e require para chamadas diretivas e sair priority e terminal sozinho.
