@jctrans-materials/nuxt 1.0.37-beta.5 → 1.0.37-beta.7

package/README.md

@@ -1,75 +1,128 @@
-# Nuxt Minimal Starter
+# @jctrans-materials/nuxt
 
-Look at the [Nuxt documentation](https://nuxt.com/docs/getting-started/introduction) to learn more.
+Nuxt 3 模块，自动注册 `@jctrans-materials/comps-vue3` 组件，并内置埋点初始化插件与事件上报指令。
 
-## Setup
-
-Make sure to install dependencies:
+## 安装
 
 ```bash
-# npm
-npm install
-
-# pnpm
-pnpm install
-
-# yarn
-yarn install
-
-# bun
-bun install
+pnpm add @jctrans-materials/nuxt @jctrans-materials/comps-vue3 @jctrans-materials/shared gio-webjs-sdk
 ```
 
-## Development Server
+## Nuxt 配置
+
+```ts
+export default defineNuxtConfig({
+  modules: ["@jctrans-materials/nuxt"],
+  jctrans: {
+    sharedConfig: {
+      appId: "ERA",
+      prefixPath: "https://api.example.com",
+    },
+    tracking: {
+      enabled: true,
+      autoInit: true,
+      directiveName: "gio-track",
+      globalVarName: "__JCTRANS_GIO_CONFIG__",
+      accountId: "your-account-id",
+      dataSourceId: "your-data-source-id",
+      appId: "your-gio-app-id",
+      initOptions: {
+        debug: false,
+        trackPage: false,
+        autoTrackPage: true,
+      },
+    },
+  },
+});
+```
 
-Start the development server on `http://localhost:3000`:
+## 环境变量与全局变量
+
+模块会在 client 插件内自动按优先级读取配置：
+
+1. `window[globalVarName]`（默认 `window.__JCTRANS_GIO_CONFIG__`）
+2. `window.__GIO_CONFIG__`
+3. `runtimeConfig.public.jctrans.tracking`
+4. `runtimeConfig.public.GIO_ACCOUNT_ID` / `runtimeConfig.public.GIO_DATA_SOURCE_ID` / `runtimeConfig.public.GIO_APP_ID`
+5. `import.meta.env.VITE_GIO_ACCOUNT_ID` / `import.meta.env.VITE_GIO_DATA_SOURCE_ID` / `import.meta.env.VITE_GIO_APP_ID`
+
+例如在 HTML 模板注入：
+
+```html
+<script>
+  window.__JCTRANS_GIO_CONFIG__ = {
+    accountId: "your-account-id",
+    dataSourceId: "your-data-source-id",
+    appId: "your-gio-app-id",
+    directiveName: "gio-track",
+    initOptions: {
+      debug: false,
+      trackPage: false,
+      autoTrackPage: true,
+    },
+  };
+</script>
+```
 
-```bash
-# npm
-npm run dev
+## 事件上报指令
 
-# pnpm
-pnpm dev
+默认注册全局指令 `v-gio-track`（可通过 `tracking.directiveName` 修改）。
 
-# yarn
-yarn dev
+字符串写法：
 
-# bun
-bun run dev
+```vue
+<button v-gio-track="'login_click'">登录</button>
 ```
 
-## Production
+对象写法：
+
+```vue
+<button
+  v-gio-track="{
+    event: 'order_submit',
+    trigger: 'click',
+    attrs: { source: 'home', type: 'sea' },
+    once: true,
+    stop: true,
+    prevent: false,
+    onTracked: ({ eventName }) => {
+      console.log('tracked:', eventName);
+    },
+  }"
+>
+	提交
+</button>
+```
 
-Build the application for production:
+支持回调字段：`onTracked`（推荐）和 `callback`（兼容）。回调会在 `gio.track` 完成回调后触发。
 
-```bash
-# npm
-npm run build
+## 注入能力
 
-# pnpm
-pnpm build
+模块会自动注入：
 
-# yarn
-yarn build
+- `$gio`：`tracker` 实例
+- `$trackEvent(eventName, attrs?)`：手动上报方法
 
-# bun
-bun run build
-```
+`script setup` 使用示例：
 
-Locally preview production build:
+```ts
+const { $trackEvent, $gio } = useNuxtApp();
 
-```bash
-# npm
-npm run preview
+const handleClick = () => {
+  $trackEvent("search_click", { tab: "air" });
+  $gio.setGeneralProps({ app: "nuxt3" });
+};
+```
 
-# pnpm
-pnpm preview
+## 说明
 
-# yarn
-yarn preview
+- 埋点初始化与指令注册都在 `client` 插件执行，不影响 SSR。
+- 当 `tracking.enabled = false` 时，指令与上报函数会退化为空实现。
+- 当缺少 `accountId` 或 `dataSourceId` 时，会跳过自动初始化，但指令和 `$trackEvent` 仍可用。
 
-# bun
-bun run preview
-```
+## 类型注意事项（重要）
 
-Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information.
+- `plugin.client.ts` 内保持从 `@jctrans-materials/shared` 直接引入 `tracker`。
+- 但在 Nuxt `provide` 和 `types.d.ts` 中，不要直接使用 `typeof tracker` 作为 `$gio` 类型。
+- 原因：`tracker` 基于 class，直接暴露具体实例类型在声明生成阶段可能触发 `TS4094`（私有成员泄漏）。
+- 规范做法：使用 `GioPublicApi` 这类公共接口作为对外类型契约。

package/dist/module.cjs

@@ -14,7 +14,18 @@ const module$1 = kit.defineNuxtModule({
   },
   defaults: {
     addStyle: true,
-    sharedConfig: {}
+    sharedConfig: {},
+    tracking: {
+      enabled: true,
+      autoInit: true,
+      directiveName: "gio-track",
+      globalVarName: "__JCTRANS_GIO_CONFIG__",
+      initOptions: {
+        debug: false,
+        trackPage: false,
+        autoTrackPage: false
+      }
+    }
   },
   async setup(options, nuxt) {
     const { resolve } = kit.createResolver((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('module.cjs', document.baseURI).href)));
@@ -22,7 +33,8 @@ const module$1 = kit.defineNuxtModule({
     nuxt.options.runtimeConfig.public.jctrans = defu.defu(
       nuxt.options.runtimeConfig.public.jctrans,
       {
-        sharedConfig: options.sharedConfig
+        sharedConfig: options.sharedConfig,
+        tracking: options.tracking
       }
     );
     if (options.addStyle) {
@@ -56,6 +68,10 @@ const module$1 = kit.defineNuxtModule({
       src: resolve("./runtime/plugin"),
       mode: "all"
     });
+    kit.addPlugin({
+      src: resolve("./runtime/plugin.client"),
+      mode: "client"
+    });
     kit.addTypeTemplate({
       filename: "types/jctrans-materials-nuxt.d.ts",
       // 生成在宿主 .nuxt/types 下的文件名，不重名即可

package/dist/module.d.cts

@@ -1,9 +1,29 @@
 import * as _nuxt_schema from '@nuxt/schema';
 import { SharedConfig } from '@jctrans-materials/comps-vue3';
 
+interface TrackingInitOptions {
+    debug?: boolean;
+    serverUrl?: string;
+    trackPage?: boolean;
+    forceLogin?: boolean;
+    idMapping?: boolean;
+    hashtag?: boolean;
+    autoTrackPage?: boolean;
+}
+interface TrackingOptions {
+    enabled?: boolean;
+    autoInit?: boolean;
+    directiveName?: string;
+    globalVarName?: string;
+    accountId?: string;
+    dataSourceId?: string;
+    appId?: string;
+    initOptions?: TrackingInitOptions;
+}
 interface ModuleOptions {
     addStyle?: boolean;
     sharedConfig?: Partial<SharedConfig>;
+    tracking?: TrackingOptions;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
@@ -11,10 +31,11 @@ declare module "@nuxt/schema" {
     interface PublicRuntimeConfig {
         jctrans?: {
             sharedConfig?: Partial<SharedConfig>;
-            appId: string;
+            appId?: string;
+            tracking?: TrackingOptions;
         };
     }
 }
 
 export = _default;
-export type { ModuleOptions };
+export type { ModuleOptions, TrackingInitOptions, TrackingOptions };

package/dist/module.d.mts

@@ -1,9 +1,29 @@
 import * as _nuxt_schema from '@nuxt/schema';
 import { SharedConfig } from '@jctrans-materials/comps-vue3';
 
+interface TrackingInitOptions {
+    debug?: boolean;
+    serverUrl?: string;
+    trackPage?: boolean;
+    forceLogin?: boolean;
+    idMapping?: boolean;
+    hashtag?: boolean;
+    autoTrackPage?: boolean;
+}
+interface TrackingOptions {
+    enabled?: boolean;
+    autoInit?: boolean;
+    directiveName?: string;
+    globalVarName?: string;
+    accountId?: string;
+    dataSourceId?: string;
+    appId?: string;
+    initOptions?: TrackingInitOptions;
+}
 interface ModuleOptions {
     addStyle?: boolean;
     sharedConfig?: Partial<SharedConfig>;
+    tracking?: TrackingOptions;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
@@ -11,10 +31,11 @@ declare module "@nuxt/schema" {
     interface PublicRuntimeConfig {
         jctrans?: {
             sharedConfig?: Partial<SharedConfig>;
-            appId: string;
+            appId?: string;
+            tracking?: TrackingOptions;
         };
     }
 }
 
 export { _default as default };
-export type { ModuleOptions };
+export type { ModuleOptions, TrackingInitOptions, TrackingOptions };

package/dist/module.d.ts

@@ -1,9 +1,29 @@
 import * as _nuxt_schema from '@nuxt/schema';
 import { SharedConfig } from '@jctrans-materials/comps-vue3';
 
+interface TrackingInitOptions {
+    debug?: boolean;
+    serverUrl?: string;
+    trackPage?: boolean;
+    forceLogin?: boolean;
+    idMapping?: boolean;
+    hashtag?: boolean;
+    autoTrackPage?: boolean;
+}
+interface TrackingOptions {
+    enabled?: boolean;
+    autoInit?: boolean;
+    directiveName?: string;
+    globalVarName?: string;
+    accountId?: string;
+    dataSourceId?: string;
+    appId?: string;
+    initOptions?: TrackingInitOptions;
+}
 interface ModuleOptions {
     addStyle?: boolean;
     sharedConfig?: Partial<SharedConfig>;
+    tracking?: TrackingOptions;
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 
@@ -11,10 +31,11 @@ declare module "@nuxt/schema" {
     interface PublicRuntimeConfig {
         jctrans?: {
             sharedConfig?: Partial<SharedConfig>;
-            appId: string;
+            appId?: string;
+            tracking?: TrackingOptions;
         };
     }
 }
 
 export = _default;
-export type { ModuleOptions };
+export type { ModuleOptions, TrackingInitOptions, TrackingOptions };

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": "^3.0.0"
   },
-  "version": "1.0.37-beta.5",
+  "version": "1.0.37-beta.7",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -11,7 +11,18 @@ const module$1 = defineNuxtModule({
   },
   defaults: {
     addStyle: true,
-    sharedConfig: {}
+    sharedConfig: {},
+    tracking: {
+      enabled: true,
+      autoInit: true,
+      directiveName: "gio-track",
+      globalVarName: "__JCTRANS_GIO_CONFIG__",
+      initOptions: {
+        debug: false,
+        trackPage: false,
+        autoTrackPage: false
+      }
+    }
   },
   async setup(options, nuxt) {
     const { resolve } = createResolver(import.meta.url);
@@ -19,7 +30,8 @@ const module$1 = defineNuxtModule({
     nuxt.options.runtimeConfig.public.jctrans = defu(
       nuxt.options.runtimeConfig.public.jctrans,
       {
-        sharedConfig: options.sharedConfig
+        sharedConfig: options.sharedConfig,
+        tracking: options.tracking
       }
     );
     if (options.addStyle) {
@@ -53,6 +65,10 @@ const module$1 = defineNuxtModule({
       src: resolve("./runtime/plugin"),
       mode: "all"
     });
+    addPlugin({
+      src: resolve("./runtime/plugin.client"),
+      mode: "client"
+    });
     addTypeTemplate({
       filename: "types/jctrans-materials-nuxt.d.ts",
       // 生成在宿主 .nuxt/types 下的文件名，不重名即可

package/dist/runtime/plugin.client.d.ts

@@ -0,0 +1,18 @@
+type TrackAttrs = Record<string, string | number | Array<string | number>>;
+type GioPublicApi = {
+    isInitialized: () => boolean;
+    isBrowser: () => boolean;
+    init: (...args: any[]) => void;
+    track: (eventName: string, attrs?: TrackAttrs, callback?: () => void) => void;
+    setGeneralProps: (props: Record<string, any>) => void;
+    setPageAttributes: (props: Record<string, any>) => void;
+    sendPage: () => void;
+};
+declare const _default: import("#app").Plugin<{
+    gio: GioPublicApi;
+    trackEvent: (eventName: string, attrs?: TrackAttrs) => void;
+}> & import("#app").ObjectPlugin<{
+    gio: GioPublicApi;
+    trackEvent: (eventName: string, attrs?: TrackAttrs) => void;
+}>;
+export default _default;

package/dist/runtime/plugin.client.js

@@ -0,0 +1,223 @@
+import { defineNuxtPlugin, useRuntimeConfig, useRouter } from "#app";
+import { tracker } from "@jctrans-materials/shared";
+import { nextTick } from "vue";
+const pickString = (...values) => {
+  for (const value of values) {
+    if (typeof value === "string") {
+      const trimmed = value.trim();
+      if (trimmed) return trimmed;
+    }
+  }
+  return "";
+};
+const pickBoolean = (...values) => {
+  for (const value of values) {
+    if (typeof value === "boolean") return value;
+    if (typeof value === "string") {
+      const normalized = value.trim().toLowerCase();
+      if (normalized === "true") return true;
+      if (normalized === "false") return false;
+    }
+  }
+  return void 0;
+};
+const getGlobalTrackingConfig = (globalVarName) => {
+  if (typeof window === "undefined") return {};
+  const currentWindow = window;
+  const fromCustom = currentWindow?.[globalVarName];
+  const fromJctrans = currentWindow?.__JCTRANS_GIO_CONFIG__;
+  const fromDefault = currentWindow?.__GIO_CONFIG__;
+  const finalConfig = fromCustom || fromJctrans || fromDefault;
+  if (finalConfig && typeof finalConfig === "object") {
+    return finalConfig;
+  }
+  return {};
+};
+const normalizeDirectiveName = (value) => {
+  const raw = pickString(value);
+  const name = raw || "gio-track";
+  return name.replace(/^v-/, "");
+};
+const normalizeBinding = (binding) => {
+  const value = binding.value;
+  if (typeof value === "string") {
+    const eventName2 = value.trim();
+    return {
+      eventName: eventName2,
+      trigger: "click",
+      attrs: {},
+      once: false,
+      stop: false,
+      prevent: false
+    };
+  }
+  if (!value || typeof value !== "object") {
+    return {
+      eventName: "",
+      trigger: "click",
+      attrs: {},
+      once: false,
+      stop: false,
+      prevent: false
+    };
+  }
+  const eventName = pickString(value.event, value.name, binding.arg);
+  const trigger = pickString(value.trigger) || "click";
+  const attrs = value.attributes || value.attrs || {};
+  return {
+    eventName,
+    trigger,
+    attrs,
+    once: Boolean(value.once),
+    stop: Boolean(value.stop),
+    prevent: Boolean(value.prevent),
+    callback: typeof value.onTracked === "function" ? value.onTracked : typeof value.callback === "function" ? value.callback : void 0
+  };
+};
+const removeElementHandler = (element) => {
+  const bound = element.__jctransTrackHandler__;
+  if (!bound) return;
+  element.removeEventListener(bound.trigger, bound.handler);
+  delete element.__jctransTrackHandler__;
+};
+const bindTrackHandler = (element, binding, gio) => {
+  removeElementHandler(element);
+  const normalized = normalizeBinding(binding);
+  if (!normalized.eventName) return;
+  const handler = (event) => {
+    if (normalized.prevent && "preventDefault" in event) {
+      event.preventDefault();
+    }
+    if (normalized.stop && "stopPropagation" in event) {
+      event.stopPropagation();
+    }
+    gio.track(normalized.eventName, normalized.attrs, () => {
+      normalized.callback?.({
+        event,
+        eventName: normalized.eventName,
+        attrs: normalized.attrs,
+        trigger: normalized.trigger
+      });
+    });
+    if (normalized.once) {
+      removeElementHandler(element);
+    }
+  };
+  element.addEventListener(normalized.trigger, handler);
+  element.__jctransTrackHandler__ = {
+    eventName: normalized.eventName,
+    trigger: normalized.trigger,
+    handler
+  };
+};
+export default defineNuxtPlugin((nuxtApp) => {
+  const runtimeConfig = useRuntimeConfig();
+  const router = useRouter();
+  const gio = tracker;
+  const runtimeTracking = runtimeConfig.public?.jctrans?.tracking || {};
+  const globalVarName = pickString(
+    runtimeTracking.globalVarName,
+    "__JCTRANS_GIO_CONFIG__"
+  );
+  const globalTracking = getGlobalTrackingConfig(globalVarName);
+  const metaEnv = import.meta.env || {};
+  const enabled = pickBoolean(runtimeTracking.enabled, globalTracking.enabled);
+  if (enabled === false) {
+    return {
+      provide: {
+        gio,
+        trackEvent: () => {
+        }
+      }
+    };
+  }
+  const initOptions = {
+    ...runtimeTracking.initOptions || {},
+    ...globalTracking.initOptions || {}
+  };
+  if (!initOptions.serverUrl) {
+    const serverUrl = pickString(
+      runtimeConfig.public?.GIO_SERVER_URL,
+      runtimeConfig.public?.gioServerUrl,
+      globalTracking?.serverUrl,
+      runtimeTracking?.serverUrl
+    );
+    if (serverUrl) {
+      initOptions.serverUrl = serverUrl;
+    }
+  }
+  const accountId = pickString(
+    globalTracking.accountId,
+    runtimeTracking.accountId,
+    runtimeConfig.public?.gioAccountId,
+    runtimeConfig.public?.GIO_ACCOUNT_ID,
+    metaEnv.VITE_GIO_ACCOUNT_ID
+  );
+  const dataSourceId = pickString(
+    globalTracking.dataSourceId,
+    runtimeTracking.dataSourceId,
+    runtimeConfig.public?.gioDataSourceId,
+    runtimeConfig.public?.GIO_DATA_SOURCE_ID,
+    metaEnv.VITE_GIO_DATA_SOURCE_ID
+  );
+  const appId = pickString(
+    globalTracking.appId,
+    runtimeTracking.appId,
+    runtimeConfig.public?.gioAppId,
+    runtimeConfig.public?.GIO_APP_ID,
+    metaEnv.VITE_GIO_APP_ID
+  );
+  const autoInit = pickBoolean(
+    runtimeTracking.autoInit,
+    globalTracking.autoInit
+  );
+  if ((autoInit ?? true) && accountId && dataSourceId && !gio.isInitialized()) {
+    if (appId) {
+      gio.init(accountId, dataSourceId, appId, initOptions);
+    } else {
+      gio.init(accountId, dataSourceId, initOptions);
+    }
+  }
+  const trackEvent = (eventName, attrs) => {
+    const normalizedEvent = pickString(eventName);
+    if (!normalizedEvent) return;
+    gio.track(normalizedEvent, attrs || {});
+  };
+  const directiveName = normalizeDirectiveName(
+    globalTracking.directiveName || runtimeTracking.directiveName
+  );
+  const trackDirective = {
+    mounted(element, binding) {
+      bindTrackHandler(element, binding, gio);
+    },
+    updated(element, binding) {
+      if (JSON.stringify(binding.value) !== JSON.stringify(binding.oldValue)) {
+        bindTrackHandler(element, binding, gio);
+      }
+    },
+    beforeUnmount(element) {
+      removeElementHandler(element);
+    }
+  };
+  nuxtApp.vueApp.directive(directiveName, trackDirective);
+  if (initOptions.trackPage === false && initOptions.autoTrackPage) {
+    if (import.meta.client) {
+      router.afterEach((to) => {
+        setTimeout(async () => {
+          await nextTick();
+          gio.setPageAttributes({
+            route_name: String(to.name || ""),
+            route_path: to.path
+          });
+          gio.sendPage();
+        }, 50);
+      });
+    }
+  }
+  return {
+    provide: {
+      gio,
+      trackEvent
+    }
+  };
+});

package/dist/runtime/types.d.ts

@@ -1,15 +1,41 @@
 // src/runtime/types.d.ts
 import { initSharedConfig } from "@jctrans-materials/comps-vue3";
 
+type TrackAttrs = Record<string, string | number | Array<string | number>>;
+
+// ⚠️ 不要使用 `typeof tracker` 作为 `$gio` 类型。
+// `tracker` 是 class 实例，直接导出具体类型会在声明生成时触发 TS4094。
+// 这里定义公共接口类型，既能保留调用提示，也能避免私有字段泄漏。
+type GioPublicApi = {
+  isInitialized: () => boolean;
+  isBrowser: () => boolean;
+  init: (...args: any[]) => void;
+  track: (eventName: string, attrs?: TrackAttrs, callback?: () => void) => void;
+  setGeneralProps: (props: Record<string, any>) => void;
+  setPageAttributes: (props: Record<string, any>) => void;
+  sendPage: () => void;
+};
+
 declare module "#app" {
   interface NuxtApp {
     $initAuthSharedConfig: typeof initSharedConfig;
+    $gio: GioPublicApi;
+    $trackEvent: (eventName: string, attrs?: TrackAttrs) => void;
   }
 }
 
 declare module "vue" {
   interface ComponentCustomProperties {
     $initAuthSharedConfig: typeof initSharedConfig;
+    $gio: GioPublicApi;
+    $trackEvent: (eventName: string, attrs?: TrackAttrs) => void;
+  }
+}
+
+declare global {
+  interface Window {
+    __JCTRANS_GIO_CONFIG__?: Record<string, unknown>;
+    __GIO_CONFIG__?: Record<string, unknown>;
   }
 }
 

package/dist/types.d.mts

@@ -1,3 +1,3 @@
 export { default } from './module.mjs'
 
-export { type ModuleOptions } from './module.mjs'
+export { type ModuleOptions, type TrackingInitOptions, type TrackingOptions } from './module.mjs'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jctrans-materials/nuxt",
   "type": "module",
-  "version": "1.0.37-beta.5",
+  "version": "1.0.37-beta.7",
   "description": "Nuxt module for JCtrans UI components",
   "exports": {
     ".": {
@@ -22,11 +22,13 @@
     "nuxt": "^3.0.0",
     "vue": "^3.5.26",
     "vue-router": "^4.6.4",
-    "@jctrans-materials/comps-vue3": "1.0.37-beta.5"
+    "@jctrans-materials/comps-vue3": "1.0.37-beta.7",
+    "@jctrans-materials/shared": "1.0.37-beta.7"
   },
   "peerDependencies": {
     "nuxt": "^3.0.0",
-    "@jctrans-materials/comps-vue3": "1.0.37-beta.5"
+    "@jctrans-materials/comps-vue3": "1.0.37-beta.7",
+    "@jctrans-materials/shared": "1.0.37-beta.7"
   },
   "devDependencies": {
     "@nuxt/module-builder": "latest",