# @atlaskit/teams-app-internal-analytics 中文文档
规范地址：https://npmcn.com/package/%40atlaskit/teams-app-internal-analytics/
版本：2\.5\.0
npm 元数据更新时间：2026-10-28T03:39:35.789Z
中文译文更新时间：2026-11-07T02:53:09.801Z
软件包许可：Apache-2\.0
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40atlaskit/teams-app-internal-analytics
原文对照：https://npmcn.com/package/%40atlaskit/teams-app-internal-analytics/?lang=original
项目主页：https://bitbucket.org/atlassian/atlassian-frontend-monorepo#readme
源码仓库：https://bitbucket.org/atlassian/atlassian-frontend-monorepo
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：303 kB，39 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.2\.0
- 首次发布：2025-09-08T06:59:14.088Z
- 最新版本发布：2026-10-28T03:39:35.593Z
- 近 30 天下载量：30472（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：65（近 12 个月 42 个）
## 中文简介
团队应用软件和平台软件包用来处理人员和团队分析
## 安装
```sh
npm install @atlaskit/teams-app-internal-analytics
```
也可以使用：`pnpm add @atlaskit/teams-app-internal-analytics`、`yarn add @atlaskit/teams-app-internal-analytics`、`bun add @atlaskit/teams-app-internal-analytics`
## README
# 团队 App 内部分析
Teams app和People & Teams平台软件包的综合分析软件包. 这个 软件包提供类型安全分析事件定义、上下文提供者和测试工具 跟踪用户互动和系统行为.
## 目录
- [概览](https://npmcn.com/package/%40atlaskit/teams-app-internal-analytics/#readme-overview)
- [建筑](https://npmcn.com/package/%40atlaskit/teams-app-internal-analytics/#readme-architecture)
- [添加新事件](https://npmcn.com/package/%40atlaskit/teams-app-internal-analytics/#readme-adding-new-events)
- [分析背景](https://npmcn.com/package/%40atlaskit/teams-app-internal-analytics/#readme-analytics-context)
- [测试分析](https://npmcn.com/package/%40atlaskit/teams-app-internal-analytics/#readme-testing-analytics)
## 概览
本软件包执行结构化分析系统,即:
- **类型安全**: 所有事件和属性都强烈输入
- **声明**: YAML 规格文件中定义的事件
- **等级**: 对丰富的元数据支持嵌入分析背景
- **可测试**:包括综合测试设施
- **频道专用**: 向专栏开火 `peopleTeams` 分析通道
## 建筑
```
analytics.spec.yaml ← Event definitions (YAML)
↓
Code Generation ← Generates TypeScript types & hooks
↓
Generated Files:
├── analytics.types.ts ← Type definitions for events
├── create-event-payload.ts ← Event payload creation logic
└── use-analytics-events.ts ← React hook for firing events
↓
Consumers ← Use hook to fire analytics events
↓
Analytics Listeners ← Events sent to 'peopleTeams' channel
```
## 添加新事件
1. **定义事件** 内 `analytics.spec.yaml`数字 :
[事件定义文件规格](https://hello.atlassian.net/wiki/spaces/SMRT/pages/742668844/RFC+-+Analytic+Definition+File#Event-definition----Context)
```yaml
- button clicked (addUserToTeam):
type: ui
description: description of when this event fires
attributes:
<<: *PackageMetaDataContext
newAttribute:
type: string
description: description of the new attribute
```
2. **再生类型**数字 :
```bash
yarn analytics:codegen
```
3. **使用新事件**数字 :
```tsx
import React from 'react';
import { useAnalyticsEvents } from '@atlaskit/teams-app-internal-analytics';
function TeamMemberButton() {
const { fireEvent } = useAnalyticsEvents();
const handleClick = () => {
fireEvent('ui.button.clicked.addUserToTeam', {
testAttribute: 'memberInvite',
});
};
return ;
}
```
### 事件命名公约
事件遵循此命名模式 :
- **UI 事件**数字 : `ui.[actionSubject].[action].[actionSubjectId]`
- **音轨事件**数字 : `track.[actionSubject].[action].[actionSubjectId]`
- **业务活动**数字 : `operational.[actionSubject].[action].[actionSubjectId]`
- **屏幕事件**数字 : `screen.[screenName].viewed`
## 分析背景
这个 `PeopleTeamsAnalyticsContext` 提供自动包含在 所有事件 由儿童部分发射.
### 嵌入上下文
```tsx
```
**结果事件有效载荷:**
```json
{
"eventType": "ui",
"actionSubject": "button",
"action": "clicked",
"actionSubjectId": "analyticsExample",
"source": "teamsProfilePage",
"attributes": {
"packageName": "@atlassian/team-profile",
"packageVersion": "X.X.X",
"consumer": "web",
"teamId": "team-123",
"testAttribute": "yourValue",
"sourceHierarchy": "teamsApp.teamsProfilePage"
}
}
```
### 环境优先
当环境被嵌入时,有一个优先系统来确保正确的元数据被附加到 发送至GASv3的事件. 重复数据按下列顺序解决:
1. **事件数据** (最高优先级)
2. **内在上下文数据**
3. **外部环境数据**
**说明**: 背景情况 `attributes` 只有在事件来自 `peopleTeamsCtx` 命名空间,例如 `TeamsAppAnalyticsContext` 从这个包裹。 其他事件有效载荷属性 喜欢 `source` 将附加到所有事件,而不论上下文名称空间.
## 测试分析
此套件包括测试帮助您校验分析事件被正确发送到 GASv3 (英语). 这些公用事业使用来自 `PeopleTeamsAnalyticsListener`,确保 事件有效载荷(包括所有提供的情况)与预期成果相匹配.
### 基本测试设置
```tsx
import {
createMockAnalyticsClient,
renderWithAnalyticsListener,
} from '@atlaskit/teams-app-internal-analytics/test-utils';
const mockClient = createMockAnalyticsClient();
test('should fire analytics event on button click', async () => {
const { user, mockClient, expectEventToBeFired } = renderWithAnalyticsListener(
,
{ mockClient },
);
// Trigger the event
await user.click(screen.getByTestId('analytics-button'));
// Verify the event was fired correctly
expectEventToBeFired('ui', {
actionSubject: 'button',
action: 'clicked',
actionSubjectId: 'analyticsExample',
source: 'teamsApp',
attributes: expect.objectContaining({
testAttribute: 'expectedValue',
}),
});
});
```
## 常见问题
### @atlaskit/teams-app-internal-analytics 是什么？
团队应用软件和平台软件包用来处理人员和团队分析
### 如何安装 @atlaskit/teams-app-internal-analytics？
在项目目录运行 npm install @atlaskit/teams-app-internal-analytics，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0 \|\| ^19\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @atlaskit/teams-app-internal-analytics 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @atlaskit/teams-app-internal-analytics 支持 ESM 还是 CommonJS？
同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。
### @atlaskit/teams-app-internal-analytics 可以商用吗？
@atlaskit/teams-app-internal-analytics 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。
### @atlaskit/teams-app-internal-analytics 的下载量有多少？
根据 npm 官方下载统计，@atlaskit/teams-app-internal-analytics 在 2026/10/07 – 2026/11/05 这 30 天内被下载 30,472 次，日均约 1,016 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @atlaskit/teams-app-internal-analytics 还在维护吗？
最新版本 2\.5\.0 发布于 2026/10/28（10 天前）；至今共发布 65 个版本，其中过去 12 个月发布了 42 个；首次发布于 2025/09/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。