В этом выпуске квеста отслеживается реализация компонентов Glimmer в Ember.js.

План

Компоненты Glimmer.js имеют следующие особенности:

1. Шаблоны «Внешний HTML» (без tagName , attributeBindings и т. Д.)
2. Аргументы в шаблонах имеют префикс @ , например {{@firstName}}
3. Аргументы компонента задаются как this.args
4. Классы компонентов используют синтаксис класса JavaScript
5. Состояние изменяемого компонента аннотируется свойствами @tracked
6. Компоненты вызываются с помощью синтаксиса <AngleBracket />
7. Атрибуты могут быть «разбиты» с помощью …attributes

Следуя духу инкрементализма Ember, мы хотим внедрить эту функциональность по частям с помощью надстройки. Это позволяет сообществу начать использовать функции и предоставлять обратную связь на ранних этапах процесса.

Фактически, мы уже начали путь к компонентам Glimmer в Ember. Первые две функции уже начали появляться:

1. В компонентах, содержащих только шаблоны, шаблоны представляют собой «внешний HTML» (при условии, что была включена дополнительная функция template-only-glimmer-components ).
2. Доступ к аргументам в шаблоне можно получить через префикс @ (например, {{@firstName}} ).

В этом выпуске предлагается завершить процесс переноса компонентов Glimmer в Ember, разрешив надстройкам предоставлять альтернативные реализации компонентов, а затем преобразовать пакет @glimmer/component в надстройку Ember, реализующую API компонентов Glimmer.js.

Мы разделим эту работу на этапы, каждый из которых открывает преимущества для существующих приложений и дополнений Ember. Фаза 0 связана с добавлением необходимых примитивов в Ember.js для поддержки альтернативных реализаций компонентов. Фазы 1, 2 и 3 посвящены постепенному включению API компонента Glimmer.js.

В то время как мы углубимся в этапы 0 и 1, мы отложим изучение технических деталей более поздних этапов до тех пор, пока первые этапы не будут ближе к завершению.

Этап 0: настройка поведения компонентов

TL; DR: добавьте API CustomComponentManager в Ember.js, чтобы позволить надстройкам реализовывать API пользовательских компонентов.

В настоящее время предполагается, что все компоненты в приложении Ember являются подклассами Ember.Component . Чтобы поддерживать альтернативные API компонентов в Ember, нам нужен способ сообщить Ember, когда и как должно измениться поведение компонента.

Когда мы говорим «поведение нестандартных компонентов», мы конкретно имеем в виду:

1. Как создаются экземпляры компонентов.
2. Как уничтожаются экземпляры компонентов.
3. Как аргументы предоставляются экземпляру компонента.
4. Как компонент уведомляется об этих изменениях жизненного цикла.

Хотя Glimmer VM вводит понятие «диспетчер компонентов», объект, который принимает эти решения, этот API очень низкого уровня. Было бы преждевременно принимать их напрямую в качестве общедоступного API в Ember, потому что их сложно писать, легко создавать таким образом, что это нарушает работу других компонентов, и они еще не стабильны.

Вместо этого мы предлагаем новый Ember API под названием CustomComponentManager который реализует шаблон делегата. CustomComponentManager обеспечивает меньшую площадь поверхности API, чем полноценный ComponentManager Glimmer VM API, что позволяет авторам дополнений попасть в «яму успеха».

Итак, как Ember узнает, какой менеджер компонентов использовать для данного компонента? Первоначальная итерация RFC для пользовательских компонентов представила концепцию ComponentDefinition , структуры данных, которая была с готовностью зарегистрирована в Ember и указывала, какой диспетчер компонентов использовать.

Одним из основных преимуществ подхода ComponentDefinition является то, что разрешение диспетчера компонентов может происходить во время сборки. К сожалению, это означает, что мы должны разработать API для того, как именно они будут регистрироваться, и, вероятно, означает некоторую интеграцию с конвейером сборки.

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

Обнаружение диспетчера настраиваемых компонентов

В этой итерации компоненты должны явно соглашаться на использование альтернативных менеджеров компонентов. Они делают это с помощью специальной функции componentManager , экспортируемой Ember, которая аннотирует во время выполнения, какой менеджер компонентов следует использовать для определенного класса компонентов:

import { componentManager } from '@ember/custom-component-manager';
import EmberObject from '@ember/object';

export default componentManager(EmberObject.extend({
  // ...
}), 'glimmer');

В конце концов, это может стать декоратором класса:

import { componentManager } from '@ember/custom-component-manager';

export default @componentManager('glimmer') class {
  // ...
}

При первом вызове этого компонента Ember проверяет класс, чтобы увидеть, есть ли у него аннотация диспетчера настраиваемых компонентов. Если это так, он использует строковое значение для поиска в контейнере. В приведенном выше примере Ember запрашивает у контейнера объект с ключом контейнера component-manager:glimmer .

Таким образом, надстройки могут использовать семантику обычного разрешения для предоставления настраиваемых диспетчеров компонентов. Наш аддон компонентов Glimmer может экспортировать диспетчер компонентов из addon/component-managers/glimmer.js который будет автоматически обнаружен с помощью обычных правил разрешения.

Хотя этот API многословен и не особенно эргономичен, приложения и надстройки могут абстрагироваться от него, вводя собственный базовый класс с аннотацией. Например, если аддон с именем turbo-component хотел предоставить диспетчер настраиваемых компонентов, он мог бы экспортировать базовый класс следующим образом:

// addon/index.js
import EmberObject from '@ember/object';
import { componentManager } from '@ember/custom-component-manager';

export default componentManager(EmberObject.extend({
  // ...
}), 'turbo');

Пользователи этого дополнения могут создать подкласс базового класса TurboComponent для определения компонентов, которые используют правильный диспетчер компонентов:

import TurboComponent from 'turbo-component';

export default TurboComponent.extend({
  didInsertElementQuickly() {
    // ...
  }
});

API пользовательских компонентов

Ни один компонент не является островком, и по причинам обратной совместимости важно, чтобы введение нового API компонентов не нарушало работу существующих компонентов.

Одним из примеров этого является существующий API иерархии представлений. Компоненты Ember могут проверять свой родительский компонент через свойство parentView . Даже если родительский элемент не является Ember.Component , дочерние компоненты Ember все равно должны иметь ненулевое свойство parentView .

В настоящее время CurlyComponentManager в Ember отвечает за поддержание этого состояния, а также другого внешнего «состояния области действия», такого как цель действий.

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

import CustomComponentManager from "@ember/custom-component-manager";

export default new CustomComponentManager({
  // major and minor Ember version this manager targets
  version: "3.1",
  create({ ComponentClass, args }) {
    // Responsible for instantiating the component class and passing provided
    // component arguments.
    // The value returned here is passed as `component` in the below hooks.
  },
  getContext(component) {
    // Returns the object that serves as the root scope of the component template.
    // Most implementations should return `component`, so the component's properties
    // are looked up in curly expressions.
  },
  update(component, args) {
    // Called whenever the arguments to a component change.
  },
  destroy(component) {
  }
});

Фаза 1: Компоненты мерцания объекта Ember

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

В качестве первого шага мы хотим предоставить способ выбора упрощенного API компонента Glimmer.js через пакет @glimmer/component . Чтобы упростить миграцию, мы предоставим реализацию базового класса Glimmer Component который наследуется от Ember.Object адресу @glimmer/component/compat .

Вот пример того, как выглядит «компонент Ember-Glimmer»:

// src/ui/components/user-profile/component.js
import Component from '@glimmer/component/compat';
import { computed } from '@ember/object';

export default Component({
  fullName: computed('args.firstName', 'args.lastName', function() {
    let { firstName, lastName } = this.args
    return `${firstName} ${lastName}`;
  })

  isAdmin: false,

  toggleAdmin() {
    this.set('isAdmin', !this.isAdmin);
  }
});

{{!-- src/ui/components/user-profile/template.hbs --}}
<h1>{{fullName}}</h1>
<p>
  Welcome back, {{@firstName}}!
  {{#if isAdmin}}
    <strong>You are an admin.</strong>
  {{/if}}
</p>
<button {{action toggleAdmin}}>Toggle Admin Status</button>

Примечательные характеристики этих компонентов:

• Шаблоны - это внешний HTML . Поскольку в приведенном выше примере шаблона нет единственного корневого элемента, он отображается как «компонент без тегов».
• Действия - это просто функции компонента, и их не нужно вкладывать в хэш actions .
• Аргументы устанавливаются в свойстве args а не в настройке отдельных свойств компонента напрямую.
• Они используют объектную модель Ember . Это означает, что такие инструменты, как вычисляемые свойства и миксины, с которыми разработчики Ember уже знакомы, продолжают работать.

Не менее важно то, что не включено:

• Свойства @tracked не будут поддерживаться до фазы 3.
• У компонента нет свойств layout или template .
• Никаких методов или свойств, относящихся к иерархии представлений, таких как childViews , parentView , nearestWithProperty и т. Д.
• Нет tagName , attributeBindings или другого настраиваемого JavaScript DSL для изменения корневого элемента.
• Нет send или sendAction для отправки событий.
• Нет обязательного ember-view class или автоматически сгенерированного идентификатора элемента guid.
• Нет ручного метода rerender() .
• Нет свойства attrs (используйте вместо него args ).
• Переданные аргументы являются «однонаправленными» и не создают двусторонних привязок.
• Переданные аргументы не устанавливаются как свойства в экземпляре компонента, что позволяет избежать трудных для отладки конфликтов имен.
• Нет this.$() для создания объекта jQuery для элемента компонента.
• Никаких ручных appendTo компонентов в DOM.
• Не поддерживаются следующие события жизненного цикла:
  
  
  
  • willInsertElement
  
  
  • didRender
  
  
  • willRender
  
  
  • willClearRender
  
  
  • willUpdate
  
  
  • didReceiveAttrs
  
  
  • didUpdateAttrs
  
  
  • parentViewDidChange
  
  
• Нет прослушивателя событий on() для событий жизненного цикла компонентов; хуки должны быть реализованы как методы.

Одним из интересных побочных эффектов этого набора функций является то, что он согласуется с усилиями по включению классов JavaScript . В сочетании с дизайном, предложенным в RFC для классов ES , мы можем предоставить альтернативную реализацию вышеуказанного компонента:

// src/ui/components/user-profile/component.js
import Component from '@glimmer/component/compat';
import { computed } from 'ember-decorators/object';

export default class extends Component {
  isAdmin = false;

  @computed('args.firstName', 'args.lastName')
  get fullName() {
    let { firstName, lastName } = this.args;
    return `${firstName} ${lastName}`;
  })

  toggleAdmin() {
    this.set('isAdmin', !this.isAdmin);
  }
});

Этап 2 - Синтаксис угловой скобки

Фаза 2 позволяет вызывать компоненты через угловые скобки ( <UserAvatar @user={{currentUser}} /> ) в дополнение к фигурным скобкам ( {{my-component user=currentUser}} ). Поскольку этот синтаксис устраняет двусмысленность между аргументами компонента и атрибутами HTML, эта функция также позволяет «разбивать» переданные атрибуты в шаблон компонента через …attributes .

{{! src/ui/components/UserAvatar/template.hbs }}
<div ...attributes> {{! <-- attributes will be inserted here }}
  <h1>Hello, {{@firstName}}!</h1>
</div>

<UserAvatar @user={{currentUser}} aria-expanded={{isExpanded}} />

Результат будет примерно таким:

<div aria-expanded="true">
  <h1>Hello, Steven!</h1>
</div>

Этап 3 - Отслеживаемые свойства

Фаза 3 включает отслеживаемые свойства с помощью декоратора @tracked в Ember. Детали взаимодействия между объектной моделью Ember и отслеживаемыми свойствами в настоящее время прорабатываются. После того, как отслеживаемые свойства появятся, пользователи смогут удалить модуль @glimmer/component/compat и использовать обычный базовый класс компонента, отличного от Ember.Object.

В сочетании с недавно объединенной функцией «autotrack» (которая автоматически определяет зависимости вычисленных свойств) это должно привести к дальнейшему упрощению кода приложения:

import Component, { tracked } from '@glimmer/component';

export default class extends Component {
  <strong i="24">@tracked</strong> isAdmin = false;

  <strong i="25">@tracked</strong> get fullName() {
    let { firstName, lastName } = this.args;
    return `${firstName} ${lastName}`;
  }

  toggleAdmin() {
    this.isAdmin = !this.isAdmin;
  }
}

Вопросы и ответы

Могу ли я добавить обратно такие вещи, как имя класса ember-view или автоматически сгенерированный атрибут id в компоненты Glimmer для совместимости с существующим CSS?

да. Пример:

<div class="ember-view" id="{{uniqueId}}">
  Component content goes here.
</div>

import Component from '@glimmer/component';
import { guidFor } from '@ember/object/internals';

export default class extends Component {
  get uniqueId() {
    return guidFor(this);
  }
}

Ресурсы

• Канал # st-glimmer-components в сообществе Ember Slack
  
  
  
  • Здесь мы координируем работу.
  
  
• Заказной компонент RFC
• custom-component-manager филиал
  
  
  
  • Незавершенная ветвь Ember.js с реализацией CustomComponentManager за флагом функции
  
  
• tracked филиал
  
  
  
  • Текущая ветка Ember.js с работой по взаимодействию между свойствами @tracked и объектами Ember
  
  

Задания

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

Пользовательский API диспетчера компонентов

• [x] Обновите RFC для пользовательских компонентов, чтобы отразить вышеупомянутые изменения (@chancancode)
  
  
  
  • https://github.com/emberjs/rfcs/pull/213#issuecomment -370494713
  
  
• [x] Добавить флаг функции glimmer-custom-component-manager
• [x] Реализовать функцию componentManager
  
  
  
  • [x] Выставить как { componentManager } from '@ember/custom-component-manager'
  
  
• [x] Resolver должен обнаруживать аннотированные классы
• [x] Резолверу необходимо найти указанный диспетчер компонентов.
  
  
  
  • [] Руководство для авторов дополнений о том, где разместить менеджеры компонентов, чтобы они были обнаружены
  
  
  • [] Как это работает с унификацией модулей? (@mixonic)
  
  
• [x] Реализовать CustomComponentManager API
  
  
  
  • [x] Определите интерфейс CustomComponentManagerDelegate
  
  
  • [x] version
  
  
  • [x] create()
  
  
  • [x] getContext()
  
  
  • [x] update()
  
  
  • [x] destroy?()
  
  
  • [x] didCreate?()
  
  
  • [x] didUpdate?()
  
  
  • [x] getView?()
  
  
  • [x] Проверить свойство version при создании
  
  
  • [x] Внутреннее устройство
  
  
  • [x] Сохранить childViews и parentView в существующих компонентах
  
  
  • [] Инструмент для рендеринга
  
  
  • [] Инструмент для совместимости с Ember Inspector
  
  

Дополнение для компонентов Glimmer

• [x] Поддержка с помощью sparkles-components addon
  
  
  
  • [x] Базовый класс должен импортировать и добавлять аннотацию componentManager при использовании из Ember
  
  
  • [x] CustomComponentManager реализация должна быть обнаружена через контейнер Ember
  
  
• [] Поддержка использования @glimmer/component в качестве надстройки Ember
  
  
  
  • [] Сохранить существующее поведение при использовании из Glimmer.js
  
  
  • [] import Component from '@glimmer/component' предоставляет простой базовый класс JavaScript.
  
  
  • [] import Component from '@glimmer/component/compat' предоставляет базовый класс Ember.Object
    
    Погляди
  
  
• [] Хуки жизненного цикла
  
  
  
  • [x] статический create(injections)
  
  
  • [x] didInsertElement()
  
  
  • [x] willDestroy()
  
  
  • [x] didUpdate()
  
  
  • [x] Методы, вызываемые делегированием событий ( click() и т. д.), не должны запускаться
  
  
• [] Доступ к элементу
  
  
  
  • [] this.bounds
  
  
  • [] this.element псевдоним вычисляемого свойства для this.bounds
  
  
  • [] API на основе модификаторов элементов для раскрытия элементов
  
  
• [] Аргументы
  
  
  
  • [x] this.args доступно в конструкторе
  
  
  • [x] this.args обновляется до вызова didUpdate
  
  
  • [] this.args не должен запускать бесконечный цикл повторного рендеринга (необходимо проверить)
  
  
• [ ] Документация
  
  
  
  • [ ] Как установить
  
  
  • [] Предостережения
  
  
  • [] Только для канареек
  
  
  • [] До 1.0
  
  
  • [] «Совместимые» компоненты Ember-Glimmer
  
  
  • [] Внешние HTML-шаблоны
  
  
  • [] Хуки жизненного цикла
  
  
  • [] Определение вычисляемых свойств
    
    
    
    
    
    • [] Как зависеть от args
    
    
    
  
  
  • [] Руководство по миграции / Компоненты Glimmer для…
  
  
  • Руководства по написанию эффективных компонентов Glimmer для людей, знакомых с другими библиотеками
  
  
  • [] Компоненты Glimmer для разработчиков Ember
  
  
  • [] Компоненты Glimmer для разработчиков React
  
  
  • [] Компоненты Glimmer для разработчиков Angular
  
  
  • [] Компоненты Glimmer для разработчиков на COBOL
  
  

Открытые вопросы

1. Каковы лучшие практики для действий? Это то, что нам нужно, чтобы позволить менеджерам компонентов подключиться?
2. Как вы используете простые классы JavaScript (те, у которых нет статического метода create() ) в качестве классов компонентов? Протокол инициализации компонента кажется простым, но на удивление сложным.
3. Где лучше всего задокументировать «дополнительные API», например CustomComponentManager ?
4. Как нам управлять версиями CustomComponentManager ?