Web Components 实践:使用 Stencil 构建自定义元素

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 的自定义元素,并声明了两个属性 nameinputValuename 属性是一个字符串,它是通过 @Prop() 装饰器定义的。inputValue 属性是一个状态值,它是通过 @State() 装饰器定义的。

我们还定义了两个方法 handleSubmithandleInput,用于监听表单输入和按钮点击事件。在 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