amp-mustache
Description
Компонент, который обеспечивает обработку шаблонов Mustache.js
Required Scripts
<script async custom-template="amp-mustache" src="https://cdn.ampproject.org/v0/amp-mustache-0.2.js"></script>
Примеры
Этот компонент обеспечивает обработку шаблонов Mustache.js.
Скрипт | <script async custom-template="amp-mustache" src="https://cdn.ampproject.org/v0/amp-mustache-0.2.js"></script> |
Примеры | Пример amp-mustache с комментариями на сайте AMP By Example. |
Примечания к версиям
Версия | Описание |
---|---|
0.2 | Реализована поддержка элементов <svg> . Размер пакета уменьшен до 12,2 КБ вместо 20,5 КБ (используется архивация gzip).Инструмент, предназначенный для устранения уязвимостей в коде HTML, теперь использует новую библиотеку (DOMPurify вместо Caja). Поскольку списки допустимых тегов и атрибутов в этих библиотеках отличаются, переход может привести к критическим изменениям. Мы рекомендуем проводить тестирование страниц перед дальнейшей подготовкой к публикации, чтобы узнать, не привело ли автоматическое обновление разметки к проблемам с функционированием различных элементов на странице. |
0.1 | Исходная реализация. |
Синтаксис
Mustache представляет собой синтаксис шаблона, не использующий логику. Подробнее читайте в документации по Mustache.js. Примеры основных тегов Mustache:
{{variable}}
: тег для переменной, который выводит значение переменной с экранированием для использования в коде HTML.{{#section}}
{{/section}}
: тег для обозначения раздела. Он может запустить проверку на наличие переменной и выполнить перебор, если она представляет собой массив.{{^section}}
{{/section}}
: тег, который выполняет противоположную операцию – осуществляет проверку на отсутствие переменной.{{{unescaped}}}
: использование тройной фигурной скобки отменяет экранирование тегов HTML. Эта функция может применяться только к отдельным элементам разметки, перечисленным в разделе "Ограничения" ниже.
Использование
Шаблон amp-mustache
должен определяться и использоваться в соответствии со спецификациями шаблонов AMP.
Чтобы объявить и загрузить шаблон amp-mustache
, нужно использовать следующий код:
<script src="https://cdn.ampproject.org/v0/amp-mustache-0.2.js" async="" custom-template="amp-mustache"></script>
Затем шаблоны Mustache нужно объявить в теге script или template, используя следующий код:
<!-- Using template tag. --> <template type="amp-mustache"> Hello {{world}}! </template>
ИЛИ
<script type="text/plain" template="amp-mustache"> Hello {{world}}! </script>
Мы рекомендуем по возможности применять тег template
, поскольку это открывает доступ к некоторым полезным функциям при валидации AMP. Тег script
следует использовать в особых случаях или при возникновении проблем с шаблонами в таблицах. Более подробные сведения приведены в разделе "Таблицы" ниже.
Определение шаблонов, выбор момента для их обработки и получение необходимых данных зависят от типа элемента AMP, к которому применяются эти шаблоны, например amp-list или amp-form.
Ограничения
Валидация
Аналогично другим шаблонам APM, шаблоны amp-mustache
должны представлять собой фрагменты кода DOM с правильным форматированием. Помимо прочего, с помощью кода amp-mustache
нельзя решать следующие задачи:
- Определять название тега. Например, запрещено использовать синтаксис
<{{tagName}}>
. - Определять название атрибута. Например, запрещено использовать синтаксис
<div {{attrName}}=something>
.
Тройные фигурные скобки можно использовать только со следующими тегами: a
, b
, br
, caption
, colgroup
, code
, del
, div
, em
, i
, ins
, li
, mark
, ol
, p
, q
, s
, small
, span
, strong
, sub
, sup
, table
, tbody
, time
, td
, th
, thead
, tfoot
, tr
, u
, ul
.
Устранение уязвимостей в коде HTML
Код, в котором используется шаблон Mustache, проходит автоматическую проверку на безопасность и соответствие требованиям AMP. В результате этой процедуры некоторые элементы и атрибуты могут быть удалены из кода без предупреждения.
Особые случаи
Вложенные шаблоны
Как указано в спецификациях AMP, нельзя использовать элементы <template>
, которые будут дочерними по отношению к другим элементам <template>
. Соблюдение этого требования проверяется при валидации. Подобная ситуация может иметь место, если вы применяете шаблоны к вложенным компонентам, например amp-list
и amp-form
.
Чтобы решить эту проблему, можно создавать ссылки на элементы <template>
с помощью элемента id
, применяя атрибут template
в компоненте. Пример:
<amp-list id="myList" src="https://foo.com/list.json"> <template type="amp-mustache"> <div>{{title}}</div> </template> </amp-list>
Другой метод:
<!-- Externalize templates to avoid nesting. --> <template type="amp-mustache" id="myTemplate"> <div>{{title}}</div> </template> <amp-list id="myList" src="https://foo.com/list.json" template="myTemplate"> </amp-list>
Таблицы
Поскольку относящиеся к шаблонам AMP строки определяются в элементах <template>
, код может обрабатываться браузером некорректно. В частности, использование элементов <table>
может привести к некорректному наследованию оформления для текста. Рассмотрим пример:
<template type="amp-mustache"> <table> <tr> {{#foo}}<td></td>{{/foo}} </tr> </table> </template>
Браузер принудительно применит форматирование к текстовым узлам {{#foo}}
и {{/foo}}
:
{{#foo}} {{/foo}} <table> <tr> <td></td> </tr> </table>
Чтобы избежать подобных проблем, использующие шаблон Mustache элементы можно упаковать в тег HTML, предназначенный для комментариев (пример: <!-- {{#bar}} -->
). При этом для определения шаблонов используйте не связанные с таблицами теги, такие как <div>
, а не <script type="text/plain">
.
<script type="text/plain" template="amp-mustache"> <table> <tr> {{#foo}}<td></td>{{/foo}} </tr> </table> </script>
Экранирование с помощью кавычек
Если шаблон amp-mustache
используется для определения значений атрибутов, проблему можно решить с помощью кавычек. Пример:
<template type="amp-mustache"> <!-- A double-quote (") in foo will cause malformed HTML. --> <amp-img alt="{{foo}}" src="example.jpg" width=100 height=100></amp-img> <!-- A single-quote (') or double-quote (") in bar will cause an AMP runtime parse error. --> <button on="tap:AMP.setState({foo: '{{bar}}'})">Click me</button> </template>
Для решения проблемы не подойдет метод, при котором переменные {{foo}}
или {{bar}}
обозначаются с помощью символьного кода HTML, поскольку код Mustache в свою очередь заменяет используемые в таком коде символы &
на символьный код HTML. В частности, элемент "
обрабатывается как &quot;
. В то же время вам может помочь использование факсимильных символов, например ′ (′
) и ″ (″
).
Также существует решение с открытым исходным кодом, предназначенное для выполнения необходимой подстановки в коде amp-mustache
. Если у вас возникнут проблемы при его использовании, сообщите нам о них.
Объекты HTML
Использование кода Mustache может повлиять на объекты HTML, расположенные внутри элементов <template>
.
Это может приводить к сбоям, если вы собираетесь обрабатывать на стороне сервера теги <template>
, внутри которых представлен добавленный пользователями текст. Дело в том, что если ваш посетитель введет символы {{
, }}
, {{{
или }}}
, они будут интерпретированы как код шаблона Mustache. Замена символов {{
на объекты HTML &lcub;&lcub;
не позволит решить проблему, поскольку они не экранируются при обработке браузером тегов <template>
.
Попробуйте заменять элементы {{
другими символами или вообще исключать их из пользовательского контента.
Валидация
С правилами для компонента amp-mustache можно ознакомиться в спецификации валидатора AMP.
Вы читали этот документ десятки раз, но так и не нашли ответов на все свои вопросы? Возможно, другие люди столкнулись с такой же проблемой — обратитесь к ним на Stack Overflow.
Перейти на Stack Overflow Нашли ошибку или недостающую функцию?Проект AMP активно поощряет ваше участие и сотрудничество! Мы надеемся, что вы станете постоянным участником нашего открытого сообщества, но разовые вклады в работу над задачами, которые вам особенно интересны, также приветствуются.
Перейти на GitHub