Masalah pencarian ini melacak implementasi komponen Glimmer di Ember.js.

Rencana

Komponen Glimmer.js memiliki fitur berikut:

1. Template “HTML Luar” (tanpa tagName , attributeBindings , dll.)
2. Argumen dalam template diawali dengan @ , seperti {{@firstName}}
3. Argumen ditetapkan pada komponen sebagai this.args
4. Kelas komponen menggunakan sintaks kelas JavaScript
5. Status komponen yang dapat diubah dianotasi dengan properti @tracked
6. Komponen dipanggil melalui sintaks <AngleBracket />
7. Atribut dapat "diperciki" melalui …attributes

Sesuai dengan semangat inkrementalisme Ember, kami ingin mendaratkan fungsionalitas ini sepotong demi sepotong melalui sebuah addon. Ini memungkinkan komunitas untuk mulai menggunakan fitur dan memberikan umpan balik di awal proses.

Bahkan, kami sudah mulai menelusuri komponen Glimmer di Ember. Dua fitur pertama sudah mulai mendarat:

1. Dalam komponen template-only, template adalah “HTML luar” (dengan asumsi fitur opsional template-only-glimmer-components telah diaktifkan.)
2. Argumen dapat diakses di template melalui awalan @ (misalnya {{@firstName}} ).

Masalah ini mengusulkan penyelesaian proses membawa komponen Glimmer ke Ember dengan mengizinkan add-on menyediakan implementasi komponen alternatif, kemudian mengubah paket @glimmer/component menjadi addon Ember yang mengimplementasikan API komponen Glimmer.js.

Kami akan membagi pekerjaan itu menjadi beberapa fase, masing-masing membuka manfaat untuk aplikasi dan add-on Ember yang ada. Fase 0 adalah tentang menambahkan primitif yang diperlukan ke Ember.js untuk mendukung implementasi komponen alternatif. Fase 1, 2, dan 3 adalah tentang mengaktifkan API komponen Glimmer.js secara bertahap.

Sementara kami mendalami Fase 0 dan 1, kami akan menunda penjelajahan detail teknis fase selanjutnya hingga fase pertama mendekati penyelesaian.

Fase 0: Menyesuaikan Perilaku Komponen

TL;DR: Tambahkan API CustomComponentManager ke Ember.js untuk memungkinkan addon mengimplementasikan API komponen khusus.

Saat ini, semua komponen dalam aplikasi Ember diasumsikan sebagai subkelas dari Ember.Component . Untuk mendukung API komponen alternatif di Ember, kami memerlukan beberapa cara untuk memberi tahu Ember kapan dan bagaimana perilaku komponen harus berubah.

Saat kami mengatakan "perilaku komponen khusus", kami secara khusus bermaksud:

1. Bagaimana instance komponen dibuat.
2. Bagaimana instance komponen dihancurkan.
3. Bagaimana argumen diberikan ke instance komponen.
4. Bagaimana komponen diberi tahu tentang perubahan siklus hidup ini.

Sementara Glimmer VM memperkenalkan konsep "pengelola komponen", sebuah objek yang membuat keputusan ini, API ini sangat rendah. Akan terlalu dini untuk mengadopsinya secara langsung sebagai API publik di Ember karena sulit untuk ditulis, mudah ditulis dengan cara yang merusak komponen lain, dan belum stabil.

Sebagai gantinya, kami mengusulkan API Ember baru yang disebut CustomComponentManager yang mengimplementasikan pola delegasi. CustomComponentManager menyediakan area permukaan API yang lebih kecil daripada ComponentManager Glimmer VM API yang lengkap, yang memungkinkan pembuat addon jatuh ke dalam "lubang kesuksesan".

Jadi, bagaimana Ember mengetahui manajer komponen mana yang digunakan untuk komponen tertentu? Iterasi asli RFC Komponen Kustom memperkenalkan konsep ComponentDefinition , struktur data yang terdaftar dengan penuh semangat di Ember dan menentukan manajer komponen mana yang akan digunakan.

Salah satu manfaat utama dari pendekatan ComponentDefinition adalah bahwa resolusi manajer komponen dapat terjadi pada waktu pembuatan. Sayangnya, itu berarti kita harus merancang API untuk persisnya bagaimana ini didaftarkan, dan kemungkinan berarti semacam integrasi dengan pipa pembangunan.

Sebagai gantinya, kami mengusulkan API untuk menyetel pengelola komponen saat runtime melalui anotasi pada kelas komponen. Langkah inkremental ini memungkinkan pekerjaan pada manajer komponen kustom untuk melanjutkan sementara solusi jangka panjang dirancang.

Penemuan Manajer Komponen Kustom

Dalam iterasi ini, komponen harus secara eksplisit memilih manajer komponen alternatif. Mereka melakukan ini melalui fungsi componentManager , diekspor oleh Ember, yang memberi anotasi saat runtime manajer komponen mana yang harus digunakan untuk kelas komponen tertentu:

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

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

Akhirnya, ini bisa menjadi dekorator kelas:

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

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

Saat pertama kali komponen ini dipanggil, Ember memeriksa kelas untuk melihat apakah ia memiliki anotasi pengelola komponen khusus. Jika demikian, ia menggunakan nilai string untuk melakukan pencarian pada wadah. Dalam contoh di atas, Ember akan meminta wadah untuk objek dengan kunci wadah component-manager:glimmer .

Addons dengan demikian dapat menggunakan semantik resolusi normal untuk menyediakan pengelola komponen khusus. Addon komponen Glimmer kami dapat mengekspor manajer komponen dari addon/component-managers/glimmer.js yang akan ditemukan secara otomatis melalui aturan resolusi normal.

Meskipun API ini bertele-tele dan tidak terlalu ergonomis, aplikasi dan add-on dapat mengabstraksikannya dengan memperkenalkan kelas dasar mereka sendiri dengan anotasi. Misalnya, jika addon bernama turbo-component ingin menyediakan pengelola komponen khusus, addon tersebut dapat mengekspor kelas dasar seperti ini:

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

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

Pengguna addon ini dapat mensubklasifikasikan kelas dasar TurboComponent untuk mendefinisikan komponen yang menggunakan manajer komponen yang benar:

import TurboComponent from 'turbo-component';

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

API Komponen Kustom

Tidak ada komponen yang merupakan sebuah pulau, dan untuk alasan kompatibilitas mundur, penting agar pengenalan API komponen baru tidak merusak komponen yang ada.

Salah satu contohnya adalah API hierarki tampilan yang ada. Komponen Ember dapat memeriksa komponen induknya melalui properti parentView . Bahkan jika induknya bukan Ember.Component , komponen Ember anak harus tetap memiliki properti parentView non-null.

Saat ini, CurlyComponentManager di Ember bertanggung jawab untuk mempertahankan status ini, serta "status lingkup" ambient lainnya seperti target tindakan.

Untuk mencegah manajer komponen yang diimplementasikan dengan buruk melanggar invarian dalam sistem yang ada, kami menggunakan pola komposisi untuk menyesuaikan perilaku sambil menyembunyikan sudut tajam dari API yang mendasarinya.

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) {
  }
});

Fase 1: Komponen Ember Object Glimmer

Kelas dasar Component di Ember mendukung daftar panjang fitur, banyak di antaranya tidak lagi banyak digunakan. Fitur-fitur ini dapat membebankan biaya kinerja, bahkan ketika tidak digunakan.

Sebagai langkah pertama, kami ingin memberikan cara untuk ikut serta dalam API komponen Glimmer.js yang disederhanakan melalui paket @glimmer/component . Untuk memudahkan migrasi, kami akan menyediakan implementasi kelas dasar Glimmer Component yang diturunkan dari Ember.Object pada @glimmer/component/compat .

Berikut adalah contoh tampilan "komponen 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>

Karakteristik penting dari komponen ini:

• Template adalah HTML luar . Karena contoh template di atas tidak memiliki elemen root tunggal, ini dirender sebagai "komponen tanpa tag".
• Tindakan hanyalah fungsi pada komponen dan tidak perlu disarangkan dalam hash actions .
• Argumen ditetapkan pada properti args daripada menyetel properti individual pada komponen secara langsung.
• Mereka menggunakan model objek Ember . Ini berarti alat seperti properti terkomputasi dan mixin yang sudah dikenal oleh pengembang Ember terus bekerja.

Sama pentingnya adalah apa yang tidak termasuk:

• Properti @tracked tidak akan didukung hingga Fase 3.
• Tidak ada properti layout atau template pada komponen.
• Tidak ada metode atau properti yang terkait dengan hierarki tampilan, seperti childViews , parentView , nearestWithProperty , dll.
• Tidak ada tagName , attributeBindings , atau DSL JavaScript khusus lainnya untuk memodifikasi elemen root.
• Tidak ada send atau sendAction untuk acara pengiriman.
• Tidak ada kelas ember-view wajib atau ID elemen panduan yang dibuat secara otomatis.
• Tidak ada metode manual rerender() .
• Tidak ada properti attrs (gunakan args sebagai gantinya).
• Argumen yang diteruskan adalah "searah" dan tidak membuat ikatan dua arah.
• Argumen yang diteruskan tidak ditetapkan sebagai properti pada instance komponen, menghindari kemungkinan tabrakan penamaan yang sulit di-debug.
• Tidak ada this.$() untuk membuat objek jQuery untuk elemen komponen.
• Tidak ada komponen manual appendTo ke dalam DOM.
• Tidak ada dukungan untuk peristiwa siklus hidup berikut:
  
  
  
  • willInsertElement
  
  
  • didRender
  
  
  • willRender
  
  
  • willClearRender
  
  
  • willUpdate
  
  
  • didReceiveAttrs
  
  
  • didUpdateAttrs
  
  
  • parentViewDidChange
  
  
• Tidak ada pendengar acara on() untuk acara siklus hidup komponen; kait harus diimplementasikan sebagai metode.

Satu efek samping yang menarik dari kumpulan fitur ini adalah bahwa hal itu sesuai dengan upaya untuk mengaktifkan kelas JavaScript . Sehubungan dengan desain yang diusulkan dalam ES Classes RFC , kami dapat menyediakan implementasi alternatif dari komponen di atas:

// 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);
  }
});

Fase 2 - Sintaks Kurung Sudut

Fase 2 memungkinkan pemanggilan komponen melalui kurung sudut ( <UserAvatar @user={{currentUser}} /> ) selain curli ( {{my-component user=currentUser}} ). Karena sintaksis ini membedakan antara argumen komponen dan atribut HTML, fitur ini juga memungkinkan atribut yang diteruskan “splatting” ke dalam template komponen melalui …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}} />

Ini akan membuat output mirip dengan berikut:

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

Fase 3 - Properti Terlacak

Fase 3 mengaktifkan properti yang dilacak melalui dekorator @tracked di Ember. Detail interop antara model objek Ember dan properti yang dilacak sedang dikerjakan. Setelah properti yang dilacak mendarat, pengguna akan dapat melepaskan modul @glimmer/component/compat dan menggunakan kelas dasar komponen non-Ember.Object yang normal.

Bersamaan dengan fitur “pelacakan otomatis” yang baru saja digabungkan (yang menyimpulkan dependensi properti yang dihitung secara otomatis), ini akan menghasilkan penyederhanaan lebih lanjut dari kode aplikasi:

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;
  }
}

T&J

Dapatkah saya menambahkan kembali hal-hal seperti nama kelas ember-view atau atribut id ke komponen Glimmer untuk kompatibilitas dengan CSS yang ada?

Ya. Contoh:

<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);
  }
}

Sumber daya

• Saluran #st-glimmer-components di komunitas Ember Slack
  
  
  
  • Kami sedang mengoordinasikan pekerjaan di sini.
  
  
• RFC Komponen Kustom
• custom-component-manager cabang
  
  
  
  • Cabang Ember.js yang sedang berlangsung dengan implementasi CustomComponentManager belakang flag fitur
  
  
• tracked cabang
  
  
  
  • Cabang Ember.js yang sedang berlangsung dengan pekerjaan pada interop antara properti @tracked dan objek Ember
  
  

Tugas

Kami akan menggunakan daftar di bawah ini untuk melacak pekerjaan yang sedang berlangsung. Saat kami mempelajari lebih lanjut selama implementasi, kami akan menambah atau menghapus item pada daftar.

API Pengelola Komponen Kustom

• [x] Perbarui RFC Komponen Kustom untuk mencerminkan perubahan di atas (@chancancode)
  
  
  
  • https://github.com/emberjs/rfcs/pull/213#issuecomment -370494713
  
  
• [x] Tambahkan tanda fitur glimmer-custom-component-manager
• [x] Menerapkan fungsi componentManager
  
  
  
  • [x] Ekspos sebagai { componentManager } from '@ember/custom-component-manager'
  
  
• [x] Resolver perlu mendeteksi kelas beranotasi
• [x] Penyelesai perlu mencari manajer komponen yang ditentukan
  
  
  
  • [ ] Panduan untuk penulis addon tentang di mana harus meletakkan manajer komponen sehingga mereka ditemukan
  
  
  • [ ] Bagaimana cara kerjanya dengan Penyatuan Modul? (@mixonik)
  
  
• [x] Terapkan CustomComponentManager API
  
  
  
  • [x] Tentukan antarmuka CustomComponentManagerDelegate
  
  
  • [x] version
  
  
  • [x] create()
  
  
  • [x] getContext()
  
  
  • [x] update()
  
  
  • [x] destroy?()
  
  
  • [x] didCreate?()
  
  
  • [x] didUpdate?()
  
  
  • [x] getView?()
  
  
  • [x] Validasi properti version setelah pembuatan
  
  
  • [x] Internal
  
  
  • [x] Pertahankan childViews dan parentView di komponen yang ada
  
  
  • [ ] Instrumen untuk menampilkan kinerja
  
  
  • [ ] Instrumen untuk kompatibilitas dengan Ember Inspector
  
  

Addon Komponen Glimmer

• [x] Dukungan menggunakan sparkles-components addon
  
  
  
  • [x] Kelas dasar harus mengimpor dan menambahkan anotasi componentManager saat dikonsumsi dari Ember
  
  
  • [x] CustomComponentManager implementasi harus dapat ditemukan melalui wadah Ember
  
  
• [ ] Dukungan menggunakan @glimmer/component sebagai addon Ember
  
  
  
  • [ ] Pertahankan perilaku yang ada saat dikonsumsi dari Glimmer.js
  
  
  • [ ] import Component from '@glimmer/component' menyediakan kelas dasar JavaScript biasa
  
  
  • [ ] import Component from '@glimmer/component/compat' menyediakan Ember.Object kelas dasar
    
    menengadah
  
  
• [ ] Kait Siklus Hidup
  
  
  
  • [x] statis create(injections)
  
  
  • [x] didInsertElement()
  
  
  • [x] willDestroy()
  
  
  • [x] didUpdate()
  
  
  • [x] Metode pemanggilan delegasi acara ( click() dll.) tidak boleh dipicu
  
  
• [ ] Akses Elemen
  
  
  
  • [ ] this.bounds
  
  
  • [ ] this.element menghitung properti alias ke this.bounds
  
  
  • [ ] API berbasis pengubah elemen untuk mengekspos elemen
  
  
• [ ] Argumen
  
  
  
  • [x] this.args tersedia di konstruktor
  
  
  • [x] this.args diperbarui sebelum didUpdate dipanggil
  
  
  • [ ] this.args seharusnya tidak memicu siklus rendering ulang yang tak terbatas (perlu diverifikasi)
  
  
• [ ] Dokumentasi
  
  
  
  • [ ] Bagaimana cara meng-install
  
  
  • [ ] Peringatan
  
  
  • [ ] Hanya kenari
  
  
  • [ ] Pra-1.0
  
  
  • [ ] Komponen "kompat" Ember-Glimmer
  
  
  • [ ] Template HTML luar
  
  
  • [ ] Kait siklus hidup
  
  
  • [ ] Mendefinisikan properti yang dihitung
    
    
    
    
    
    • [ ] Bagaimana bergantung pada args
    
    
    
  
  
  • [ ] Panduan Migrasi / Komponen Glimmer untuk…
  
  
  • Panduan untuk menulis komponen Glimmer yang efektif untuk orang yang akrab dengan perpustakaan lain
  
  
  • [ ] Komponen Glimmer untuk Pengembang Ember
  
  
  • [ ] Komponen Glimmer untuk Pengembang React
  
  
  • [ ] Komponen Secercah untuk Pengembang Sudut
  
  
  • [ ] Komponen Glimmer untuk Pengembang COBOL
  
  

Pertanyaan-pertanyaan terbuka

1. Apa praktik terbaik untuk tindakan? Apakah ini sesuatu yang kita perlukan untuk memungkinkan manajer komponen terhubung?
2. Bagaimana Anda menggunakan kelas JavaScript kosong (yang tidak memiliki metode create() statis) sebagai kelas komponen? Protokol untuk menginisialisasi komponen tampaknya sederhana tetapi ternyata rumit.
3. Di mana tempat terbaik untuk mendokumentasikan “addon API” seperti CustomComponentManager ?
4. Bagaimana kita menangani versi CustomComponentManager ?