可复用 UI 组件¶

背景¶

不同的 Firefox 表面使用了类似的 UI 元素，例如卡片、菜单、切换按钮和消息栏。一组设计师和开发人员开始合作，以新的 Web Components 的形式创建这些元素的标准化版本。目的是让这些组件封装我们的设计系统，确保应用程序的辅助功能和可用性，并减少维护多个不同 UI 模式实现的负担。

许多这些组件都使用 Lit 库构建，以利用其模板语法和重新渲染逻辑。所有新组件都将在 Storybook 中记录，以创建一个目录，工程师和设计师可以使用它来查看哪些组件可以轻松地从货架上取下并在整个 Firefox 中使用。

如果您想查看这些新的可复用组件随时间的进展，我们有一个可复用组件采用图表，您应该查看一下！

设计新的可复用组件¶

位于全局级别的组件，“UI 组件”，应与设计系统团队协作创建。这确保了与设计系统中其他元素以及现有 UI 元素的一致性。否则，您应咨询您的团队和相应的设计师以创建特定于领域的 UI 组件。理想情况下，这些领域组件应与 Firefox 中建立的其他 UI 模式保持一致。

现有的组件是否满足您的使用场景？¶

在创建新的可复用组件之前，请确保没有您可以使用的组件。在设计新的可复用组件时，请确保它是为所有用户设计的。以下是一些您可以用来帮助包含所有用户的问题：人们将如何感知、操作和理解此组件？该组件是否使用经过验证的标准技术。有关更多详细信息，请参阅 Mozilla 辅助功能发布指南文档的“一般注意事项”部分，以确保您的组件符合辅助功能标准。

支持在不同进程中使用组件¶

根据您的使用场景，新设计的组件可能需要在父进程、内容进程或两者中工作。有关这些不同进程的更多信息，请参阅进程模型文档。您可能会在具有访问 Services、XPCOMUtils 和其他全局变量的特权进程（例如父进程或特权内容进程）中使用您的组件。Storybook 和其他 Web 内容无法访问这些特权全局变量，因此您需要为 Services、XPCOMUtils、CSS 文件和资产的 chrome URI 等编写解决方法。查看 moz-support-link.mjs 和 moz-support-link.stories.mjs 以了解在父/chrome 中使用组件并需要在 Storybook 中处理 XPCOMUtils 的示例。查看 moz-toggle.mjs 以了解如何在 Storybook 中处理 CSS 的 chrome URI。查看 moz-label.mjs 以了解如何在 Storybook 中处理 Services 的示例。

自主或自定义内置自定义元素¶

有两种类型的自定义元素，扩展 HTMLElement 的自主元素和扩展基本 HTML 元素的自定义内置元素。如果您使用自主元素，则可以使用 Shadow DOM 和/或 Lit 库。 Lit 不支持自定义内置自定义元素。

在某些情况下，您可能希望在内置 HTML 元素之上提供一些功能，例如 moz-support-link 如何为锚元素准备 href 值。在其他情况下，您可能希望专注于创建标记并对元素上的更改做出反应。这就是 Lit 可以用于声明式地定义标记并在更新属性时对更改做出反应的地方。

添加新的设计系统组件¶

我们有一个 ./mach addwidget 脚手架命令，使创建新的可复用组件并将其连接到 Storybook 变得更容易。目前，此命令只能用于将新的基于 Lit 的 Web 组件添加到 toolkit/content/widgets。将来，我们可能会扩展它以支持创建不使用 Lit 的组件的选项以及将组件添加到不同目录的选项。有关这些未来用例的更多详细信息，请参阅 Bug 1803677。

要创建一个新的组件，您可以运行

# Component names should be in kebab-case and contain at least 1 -.
./mach addwidget component-name

脚手架命令将生成以下文件

└── toolkit
    └── content
        ├── tests
        │   └── widgets
        │       └── test_component_name.html # chrome test
        └── widgets
            └── component-name # new folder for component code
                ├── component-name.css # component specific CSS
                ├── component-name.mjs # Lit based component
                └── component-name.stories.mjs # component stories

它还将修改 toolkit/content/jar.mn 以添加新文件的 chrome:// URL，以及修改 toolkit/content/tests/widgets/chrome.ini 以启用运行新添加的测试。

运行脚手架命令后，您可以启动 Storybook，您将看到为您的组件生成的占位符内容。然后，您可以开始更改生成的文件并在 Storybook 中查看您的更改。

已知的 `browser_all_files_referenced.js` 问题¶

不幸的是，目前 browser_all_files_referenced.js 测试将失败，除非您的新组件立即在 Storybook 之外的地方使用。我们计划解决此问题，请参阅 Bug 1806002 以了解更多详细信息，但目前您可以通过更新此数组以包含您的新 chrome 文件路径来解决此问题。

使用新的设计系统组件¶

将新组件添加到 toolkit/content/widgets 并通过 toolkit/content/jar.mn 创建 chrome:// URL 后，您应该能够在整个 Firefox 中开始使用它。在大多数情况下，您应该能够依靠自定义元素在第一次使用时延迟加载，前提是您在 customElements.js 可用的特权上下文中工作。

注意自 bug 1896837 以来，延迟加载的 UI 组件在 DOMContentLoaded 事件中加载。如果您看到由于此问题导致的异常情况，请通知可复用组件团队。

您可以通过带有 type="module" 的 script 标签将组件直接导入到 html/xhtml 文件中

<script type="module" src="chrome://global/content/elements/your-component-name.mjs"></script>

注意您需要将您的新组件添加到 customElements.js 中的此数组以确保它在创建时延迟加载。

常见陷阱¶

如果您尝试使用可复用组件但页面上没有显示任何内容，可能是由于以下问题之一导致的

在 script 标签中省略了 type="module"。
导入模块的 src 的文件路径错误。
组件未在正确的 jar.mn 文件中声明或声明错误。
在 xhtml 文件中使用自定义 HTML 元素时未指定 html: 命名空间。例如，标签应如下所示
```
<html:your-component-name></html:your-component-name>
```
向 inc.xhtml 文件添加 script 标签。例如，在 about:preferences 的隐私部分使用新组件时，需要将 script 标签添加到 preferences.xhtml 而不是 privacy.inc.xhtml。
尝试在 Lit 中扩展内置 HTML 元素。由于 Webkit 从未实现对自定义内置的支持，因此 Lit 也不支持它。这意味着如果您想执行以下操作
```
customElements.define("cool-button", CoolButton, { extends: "button" });
```
您需要创建一个普通的自定义元素，不能使用 Lit。有关扩展 HTML 元素的示例，请参阅 moz-support-link。