# @datadog/apps-frontend 中文文档

规范地址：https://npmcn.com/package/%40datadog/apps-frontend/

版本：0\.0\.12
npm 元数据更新时间：2026-11-06T20:46:24.241Z
中文译文更新时间：2026-11-11T13:16:36.018Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40datadog/apps-frontend
原文对照：https://npmcn.com/package/%40datadog/apps-frontend/?lang=original
项目主页：https://datadoghq.com/
源码仓库：https://datadoghq.com/

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

- 包体积（解压后）：1.2 MB，89 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，@datadog/druids \>=0\.0\.7 \<0\.2\.0，@datadog/action-catalog \>=0\.0\.7 \<0\.1\.0
- 首次发布：2026-08-14T16:53:06.389Z
- 最新版本发布：2026-11-06T20:46:24.069Z
- 近 30 天下载量：6599（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

Datadog Apps 的反应输入

## 安装

```sh
npm install @datadog/apps-frontend
```

也可以使用：`pnpm add @datadog/apps-frontend`、`yarn add @datadog/apps-frontend`、`bun add @datadog/apps-frontend`

## README

# @ datadog/ apps- 前端

Datadog Apps的前端能力.

```sh
npm install @datadog/apps-frontend
```

软件包根不暴露任何信息: 反应能力存在于此软件包中 子路径条目 .

-   `@datadog/apps-frontend/embedding/react` —— 说 `DatadogAppProvider` 连接一个应用程序到主机,安装此软件包的默认模块,以及 与其下方的每个模块钩子共享一个嵌入连接; `useDatadogAppEmbedding` 读取连接状态.
-   `@datadog/apps-frontend/inputs/react` —— 说 `useDatadogAppInput` 读取键入 输入主机提供的.
-   `@datadog/apps-frontend/inputs/schema` ——输入计划本身,如: 作为 `datadogTheme` 财务报告和审定财务报表 `datadogDashboard`,转至 `useDatadogAppInput`。 。 。 .
-   `@datadog/apps-frontend/parameters` —— 说 `defineDatadogAppParameters` 声明 设置可以选择每次嵌入应用程序.
-   `@datadog/apps-frontend/parameters/react` —— 说 `useDatadogAppParameters` 读取 用于当前嵌入的数值.
-   `@datadog/apps-frontend/visualizations/react` —— 说 `DatadogVisualization` 创建本地数据犬部件, 嵌入或下方 `datadog-apps dev`。 。 。 .
-   `@datadog/apps-frontend/visualizations` - 部件定义和时限 类型,加 `DatadogVisualizationError`。 。 。 .

## 使用量

在您的应用程序根附近挂载提供者; 它安装此软件包的默认值 模块并共享下方每个模块钩的嵌入连接 内容:

```tsx
import { DatadogAppProvider } from '@datadog/apps-frontend/embedding/react';

export function App() {
    return <DatadogAppProvider>{/* app UI */}</DatadogAppProvider>;
}
```

其他模块通过传送到 `modules`模块是 启动能力, 不是UI 层: 在挂载时, 提供者运行每个系统 `install` 与共享连接和处置信号,以及应用程序的UI 不受影响 :

```tsx
<DatadogAppProvider modules={[someModule({ option: true })]}>
    {/* app UI */}
</DatadogAppProvider>
```

`disabledModules` 完全接受此软件包默认模块的 id —— 从默认集中检查并自动完成字型,所以拼错的 id 是 编译错误 。 深层链接( E)`'datadog.deep-links'`默认安装,并 当应用程序必须选择退出时,可以排除。 在跑步时间,一个未知的ID只警告, 以旧的默认设定编译的被冻结的应用程序 继续渲染.

## 参数

参数允许一个应用程序嵌入 多个不同设置的地方, 例如环境或行限制。 说出你读过的地方:

```tsx
import { defineDatadogAppParameters } from '@datadog/apps-frontend/parameters';
import { useDatadogAppParameters } from '@datadog/apps-frontend/parameters/react';

function Results() {
    const parameters = useDatadogAppParameters(
        defineDatadogAppParameters({
            environment: {
                type: 'string',
                label: 'Environment',
                default: 'production',
                options: ['production', 'staging'],
            },
            limit: { type: 'number', label: 'Rows', default: 10 },
        }),
    );
    if (parameters.status !== 'ready') {
        return null;
    }
    const { environment, limit } = parameters.values; // 'production' | 'staging', number
    // ...
}
```

Datadog Vite 插件在应用程序构建时找到这些声明 在每次上传时记录它们, 因此, Datadog 显示匹配控件 有人添加或配置嵌入式。 按字面写声明( plain) 字符串、数字和布尔,没有变量或分布) 可以读取。 宣言也可以生活在自己的模块中,并被共享 多个组件; 仅在多处声明相同的参数 如果每项声明相同.

值总是与声明相符:缺失或过时的值使用其 默认,在已配置的嵌入参数之外,每个参数都有默认值. 值与嵌入器一起存储并发送到浏览器,所以参数必须 从来没有秘密.

反应18和19作为同级依赖关系支持. `@datadog/druids` 是一个 可选对等点,由 `druids/react` 进入和可视化; `@datadog/action-catalog` 是一个可选的对等点,仅通过可视化需要.

## 可视化

在 Datadog App 中渲染本地数据狗可视化 `DatadogVisualization` 从 `@datadog/apps-frontend/visualizations/react`。 。 。 .

图表需要:

-   `@datadog/action-catalog` 安装在这个软件包旁边.
-   `@datadog/vite-plugin` `>= 3.4.0` (包括软件包提供的后端) 用于构建应用程序。 旧的插件捆绑此软件包的后端 操作到浏览器中,而不是在 Datadog 上运行;然后是它的图表 显示错误而不是数据.
-   DRUIDS 的样式表和环境, 作为默认的应用程序模板设置 : 导入 `@datadog/druids/styles.css` 一次在应用程序的条目, 并渲染 内部图表 `DruidsEnvironmentWithThemeInput` 从 `@datadog/apps-frontend/druids/react`。图表定义了没有设计符号或 自己的字体; 它们使用 DRUIDS' `--ui-*` 光和暗的标志 主题,以及这些字体.

数据犬的图表渲染器,它的当前构造 `v1` 频道,载荷 运行时间和运行在您的应用程序的页面中, 并带有它的正常数据处理 。 每个 请求它作为后端函数运行此包船,通过 Datadog 的公开查询动作: Datadog Apps 构建将其编译为您 应用,所以图表会获得平台的身份,权限,并限制任何地方 应用程序运行,嵌入或下 `datadog-apps dev`后端代码 对于它,没有框架 巢.

```tsx
import type { DatadogVisualizationDefinition } from '@datadog/apps-frontend/visualizations';
import { DatadogVisualization } from '@datadog/apps-frontend/visualizations/react';

const cpu: DatadogVisualizationDefinition = {
    type: 'timeseries',
    requests: [
        {
            response_format: 'timeseries',
            queries: [
                {
                    data_source: 'metrics',
                    name: 'cpu',
                    query: 'avg:system.cpu.user{*}',
                },
            ],
            formulas: [{ formula: 'cpu' }],
            display_type: 'line',
        },
    ],
};

<DatadogVisualization definition={cpu} height={300} />;
```

-   定义使用公共 Dashboard API 的部件格式,作为普通的JSON.
-   通过 Datadog 的公开查询动作进行图表查询,所以它们支持什么 这些行动包括:
    -   数据来自时序或分级公式查询的部件,例如 作为 `timeseries` 财务报告和审定财务报表 `query_value`。需要其它数据狗的部件 端点显示图表中的错误.
    -   查询 `metrics` 财务报告和审定财务报表 `cloud_cost` 数据来源,以及 `logs`, (中文(简体) ), `rum` 财务报告和审定财务报表 `dora` 事件。 动作拒绝任何其他数据来源,例如: APM横跨或安全信号,图表显示其出错.
    -   Scalar 查询支持以单一公式排序; 排序查询表 不支持组合列并显示出错.
    -   行动不 `minimum_interval` 和不加热推倒 参数,因此对于这些请求,API会自行取出其卷起.
-   `timeFrame` 接受 `{ start, end, isLive }` 内 **毫秒** 已经 由您的应用程序拥有, 因为数据狗的页面拥有它的时间。 现场直播 过去一个小时,通过Datadog的仪表板时间表更新。 当嵌入一个 仪表板,通过 `datadogDashboard` 输入的 `timeframe`。 。 。 .
-   `onTimeFrameChange` 允许刷新放大时间序列 。 图表是 不改变它自己的范围: 将报告的范围保留在状态中并传回 作为 `timeFrame`。 。 。 .
-   `theme` 接受 `'light'` 或者说 `'dark'`· ; `height` 默认为 300px.
-   `onError` 报告无效输入,无法装入的渲染器,以及 一旦失败, 渲染器无法显示定义 。 部件和查询 失败出现在图表中,如Datadog仪表板,包括 查询为平台返回过多的数据、超时和速率 限制.
-   渲染器是一个从 `https://static.datadoghq.com` 时间 运行时间, 因此您的应用程序的内容安全政策必须允许脚本和样式 从 `https://static.datadoghq.com`。每页只运行一个渲染器. 此软件包的每份主要装入一个信道, 所以不要混合 在一个应用程序中的主要.

## 深层链接

深链接映射应用程序的查询字符串和碎片到主机页面 URL,因此可以共享并重新开放导航状态. 模块已安装 默认; 参见 [深链接指南](https://npmcn.com/package/%40datadog/apps-frontend/src/deep-links/GUIDE.md) 联 合 国 URL 格式, 如何构建可共享链接, 以及如何读取深链接 状态为负载.

## 发展

```sh
cd packages/published/apps-frontend
yarn build
yarn -T typecheck:workspace
yarn -T test-unit:workspace
```

### 撰写输入计划

写一个工厂的工地和出版政策 然后注册 那个工厂 [`src/inputs/schemas/`](https://npmcn.com/package/%40datadog/apps-frontend/src/inputs/schemas/README.md)。模块拥有计划 注册、工具和生成主机/消费者视图。 公共进口停留 `inputs/schema`; 使用web-ui主机 `inputs/internal`。 。 。 .

### 释放可视化

图表加载渲染器(`static-apps/apps-visualization-renderer`从它的 `v1` datadog公共静态CDN的频道, `https://static.datadoghq.com/apps-visualization-renderer/v1/renderer.js`。 。 。 . 每个渲染器部署上传一个不可改变的构建到 `v/<version>/`,则 将频道指向它;频道被缓存5分钟. 一个渲染器 固定因此到达应用, 不发布此软件包或应用 重新装入。 制造器必须在第一次生产前部署 发布谁的图表加载它.

内部 `v1`每一个制造器的建筑 都必须与每一个上传的应用程序合作, 包括此软件包运出的最老后端函数 (单位:千美元)`src/visualizations/data.backend.ts`: 它只接受 `/api/ui/query/timeseries` 财务报告和审定财务报表 `/api/ui/query/scalar` 与当前 `data[].attributes` 请求正文,并返回响应形状 变相器读取。 修复后端功能本身仍需要发布 此软件包和应用程序重载.

变相器合同船舶作为 `v2` 带新频道 这个包的主要内容。 用于开发, 使用另一个渲染器 URL 构建 `APPS_VISUALIZATION_RENDERER_URL=<module URL> yarn build`。 。 。 .

## 许可证

阿帕奇 - 2.0

## 常见问题

### @datadog/apps-frontend 是什么？

Datadog Apps 的反应输入

### 如何安装 @datadog/apps-frontend？

在项目目录运行 npm install @datadog/apps-frontend，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @datadog/apps-frontend 支持 TypeScript 吗？

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

### @datadog/apps-frontend 支持 ESM 还是 CommonJS？

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

### @datadog/apps-frontend 可以商用吗？

@datadog/apps-frontend 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @datadog/apps-frontend 的下载量有多少？

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

### @datadog/apps-frontend 还在维护吗？

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