Улучшить эту документациюКомпилятор HTML

Обзор

Компилятор HTML AngularJS HTML-компилятор позволяет разработчику обучить браузер новой синтаксической конструкции HTML. Компилятор позволяет прикреплять поведение к любому HTML-элементу или атрибуту, а также создавать новые HTML-элементы или атрибуты с пользовательским поведением. AngularJS называет эти расширения поведения директивами.

HTML содержит множество конструкций для форматирования HTML-документов статическим способом. Например, если что-то нужно выровнять по центру, нет необходимости предоставлять браузеру инструкции о том, как разделить размер окна пополам, чтобы найти центр, и как выровнять этот центр по центру текста. Просто добавьте атрибут align="center" к любому элементу, чтобы достичь желаемого поведения. Такова мощь декларативного языка.

Однако декларативный язык также ограничен, так как он не позволяет обучить браузер новому синтаксису. Например, нет простого способа заставить браузер выровнять текст в 1/3 позиции вместо 1/2. Необходимо способ обучения браузера новому синтаксису HTML.

AngularJS поставляется с предварительно настроенными общими директивами, которые полезны для создания любого приложения. Мы также ожидаем, что вы будете создавать директивы, специфичные для вашего приложения. Эти расширения становятся языком доменной области для построения вашего приложения.

Вся эта компиляция происходит в веб-браузере; не требуется этап серверной обработки или предварительной компиляции.

Компилятор

Компилятор — это служба AngularJS, которая обходит DOM, ища атрибуты. Процесс компиляции происходит в два этапа.

1. Компиляция: обход DOM и сбор всех директив. Результатом является функция связывания.

2. Связывание: объединение директив со областью видимости и создание живого представления. Любые изменения в модели области видимости отражаются в представлении, а любые взаимодействия пользователя с представлением отражаются в модели области видимости. Это делает модель области видимости единственным источником правды.

Некоторые директивы, такие как ng-repeat, клонируют элементы DOM один раз для каждого элемента в коллекции. Наличие этапов компиляции и связывания улучшает производительность, так как шаблон, который клонируется, компилируется только один раз, а затем связывается один раз для каждого экземпляра клона.

Директива

Директива — это поведение, которое должно вызываться при обнаружении определенных конструкций HTML во время процесса компиляции. Директивы могут быть размещены в именах элементов, атрибутах, именах классов, а также в комментариях. Ниже приведены несколько эквивалентных примеров вызова директивы ng-bind.

<span ng-bind="exp"></span>
<span class="ng-bind: exp;"></span>
<ng-bind></ng-bind>
<!-- directive: ng-bind exp -->

Директива — это просто функция, которая выполняется при обнаружении компилятором в DOM. См. API директив для получения подробной информации о том, как писать директивы.

Вот директива, которая делает любой элемент перетаскиваемым. Обратите внимание на атрибут draggable в элементе <span>.

Наличие атрибута draggable в любом элементе придает элементу новое поведение. Мы расширили словарь браузера естественным образом для всех, кто знаком с принципами HTML.

Понимание представления

Большинство других систем шаблонов потребляют статический шаблон в виде строки и комбинируют его с данными, создавая новую строку. Результирующий текст затем innerHTML в элемент.

Это означает, что любые изменения в данных необходимо повторно объединять с шаблоном, а затем innerHTML в DOM. Некоторые проблемы с этим подходом:

1. чтение пользовательского ввода и объединение его с данными
2. затирание пользовательского ввода заменой его
3. управление всем процессом обновления
4. недостаток выразительности поведения

AngularJS отличается. Компилятор AngularJS потребляет DOM, а не шаблоны в виде строк. Результатом является функция связывания, которая, когда объединяется с моделью области видимости, приводит к появлению живого представления. Связи между представлением и моделью области видимости прозрачны. Разработчику не нужно выполнять никаких специальных вызовов для обновления представления. И поскольку innerHTML не используется, вы случайно не затрете пользовательский ввод. Кроме того, директивы AngularJS могут содержать не только текстовые связи, но и конструктивные элементы поведения.

Подход AngularJS создает стабильный DOM. Экземпляр элемента DOM, связанный с экземпляром элемента модели, не меняется в течение всего срока действия связи. Это означает, что код может получить доступ к элементам, зарегистрировать обработчики событий и знать, что ссылка не будет уничтожена объединением шаблона с данными.

Как компилируются директивы

Важно отметить, что AngularJS работает с узлами DOM, а не со строками. Обычно вы не замечаете этого ограничения, потому что при загрузке страницы веб-браузер автоматически преобразует HTML в DOM.

Компиляция HTML происходит в три этапа:

1. $compile обходит DOM и сопоставляет директивы.

   Если компилятор обнаруживает, что элемент соответствует директиве, то директива добавляется в список директив, соответствующих элементу DOM. Один элемент может соответствовать нескольким директивам.

2. После того как все директивы, соответствующие элементу DOM, будут идентифицированы, компилятор сортирует директивы по их priority.

   Выполняются функции compile каждой директивы. Каждая функция compile имеет возможность изменить DOM. Каждая функция compile возвращает функцию link. Эти функции объединяются в «объединённую» функцию связывания, которая вызывает возвращаемую функцию link каждой директивы.

3. $compile связывает шаблон с областью видимости, вызвав объединённую функцию связывания с предыдущего шага. Это, в свою очередь, вызовет функцию связывания отдельных директив, зарегистрирует слушатели на элементах и настроит $watch с scope, как это настроено для каждой директивы.

Результат — живая привязка между областью видимости и DOM. Таким образом, в этот момент изменение модели в скомпилированной области видимости отразится в DOM.

Ниже приведен соответствующий код, использующий службу $compile. Это должно помочь вам понять, что делает AngularJS внутри.

var $compile = ...; // injected into your code
var scope = ...;
var parent = ...; // DOM element where the compiled template can be appended

var html = '<div ng-bind="exp"></div>';

// Step 1: parse HTML into DOM element
var template = angular.element(html);

// Step 2: compile the template
var linkFn = $compile(template);

// Step 3: link the compiled template with the scope.
var element = linkFn(scope);

// Step 4: Append to DOM (optional)
parent.appendChild(element);

Разница между Compile и Link

На этом этапе вы можете задаться вопросом, почему процесс компиляции имеет отдельные этапы компиляции и связывания. Короткий ответ заключается в том, что разделение компиляции и связывания необходимо всякий раз, когда изменение модели приводит к изменению **структуры** DOM.

Редко встречаются директивы с **функцией компиляции**, так как большинство директив работают с конкретным экземпляром элемента DOM, а не меняют его общую структуру.

Директивы часто имеют **функцию связывания**. Функция связывания позволяет директиве регистрировать слушателей для конкретного клонированного экземпляра элемента DOM, а также копировать содержимое из области видимости в DOM.

Пример "Компиляции" против "Связывания"

Чтобы понять, давайте рассмотрим реальный пример с ngRepeat:

Hello {{user.name}}, you have these actions:
<ul>
  <li ng-repeat="action in user.actions">
    {{action.description}}
  </li>
</ul>

При компиляции вышеприведенного примера компилятор посещает каждый узел и ищет директивы.

{{user.name}} соответствует директиве интерполяции интерполяции, а ng-repeat соответствует директиве ngRepeat.

Но у ngRepeat есть проблема.

Ей необходимо возможность клонировать новые <li> элементы для каждого action в user.actions. На первый взгляд это кажется тривиальным, но становится сложнее, когда вы учитываете, что в user.actions могут добавляться элементы позже. Это означает, что ей нужно сохранить чистую копию элемента <li> для целей клонирования.

Когда добавляются новые action элементы, шаблон <li> элемента должен клонироваться и вставляться в ul элемент. Но клонирования элемента <li> недостаточно. Также необходимо скомпилировать <li> таким образом, чтобы его директивы, такие как {{action.description}}, оценивались относительно правильной области видимости.

Примитивный подход к решению этой проблемы заключался бы в простом вставлении копии элемента <li> и его компиляции. Проблема с этим подходом заключается в том, что компиляция каждого клонированного элемента <li> дублирует много работы. В частности, мы бы каждый раз обходили <li> перед клонированием, чтобы найти директивы. Это привело бы к замедлению процесса компиляции, а следовательно, к снижению отзывчивости приложений при вставке новых узлов.

Решение состоит в разделении процесса компиляции на два этапа:

**этап компиляции**, где все директивы идентифицируются и сортируются по приоритету, и **этап связывания**, где выполняется любая работа, связывающая конкретный экземпляр области видимости и конкретный экземпляр <li>.

ngRepeat работает, препятствуя процессу компиляции входить в элемент <li>, чтобы он мог создать клон оригинала и самостоятельно обрабатывать вставку и удаление узлов DOM.

Вместо этого директива ngRepeat компилирует <li> отдельно. Результатом компиляции элемента <li> является функция связывания, которая содержит все директивы, содержащиеся в элементе <li>, готовые к подключению к конкретному клону элемента <li>.

При выполнении ngRepeat отслеживает выражение, и по мере добавления элементов в массив клонирует элемент <li>, создаёт новый scope для клонированного элемента <li> и вызывает функцию связывания для клонированного элемента <li>.

Понимание работы scope с трансклюдированными директивами

Одним из самых распространённых случаев использования директивы является создание переиспользуемых компонентов.

Ниже приведён псевдокод, демонстрирующий работу упрощённого компонента диалога.

<div>
  <button ng-click="show=true">show</button>

  <dialog title="Hello {{username}}."
          visible="show"
          on-cancel="show = false"
          on-ok="show = false; doSomething()">
     Body goes here: {{username}} is {{title}}.
  </dialog>
</div>

Нажатие на кнопку "показать" откроет диалог. Диалог будет иметь заголовок, связанный с данными по username, и тело, которое мы хотим трансклюдировать в диалог.

Вот пример того, как может выглядеть определение шаблона для виджета dialog.

<div ng-show="visible">
  <h3>{{title}}</h3>
  <div class="body" ng-transclude></div>
  <div class="footer">
    <button ng-click="onOk()">Save changes</button>
    <button ng-click="onCancel()">Close</button>
  </div>
</div>

Это не будет правильно отображаться, если не использовать некоторую магию scope.

Первая проблема, которую нужно решить, состоит в том, что шаблон диалогового окна ожидает, что title будет определено. Но мы хотим, чтобы свойство scope шаблона title было результатом интерполяции атрибута <dialog> элемента (то есть "Hello {{username}}"). Кроме того, кнопки ожидают, что функции onOk и onCancel будут присутствовать в scope. Это ограничивает полезность виджета. Для решения проблемы сопоставления мы используем scope для создания локальных переменных, которые шаблон ожидает следующим образом:

scope: {
  title: '@',             // the title uses the data-binding from the parent scope
  onOk: '&',              // create a delegate onOk function
  onCancel: '&',          // create a delegate onCancel function
  visible: '='            // set up visible to accept data-binding
}

Создание локальных свойств в scope виджета создаёт две проблемы:

1. изоляция — если пользователь забудет установить атрибут title виджета диалога, шаблон диалога будет привязываться к свойству родительского scope. Это непредсказуемо и нежелательно.

2. трансклюзия — трансклюдированный DOM может видеть локальные переменные виджета, что может перезаписывать свойства, необходимые для привязки данных к трансклюзии. В нашем примере свойство title виджета перекрывает свойство title трансклюзии.

Для решения проблемы отсутствия изоляции директива объявляет новый isolated scope. Изолированный scope не наследует прототипно от родительского scope, и поэтому нам не нужно беспокоиться о случайном перекрытии свойств.

Однако isolated scope создаёт новую проблему: если трансклюдированный DOM является дочерним элементом изолированного scope виджета, то он не сможет связаться ни с чем. По этой причине трансклюдированный scope является дочерним элементом исходного scope, прежде чем виджет создал изолированный scope для своих локальных переменных. Это делает трансклюдированный и изолированный scope виджета братьями.

Это может показаться неожиданной сложностью, но это даёт пользователю и разработчику виджета наименьшее количество неожиданностей.

Следовательно, окончательное определение директивы выглядит примерно так:

transclude: true,
scope: {
    title: '@',             // the title uses the data-binding from the parent scope
    onOk: '&',              // create a delegate onOk function
    onCancel: '&',          // create a delegate onCancel function
    visible: '='            // set up visible to accept data-binding
},
restrict: 'E',
replace: true

Двойная компиляция и как её избежать

Двойная компиляция возникает, когда уже скомпилированная часть DOM компилируется снова. Это нежелательный эффект и может привести к некорректной работе директивы, проблемам с производительностью и утечкам памяти. Распространённый сценарий, в котором это происходит, — это директива, которая вызывает $compile в функции связывания директивы на элементе директивы. В следующем неправильном примере директива добавляет поведение при наведении мыши на кнопку с ngClick на ней:

angular.module('app').directive('addMouseover', function($compile) {
  return {
    link: function(scope, element, attrs) {
      var newEl = angular.element('<span ng-show="showHint"> My Hint</span>');
      element.on('mouseenter mouseleave', function() {
        scope.$apply('showHint = !showHint');
      });

      attrs.$set('addMouseover', null); // To stop infinite compile loop
      element.append(newEl);
      $compile(element)(scope); // Double compilation
    }
  }
})

На первый взгляд, кажется, что удаление исходного атрибута addMouseover — всё, что нужно для работы этого примера. Однако, если на элементе директивы или его дочерних элементах есть другие прикреплённые директивы, они будут скомпилированы и связаны снова, потому что компилятор не отслеживает, какие директивы были назначены каким элементам.

Это может привести к непредсказуемому поведению, например, ngClick или другие обработчики событий будут прикреплены снова. Это также может ухудшить производительность, так как наблюдатели за интерполяцией текста добавляются в scope дважды.

Поэтому следует избегать двойной компиляции. В приведённом выше примере нужно скомпилировать только новый элемент:

angular.module('app').directive('addMouseover', function($compile) {
  return {
    link: function(scope, element, attrs) {
      var newEl = angular.element('<span ng-show="showHint"> My Hint</span>');
      element.on('mouseenter mouseleave', function() {
        scope.$apply('showHint = !showHint');
      });

      element.append(newEl);
      $compile(newEl)(scope); // Only compile the new element
    }
  }
})

Другой сценарий — это программирование директивы на уже скомпилированный элемент и повторная компиляция. Смотрите следующий неправильный пример:

<input ng-model="$ctrl.value" add-options>

angular.module('app').directive('addOptions', function($compile) {
  return {
    link: function(scope, element, attrs) {
      attrs.$set('addOptions', null) // To stop infinite compile loop
      attrs.$set('ngModelOptions', '{debounce: 1000}');
      $compile(element)(scope); // Double compilation
    }
  }
});

В этом случае необходимо перехватить первоначальную компиляцию элемента:

1. Надайте своей директиве свойство terminal и более высокий приоритет, чем директивам, которые не должны компилироваться дважды. В примере компилятор будет компилировать только директивы, у которых приоритет 100 или выше.
2. Внутри функции compile этой директивы добавьте другие атрибуты директивы в шаблон.
3. Скомпилируйте элемент, но ограничьте максимальный приоритет, чтобы любые уже скомпилированные директивы (включая директиву addOptions) не компилировались повторно.
4. В функции link свяжите скомпилированный элемент со scope элемента.

angular.module('app').directive('addOptions', function($compile) {
  return {
    priority: 100, // ngModel has priority 1
    terminal: true,
    compile: function(templateElement, templateAttributes) {
      templateAttributes.$set('ngModelOptions', '{debounce: 1000}');

      // The third argument is the max priority. Only directives with priority < 100 will be compiled,
      // therefore we don't need to remove the attribute
      var compiled = $compile(templateElement, null, 100);

      return function linkFn(scope) {
        compiled(scope) // Link compiled element to scope
      }
    }
  }
});