注册脚本 · Nuxt 脚本

注册脚本通过简化在 Nuxt 脚本中集成第三方脚本，来提升开发体验。

有关受支持的注册脚本列表，请参阅脚本注册表列表。

特性

😌 安全初始化

许多第三方脚本在加载脚本之前需要初始化一些全局状态，Nuxt 脚本以优化方式为您处理此操作。

🏎️ 精细性能调整

每个注册脚本都经过优化，以尽可能高效的方式加载脚本功能。

📜 全类型化

处理第三方脚本通常意味着自己处理其 API 类型。注册脚本通过提供预定义类型来缓解这种情况，从而在您的项目中启用代码补全和类型安全性。

✅ 验证选项

使用 Valibot，注册脚本会自动验证第三方脚本的配置选项，帮助您及早识别和解决配置错误。例如，它们会检查 Cloudflare Web Analytics 的令牌长度。

export const CloudflareWebAnalyticsOptions = object({
  /**
   * The Cloudflare Web Analytics token.
   */
  token: string([minLength(32)]),
  /**
   * Cloudflare Web Analytics enables measuring SPAs automatically by overriding the History API’s pushState function
   * and listening to the onpopstate. Hash-based router is not supported.
   *
   * @default true
   */
  spa: optional(boolean()),
})

出于性能原因，验证只会发生在开发过程中。它将从您的生产构建中树摇去除。

🤫 运行时配置集成

注册脚本可以通过您的 .env 文件进行配置，允许您提供脚本选项，而无需在您的代码库中硬编码它们。

NUXT_SCRIPTS_CLOUDFLARE_WEB_ANALYTICS=YOUR_TOKEN

用法

在开发中禁用

当您想在开发中使用公开的 API 脚本，比如在组件中调用 gtag 时，您希望加载脚本的模拟版本，这样它就永远不会加载。

您可以通过向注册脚本提供 mock 值来实现这一点。

nuxt.config.ts

export default defineNuxtConfig({
  scripts: {
    registry: {
      googleTagManager: true,
    },
  },
  $development: {
    scripts: {
      registry: {
        googleTagManager: "mock",
      },
    },
  },
})

加载多个相同脚本

您可能有一个设置，您需要使用不同的配置多次加载相同的注册脚本。

默认情况下，它们将被去重并且只加载一次，要加载同一个脚本的多个实例，您可以为该脚本提供一个唯一的 key。

const { gtag, $script } = useScriptGoogleAnalytics({
  id: 'G-TR58L0EF8P',
})

const { gtag: gtag2, $script: $script2 } = useScriptGoogleAnalytics({
  // without a key the first script instance will be returned
  key: 'gtag2',
  id: 'G-1234567890',
})

需要注意的是，当修改键时，您正在使用的任何环境变量都会失效。

例如，使用 gtag2 作为键，您需要提供以下运行时配置

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      scripts: {
        gtag2: {
          id: '', // NUXT_PUBLIC_SCRIPTS_GTAG2_ID
        },
      },
    },
  },
})

使用脚本选项和脚本输入

注册脚本不会阻止您使用核心 useScript 功能，您可以提供额外的选项来选择高级功能。

scriptOptions - 传递给脚本的附加选项。与 useScript 选项相同。
scriptInput - 传递给脚本的附加输入。与 useScript 输入相同。

import { useTimeout } from '@vueuse/core'
import { useScriptCloudflareWebAnalytics } from '#imports'

const { ready } = useTimeout(5000)
useScriptCloudflareWebAnalytics({
  token: '123',
  // HTML attributes to pass to the script element
  scriptInput: {
    'data-cf-test': 'true'
  },
  // useScript options used for advanced features
  scriptOptions: {
    trigger: ready,
    bundle: true,
  },
})

加载最佳实践

当在多个页面或组件中使用注册脚本时，建议您在您的 app.vue 或您的 nuxt.config 中使用所需的选项初始化该脚本。

任何后续对注册脚本的调用都将使用脚本的同一实例，不需要任何选项。

export default defineNuxtConfig({
  scripts: {
    registry: {
      // loads the script
      fathomAnalytics: {
        site: 'SITE_ID',
      }
    }
  }
})

或者，您可以将注册脚本封装在一个可组合项中，以便更容易地实例化该脚本。

export function useFathomAnalytics() {
  return useScriptFathomAnalytics({
    site: 'SITE_ID',
  })
}

关键概念

了解 Nuxt 脚本的关键概念。

触发脚本加载

Nuxt 脚本提供了几种触发脚本加载的方式。