O que é ng-transclude?

Eu vi uma série de perguntas sobre StackOverflow discutindo ng-transclude, mas nenhuma explicando em termos leigos o que é.

A descrição na documentação é a seguinte:

Diretiva que marca o ponto de inserção para o DOM transcluído da diretiva pai mais próxima que usa a transclusão.

Isso é bastante confuso. Alguém poderia explicar em termos simples o que o ng-transclude se destina a fazer e onde ele pode ser usado?

Transclude é uma configuração para dizer ao angular para capturar tudo o que é colocado dentro da diretiva na marcação e usá-la em algum lugar (onde, na verdade, a ng-transclude está) no modelo da diretiva. Leia mais sobre isso na seção Criando uma diretiva que envolve outros elementos na documentação de diretivas .

Se você escrever uma diretiva personalizada, use ng-transclude no modelo de diretiva para marcar o ponto em que deseja inserir o conteúdo do elemento.

 angular.module('app', []) .directive('hero', function () { return { restrict: 'E', transclude: true, scope: { name:'@' }, template: '
' + '
{{name}}

' + '
' + '
' }; });

Se você colocar isso na sua marcação

 Stuff inside the custom directive 

Apareceria como:

Super homen

Coisas dentro da diretiva personalizada

Exemplo completo:

Index.html

  
Stuff inside the custom directive

jscript.js

 angular.module('myApp', []).directive('hero', function () { return { restrict: 'E', transclude: true, scope: { name:'@' }, template: '
' + '
{{name}}

' + '
' + '
' }; });

Output markup

insira a descrição da imagem aqui

Visualize:

insira a descrição da imagem aqui

é um tipo de rendimento, tudo do element.html () é renderizado lá, mas os atributos da diretiva ainda são visíveis no escopo certo.