Web Components 是一组技术规范,用于创建可重用、可组合的自定义 HTML 元素。这种技术可以将应用程序模块化,使其易于维护和重用,同时降低应用程序的复杂度。
Stencil 是一个基于 Web Components 规范的工具集,可以帮助我们轻松地构建、测试和部署自定义元素。
本文将介绍如何使用 Stencil 构建自定义元素,并提供实例代码和指导意义。
安装和创建项目
首先,在全局范围内安装 Stencil:
--- - -- -------------
然后使用以下命令创建一个新项目:
--- ---- -------
这将引导您完成以下步骤:
- 输入项目名称、描述和作者信息。
- 选择 Web Components 的预设模板。Stencil 提供了一个基本模板、一个 Todo List 模板和一个 Ionic 模板。我们选择基本模板。
- 安装所需的依赖项。Stencil 使用 TypeScript 和 Sass,因此会在项目中自动加入这些依赖项。
完成项目创建后,转到项目目录并运行以下命令:
--- -----
这将启动本地服务器,并在默认端口上(通常是 http://localhost:3333)显示您的应用程序。
项目的根目录结构如下所示:
--- ------------- --- ---- - --- ----------- - - --- --------- - - - --- ------------ - - - --- ------------ - - - --- --------- - - --- --------- - - - --- ------------ - - - --- ------------ - - - --- --------- - - --- ------------ - - - --- --------------- - - - --- --------------- - - - --- --------- - --- ------- - - --- ------- - - --- ---------- - --- ---------- - --- -------- --- ------- - --- --- --- ----------------- --- ------------ --- -------------
/src/components
目录包含所有自定义元素的代码。/src/global
目录包含全局样式和基本 HTML 文件。/src/assets
目录包含应用程序的静态资源和数据(例如图像和字体)。stencil.config.ts
包含展开 Stencil 构建和部署的配置选项。
创建自定义元素
Stencil 的每个组件都是一个自定义元素(Custom Element),它继承了原生的 HTMLElement 和所有其他 DOM API。我们可以使用标准的 HTML,为每个元素添加属性和事件,就像使用内置的 html 元素一样。
在 /src/components
目录下创建一个新的目录(例如 my-component
),并在该目录中创建一个新的 TypeScript 文件(例如 my-component.tsx
)。
Stencil 允许使用 JSX 语法编写 HTML 模板。在 my-component.tsx
文件中,我们将创建一个简单的自定义元素,其中包含一个输入框和一个按钮,用于输入名称并发送问候语给用户:
------ - ---------- -- ----- ----- - ---- ---------------- ------------ ---- --------------- --------- ------------------- ------- ---- -- ------ ----- ----------- - ------- ----- ------- -------- ----------- ------- ------------ - ------- ------ -- - ----------------------- ----- -------- - ------- --------------------- ---------------- - ----------- - ------- ------ -- - ----- ----- - ------------ -- ----------------- --------------- - ------------ - -------- - ------ - ----- ----------------------------- ------- ----- ---- ----- ------ ----------- -------------------------- -- -------- ------- ------------------ ----------------- ------- -- - -
在这个例子中,我们定义了一个 my-component
的自定义元素,并声明了两个属性 name
和 inputValue
。name
属性是一个字符串,它是通过 @Prop()
装饰器定义的。inputValue
属性是一个状态值,它是通过 @State()
装饰器定义的。
我们还定义了两个方法 handleSubmit
和 handleInput
,用于监听表单输入和按钮点击事件。在 render()
方法中,我们返回一个表单元素,并将事件绑定到相应的方法上。
这个例子演示了如何在 Stencil 中使用 JSX 和 TypeScript 编写自定义元素。现在我们需要将这个自定义元素添加到我们的应用程序中。
添加自定义元素到应用程序
要将 my-component
添加到应用程序中,在 /src/index.html
文件的 <body>
标签中插入 <my-component>
元素:
------ ----------------------------- -------
我们还需要在 index.ts
中引用自定义元素并将其添加到全局范围:
------ - -------------------- - ---- --------------------------- -----------------------
这样,我们的自定义元素就可以在应用程序中使用了。
现在启动本地服务器,打开 http://localhost:3333 并查看结果。您应该会看到一个表单,可以输入名称并点击按钮发送问候语。
给自定义元素添加样式
Stencil 允许为自定义元素添加样式,这些样式在使用 Shadow DOM 时可以隔离。
在 my-component
目录中,创建一个新的 Sass 文件(例如 my-component.scss
),并在 my-component.tsx
文件中引用该文件。
------ - ---------- -- ----- ----- - ---- ---------------- ------------ ---- --------------- --------- -------------------- ------- ---- -- ------ ----- ----------- - -- --- -
现在,可以在 my-component.scss
中编写 Sass 样式代码:
----- - -------- ------ -------- ----- ----------------- ----- ------- ----- --- ----- - ---- - -------- ----- --------------- ------- ------------ ----------- -------- ---- -- - ----- - ------------ ----- -------------- ------- - ------------------ - -------- ------- ------- ----- --- ----- - --------------------- - -------- ------ ----- ------- ----- ----------------- -------- ------ ----- ----------- - --- --- ---------------- -------------- -------- - --------------------------- - ----------------- -------- -
这个例子演示了如何使用 Sass 为自定义元素添加样式。:host
选择器表示自定义元素本身的根节点。这样,我们可以在全局 CSS 中覆盖自定义元素的样式,而不会对其它节点产生任何影响。
测试自定义元素
Stencil 提供了一个集成测试框架,用于测试自定义元素的行为和功能。
创建一个新的目录 /src/components/my-component/test
,并在该目录中创建一个新的测试文件 my-component.spec.tsx
。在此文件中,我们将编写一个测试脚本,以确保自定义元素的输入和输出正常工作:
------ - ----------- - ---- ------------------------ ------ - ----------- - ---- ------------------ ------------------------ -- -- - ------------- ----- -- -- - ----- ---- - ----- ------------- ----------- -------------- ----- ------------------------------- --- ------------------------------- --- ------------ -------- ---- ---- -- ----------- ----- -- -- - ----- ---- - ----- ------------- ----------- -------------- ----- ------------------------------- --- ----- ----- - ----------------------------------------------- ----- ------ - -------------------------------------------------- ----- ---- - --------------------------------- --------------------------- ---------------------------- ----------------------------- ------------ - ------- ----- ------------------------ ---------------- ----- -------------- ------------------------------------------------- -------- --- ---
在这个例子中,我们使用 newSpecPage()
方法创建了一个实例,并模拟了一个 <my-component>
标签。我们测试了两种情况:
- 当
<my-component>
元素渲染时,根节点必须存在。 - 当表单提交时,我们期望出现弹框,其中包含正确的问候语。
现在运行 npm test
命令,就可以看到测试结果了。
构建和部署自定义元素
Stencil 提供了多种选项,用于构建和部署自定义元素。
在 stencil.config.ts
中,您可以指定构建选项,例如要构建的目标平台、输出的目录和构建过程中的文件转换。
在 /public
目录中,您可以存放与应用程序相关的静态资源(例如图像和字体)和基本 HTML 模板。
要构建自定义元素的生产版本,请运行以下命令:
--- --- -----
这将在 /build
目录中生成一个打包好的文件。您可以将这些文件直接部署到 Web 服务器上,并使用自定义元素来构建更大的应用程序。
您还可以使用本地存储,通过自定义元素扩展现有应用程序的功能。由于自定义元素是标准的 HTML 元素,所以您可以将其添加到任何使用 HTML 的 Web 应用程序中。
结论
在本文中,我们介绍了如何使用 Stencil 构建自定义元素,并演示了如何在 Stencil 中使用 JSX 和 TypeScript 编写自定义元素。我们还介绍了如何测试自定义元素以及如何构建和部署它们。
Web Components 技术可以大大简化现代 Web 应用程序的开发、维护和部署。掌握 Web Components 技术可以使前端工程师更加轻松地开发可重用、可组合的自定义元素,提高应用程序的可维护性和可扩展性。我们鼓励您继续学习这种技术,以便在实际应用程序中使用 Web Components。
来源:JavaScript中文网 ,转载请注明来源 本文地址:https://www.javascriptcn.com/post/671a0a0f9babaf620fa09c95