# @dash0hq/codemirror-promql 中文文档

规范地址：https://npmcn.com/package/%40dash0hq/codemirror-promql/

版本：0\.302\.1-dash03
npm 元数据更新时间：2026-03-30T09:22:00.304Z
中文译文更新时间：2026-11-11T12:28:24.501Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40dash0hq/codemirror-promql
原文对照：https://npmcn.com/package/%40dash0hq/codemirror-promql/?lang=original
项目主页：https://github.com/prometheus/prometheus/blob/main/web/ui/module/codemirror-promql/README.md
源码仓库：https://github.com/prometheus/prometheus

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

- 包体积（解压后）：505 kB，120 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=12\.0\.0
- 运行依赖：2 个
- peer 依赖：@codemirror/autocomplete ^6\.4\.0，@codemirror/language ^6\.3\.0，@codemirror/lint ^6\.0\.0，@codemirror/state ^6\.1\.1，@codemirror/view ^6\.4\.0，@lezer/common ^1\.0\.1
- 首次发布：2025-04-25T16:15:05.830Z
- 最新版本发布：2026-03-30T09:22:00.111Z
- 近 30 天下载量：10789（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 2 个）

## 中文简介

promQL 语言的代码Mirror 模式

## 安装

```sh
npm install @dash0hq/codemirror-promql
```

也可以使用：`pnpm add @dash0hq/codemirror-promql`、`yarn add @dash0hq/codemirror-promql`、`bun add @dash0hq/codemirror-promql`

## README

# 代码Morror-promql

此工程为 [代码](https://codemirror.net/6/) 处理语法突出显示, 折叠 并自动完成 PromQL ()[Prometheus 查询语言](https://prometheus.io/docs/introduction/overview/)) (中文(简体) ).

![preview](https://user-images.githubusercontent.com/4548045/95660829-d5e4b680-0b2a-11eb-9ecb-41dca6396273.gif)

## 安装

此模式作为 npm 软件包可用 :

```bash
npm install --save @dash0hq/codemirror-promql
```

**说明:** 您需要手动安装不同组件的软件包 联 合 国 [代码](https://codemirror.net/6/),因为它们是本套件的同伴依赖。 这儿是不同的 您需要安装的软件包 :

-   **@ codemirror/ 自动完成**
-   **@ codemirror/ 语言**
-   **@ codemirror/ lint (英语)**
-   **@ codemirror/ 状态**
-   **@ codemirror/ 视图**
-   **@ lezer/ 常见**

```bash
npm install --save @codemirror/autocomplete @codemirror/language @codemirror/lint @codemirror/state @codemirror/view @lezer/common
```

**说明2**:这是安装 lib 所需的最小值. 你可能需要安装 以及依赖 **@ codemirror/ 基本设置** 以简化代码Mirror本身的设置:

```bash
npm install --save @codemirror/basic-setup
```

## 使用量

由于 PromQL 语言的设置在 CMN 中会有些棘手, 因此这个 lib 提供了一个类 `PromQLExtension` 来帮助您配置我们想要提供的不同扩展 .

### 默认设置

如果您想要享受所提供的不同特性而不需要花费太多时间来理解如何配置 他们,那么最简单的方法是这个:

```typescript
import {PromQLExtension} from '@dash0hq/codemirror-promql';
import {basicSetup} from '@codemirror/basic-setup';
import {EditorState} from '@codemirror/state';
import {EditorView} from '@codemirror/view';

const promQL = new PromQLExtension()
new EditorView({
    state: EditorState.create({
        extensions: [basicSetup, promQL.asExtension()],
    }),
    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
    // tslint:disable-next-line:no-non-null-assertion
    parent: document.getElementById('editor')!,
});
```

使用默认设置将激活 :

-   语法突出显示
-   离线自动补全,将显示函数/聚合等 PromQL 关键字,视 上下文.
-   一个将显示 PromQL 语法错误的离线linter( 它更接近 Prometheus 返回的内容)

### 取消自动补全 - 线性

如果你想要关闭电线和(或)自动补全 很简单:

```typescript
const promQL = new PromQLExtension().activateLinter(false).activateCompletion(false) // here the linter and the autocomplete are deactivated
```

### 线条

今天没有特定配置的linter。 随便你,如果你有需要的话 需要可配置性.

### 自动补全

自动补全特性提供了多种不同的参数,可用于使此 lib 适应您的 环境.

#### 最大计量元数据

`maxMetricsMetadata` 是获取元数据在普罗米修斯的最大度量。 如果数目 度量衡超过此限值,根本没有获取任何度量元数据.

默认限制为一万公分.

谨慎使用. 由于获取的数据过多,此限制值高,可能导致您的浏览器崩溃 .

```typescript
const promQL = new PromQLExtension().setComplete({maxMetricsMetadata: 10000})
```

#### 将自动补全扩展连接到远程 Prometheus 服务器

将自动补全扩展连接到远程的Prometheus服务器,将自动补全公制名称、标签 名称和标签值.

##### 使用默认的 Prometheus 客户端

###### 普罗米修斯 URL

如果您想要使用此 lib 提供的默认 Prometheus 客户端, 您必须提供 URL 来联系 普罗米修斯服务器.

注意: 这是您想要使用默认的 Prometheus 客户端时唯一的强制参数 。 没有这个 参数,其余的配置将被忽略,而Prometheus客户端将不会被初始化.

```typescript
const promQL = new PromQLExtension().setComplete({remote: {url: 'https://prometheus.land'}})
```

###### 覆盖获取Fn

如果您的 Prometheus 服务器被保护并需要特殊的 HTTP 客户端, 您可以覆盖此功能 `fetchFn` 用于执行任何所需的 HTTP 请求.

```typescript
const promQL = new PromQLExtension().setComplete({remote: {fetchFn: myHTTPClient}})
```

###### 检索指标/标签时用于回顾的时间

如果你对"普罗米修斯API"有点熟悉,你意识到你可以通过一个时间间隔,用来告诉 到 Prometheus 在检索元数据( 如 度量 / 标签 ) 时需要的时间 .

如果您想要提供您自己的持续时间, 您可以覆盖变量 `lookbackInterval`默认情况下 值为 `12 * 60 * 60 * 1000` (12h) (英语). 数值必须在 **毫秒**。 。 。 .

```typescript
const promQL = new PromQLExtension().setComplete({remote: {lookbackInterval: 12 * 60 * 60 * 1000}})
```

###### 处理错误

您可以设置自己的错误处理器, 以捕捉在PrometheusClient 联系时可能发生的 HTTP 错误 普罗米修斯.

```typescript
const promQL = new PromQLExtension().setComplete({remote: {httpErrorHandler: (error: any) => console.error(error)}})
```

###### 使用的HTTP方法

默认情况下, Prometheus 客户端将使用 HTTP 方法 `POST` 当联系普罗米修斯时 结束点 `/api/v1/labels` 财务报告和审定财务报表 `/api/v1/series`。 。 。 .

您可以更改为使用 HTTP 方法 `GET` 如果你喜欢.

```typescript
const promQL = new PromQLExtension().setComplete({remote: {httpMethod: 'GET'}})
```

###### HTTP 请求头

如果您需要将特定的 HTTP 信头连同请求一起发送到 Prometheus, 您可以调整如下 :

```typescript
const customHeaders = new Headers({'header-name': 'test-value'});
const promql = new PromQLExtension().setComplete({remote: {requestHeaders: customHeaders}})
```

###### 覆盖 API 前缀

默认的 Prometheus 客户端 在构建查询从 Prometheus 获取数据时, 使用 API 前缀 默认 `/api/v1`。 。 。 .

您可以覆盖此值 :

```typescript
const promql = new PromQLExtension().setComplete({remote: {apiPrefix: '/my/api/prefix'}})
```

###### 缓存

默认客户端有一个嵌入式缓存,用于存储从远程获取的不同度量和标签 普罗米修斯服务器.

###### 最大年龄

数据存储在缓存中, 时间由变量定义 `maxAge` 默认为 5 几分钟。 数值必须在 **毫秒**。 。 。 .

```typescript
const promQL = new PromQLExtension().setComplete({remote: {cache: {maxAge: 5 * 60 * 1000}}})
```

###### 初始计量列表

缓存可以初始化使用一个公尺名列表. 如果您已经掌握了参数列表, 将会有所帮助 您想与嵌入式的Prometheus客户端共享此列表 联 合 国 `codemirror-promql`。 。 。 .

注意: 请记住, 此列表将保留在嵌入式的 Prometheus 客户端中, 直到定义的时间 `maxAge`。 。 。 .

```typescript
const promQL = new PromQLExtension().setComplete({
    remote: {
        cache: {
            initialMetricList: [
                'ALERTS',
                'ALERTS_FOR_STATE',
                'alertmanager_alerts',
                'alertmanager_alerts_invalid_total',
                'alertmanager_alerts_received_total',
            ]
        }
    }
})
```

##### 覆盖默认的 Prometheus 客户端

如果你对我们默认的普罗米修斯客户端不满意,你仍然可以提供自己的客户端. 它必须执行 接口 [普罗米修斯](https://github.com/prometheus/codemirror-promql/blob/main/src/client/prometheus.ts#L24-L39) 。 。 。 .

```typescript
const promQL = new PromQLExtension().setComplete({remote: MyPrometheusClient})
```

#### 提供您自己执行的自动补全

如果你想让您自己执行自动补全,您可以简单地这样做:

```typescript
const promQL = new PromQLExtension().setComplete({completeStrategy: myCustomImpl})
```

说明: 如果提供了这个参数,则会忽略其余配置.

### 示例

-   [ReactJS 实例](https://github.com/prometheus/prometheus/blob/431ea75a11ca165dad9dd5d629b3cf975f4c186b/web/ui/react-app/src/pages/graph/CMExpressionInput.tsx)
-   [角实例](https://github.com/perses/perses/blob/28b3bdac88b0ed7a4602f9c91106442eafcb6c34/internal/api/front/perses/src/app/project/prometheusrule/promql-editor/promql-editor.component.ts)

## 许可证

该代码根据 [Apache 2.0 (英语)](https://github.com/prometheus/prometheus/blob/main/LICENSE) 执照.

## 常见问题

### @dash0hq/codemirror-promql 是什么？

promQL 语言的代码Mirror 模式

### 如何安装 @dash0hq/codemirror-promql？

在项目目录运行 npm install @dash0hq/codemirror-promql，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@codemirror/autocomplete（^6\.4\.0）、@codemirror/language（^6\.3\.0）、@codemirror/lint（^6\.0\.0）、@codemirror/state（^6\.1\.1）、@codemirror/view（^6\.4\.0）、@lezer/common（^1\.0\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dash0hq/codemirror-promql 支持 TypeScript 吗？

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

### @dash0hq/codemirror-promql 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @dash0hq/codemirror-promql 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=12\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dash0hq/codemirror-promql 可以商用吗？

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

### @dash0hq/codemirror-promql 的下载量有多少？

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

### @dash0hq/codemirror-promql 还在维护吗？

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