Skip to content

@astrojs/ lit

v4.3.0 GitHub npm Changelog

此 Astro 整合 为你的 点燃 自定义元素启用服务器端渲染和客户端水合作用。

¥This Astro integration enables server-side rendering and client-side hydration for your Lit custom elements.

安装

Section titled 安装

¥Installation

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

¥Astro includes an astro add command to automate the setup of official integrations. If you prefer, you can install integrations manually instead.

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

¥To install @astrojs/lit, run the following from your project directory and follow the prompts:

Terminal window
npx astro add lit

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

¥If you run into any issues, feel free to report them to us on GitHub and try the manual installation steps below.

手动安装

Section titled 手动安装

¥Manual Install

首先，安装 @astrojs/lit 包：

¥First, install the @astrojs/lit package:

Terminal window
npm install @astrojs/lit

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

¥Most package managers will install associated peer dependencies as well. If you see a “Cannot find package ‘lit’” (or similar) warning when you start up Astro, you’ll need to install lit and @webcomponents/template-shadowroot:

Terminal window
npm install lit @webcomponents/template-shadowroot

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

¥Then, apply the integration to your astro.config.* file using the integrations property:

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


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

入门

Section titled 入门

¥Getting started

要在 Astro 中使用你的第一个 Lit 组件，请前往我们的 UI 框架文档。这解释了：

¥To use your first Lit component in Astro, head to our UI framework documentation. This explains:

  • 📦 如何加载框架组件，

  • 💧 客户端水合选项，以及

  • 🤝 将框架混合和嵌套在一起的机会

在 Astro 中编写和导入 Lit 组件如下所示：

¥Writing and importing a Lit component in Astro looks like this:

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 导入：

¥Now, the component is ready to be imported via the Astro frontmatter:

src/pages/index.astro
---
import { MyElement } from '../components/my-element.js';
---


<MyElement />

实验性装饰器

Section titled 实验性装饰器

¥Experimental Decorators

要使用 Lit 中的实验性装饰器，请将以下内容添加到 tsconfig.json 文件中：

¥To use experimental decorators in Lit, add the following to your tsconfig.json file:

tsconfig.json
{
  "compilerOptions": {
    "experimentalDecorators": true,
  }
}

这允许你使用实验性装饰器（例如 @customElement 和 @state）在 Lit 组件中注册自定义元素并定义状态属性：

¥This allows you to use experimental decorators such as @customElement and @state to register a custom element and define a state property in your Lit component:

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>Hello world! From ${this.name}</p>`;
    }
}

填充物和保湿

Section titled 填充物和保湿

¥Polyfills & Hydration

渲染器自动处理添加适当的 polyfills 以支持没有声明性 Shadow DOM 的浏览器。Polyfill 大约为 1.5kB。如果浏览器确实支持声明式 Shadow DOM，则加载的字节数少于 250 个字节（以检测支持功能）。

¥The renderer automatically handles adding appropriate polyfills for support in browsers that don’t have Declarative Shadow DOM. The polyfill is about 1.5kB. If the browser does support Declarative Shadow DOM then less than 250 bytes are loaded (to feature detect support).

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

¥Hydration is also handled automatically. You can use the same hydration directives such as client:load, client:idle and client:visible as you can with other libraries that Astro supports.

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


<MyElement client:visible />

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

¥The above will only load the element’s JavaScript when the user has scrolled it into view. Since it is server rendered they will not see any jank; it will load and hydrate transparently.

故障排除

Section titled 故障排除

¥Troubleshooting

如需帮助，请查看 Discord 上的 #support 通道。我们友好的支持小队成员随时为你提供帮助！

¥For help, check out the #support channel on Discord. Our friendly Support Squad members are here to help!

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

¥You can also check our Astro Integration Documentation for more on integrations.

常见问题如下：

¥Common issues are listed below:

浏览器全局变量

Section titled 浏览器全局变量

¥Browser globals

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

¥The Lit integration’s SSR works by adding a few browser global properties to the global environment. Some of the properties it adds includes window, document, and location.

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

¥These globals can interfere with other libraries that might use the existence of these variables to detect that they are running in the browser, when they are actually running in the server. This can cause bugs with these libraries.

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

¥Because of this, the Lit integration might not be compatible with these types of libraries. One thing that can help is changing the order of integrations when Lit is interfering with other integrations:

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 集成，则无法使用某些库。

¥The correct order might be different depending on the underlying cause of the problem. This is not guaranteed to fix every issue however, and some libraries cannot be used if you are using the Lit integration because of this.

严格的包管理器

Section titled 严格的包管理器

¥Strict package managers

当使用 严格的包管理器（如 pnpm）时，你可能会在运行网站时收到诸如 ReferenceError: module is not defined 之类的错误。要解决此问题，请使用 .npmrc 文件提升 Lit 依赖：

¥When using a strict package manager like pnpm, you may get an error such as ReferenceError: module is not defined when running your site. To fix this, hoist Lit dependencies with an .npmrc file:

.npmrc
public-hoist-pattern[]=*lit*

局限性

Section titled 局限性

¥Limitations

  • Lit 集成由 @lit-labs/ssr 提供支持，但有一些限制。请参阅他们的 限制文档 以了解更多信息。

  • Astro 不支持 Lit 组件的 IntelliSense。

More integrations

UI Frameworks

SSR Adapters

Other integrations

Astro 中文网 - 粤ICP备13048890号