Question

这个 Astro 集成 为你的 Lit 自定义元素提供了服务端渲染和客户端水合。

安装

Astro 包含了一个 astro add 命令，用于自动设置官方集成。如果你愿意，你也可以选择手动安装集成。

要安装 @astrojs/lit，请从项目目录运行以下命令并按照提示操作：

• npm
• pnpm
• Yarn

npx astro add lit

pnpm astro add lit

yarn astro add lit

如果你遇到任何问题，请随时在 GitHub 上向我们报告 并尝试下面的手动安装步骤。

手动安装

首先，安装 @astrojs/lit 包：

• npm
• pnpm
• Yarn

npm install @astrojs/lit

pnpm add @astrojs/lit

yarn add @astrojs/lit

大多数包管理器也会安装相关的对等依赖。如果你在启动 Astro 时看到 “Cannot find package ‘lit’“（或类似）的警告，你需要安装 lit 和 @webcomponents/template-shadowroot：

• npm
• pnpm
• Yarn

npm install lit @webcomponents/template-shadowroot

pnpm add lit @webcomponents/template-shadowroot

yarn add lit @webcomponents/template-shadowroot

然后，使用 integrations 属性将集成应用到你的 astro.config.* 文件中：

astro.config.mjs

import { defineConfig } from 'astro/config';import lit from '@astrojs/lit';


export default defineConfig({
  // ...
  integrations: [lit()],
});

入门

要在 Astro 中使用你的第一个 Lit 组件，你可以移步我们的 UI 框架文档。你将会了解到：

• 如何加载框架组件
• 客户端水合选项
• 混合和嵌套框架的机会

在 Astro 中编写和导入 Lit 组件的代码如下：

src/components/my-element.js

import { LitElement, html } from 'lit';


export class MyElement extends LitElement {
  render() {
    return html`<p>Hello world! From my-element</p>`;
  }
}


customElements.define('my-element', MyElement);

现在，该组件已经准备好通过 Astro frontmatter 导入：

src/pages/index.astro

---
import { MyElement } from '../components/my-element.js';
---


<MyElement />

注意

Lit 需要浏览器全局变量，如 HTMLElement 和 customElements。因此，Lit 渲染器会在服务器上模拟这些全局变量，以便 Lit 可以运行。你 可能 会遇到一些因此而无法正常工作的库。

Experimental Decorators

要在 Lit 中使用 experimental decorators，请在你的 tsconfig.json 文件中添加以下内容：

tsconfig.json

{
  "compilerOptions": {    "experimentalDecorators": true,
  }
}

这使你可以使用如 @customElement 和 @state 这样的 experimental decorators 来注册自定义元素并在你的 Lit 组件中定义状态属性：

src/components/my-element.ts

import { LitElement, html } from "lit";
import { customElement, state } from "lit/decorators.js";


@customElement("my-element")
export class MyElement extends LitElement {
    @state() name = "my-element";


    override render() {
        return html`<p>你好世界！来自 ${this.name}</p>`;
    }
}

Polyfills 与水合

渲染器会自动处理为不支持 Declarative Shadow DOM 的浏览器添加适当的 polyfill。polyfill 大约为 1.5kB。如果浏览器支持 Declarative Shadow DOM，则加载的字节数少于 250 字节（用于检测支持）。

水合也是自动处理的。你可以使用与 Astro 支持的其他库相同的水合指令，例如 client:load、client:idle 和 client:visible。

---
import { MyElement } from '../components/my-element.js';
---


<MyElement client:visible />

上面的代码将只在用户滚动到视图中时加载元素的 JavaScript。由于它是服务器渲染的，用户将看不到任何卡顿；它将透明地加载和水合。

故障排除

如需帮助，请查看 Discord 上的 #support 频道。我们友好的支持小组成员将在此处提供帮助！

你也可以查看我们的 Astro 集成文档 了解更多信息。

常见问题如下：

浏览器全局变量

Lit 集成的 SSR 通过向全局环境添加一些浏览器全局属性来工作。它添加的一些属性包括 window、document 和 location。

这些全局变量 可能 会干扰其他可能使用这些变量的库，以检测它们是否在浏览器中运行，而实际上它们是在服务器中运行的。这可能会导致这些库出现错误。

因此，Lit 集成可能与这些类型的库不兼容。可以帮助的一件事是在 Lit 干扰其他集成时更改集成的顺序：

astro.config.mjs

  import { defineConfig } from 'astro/config';
  import vue from '@astrojs/vue';
  import lit from '@astrojs/lit';


  export default defineConfig({    integrations: [vue(), lit()]    integrations: [lit(), vue()]
  });

正确的顺序可能因问题的根本原因而有所不同。但是，这并不能保证解决每个问题，而且由于这个原因，一些库不能在使用 Lit 集成时使用。

严格的包管理器

当使用像 pnpm 这样的 严格的包管理器 时，你可能会遇到错误，例如 ReferenceError: module is not defined。要解决这个问题，请使用 .npmrc 文件提升 Lit 依赖项：

.npmrc

public-hoist-pattern[]=*lit*

限制

• Lit 集成由 @lit-labs/ssr 提供支持，该集成存在一些限制。请查看他们的 限制文档 了解更多信息。

• Astro 不支持 Lit 组件的 IntelliSense 功能。

更多集成

UI 框架

• 

  @astrojs/alpinejs

• 

  @astrojs/lit

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

SSR 适配器

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

其他集成

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap

• 

  @astrojs/tailwind

Recipes