@astrojs/ partytown

这个 Astro 整合在你的 Astro 项目中启用了 Partytown。

¥This Astro integration enables Partytown in your Astro project.

为什么选择 Astro Partytown

¥Why Astro Partytown

Partytown 是一个延迟加载库，可帮助将资源密集型脚本重新定位到网络工作者中，并从主线程中移出。

¥Partytown is a lazy-loaded library to help relocate resource intensive scripts into a web worker, and off of the main thread.

如果你使用第三方脚本进行分析或广告等操作，Partytown 是确保它们不会降低你网站速度的好方法。

¥If you’re using third-party scripts for things like analytics or ads, Partytown is a great way to make sure that they don’t slow down your site.

Astro Partytown 集成会为你安装 Partytown 并确保它在你的所有页面上启用。

¥The Astro Partytown integration installs Partytown for you and makes sure it’s enabled on all of your pages.

安装

¥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.

在新的终端窗口中运行以下命令之一。

¥Run one of the following commands in a new terminal window.

npx astro add partytown

pnpm astro add partytown

yarn astro add partytown

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

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

手动安装

¥Manual Install

首先，安装 @astrojs/partytown 包：

¥First, install the @astrojs/partytown package:

npm install @astrojs/partytown

pnpm add @astrojs/partytown

yarn add @astrojs/partytown

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

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

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

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

用法

¥Usage

Partytown 应该准备好零配置。如果你的网站上已有第 3 方脚本，请尝试添加 type="text/partytown" 属性：

¥Partytown should be ready to go with zero config. If you have an existing 3rd party script on your site, try adding the type="text/partytown" attribute:

<script type="text/partytown" src="fancy-analytics.js"></script>

如果你从你的浏览器的开发工具打开 “网络” 选项卡，你应该看到 partytown 代理拦截此请求。

¥If you open the “Network” tab from your browser’s dev tools, you should see the partytown proxy intercepting this request.

配置

¥Configuration

要配置此集成，请将 ‘config’ 对象传递给 astro.config.mjs 中的 partytown() 函数调用。

¥To configure this integration, pass a ‘config’ object to the partytown() function call in astro.config.mjs.

export default defineConfig({
  // ...
  integrations: [
    partytown({
      config: {
        // options go here
      },
    }),
  ],
});

这反映了 Partytown 配置对象。

¥This mirrors the Partytown config object.

config.debug

Partytown 附带 debug 模式；通过将 true 或 false 传递给 config.debug 来启用或禁用它。如果启用 debug 模式，则会将详细日志输出到浏览器控制台。

¥Partytown ships with a debug mode; enable or disable it by passing true or false to config.debug. If debug mode is enabled, it will output detailed logs to the browser console.

如果不设置该选项，则在 dev 或 preview 模式下默认开启 debug 模式。

¥If this option isn’t set, debug mode will be on by default in dev or preview mode.

export default defineConfig({
  // ...
  integrations: [
    partytown({
      // Example: Disable debug mode.
      config: { debug: false },
    }),
  ],
});

config.forward

第三方脚本通常会向 window 对象添加变量，以便你可以在整个站点中与它们进行通信。但是，当脚本加载到 Web Worker 中时，它无法访问该全局 window 对象。

¥Third-party scripts typically add variables to the window object so that you can communicate with them throughout your site. But when a script is loaded in a web-worker, it doesn’t have access to that global window object.

为了解决这个问题，Partytown 可以将 “patch” 变量添加到全局窗口对象并将它们转发到适当的脚本。

¥To solve this, Partytown can “patch” variables to the global window object and forward them to the appropriate script.

你可以使用 config.forward 选项指定要转发的变量。请阅读 Partytown 的文档了解更多信息。

¥You can specify which variables to forward with the config.forward option. Read more in Partytown’s documentation.

export default defineConfig({
  // ...
  integrations: [
    partytown({
      // Example: Add dataLayer.push as a forwarding-event.
      config: {
        forward: ['dataLayer.push'],
      },
    }),
  ],
});