使用 lit-element 构建 Brick Viewer

1. 简介

Web 组件

Web 组件是一组 Web 标准,可让开发者使用自定义元素扩展 HTML。在此 Codelab 中,您将定义 <brick-viewer> 元素,该元素将能够显示积木模型!

lit-element

为了帮助我们定义自定义元素 <brick-viewer>,我们将使用 lit-element。lit-element 是一个轻量级基类,可为 Web 组件标准添加一些语法糖。这样,我们就可以轻松地启动并运行自定义元素。

开始使用

我们将在 Stackblitz 在线环境中编写代码,因此请在新窗口中打开以下链接:

stackblitz.com/edit/brick-viewer

让我们开始吧!

2. 定义自定义元素

课程定义

如需定义自定义元素,请创建一个扩展 LitElement 的类,并使用 @customElement 修饰该类。@customElement 的实参将是自定义元素的名称。

在 brick-viewer.ts 中,添加以下内容:

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

现在,<brick-viewer></brick-viewer> 元素已可在 HTML 中使用。但如果您尝试这样做,系统不会渲染任何内容。让我们解决这个问题。

呈现方法

如需实现组件的视图,请定义一个名为 render 的方法。此方法应返回一个使用 html 函数标记的模板字面量。在带标签的模板字面量中放入您想要的任何 HTML。当您使用 <brick-viewer> 时,系统会呈现此内容。

添加 render 方法:

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

3. 指定 LDraw 文件

定义属性

如果 <brick-viewer> 的用户可以使用属性指定要显示的积木模型,那就太好了,如下所示:

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

由于我们要构建 HTML 元素,因此可以利用声明式 API 并定义 source 属性,就像 <img> 或 <video> 标记一样。使用 lit-element,只需使用 @property 修饰类属性即可。借助 type 选项,您可以指定 lit-element 如何解析属性以用作 HTML 属性。

定义 src 属性和特性:

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

<brick-viewer> 现在有一个 src 属性,我们可以在 HTML 中设置该属性!得益于 lit-element,其值已经可以从 BrickViewer 类中读取。

显示值

我们可以在 render 方法的模板字面量中使用 src 属性,从而显示该属性的值。使用 ${value} 语法将值插值到模板字面量中。

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

现在,我们可以在窗口中看到 <brick-viewer> 元素中 src 属性的值。试试看:打开浏览器的开发者工具,然后手动更改 src 属性。快来试试吧…

…您是否注意到元素中的文本会自动更新?lit-element 会观察使用 @property 修饰的类属性,并为您重新渲染视图!lit-element 会完成繁重的工作,因此您不必这样做。

4. 使用 Three.js 设置场景

灯光、镜头、渲染!

我们的自定义元素将使用 three.js 来渲染 3D 积木模型。有些操作我们只想对 <brick-viewer> 元素的每个实例执行一次,例如设置 Three.js 场景、相机和光线。我们会将这些添加到 BrickViewer 类的构造函数中。我们将一些对象保留为类属性,以便稍后使用:camera、scene、controls 和 renderer。

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

WebGLRenderer 对象提供了一个 DOM 元素,用于显示渲染的 three.js 场景。可通过 domElement 属性访问。我们可以使用 ${value} 语法将此值插值到渲染模板字面量中。

移除模板中的 src 消息,然后插入渲染器的 DOM 元素:

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

为了让渲染器的 DOM 元素能够完整显示,我们还需要将 <brick-viewer> 元素本身设置为 display: block。我们可以在名为 styles 的静态属性中提供样式,并将其设置为 css 模板字面量。

将以下样式添加到该类中:

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

现在,<brick-viewer> 会显示渲染后的 Three.js 场景:

一个 brick-viewer 元素,显示已渲染但为空的场景。

但…里面空空如也。我们来为它提供一个模型。

积木装载机

我们将之前定义的 src 属性传递给 LDrawLoader,后者随 three.js 一起提供。

LDraw 文件可以将积木模型拆分为单独的搭建步骤。您可以通过 LDrawLoader API 访问总步骤数和单个积木的可见性。

复制这些属性、新的 _loadModel 方法以及构造函数中的新行:

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

何时应调用 _loadModel?每次 src 属性发生变化时,都需要调用该方法。通过使用 @property 修饰 src 属性,我们已将该属性纳入 lit-element 更新生命周期。每当这些修饰属性的值发生变化时,系统都会调用一系列方法,这些方法可以访问属性的新值和旧值。我们感兴趣的生命周期方法名为 update。update 方法接受 PropertyValues 参数,该参数将包含有关刚刚发生更改的所有属性的信息。这是调用 _loadModel 的理想位置。

添加 update 方法:

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

现在,我们的 <brick-viewer> 元素可以显示使用 src 属性指定的砖块文件。

一个显示汽车模型的 brick-viewer 元素。

5. 显示部分模型

现在,我们将当前构建步骤设为可配置。我们希望能够指定 <brick-viewer step="5"></brick-viewer>,并且应该能够看到第 5 个搭建步骤中的积木模型。为此,我们使用 @property 修饰 step 属性,使其成为可观察属性。

修饰 step 属性:

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

现在,我们将添加一个辅助方法,该方法仅使当前构建步骤之前的积木可见。我们将在 update 方法中调用该辅助函数,以便在每次 step 属性发生更改时运行该函数。

更新 update 方法,并添加新的 _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);
  }
}

现在,打开浏览器的开发者工具,然后检查 <brick-viewer> 元素。为其添加 step 属性,如下所示:

brick-viewer 元素的 HTML 代码,其 step 属性设置为 10。

观察渲染的模型会发生什么变化!我们可以使用 step 属性来控制模型的显示比例。当 step 属性设置为 "10" 时,它应如下所示:

一个仅需十个搭建步骤即可完成的积木模型。

6. Brick Set Navigation

mwc-icon-button

<brick-viewer> 的最终用户还应该能够通过界面浏览构建步骤。我们来添加用于前往下一步、上一步和第一步的按钮。我们将使用 Material Design 的按钮 Web 组件来简化此过程。由于 @material/mwc-icon-button 已导入,我们可以直接添加 <mwc-icon-button></mwc-icon-button>。我们可以使用 icon 属性指定要使用的图标,如下所示:<mwc-icon-button icon="thumb_up"></mwc-icon-button>。您可以在以下网址中找到所有可能的图标:material.io/resources/icons。

让我们向 render 方法添加一些图标按钮:

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

得益于 Web 组件,在网页上使用 Material Design 就是这么简单!

事件绑定

这些按钮应该具有实际功能。“reply”(回复)按钮应将构造步骤重置为 1。“navigate_before”按钮应递减施工步骤,“navigate_next”按钮应递增施工步骤。lit-element 可让您通过事件绑定轻松添加此功能。在 HTML 模板字面量中,使用语法 @eventname=${eventHandler} 作为元素属性。现在,当在该元素上检测到 eventname 事件时,eventHandler 就会运行!例如,我们为三个图标按钮添加点击事件处理脚本:

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

现在,请尝试点击这些按钮。做得好!

样式

这些按钮可以正常运行,但看起来不太美观。它们都挤在底部。我们来设置其样式,使其叠加在场景上。

如需为这些按钮应用样式,我们需返回到 static styles 属性。这些样式具有作用域,这意味着它们只会应用于此 Web 组件内的元素。这是编写 Web 组件的乐趣之一:选择器可以更简单,CSS 也更容易读写。再见,BEM!

更新样式,使其如下所示:

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

一个包含重启、后退和前进按钮的 brick-viewer 元素。

重置相机按钮

<brick-viewer> 的最终用户可以使用鼠标控件旋转场景。在添加按钮时,我们来添加一个用于将相机重置为默认位置的按钮。另一个具有点击事件绑定的 <mwc-icon-button> 即可完成这项工作。

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

导航更快捷

有些积木套装有很多步骤。用户可能希望跳到特定步骤。添加带有步骤编号的滑块有助于快速导航。为此,我们将使用 <mwc-slider> 元素。

mwc-slider

滑块元素需要一些重要数据,例如滑块的最小值和最大值。滑块的最小值始终可以为“1”。如果模型已加载,则滑块的最大值应为 this._numConstructionSteps。我们可以通过 <mwc-slider> 的属性来告知其这些值。我们还可以使用 ifDefined lit-html 指令,避免在未定义 _numConstructionSteps 属性时设置 max 属性。

在“后退”和“前进”按钮之间添加一个 <mwc-slider>:

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

数据“上行”

当用户移动滑块时,当前施工步骤应发生变化,并且模型的可见性应相应更新。每当拖动滑块时,滑块元素都会发出输入事件。在滑块本身上添加事件绑定,以捕获此事件并更改构造步骤。

添加事件绑定:

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

哇!我们可以使用滑块来更改显示的步骤。

数据“下行”

还有一件事。使用“上一步”和“下一步”按钮更改步骤时,需要更新滑块手柄。将 <mwc-slider> 的 value 属性绑定到 this.step。

添加 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>
    `;
  }
}

滑块即将完成。添加 flex 样式,使其与其他控件完美搭配:

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

此外,我们还需要对滑块元素本身调用 layout。我们将在 firstUpdated 生命周期方法中执行此操作,该方法会在 DOM 首次布局后调用。query 装饰器可以帮助我们获取对模板中滑块元素的引用。

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

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

以下是所有滑块添加项的汇总(滑块上还有额外的 pin 和 markers 属性,使其看起来更酷):

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

这就是最终成品!

使用 brick-viewer 元素浏览汽车积木模型

7. 总结

我们学到了很多关于如何使用 lit-element 构建自己的 HTML 元素的知识。我们学习了如何:

  • 定义自定义元素
  • 声明属性 API
  • 为自定义元素呈现视图
  • 封装样式
  • 使用事件和属性传递数据

如需详细了解 lit-element,请访问其官方网站。

您可以在 stackblitz.com/edit/brick-viewer-complete 查看完整的 brick-viewer 元素。

brick-viewer 也会在 NPM 上发布,您可以在此处查看源代码:Github 代码库。