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 场景:

但…里面空空如也。我们来为它提供一个模型。
积木装载机
我们将之前定义的 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 属性指定的砖块文件。

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 属性,如下所示:

观察渲染的模型会发生什么变化!我们可以使用 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> 的最终用户可以使用鼠标控件旋转场景。在添加按钮时,我们来添加一个用于将相机重置为默认位置的按钮。另一个具有点击事件绑定的 <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>
`;
}
}
这就是最终成品!

7. 总结
我们学到了很多关于如何使用 lit-element 构建自己的 HTML 元素的知识。我们学习了如何:
- 定义自定义元素
- 声明属性 API
- 为自定义元素呈现视图
- 封装样式
- 使用事件和属性传递数据
如需详细了解 lit-element,请访问其官方网站。
您可以在 stackblitz.com/edit/brick-viewer-complete 查看完整的 brick-viewer 元素。
brick-viewer 也会在 NPM 上发布,您可以在此处查看源代码:Github 代码库。