# @cacic-fct/ngx-umami 中文文档

规范地址：https://npmcn.com/package/%40cacic-fct/ngx-umami/

版本：1\.2\.3
npm 元数据更新时间：2026-06-25T22:40:00.879Z
中文译文更新时间：2026-11-08T23:16:56.276Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cacic-fct/ngx-umami
原文对照：https://npmcn.com/package/%40cacic-fct/ngx-umami/?lang=original
项目主页：https://github.com/cacic-fct/ngx-umami#readme
源码仓库：https://github.com/cacic-fct/ngx-umami

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：62.4 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@angular/common \>=17\.0\.0，@angular/core \>=17\.0\.0，@angular/router \>=17\.0\.0
- 首次发布：2026-06-25T21:08:58.981Z
- 最新版本发布：2026-06-25T22:40:00.744Z
- 近 30 天下载量：3465（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

Umami 分析的角库 - 注重隐私的轻量级分析跟踪

## 安装

```sh
npm install @cacic-fct/ngx-umami
```

也可以使用：`pnpm add @cacic-fct/ngx-umami`、`yarn add @cacic-fct/ngx-umami`、`bun add @cacic-fct/ngx-umami`

## README

# ngx-umami (英语)

角库 [Umami 分析](https://umami.is/) - 一个注重隐私、轻量级分析平台.

[![npm version](https://badge.fury.io/js/%40cacic-fct%2Fngx-umami.svg)](https://www.npmjs.com/package/@cacic-fct/ngx-umami) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 特征

-   🚀 **简单设置** - 简单的独立配置 `provideUmami()`
-   📊 **事件跟踪** - 跟踪带有可选数据有效载荷的自定义事件
-   🔄 **路由器集成** - 在路由更改时自动查看页面
-   🎯 **指令** - 申报活动跟踪 `umamiTrack` 指令
-   🔒 **隐私第一** - 尊重不跟踪,符合GDPR
-   🌐 **SSR 兼容性** - 与Angular Universal/SSR合作
-   📦 **树能震动** - 只包括你使用的东西

## 兼容性

| 角质版本 | ngx- umami 版本 |
| --- | --- |
| 17.x 及以后 | 1.x 运算 |

## 安装

```bash
# Recommended
pnpm add @cacic-fct/ngx-umami

# Or with npm
npm install @cacic-fct/ngx-umami

# Or with yarn
yarn add @cacic-fct/ngx-umami
```

> **说明:** 我们建议使用 [小时](https://pnpm.io/) 用于更快的安装和更好的磁盘空间效率.

## 快速启动

### 1\. 在应用程序中配置

```typescript
// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideUmami, withRouterTracking } from '@cacic-fct/ngx-umami';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideUmami({
      websiteId: 'your-website-id',
      src: 'https://analytics.yourdomain.com/script.js'
    }),
    // Optional: Enable automatic page view tracking on route changes
    withRouterTracking()
  ]
};
```

### 2\. 各组成部分的跟踪活动

```typescript
import { Component } from '@angular/core';
import { injectUmami } from '@cacic-fct/ngx-umami';

@Component({
  selector: 'app-checkout',
  template: `<button (click)="onPurchase()">Buy Now</button>`
})
export class CheckoutComponent {
  private umami = injectUmami();

  onPurchase() {
    this.umami.trackEvent('purchase', {
      product: 'Premium Plan',
      price: 99.99,
      currency: 'USD'
    });
  }
}
```

### 3\. 或使用指令

```typescript
import { Component } from '@angular/core';
import { UmamiTrackDirective } from '@cacic-fct/ngx-umami';

@Component({
  selector: 'app-signup',
  standalone: true,
  imports: [UmamiTrackDirective],
  template: `
    <button umamiTrack="signup_click">Sign Up</button>

    <button
      umamiTrack="cta_click"
      [umamiTrackData]="{ location: 'header', variant: 'blue' }">
      Get Started
    </button>
  `
})
export class SignupComponent {}
```

## 配置选项

```typescript
provideUmami({
  // Required
  websiteId: 'your-website-id',  // From Umami dashboard
  src: 'https://analytics.example.com/script.js',  // Your Umami script URL

  // Optional
  enabled: true,              // Enable/disable tracking (default: true)
  autoTrack: true,            // Auto track page views (default: true)
  doNotTrack: false,          // Honor browser DNT setting (default: false)
  domains: ['example.com'],   // Restrict to specific domains
  tag: 'production',          // Tag for filtering in dashboard
  excludeSearch: false,       // Exclude URL search params
  excludeHash: false,         // Exclude URL hash
  hostUrl: 'https://proxy.example.com'  // Custom data endpoint
})
```

## API 参考

### Umami服务

#### `trackPageView(payload?)`

手动跟踪页面视图.

```typescript
umami.trackPageView();

umami.trackPageView({
  url: '/custom-page',
  title: 'Custom Page Title',
  referrer: 'https://google.com'
});
```

#### `trackEvent(eventName, eventData?)`

跟踪自定义事件 .

```typescript
// Simple event
umami.trackEvent('button_click');

// Event with data (max 50 properties)
umami.trackEvent('form_submit', {
  formName: 'contact',
  fields: 5,
  hasAttachment: true
});
```

#### `identify(sessionIdOrData, sessionData?)`

识别用户会话.

```typescript
// With session ID
umami.identify('user-123');

// With session ID and data
umami.identify('user-123', {
  plan: 'premium',
  role: 'admin'
});

// With data only
umami.identify({
  plan: 'premium',
  signupDate: '2024-01-15'
});
```

#### `isAvailable()`

检查是否有可用的跟踪 .

```typescript
if (umami.isAvailable()) {
  umami.trackEvent('ready');
}
```

#### `disable()`

程序上禁用跟踪 .

```typescript
umami.disable();
```

### Umami 跟踪指令

关于DOM元素的宣告事件跟踪.

```html
<!-- Track click events -->
<button umamiTrack="signup">Sign Up</button>

<!-- With event data -->
<button
  umamiTrack="download"
  [umamiTrackData]="{ file: 'report.pdf', size: 1024 }">
  Download
</button>

<!-- Track different events -->
<input
  umamiTrack="search_focus"
  umamiTrackOn="focus"
  placeholder="Search...">

<form
  umamiTrack="form_submit"
  umamiTrackOn="submit">
  <!-- form fields -->
</form>
```

**支持的活动 :** `click`, (中文(简体) ), `focus`, (中文(简体) ), `blur`, (中文(简体) ), `mouseenter`, (中文(简体) ), `mouseleave`, (中文(简体) ), `submit`

### 与鲁特跟踪( )

在角路由器导航上启用自动页面视图跟踪 .

```typescript
// app.config.ts
providers: [
  provideRouter(routes),
  provideUmami({
    websiteId: 'xxx',
    src: 'https://...',
    autoTrack: false  // Disable Umami's auto-track since router handles it
  }),
  withRouterTracking()
]
```

### 提供Umami与事实( )

使用工厂功能配置有依赖性注射的 Umami .

```typescript
import { provideUmamiWithFactory } from '@cacic-fct/ngx-umami';
import { ConfigService } from './config.service';

providers: [
  provideUmamiWithFactory(
    (config: ConfigService) => ({
      websiteId: config.umamiWebsiteId,
      src: config.umamiSrc,
      enabled: config.isProduction
    }),
    [ConfigService]
  )
]
```

## 环境配置

```typescript
// environments/environment.ts
export const environment = {
  production: false,
  umami: {
    websiteId: 'dev-website-id',
    src: 'https://analytics.example.com/script.js',
    enabled: false  // Disable in development
  }
};

// environments/environment.prod.ts
export const environment = {
  production: true,
  umami: {
    websiteId: 'prod-website-id',
    src: 'https://analytics.example.com/script.js',
    enabled: true
  }
};

// app.config.ts
import { environment } from './environments/environment';

providers: [
  provideUmami(environment.umami)
]
```

## 安全部门改革的考虑因素

库会自动处理服务器侧渲染. 跟踪只在浏览器环境中活动 - 不需要配置 .

## 许可证

麻省理工学院

## 常见问题

### @cacic-fct/ngx-umami 是什么？

Umami 分析的角库 - 注重隐私的轻量级分析跟踪

### 如何安装 @cacic-fct/ngx-umami？

在项目目录运行 npm install @cacic-fct/ngx-umami，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@angular/common（\>=17\.0\.0）、@angular/core（\>=17\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cacic-fct/ngx-umami 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cacic-fct/ngx-umami 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cacic-fct/ngx-umami 可以商用吗？

@cacic-fct/ngx-umami 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cacic-fct/ngx-umami 的下载量有多少？

根据 npm 官方下载统计，@cacic-fct/ngx-umami 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,465 次，日均约 116 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cacic-fct/ngx-umami 还在维护吗？

最新版本 1\.2\.3 发布于 2026/06/26（4 个月前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/06/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。