Zbuduj podgląd klocków przy użyciu oświetlenia

1. Wprowadzenie

Komponenty sieciowe

Komponenty internetowe to zbiór standardów internetowych, które umożliwiają deweloperom rozszerzanie kodu HTML o niestandardowe elementy. W tym ćwiczeniu zdefiniujesz element <brick-viewer>, który będzie mógł wyświetlać modele klocków.

lit-element

Do zdefiniowania elementu niestandardowego <brick-viewer> użyjemy lit-element. lit-element to lekka klasa bazowa, która dodaje trochę lukru składniowego do standardu komponentów internetowych. Dzięki temu łatwo będzie nam rozpocząć pracę z elementem niestandardowym.

Rozpocznij

Będziemy kodować w środowisku Stackblitz online, więc otwórz ten link w nowym oknie:

stackblitz.com/edit/brick-viewer

Zaczynajmy!

2. Definiowanie elementu niestandardowego

Definicja klasy

Aby zdefiniować element niestandardowy, utwórz klasę, która rozszerza LitElement, i udekoruj ją za pomocą @customElement. Argumentem funkcji @customElement będzie nazwa elementu niestandardowego.

W pliku brick-viewer.ts umieść:

@customElement('brick-viewer')
export class BrickViewer extends LitElement {
}

Teraz element <brick-viewer></brick-viewer> jest gotowy do użycia w kodzie HTML. Jeśli jednak spróbujesz, nic się nie wyrenderuje. Zajmijmy się tym.

Metoda renderowania

Aby zaimplementować widok komponentu, zdefiniuj metodę o nazwie render. Ta metoda powinna zwracać literał szablonu oznaczony tagiem funkcji html. W szablonie literału z tagiem umieść dowolny kod HTML. Ten element zostanie wyrenderowany, gdy użyjesz <brick-viewer>.

Dodaj metodę render:

export class BrickViewer extends LitElement {
  render() {
    return html`<div>Brick viewer</div>`;
  }
}

3. Określanie pliku LDraw

Definiowanie właściwości

Byłoby świetnie, gdyby użytkownik elementu <brick-viewer> mógł określić, który model klocka ma być wyświetlany, za pomocą atrybutu, na przykład w ten sposób:

<brick-viewer src="path/to/model.ldraw"></brick-viewer>

Ponieważ tworzymy element HTML, możemy skorzystać z deklaratywnego interfejsu API i zdefiniować atrybut źródła, tak jak w przypadku tagu <img> lub <video>. W przypadku lit-element jest to tak proste jak udekorowanie właściwości klasy za pomocą @property. Opcja type pozwala określić, jak lit-element analizuje właściwość, aby użyć jej jako atrybutu HTML.

Zdefiniuj właściwość i atrybut src:

export class BrickViewer extends LitElement {
  @property({type: String})
  src: string|null = null;
}

<brick-viewer> ma teraz atrybut src, który możemy ustawić w kodzie HTML. Dzięki lit-element jego wartość jest już możliwa do odczytania w klasie BrickViewer.

Wyświetlanie wartości

Wartość atrybutu src możemy wyświetlić, używając go w szablonie literału metody renderowania. Interpoluj wartości w literałach szablonu, używając składni ${value}.

export class BrickViewer extends LitElement {
  render() {
    return html`<div>Brick model: ${this.src}</div>`;
  }
}

Teraz w oknie widzimy wartość atrybutu src w elemencie <brick-viewer>. Spróbuj wykonać następujące czynności: otwórz narzędzia dla programistów w przeglądarce i ręcznie zmień atrybut src. Spróbuj…

…Czy zauważasz, że tekst w elemencie aktualizuje się automatycznie? lit-element obserwuje właściwości klasy oznaczone dekoratorem @property i ponownie renderuje widok. lit-element wykonuje całą ciężką pracę za Ciebie.

4. Konfigurowanie sceny za pomocą Three.js

Światła, kamera, renderowanie!

Nasz element niestandardowy będzie używać three.js do renderowania modeli 3D klocków. Niektóre czynności chcemy wykonać tylko raz dla każdej instancji elementu <brick-viewer>, np. skonfigurować scenę, kamerę i oświetlenie three.js. Dodamy je do konstruktora klasy BrickViewer. Niektóre obiekty zachowamy jako właściwości klasy, aby móc ich użyć później: camera, scene, controls i renderer.

Dodaj konfigurację sceny three.js:

export class BrickViewer extends LitElement {

  private _camera: THREE.PerspectiveCamera;
  private _scene: THREE.Scene;
  private _controls: OrbitControls;
  private _renderer: THREE.WebGLRenderer;

  constructor() {
    super();

    this._camera = new THREE.PerspectiveCamera(45, this.clientWidth/this.clientHeight, 1, 10000);
    this._camera.position.set(150, 200, 250);

    this._scene = new THREE.Scene();
    this._scene.background = new THREE.Color(0xdeebed);

    const ambientLight = new THREE.AmbientLight(0xdeebed, 0.4);
    this._scene.add( ambientLight );

    const directionalLight = new THREE.DirectionalLight(0xffffff, 1);
    directionalLight.position.set(-1000, 1200, 1500);
    this._scene.add(directionalLight);

    this._renderer = new THREE.WebGLRenderer({antialias: true});
    this._renderer.setPixelRatio(window.devicePixelRatio);
    this._renderer.setSize(this.offsetWidth, this.offsetHeight);

    this._controls = new OrbitControls(this._camera, this._renderer.domElement);
    this._controls.addEventListener("change", () =>
      requestAnimationFrame(this._animate)
    );

    this._animate();

    const resizeObserver = new ResizeObserver(this._onResize);
    resizeObserver.observe(this);
  }

  private _onResize = (entries: ResizeObserverEntry[]) => {
    const { width, height } = entries[0].contentRect;
    this._renderer.setSize(width, height);
    this._camera.aspect = width / height;
    this._camera.updateProjectionMatrix();
    requestAnimationFrame(this._animate);
  };

  private _animate = () => {
    this._renderer.render(this._scene, this._camera);
  };
}

Obiekt WebGLRenderer udostępnia element DOM, który wyświetla wyrenderowaną scenę three.js. Dostęp do niego można uzyskać za pomocą właściwości domElement. Możemy interpolować tę wartość do literału szablonu renderowania, używając składni ${value}.

Usuń wiadomość src, która była w szablonie, i wstaw element DOM mechanizmu renderowania:

export class BrickViewer extends LitElement {
  render() {
    return html`
      ${this._renderer.domElement}
    `;
  }
}

Aby umożliwić wyświetlanie elementu DOM modułu renderującego w całości, musimy też ustawić sam element <brick-viewer> na display: block. Style możemy podać we właściwości statycznej o nazwie styles, ustawionej na literał szablonu css.

Dodaj ten styl do klasy:

export class BrickViewer extends LitElement {
  static styles = css`
    /* The :host selector styles the brick-viewer itself! */
    :host {
      display: block;
    }
  `;
}

Teraz <brick-viewer> wyświetla wyrenderowaną scenę three.js:

Element brick-viewer wyświetlający wyrenderowaną, ale pustą scenę.

Ale… jest pusta. Podajmy model.

Ładowarka klocków

Przekażemy właściwość src, którą zdefiniowaliśmy wcześniej, do LDrawLoader, który jest dostarczany z three.js.

Pliki LDraw mogą dzielić model Brick na osobne etapy budowy. Łączna liczba kroków i widoczność poszczególnych klocków są dostępne w interfejsie LDrawLoader API.

Skopiuj te właściwości, nową metodę _loadModel i nowy wiersz w konstruktorze:

@customElement('brick-viewer')
export class BrickViewer extends LitElement {
  private _loader = new LDrawLoader();
  private _model: any;
  private _numConstructionSteps?: number;
  step?: number;

  constructor() {
    // ...
    // Add this line right before this._animate();
    (this._loader as any).separateObjects = true;
    this._animate();
  }

  private _loadModel() {
    if (this.src === null) {
      return;
    }
    this._loader
        .setPath('')
        // Using our src property!
        .load(this.src, (newModel) => {

          if (this._model !== undefined) {
            this._scene.remove(this._model);
            this._model = undefined;
          }

          this._model = newModel;

          // Convert from LDraw coordinates: rotate 180 degrees around OX
          this._model.rotation.x = Math.PI;
          this._scene.add(this._model);

          this._numConstructionSteps = this._model.userData.numConstructionSteps;
          this.step = this._numConstructionSteps!;

          const bbox = new THREE.Box3().setFromObject(this._model);
          this._controls.target.copy(bbox.getCenter(new THREE.Vector3()));
          this._controls.update();
          this._controls.saveState();
        });
  }
}

Kiedy należy wywołać funkcję _loadModel? Należy ją wywoływać za każdym razem, gdy zmienia się atrybut src. Dekorując właściwość src za pomocą @property, dodaliśmy ją do cyklu życia aktualizacji lit-element. Za każdym razem, gdy wartość jednej z tych właściwości ulega zmianie, wywoływana jest seria metod, które mogą uzyskać dostęp do nowych i starych wartości właściwości. Metoda cyklu życia, która nas interesuje, to update. Metoda update przyjmuje argument PropertyValues, który zawiera informacje o właściwościach, które właśnie uległy zmianie. To idealne miejsce, aby zadzwonić do: _loadModel.

Dodaj metodę update:

export class BrickViewer extends LitElement {
  update(changedProperties: PropertyValues) {
    if (changedProperties.has('src')) {
      this._loadModel();
    }
    super.update(changedProperties);
  }
}

Element <brick-viewer> może teraz wyświetlać plik klocka określony za pomocą atrybutu src.

Element przeglądarki klocków wyświetlający model samochodu.

5. Wyświetlanie modeli częściowych

Teraz skonfigurujemy bieżący krok konstrukcyjny. Chcemy mieć możliwość określenia <brick-viewer step="5"></brick-viewer> i zobaczyć, jak wygląda model klocków na 5 etapie budowy. Aby to zrobić, ustaw właściwość step jako obserwowaną, dekorując ją za pomocą @property.

Udekoruj właściwość step:

export class BrickViewer extends LitElement {
  @property({type: Number})
  step?: number;
}

Teraz dodamy metodę pomocniczą, która sprawi, że widoczne będą tylko klocki do bieżącego etapu budowy. Wywołamy funkcję pomocniczą w metodzie aktualizacji, aby była uruchamiana za każdym razem, gdy zmieni się właściwość step.

Zaktualizuj metodę update i dodaj nową metodę _updateBricksVisibility:

export class BrickViewer extends LitElement {
  update(changedProperties: PropertyValues) {
    if (changedProperties.has('src')) {
      this._loadModel();
    }
    if (changedProperties.has('step')) {
      this._updateBricksVisibility();
    }
    super.update(changedProperties);
  }

  private _updateBricksVisibility() {
    this._model && this._model.traverse((c: any) => {
      if (c.isGroup && this.step) {
        c.visible = c.userData.constructionStep <= this.step;
      }
    });
    requestAnimationFrame(this._animate);
  }
}

Teraz otwórz narzędzia dla programistów w przeglądarce i sprawdź element <brick-viewer>. Dodaj do niego atrybut step, na przykład:

Kod HTML elementu brick-viewer z atrybutem step ustawionym na 10.

Zobacz, co się stanie z wyrenderowanym modelem. Możemy użyć atrybutu step, aby kontrolować, jaka część modelu jest wyświetlana. Oto jak powinien wyglądać, gdy atrybut step jest ustawiony na "10":

Model z klocków, który składa się tylko z 10 etapów budowy.

6. Nawigacja po zestawach klocków

mwc-icon-button

Użytkownik naszej aplikacji <brick-viewer> powinien też mieć możliwość poruszania się po krokach kompilacji za pomocą interfejsu. Dodajmy przyciski umożliwiające przejście do następnego, poprzedniego i pierwszego kroku. Aby ułatwić sobie zadanie, użyjemy komponentu internetowego przycisku Material Design. Ponieważ @material/mwc-icon-button jest już zaimportowany, możemy dodać <mwc-icon-button></mwc-icon-button>. Możemy określić ikonę, której chcemy użyć, za pomocą atrybutu icon, na przykład: <mwc-icon-button icon="thumb_up"></mwc-icon-button>. Wszystkie możliwe ikony znajdziesz na stronie material.io/resources/icons.

Dodajmy kilka przycisków ikon do metody renderowania:

export class BrickViewer extends LitElement {
  render() {
    return html`
      ${this._renderer.domElement}
      <div id="controls">
        <mwc-icon-button icon="replay"></mwc-icon-button>
        <mwc-icon-button icon="navigate_before"></mwc-icon-button>
        <mwc-icon-button icon="navigate_next"></mwc-icon-button>
      </div>
    `;
  }
}

Dzięki komponentom internetowym używanie Material Design na naszej stronie jest bardzo proste.

Powiązania zdarzeń

Te przyciski powinny coś robić. Przycisk „Odpowiedz” powinien resetować krok konstrukcji do 1. Przycisk „navigate_before” powinien zmniejszać krok konstrukcji, a przycisk „navigate_next” powinien go zwiększać. Lit-element ułatwia dodanie tej funkcji za pomocą powiązań zdarzeń. W szablonie literału HTML użyj składni @eventname=${eventHandler} jako atrybutu elementu. eventHandler będzie teraz uruchamiany, gdy w tym elemencie zostanie wykryte zdarzenie eventname. Dodajmy na przykład moduły obsługi zdarzeń kliknięcia do 3 przycisków ikon:

export class BrickViewer extends LitElement {
  private _restart() {
    this.step! = 1;
  }

  private _stepBack() {
    this.step! -= 1;
  }

  private _stepForward() {
    this.step! += 1;
  }

  render() {
    return html`
      ${this._renderer.domElement}
      <div id="controls">
        <mwc-icon-button @click=${this._restart} icon="replay"></mwc-icon-button>
        <mwc-icon-button @click=${this._stepBack} icon="navigate_before"></mwc-icon-button>
        <mwc-icon-button @click=${this._stepForward} icon="navigate_next"></mwc-icon-button>
      </div>
    `;
  }
}

Spróbuj teraz kliknąć przyciski. Świetnie!

Style

Przyciski działają, ale nie wyglądają dobrze. Wszystkie są skupione na dole. Zmieńmy ich styl, aby nałożyć je na scenę.

Aby zastosować style do tych przycisków, wracamy do właściwości static styles. Te style są ograniczone, co oznacza, że będą stosowane tylko do elementów w tym komponencie internetowym. To jedna z zalet tworzenia komponentów internetowych: selektory mogą być prostsze, a kod CSS będzie łatwiejszy do odczytania i napisania. Do widzenia, BEM!

Zaktualizuj style, aby wyglądały tak:

export class BrickViewer extends LitElement {
  static styles = css`
    :host {
      display: block;
      position: relative;
    }
    #controls {
      position: absolute;
      bottom: 0;
      width: 100%;
      display: flex;
    }
  `;
}

Element przeglądarki klocków z przyciskami ponownego uruchomienia, wstecz i dalej.

Przycisk resetowania kamery

Użytkownicy <brick-viewer> mogą obracać scenę za pomocą myszy. Dodajmy jeszcze jeden przycisk, który będzie resetować kamerę do jej domyślnej pozycji. Wystarczy dodać kolejny element <mwc-icon-button> z powiązaniem zdarzenia kliknięcia.

export class BrickViewer extends LitElement {
  private _resetCamera() {
    this._controls.reset();
  }

  render() {
    return html`
      <div id="controls">
        <!-- ... -->
        <!-- Add this button: -->
        <mwc-icon-button @click=${this._resetCamera} icon="center_focus_strong"></mwc-icon-button>
      </div>
    `;
  }
}

Szybsza nawigacja

Niektóre zestawy klocków mają wiele kroków. Użytkownik może chcieć przejść do konkretnego kroku. Dodanie suwaka z numerami kroków może ułatwić szybką nawigację. Użyjemy do tego elementu <mwc-slider>.

mwc-slider

Element suwaka wymaga kilku ważnych danych, takich jak minimalna i maksymalna wartość suwaka. Minimalna wartość suwaka może zawsze wynosić „1”. Jeśli model został wczytany, maksymalna wartość suwaka powinna wynosić this._numConstructionSteps. Możemy przekazać te wartości do <mwc-slider> za pomocą atrybutów. Możemy też użyć dyrektywy ifDefined lit-html, aby uniknąć ustawiania atrybutu max, jeśli właściwość _numConstructionSteps nie została zdefiniowana.

Dodaj <mwc-slider> między przyciskami „wstecz” i „dalej”:

export class BrickViewer extends LitElement {
  render() {
    return html`
      <div id="controls">
        <!-- ... backwards button -->
        <!-- Add this slider: -->
        <mwc-slider
            step="1"
            pin
            markers
            min="1"
            max=${ifDefined(this._numConstructionSteps)}
        ></mwc-slider>
        <!-- ... forwards button -->
      </div>
    `;
  }
}

Dane „w górę”

Gdy użytkownik przesuwa suwak, bieżący krok konstrukcji powinien się zmienić, a widoczność modelu powinna zostać odpowiednio zaktualizowana. Element suwaka będzie emitować zdarzenie wejściowe za każdym razem, gdy suwak zostanie przeciągnięty. Dodaj powiązanie zdarzenia do suwaka, aby przechwycić to zdarzenie i zmienić krok konstrukcji.

Dodaj powiązanie zdarzenia:

export class BrickViewer extends LitElement {
  render() {
    return html`
      <div id="controls">
        <!-- ...  -->
        <!-- Add the @input event binding: -->
        <mwc-slider
            ...
            @input=${(e: CustomEvent) => this.step = e.detail.value}
        ></mwc-slider>
        <!-- ... -->
      </div>
    `;
  }
}

Super! Możemy użyć suwaka, aby zmienić wyświetlany krok.

Dane „w dół”

Jest jeszcze jedna rzecz. Gdy do zmiany kroku używane są przyciski „Wstecz” i „Dalej”, należy zaktualizować uchwyt suwaka. Powiąż atrybut wartości <mwc-slider> z this.step.

Dodaj powiązanie value:

export class BrickViewer extends LitElement {
  render() {
    return html`
      <div id="controls">
        <!-- ...  -->
        <!-- Add the value property binding: -->
        <mwc-slider
            ...
            value=${ifDefined(this.step)}
        ></mwc-slider>
        <!-- ... -->
      </div>
    `;
  }
}

Już prawie skończyliśmy suwak. Dodaj styl flex, aby dobrze współgrał z innymi elementami sterującymi:

export class BrickViewer extends LitElement {
  static styles = css`
    /* ... */
    mwc-slider {
      flex-grow: 1;
    }
  `;
}

Musimy też wywołać funkcję layout na samym elemencie suwaka. Zrobimy to w metodzie cyklu życia firstUpdated, która jest wywoływana po pierwszym wyrenderowaniu DOM. Dekorator query może nam pomóc uzyskać odwołanie do elementu suwaka w szablonie.

export class BrickViewer extends LitElement {
  @query('mwc-slider')
  slider!: Slider|null;

  async firstUpdated() {
    if (this.slider) {
      await this.slider.updateComplete
      this.slider.layout();
    }
  }
}

Oto wszystkie dodatki do suwaka (z dodatkowymi atrybutami pin i markers, które nadają mu atrakcyjny wygląd):

export class BrickViewer extends LitElement {
 @query('mwc-slider')
 slider!: Slider|null;

 static styles = css`
   /* ... */
   mwc-slider {
     flex-grow: 1;
   }
 `;

 async firstUpdated() {
   if (this.slider) {
     await this.slider.updateComplete
     this.slider.layout();
   }
 }

 render() {
   return html`
     ${this._renderer.domElement}
     <div id="controls">
       <mwc-icon-button @click=${this._restart} icon="replay"></mwc-icon-button>
       <mwc-icon-button @click=${this._stepBack} icon="navigate_before"></mwc-icon-button>
       <mwc-slider
         step="1"
         pin
         markers
         min="1"
         max=${ifDefined(this._numConstructionSteps)}
         ?disabled=${this._numConstructionSteps === undefined}
         value=${ifDefined(this.step)}
         @input=${(e: CustomEvent) => this.constructionStep = e.detail.value}
       ></mwc-slider>
       <mwc-icon-button @click=${this._stepForward} icon="navigate_next"></mwc-icon-button>
       <mwc-icon-button @click=${this._resetCamera} icon="center_focus_strong"></mwc-icon-button>
     </div>
   `;
 }
}

Oto gotowy produkt.

Nawigowanie po modelu samochodu z klocków za pomocą elementu brick-viewer

7. Podsumowanie

Dowiedzieliśmy się, jak używać lit-element do tworzenia własnego elementu HTML. Dowiedzieliśmy się, jak:

  • Definiowanie elementu niestandardowego
  • Deklarowanie interfejsu API atrybutów
  • Renderowanie widoku elementu niestandardowego
  • Hermetyzacja stylów
  • Przekazywanie danych za pomocą zdarzeń i właściwości

Jeśli chcesz dowiedzieć się więcej o lit-element, odwiedź oficjalną stronę.

Gotowy element brick-viewer możesz zobaczyć na stronie stackblitz.com/edit/brick-viewer-complete.

Przeglądarka brick-viewer jest też dostępna w NPM, a jej kod źródłowy znajdziesz w repozytorium GitHub.