开发

在项目的开发阶段，当你在编写 Lit 组件时，以下工具可以帮助提高你的生产力：

• 开发服务器，用于在不需要构建步骤的情况下预览代码。
• TypeScript，用于编写类型检查的代码。
• 代码检查器，用于捕获 JavaScript 错误。
• 代码格式化工具，用于一致地格式化代码。
• Lit 特定的 IDE 插件，用于对 Lit 模板进行代码检查和语法高亮。

查看 入门套件 文档，轻松设置一个预配置了所有这些功能的开发环境。

所有的 Lit 包都发布了开发和生产构建版本，使用 Node 的 导出条件 支持。

生产构建使用非常激进的压缩设置进行了优化。开发构建未经压缩，便于调试，并包含额外的检查和警告。默认构建是生产构建，这样项目就不会意外部署较大的开发构建版本。

你必须在支持导出条件的工具（如 Rollup、Webpack 和 Web Dev Server）中指定 "development" 导出条件来选择开发构建。每个工具的设置方式都不同。

例如，在 Rollup 中，使用 @rollup/node-resolve 插件，你可以通过 exportConditions 选项选择开发构建：

import { nodeResolve } from '@rollup/plugin-node-resolve';

export default {
  // ...
  plugins: [nodeResolve({
    exportConditions: ['development']
  })]
};

ReactiveElement 和 LitElement 的开发构建支持额外的运行时警告，这些警告可以帮助识别在生产构建中检查成本较高的问题。

某些警告始终显示。还有两类可以打开或关闭的_可选警告_：

• migration：与从 LitElement 2.x 迁移相关的警告。默认关闭。
• change-in-update：与在更新期间更改响应式状态相关的警告。默认开启。

你可以使用 ReactiveElement.disableWarning() 和 ReactiveElement.enableWarning() 方法控制可选警告。你可以在 ReactiveElement 的任何子类上调用它们，包括 LitElement 和你自己的类。在给定类上调用这些方法会打开或关闭该类及其任何子类的警告。例如，你可以在所有 ReactiveElement 类、所有 LitElement 类或特定的 LitElement 子类上关闭某个类别的警告。

这些方法仅在开发构建中可用，所以请确保使用可选链来保护它们的访问。我们建议使用可选链。

示例：

import {LitElement, ReactiveElement} from 'lit';

// 在所有 ReactiveElements 上关闭迁移警告，
// 包括 LitElements
ReactiveElement.disableWarning?.('migration');

// 在所有 LitElements 上关闭更新警告
LitElement.disableWarning?.('change-in-update');

// 在一个元素上关闭更新警告
MyElement.disableWarning?.('change-in-update');

你也可以通过定义 static enabledWarnings 属性来控制单个类中的警告：

class MyElement extends LitElement {
  static enabledWarnings = ['migration'];
}

最好在你自己的生产构建中消除控制警告的代码，以优化代码大小。

当检测到任何 Lit 核心包（lit-html、lit-element、@lit/reactive-element）的多个版本，或者甚至同一版本的多个副本时，会触发仅在开发模式下的警告。

如果 Lit 作为元素的内部依赖项使用，元素可以使用不同版本的 Lit，并且完全可以互操作。 我们也注意确保 Lit 2 和 Lit 3 大体上相互兼容。例如，你可以将 Lit 2 模板传递给 Lit 3 渲染函数，反之亦然。

那么，为什么会有警告呢？Lit 有时会被与那些在混合使用不同版本组件时经常会出现问题的框架进行比较。因此，很容易在不知不觉中安装了多个重复的 Lit 版本。

加载多个兼容的 Lit 版本并不理想，因为需要向用户发送额外的重复字节。

如果你正在发布使用 Lit 的库，请遵循我们的发布最佳实践，这样你的库的使用者就能在他们的项目中去重 Lit。

解决多个 Lit 版本问题

可能会出现按照以下步骤操作后仍然无法去重 Lit 的情况，例如，你依赖的某个库捆绑了特定版本的 Lit。在这些情况下，可以忽略该警告。

如果你看到 Multiple versions of Lit loaded（加载了多个 Lit 版本）的开发模式警告，可以尝试以下几种方法：

1. 通过在浏览器控制台中检查以下变量来找出哪些 Lit 库加载了多个版本：window.litElementVersions、window.reactiveElementVersions 和 window.litHtmlVersions。

2. 使用 npm ls（注意，你可以指定要查找的确切库，例如 npm ls @lit/reactive-element）来缩小范围，找出哪些依赖项正在加载多个不同版本的 Lit。

3. 尝试使用 npm dedupe 来去重 Lit。使用 npm ls 验证重复的 Lit 包是否成功去重。

4. 可以通过将核心 Lit 包安装为项目的直接依赖项来引导 npm 提升特定版本，使用 npm i @lit/reactive-element@latest lit-element@latest lit-html@latest。将 latest 替换为你想要去重到的版本。

5. 如果仍然存在重复，你可能需要删除你的包锁定文件和 node_modules。然后先安装你想要的 lit 版本，再安装你的依赖项。

Lit 以 JavaScript 模块的形式打包，并且使用了大多数浏览器尚不支持的裸模块说明符。裸说明符被广泛使用，你可能也想在自己的代码中使用它们。例如：

import {LitElement, html, css} from 'lit';

要在浏览器中运行此代码，需要将裸说明符（'lit'）转换为浏览器可以加载的 URL（如 '/node_modules/lit/lit.js'）。

有许多开发服务器可以处理模块说明符。如果你已经有一个可以处理这个问题并与你的构建过程集成的开发服务器，那就足够了。

如果你需要一个开发服务器，我们推荐使用 Web Dev Server。

Web Dev Server 是一个开源的开发服务器，可以实现无构建的开发过程。

它可以处理将裸模块说明符重写为浏览器所需的有效 URL。

安装 Web Dev Server：

npm i @web/dev-server --save-dev

在你的 package.json 文件中添加一个命令：

"scripts": {
  "start": "web-dev-server"
}

以及一个 web-dev-server.config.js 文件：

export default {
  open: true,
  watch: true,
  appIndex: 'index.html',
  nodeResolve: {
    exportConditions: ['development'],
  },
};

运行开发服务器：

npm run start

对于像 IE11 这样的旧版浏览器，Web Dev Server 可以将 JavaScript 模块转换为向后兼容的 SystemJS 模块加载器，并自动提供 web components polyfills。你需要配置 @web/dev-server-legacy 包来支持旧版浏览器。

安装 Web Dev Server legacy 包：

npm i @web/dev-server-legacy --save-dev

配置 web-dev-server.config.js：

import { legacyPlugin } from '@web/dev-server-legacy';

export default {
  // ...
  plugins: [
    // 确保这个插件始终是最后一个
    legacyPlugin({
      polyfills: {
        webcomponents: true,
        // 在测试文件中注入 lit 的 polyfill-support 模块，这是与
        // webcomponents polyfills 交互所必需的
        custom: [
          {
            name: 'lit-polyfill-support',
            path: 'node_modules/lit/polyfill-support.js',
            test: "!('attachShadow' in Element.prototype)",
            module: false,
          },
        ],
      },
    }),
  ],
};

Lit 支持使用 TypeScript 开发组件，包括 Lit API 的完整类型声明、标准和实验性装饰器，以及用于模板类型检查和代码检查的社区工具。

因为 Lit 只是一个库，不需要编译器或使用非标准的语言语法，所以没有特定的必需 TypeScript 工具。Lit 可以与官方的 TypeScript 编译器 tsc 一起使用，也可以与 Rollup、Vite 或 Webpack 的 TypeScript 包装器，以及像 esbuild 这样的替代编译器一起使用。

TypeScript 项目的主要要求是：

• 启用现代 JavaScript 语言级别，比如使用 "ES2021" lib。
• 通过 "DOM" lib 启用 DOM 类型。
• 如果你选择使用 TypeScript 的实验性装饰器，可以选择启用实验性装饰器和禁用类字段的 "define" 语义。

这些选项通常在你项目的 tsconfig 中设置。

要在你的项目中安装 TypeScript：

npm i -D typescript

要构建代码：

npx tsc --watch

完整的安装和使用说明，请参见 TypeScript 网站。入门时，安装 TypeScript 和使用其功能 这两个章节特别有帮助。

TypeScript 支持两个版本的装饰器：实验性和标准。更多信息请参见我们的装饰器文档。

代码检查可以帮助捕获代码中的错误。我们推荐使用 ESLint 来检查 Lit 代码。

要在你的项目中安装 ESLint：

npm install eslint --save-dev
npx eslint --init

要运行它：

npx eslint yourfile.js

或者将它添加到你的 npm 脚本中：

{
  "scripts": {
    "lint": "eslint \"**/*.{js,ts}\"",
  }
}

完整的安装和使用说明，请参见 ESLint 文档。

我们还推荐使用 ESLint 的 eslint-plugin-lit，它为 Lit 的 HTML 模板提供代码检查，包括常见的 HTML 检查以及 Lit 特定的规则。

将代码检查集成到你的 IDE 工作流程中可以帮助尽早捕获错误。请参见 Lit 特定的 IDE 插件 来为 Lit 配置你的 IDE。

使用代码格式化工具可以帮助确保代码的一致性和可读性。将你选择的格式化工具与 IDE 集成可以确保你的代码始终整洁有序。

一些流行的选项包括：

• Prettier：VS Code 插件
• Beautifier：VS Code 插件
• Clang：VS Code 插件

在使用 Lit 开发时，有许多 IDE 插件可能会有用。特别是，我们推荐使用适用于 Lit 模板的语法高亮器。

lit-plugin 为 Lit 模板提供语法高亮、类型检查等功能。它可用于 VS Code，或者你可以使用 ts-lit-plugin TypeScript 编译器插件，它适用于 Sublime Text 和 Atom。

lit-plugin 和 ts-lit-plugin 提供：

• 语法高亮
• 类型检查
• 代码补全
• 悬停文档
• 跳转到定义
• 代码检查
• 快速修复

ESLint 有多个代码编辑器的集成。如果你在 ESLint 配置中安装了 ESLint 的 eslint-plugin-lit，你的 IDE 将显示 Lit 特定的错误和警告。

查看 awesome-lit-html 仓库了解其他 IDE 插件，以及其他工具和信息。