Создание расширения для AMP

$ amp make-extension --name=amp-my-элемент

В большинстве случаев вам потребуется создать только необходимые (необходимо) файлы. Если ваш элемент не требует пользовательского CSS, создавать файл CSS не нужно.

## Расширение AMP.BaseElement

 practically all AMP extensions extend AMP.BaseElement, which provides some
hookups and callbacks for you to override in order to implement and
customize your element behavior. These callbacks are explained below in
the BaseElement Callbacks section, and are also explained inline in the
[BaseElement](https://github.com/ampproject/amphtml/blob/main/src/base-element.js#L26)
class.

### Класс элемента

Следующий пример показывает общую структуру файла реализации элемента (extensions/amp-my-элемент/0.1/amp-my-элемент.js).

```js
import {func1, func2} from '../src/module';
import {CSS} from '../../../build/amp-my-элемент-0.1.css';
// более ES2015-стиль импортных заявлений.

/extensions/amp-my-элемент/
├── 0.1/
|   ├── test/
|   |   ├── test-amp-my-элемент.js       # Набор тестов элемента (необходимо)
|   |   └── Дополнительные файлы тестов JS (необязательно)
|   ├── amp-my-элемент.js                # Реализация элемента (необходимо)
|   ├── amp-my-элемент.css               # Пользовательский CSS (необязательно)
|   └── Дополнительные файлы JS (необязательно)
├── validator-amp-my-элемент.protoascii  # Правила валидатора (необходимо)
├── amp-my-элемент.md                    # Основная документация элемента (необходимо)
└── Дополнительные файлы документации в формате .md (необязательно)
└── OWNERS                               # Файл владельцев. Основные контакты для расширения (необходимо)

import {func1, func2} from '../src/module';
import {CSS} from '../../../build/amp-my-элемент-0.1.css';
// более ES2015-стиль импортных заявлений.
``````markdown
class AmpMyElement extends AMP.BaseElement {
  /** @param {!AmpElement} element */
  constructor(element) {
    super(element);

    // Объявляем экземплярные переменные с аннотациями типа.
  }

  /** @override */
  isLayoutSupported(layout) {
    return layout == LAYOUT.FIXED;
  }

  /** @override */
  buildCallback() {
    // Получаем атрибуты, утверждаем значения, присваиваем экземплярные переменные.
    // Создаем легковесную структуру DOM и добавляем её к элементу.
  }

  /** @override */
  layoutCallback() {
    // Загружаем ваш ресурс или рендерим более дорогие ресурсы.
  }
}

AMP.extension('amp-my-элемент', '0.1', (AMP) => {
  AMP.registerElement('amp-my-элемент', AmpMyElement, CSS);
});

-   **Переопределение**: Почти всегда
-   **Контекст Vsync**: Мутация
-   **Использование**: Если ваш элемент имеет элементы пользовательского интерфейса, здесь вы должны создать структуру DOM и добавить её к элементу. Вы также можете прочитать атрибуты (например, ширина, высота...) предоставленные пользователем на вашем элементе в этом callback.
-   **Предупреждение**: Не загружайте удалённые ресурсы во время buildCallback. Это не только обходит менеджер ресурсов AMP, но также приводит к более высоким тарифам на данные для пользователей, так как все эти ресурсы будут загружены до того, как потребуется размещение.
-   **Предупреждение 2**: Выполняйте минимально необходимую работу здесь, и не создавайте DOM, который не требуется в данный момент.#### preconnectCallback

-   **По умолчанию**: Ничего не делает.
-   **Контекст Vsync**: Нет (ни мутация, ни измерение)
-   **Переопределение**: Иногда, если ваш элемент будет загружать удалённые ресурсы.
-   **Использование**: Используйте для инструктирования AMP, какие хосты предварительно подключить, и какие ресурсы предварительно загрузить; это позволяет AMP делегировать браузеру для получения производительности за счёт предварительного подключения, предварительной загрузки и предварительной загрузки ресурсов через службу предварительного подключения.
-   **Пример использования**: [Instagram использует это для предварительного подключения](https://github.com/ampproject/amphtml/blob/main/extensions/amp-instagram/0.1/amp-instagram.js) к хостам Instagram.

#### createPlaceholderCallback-   **По умолчанию**: Ничего не делает.
-   **Контекст Vsync**: Мутация
-   **Переопределение**: Иногда. Если ваш компонент предоставляет способ динамически создавать легковесное местоимение. Это вызывается только если элемент не имеет уже предоставленного издателем местоимения (через [атрибут местоимения](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-html-layout.md#placeholder)).
-   **Использование**: Создайте DOM местоимения и верните его. Например, amp-instagram использует это для динамического создания местоимения, создавая amp-img местоимение вместо загрузки iframe, оставляя загрузку iframe на layoutCallback.
-   **Предупреждение**: Используйте только amp-элементы для создания местоимений, которые требуют загрузки внешних ресурсов. Это позволяет времени выполнения создать это заранее, но всё ещё откладывает загрузку и управление ресурсами на менеджер ресурсов AMP. Не создавайте или загружайте тяжеловесные ресурсы (например, iframe...).
-   **Пример использования**: amp-instagram.#### onLayoutMeasure

-   **По умолчанию**: Ничего не делает.
-   **Контекст Vsync**: Измерение.
-   **Переопределение**: Редко.
-   **Использование**: Используйте это для измерения макетов для вашего элемента.
-   **Пример использования**: amp-iframe

#### layoutCallback

-   **По умолчанию**: Ничего не делает.
-   **Контекст Vsync**: Мутация
-   **Переопределение**: Почти всегда.
-   **Использование**: Используйте это для фактического рендеринга окончательной версии вашего элемента. Если элемент должен загружать видео, это место для загрузки видео. Это должно вернуть промис, который разрешается, когда элемент считается "расположенным". Обычно это означает, что событие загрузки было сгенерировано, но это может быть разным для разных элементов. Обратите внимание, что события загрузки обычно срабатывают очень рано, поэтому если у вашего элемента есть другое событие, которое он может прослушивать и которое лучше описывает готовность, используйте это для разрешения вашего промиса вместо этого — например: [amp-youtube](https://github.com/ampproject/amphtml/blob/main/extensions/amp-youtube/0.1/amp-youtube.js) использует событие playerready, которое отправляет нижележащий iframe YT Player, чтобы разрешить промис layoutCallback.

#### firstLayoutCompleted-   **По умолчанию**: Скрыть местоимение элемента.
-   **Контекст Vsync**: Мутация
-   **Переопределение**: Иногда. Если вы хотите переопределить поведение по умолчанию и не скрывать местоимение, когда элемент считается первым расположенным. Иногда вы хотите контролировать момент скрытия местоимения.
-   **Пример использования**: amp-anim#### pauseCallback-   **По умолчанию**: Ничего не делает.
-   **Контекст Vsync**: Мутация
-   **Вызывается**: Когда вы свайпаете в сторону от документа в просмотрщике. Вызывается на дочерних элементах lightbox при закрытии экземпляра lightbox, вызывается на дочерних элементах карусели, когда слайд не является активным. И возможно в других местах.
-   **Переопределение**: Иногда. Чаще всего, если вы создаёте проигрыватель.
-   **Использование**: Используйте для остановки видео, автопрокрутки слайд-шоу... и т.д.
-   **Пример использования**: amp-video, amp-youtube

#### resumeCallback

-   **По умолчанию**: Ничего не делает.
-   **Контекст Vsync**: Мутация
-   **Переопределение**: Иногда.
-   **Использование**: Используйте для возобновления автопрокрутки слайд-шоу.
-   **Примечание**: Это ещё не широко используется, так как возобновление воспроизведения видео, например, на мобильных устройствах невозможно.

#### unlayoutOnPause

-   **По умолчанию**: Возвращает false.
-   **Контекст Vsync**: Мутация
-   **Переопределение**: Если ваш элемент не предоставляет механизм остановки, вместо этого переопределите это, чтобы разложить элемент, когда AMP пытается его остановить.
-   **Возврат**: True, если вы хотите, чтобы unlayoutCallback был вызван при остановке.
-   **Пример использования**: amp-brightcove

#### unlayoutCallback-   **По умолчанию**: Ничего не делает.
-   **Контекст Vsync**: Мутация.
-   **Переопределение**: Иногда.
-   **Использование**: Используйте для удаления и выгрузки тяжёлых ресурсов, таких как iframe, видео, аудио и другие, которые ваш элемент создал.
-   **Возврат**: **True**, если ваш элемент нуждается в переразметке.
-   **Пример использования**: amp-iframe## Стилизация элемента

Вы можете написать стилистический лист для стилизации вашего элемента, чтобы обеспечить минимальную визуальную привлекательность. Структура вашего элемента должна учитывать, хотите ли вы, чтобы пользователи (издатели и разработчики, использующие ваш элемент) кастомизировали предоставленное вами по умолчанию стилизование, и позволяли бы легко использовать CSS классы и/или хорошо структурированные DOM элементы.

Стили элемента загружаются вместе с самим скриптом элемента, когда он включён в AMP документ. Вы сообщаете AMP, какие CSS относятся к этому элементу при регистрации элемента (см. ниже).

Классы, префиксированные `i-amphtml`, считаются приватными. Издатели не имеют права использовать их для кастомизации (исполняется AMP валидатором).

Классы, префиксированные `amp-`, являются публичными CSS классами, которые могут быть кастомизированы издателями. Все такие классы должны быть документированы в специфическом для компонента `.md` файле. Все CSS классы в стилистических листах компонентов должны быть префиксированы либо `i-amphtml-`, либо `amp-`.

## Регистрация элемента с AMP

После реализации вашего элемента AMP, вам нужно зарегистрировать его с AMP; все расширения AMP имеют префикс `amp-`. Здесь вы сообщаете AMP, какой класс использовать для этого тега и какую CSS загрузить.```javascript
AMP.extension('amp-carousel', '0.1', (AMP) => {
  AMP.registerElement('amp-carousel', CarouselSelector, CSS);
});

<form
  on="submit-success:my-success-lightbox.open;submit-error:my-error-lightbox.open"
></form>

actionServiceForDoc(doc.documentElement).trigger(
  this.form_,
  'submit-success',
  null
);

this.registerAction('close', this.close.bind(this));
```Ваш элемент также может переопределить метод `activate`, наследуемый от `BaseElement`, чтобы определить стандартное действие для вашего элемента. Например, amp-lightbox переопределяет activate для определения случая по умолчанию.Убедитесь, что документация вашего элемента описывает события и действия, которые он выставляет.

## Владение подэлементами

Элементы AMP обычно обнаруживаются и планируются AMP runtime автоматически и управляются через ресурсы. В некоторых случаях элемент AMP может захотеть контролировать и владеть моментом, когда его подэлементы будут планироваться, и не оставлять это AMP runtime. Примером этого является компонент `<amp-carousel>`, который хочет планировать предзагрузку/предрендеринг или разметку его ячеек в зависимости от окна, в котором находится пользователь. AMP предоставляет способ для элемента контролировать это, устанавливая владельца на элемент, который вы хотите контролировать. В примере карусели компонент проходит по всем своим элементам и устанавливает себя как владельца этих элементов. Ядро AMP не будет управлять расписанием разметки для элементов, которые имеют владельцев.

```javascript
this.cells_ = realChildElements(this.element);

this.cells_.forEach((cell) => {
  Services.ownersForDoc(this.element).setOwner(cell, this.element);
  cell.style.display = 'inline-block';
  this.container_.appendChild(cell);
});
```Элемент может позже вызвать `schedulePreload` или `scheduleLayout` для
расписания предварительной загрузки или разметки соответственно. Например, &lt;amp-carousel
type=slider&gt; (экземпляр слайдера amp-carousel) вызывает
`schedulePreload` для следующего/предыдущего слайда, когда пользователь перемещается
вперед/назад по слайдам, а затем вызывает `scheduleLayout` для
текущего слайда, когда пользователь перемещается к нему.```javascript
const owners = Services.ownersForDoc(this.element);
owners.scheduleLayout(this.element, newSlide);
this.setControlsState();
owners.schedulePause(this.element, oldSlide);
owners.schedulePreload(this.element, nextSlide);

<amp-carousel> ← Родительский элемент
  <amp-figure> ← Родительский элемент должен расписание этого элемента
    <amp-img placeholder></amp-img> ← AMP расписание этого элемента, когда amp-figure расписание
    <amp-img></amp-img> ← Родительский элемент должен расписание этого элемента
    <amp-fit-text></amp-fit-text> ← Родительский элемент должен расписание этого элемента
  </amp-figure>
</amp-carousel>

class AmpInstagram extends AMP.BaseElement {
  // ...
  /** @override */
  createPlaceholderCallback() {
    const placeholder = this.win.document.createElement('div');
    placeholder.setAttribute('placeholder', '');
    const image = this.win.document.createElement('amp-img');
    // Это всегда тот же URL, который используется внутри вставки.
    // Это позволяет избежать двойной загрузки изображения и использовать кэш браузера.
    image.setAttribute(
      'src',
      'https://www.instagram.com/p/' +
        encodeURIComponent(this.shortcode_) +
        '/media/?size=l'
    );
    image.setAttribute('width', this.element.getAttribute('width'));
    image.setAttribute('height', this.element.getAttribute('height'));
    image.setAttribute('layout', 'responsive');
    setStyles(image, {
      'object-fit': 'cover',
    });
    const wrapper = this.element.ownerDocument.createElement('div');
    // Это делает изображение без iframe появляться в точно таком же месте,
   , где оно будет внутри iframe.
    setStyles(wrapper, {
      'position': 'absolute',
      'top': '48px',
      'bottom': '48px',
      'left': '8px',
      'right': '8px',
    });
    wrapper.appendChild(image);
    placeholder.appendChild(wrapper);
    this.applyFillContent(image);
    return placeholder;
  }
  // …
}
```**Важно**: Одно из ключевых моментов — при создании placeholder'а используйте элементы, предоставленные AMP, при загрузке внешних ресурсов. Это, скорее всего, будет `amp-img`, как в случае с Instagram'ом выше. Это позволяет менеджеру ресурсов AMP контролировать, когда эти ресурсы загружаются и отображаются, а не использовать HTML-нativo `img` тег, который будет вне управления ресурсами AMP.

#### Индикаторы загрузки

Рассмотрите возможность отображения индикатора загрузки, если ваш элемент ожидается загружаться долго (например, загрузка GIF, видео или iframe). AMP имеет встроенную механику для отображения индикатора загрузки, просто добавив ваш элемент в список разрешенных элементов. Вы можете это сделать внутри файла `layout.js` в объекте `LOADING_ELEMENTS_ENUM`.

```javascript
export const LOADING_ELEMENTS_ENUM = {
  ...
  AMP_YOUTUBE: 'AMP-YOUTUBE',
  AMP_MY_ELEMENT: 'AMP-MY-ELEMENT',
}

/** @override */
unlayoutCallback() {
  if (this.iframe_) {
    removeElement(this.iframe_);
    this.iframe_ = null;
    this.iframePromise_ = null;
    setStyles(this.placeholderWrapper_, {
      'display': '',
    });
  }
  return true; // Вызвать layoutCallback снова.
}

В то время как `amp-carousel` поддерживает все макеты, определенные размером.

```javascript
class AmpSlides extends AMP.BaseElement {
  /** @override */
  isLayoutSupported(layout) {
    return isLayoutSizeDefined(layout);
  }
}

/** @const {!Array<!ExperimentDef>} */
const EXPERIMENTS = [
  // ...
  {
    id: 'amp-my-element',
    name: 'AMP My Element',
    spec:
      'https://github.com/ampproject/amphtml/blob/main/extensions/' +
      'amp-my-element/amp-my-element.md',
    cleanupIssue: 'https://github.com/ampproject/amphtml/issues/XXXYYY',
  },
  // ...
];

import {isExperimentOn} from '../../../src/experiments';
import {userAssert} from '../../../src/log';
``````markdown
### Включение и отключение вашего эксперимента

Пользователи, желающие экспериментировать с вашим элементом, могут перейти на страницу [экспериментов](https://cdn.ampproject.org/experiments.html) и включить ваш эксперимент.

Если вы тестируете на локальной машине, используйте команду `AMP.toggleExperiment(id, true/false)` для включения эксперимента.

Создайте issue в GitHub для очистки вашего эксперимента. Назначьте его себе в качестве напоминания о необходимости удаления вашего эксперимента и проверок кода. Удаление вашего эксперимента происходит после тщательного тестирования расширения и решения всех проблем.
```## Документация вашего элемента

Создайте файл .md, который будет служить основной документацией для вашего элемента. Этот документ должен включать:

-   Таблицу сумм
-   Обзор
-   Как использовать, включая фрагменты кода и изображения
-   Примеры
-   Атрибуты для указания (необходимые и необязательные)
-   Валидация

Для примеров документации элементов, см.: [amp-list](https://github.com/ampproject/amphtml/blob/main/extensions/amp-list/amp-list.md), [amp-instagram](https://github.com/ampproject/amphtml/blob/main/extensions/amp-instagram/amp-instagram.md), [amp-carousel](https://github.com/ampproject/amphtml/blob/main/extensions/amp-carousel/amp-carousel.md)

## Пример использования вашего расширения

Это значительно помогает пользователям понять и продемонстрировать, как ваш элемент работает, и предоставляет легкий стартовый пункт для их экспериментов с ним. Это, по сути, то место, где вы действительно создаете документ AMP HTML и используете ваш элемент в нем, создавая файл в директории `examples/`, обычно с именем файла `my-element.сhml`. Обзор этой директории позволит вам увидеть примеры для других элементов и расширений.

Также рассмотрите возможность внесения примера в [amp.dev](https://amp.dev/) на [GitHub](https://github.com/ampproject/amp.dev).

## Обновление конфигураций сборкиЧтобы ваш элемент собирался правильно, вам потребуется внести несколько
изменений в файл
[`build-system/compile/bundles.config.extensions.json`](../build-system/compile/bundles.config.extensions.json), чтобы сообщить о вашем
расширении, его файлах и примерах. Вам потребуется добавить запись в
верхнеуровневый массив.```javascript
exports.extensionBundles = [
...
  {name: 'amp-kaltura-player', version: '0.1'},
  {name: 'amp-carousel', version: '0.1', options: {hasCss: true}},
...
];

$ amp unit --files=extensions/amp-my-element/0.1/test/test-amp-my-element.js --watch

$ amp check-types
```## Примеры PR

- Добавление нового поставщика рекламы
    - [Teads](https://github.com/ampproject/amphtml/commit/654ade680d796527345af8ff298a41a7532ee074)
    - [EPlanning](https://github.com/ampproject/amphtml/commit/a007543518a07ff77d48297e76bd264cadf36f57)
    - [Taboola](https://github.com/ampproject/amphtml/commit/79a58e545939cca0b75e62b2e62147829c59602a)
- Добавление встраиваемых элементов, не основанных на iframe (требует JS SDK)
    - [amp-facebook](https://github.com/ampproject/amphtml/commit/6679db198d8b9d9c38854d93aa04801e8cf6999f)
- Добавление iframe-встраиваемых элементов
    - [amp-soundcloud](https://github.com/ampproject/amphtml/commit/2ac845641c8eea9e67f17a1d471cfb9bab459fd1)
    - [amp-vine](https://github.com/ampproject/amphtml/commit/eb98861b25210f89b41abc9ac52b29d9a4ff45a6)
    - [amp-brightcove](https://github.com/ampproject/amphtml/commit/9a0f6089600da0c42e1f3787402a1ced0c377c65)
- Добавление невизуальных элементов
    - [amp-font](https://github.com/ampproject/amphtml/commit/ef040b60664a5aad465cb83507d37fae5e361772)
    - [amp-install-serviceworker](https://github.com/ampproject/amphtml/commit/e6199cfb5b9d13b0e4bb590b80c09ba3614877e6)
- Добавление общих элементов пользовательского интерфейса
    - [amp-sidebar](https://github.com/ampproject/amphtml/commit/99634b18310129f4260e4172cb2750ae7b8ffbf0)
    - [amp-image-lightbox](https://github.com/ampproject/amphtml/commit/e6006f9ca516ae5d7d79267976d3df39cc1f9636)
    - [amp-accordion](https://github.com/ampproject/amphtml/commit/1aae4eee37ec80c6ea9b822fb43ecce73feb7df6)
- Реализация плеера для видео.
    - [amp-jwplayer](https://github.com/ampproject/amphtml/commit/4acdd9f1d70a8a374cb886d3a4778476d13e7daf#diff-f650f38f7840dc8148bacd88733be338)