UI 扩展

本页详细描述了 UI 扩展 API。

Grafana 中的扩展点

Grafana 中可用的扩展点列表，这些扩展点可由插件进行扩展。所有这些扩展点 ID 都可以通过 @grafana/data 包暴露的 PluginExtensionPoints 枚举访问。

import { PluginExtensionPoints } from '@grafana/data';

const extensionPointId = PluginExtensionPoints.DashboardPanelMenu;

扩展点 ID	类型	描述
`AlertingAlertingRuleAction`	链接	使用自定义操作扩展告警规则菜单。
`AlertingHomePage`	组件	使用自定义告警创建体验扩展告警主页。
`AlertingRecordingRuleAction`	链接	使用自定义操作扩展告警规则菜单，用于记录规则。
`AlertInstanceAction`	链接	使用自定义操作扩展告警实例表。
`CommandPalette`	链接	使用自定义操作扩展命令面板。
`DashboardPanelMenu`	链接	使用自定义操作扩展面板菜单。
`ExploreToolbarAction`	链接	使用自定义操作扩展“探索”页面上的“添加”按钮。
`UserProfileTab`	组件	使用自定义选项卡扩展用户资料页。

方法

`addComponent`

信息

在 Grafana >=v11.1.0 中可用。

此方法可用于将 React 组件注册到特定扩展点，以提供新的 UI 体验。

export const plugin = new AppPlugin<{}>().addComponent({
  targets: ['grafana/user/profile/tab/v1'],
  title: 'New user profile tab',
  description: 'A new tab that shows extended user profile information',
  component: () => {
    return <div>Hello World!</div>;
  },
});

参数

addComponent() 方法接受一个包含以下属性的 config 对象

属性	描述
`targets`	将注册扩展的扩展点 ID 列表。示例：`"grafana/dashboard/panel/menu/v1"`。查看 Grafana 中的可用扩展点 →
`title`	组件的人类可读标题。
`description`	组件的人类可读描述。
`component`	将由扩展点渲染的 React 组件。注意：传递给组件的 props 由每个扩展点定义。

返回值

该方法返回 AppPlugin 实例，以便进行链式调用。

示例

另请参阅

添加组件的最佳实践

`addLink`

信息

在 Grafana >=v11.1.0 中可用。

此方法可用于将链接扩展注册到特定扩展点。链接扩展用于导航到 Grafana UI 或其他插件的不同部分，并且可以通过 onClick 声明模态元素。

export const plugin = new AppPlugin<{}>().addLink({
  targets: ['grafana/dashboard/panel/menu/v1'],
  title: 'Declare incident',
  description: 'Declare an incident and attach the panel context to it',
  path: '/a/myorg-incidents-app/incidents',
});

参数

addLink() 方法接受一个包含以下属性的 config 对象

属性	描述	必需
`targets`	将注册扩展的扩展点 ID 列表。示例：`"grafana/dashboard/panel/menu/v1"`。查看 Grafana 中的可用扩展点 →	true
`title`	链接的人类可读标题。	true
`description`	链接的人类可读描述。	true
`path?`	应用插件中的一个路径，当用户点击链接时将用户发送到此处。（使用 `path` 或 `onClick`。）示例：`"/a/myorg-incidents-app/incidents"`	true
`onClick?`	当用户点击链接时应触发的回调。（使用 `path` 或 `onClick`。）	false
`category?`	用于将您的链接与其他链接分组的类别。	false
`icon?`	显示链接时应使用的图标。示例：`"edit"` 或 `"bookmark"`。查看所有可用图标名称 →	false
`configure?`	在显示链接之前调用此函数，使您能够根据其 `context` 动态更改或隐藏您的链接。	false

返回值

该方法返回 AppPlugin 实例，以便进行链式调用。

示例

`exposeComponent`

信息

在 Grafana >=v11.1.0 中可用。

此方法暴露一个 React 组件，并使其可供其他插件使用。其他插件可以通过调用 usePluginComponent() 并引用所暴露组件的 id 来在其应用中渲染该组件。

export const plugin = new AppPlugin<{}>()
    .exposeComponent({
        id: "myorg-incidents-app/create-incident-form/v1",],
        title: "Create incident form",
        description: "A form to create a new incident.",
        component: () => {
            return <div>Hello World!</div>;
        },
    });

参数

exposeComponent() 方法接受一个包含以下属性的 config 对象

属性	描述
`id`	您正在暴露的组件的唯一字符串标识符。它必须以您的插件 ID 为前缀。示例：`"myorg-incidents-app/create-incident-form/v1"`。
`title`	组件的人类可读标题。
`description`	组件的人类可读描述。
`component`	一个您正在暴露的 React 组件。请务必使用组件所依赖的必要的 React 上下文提供者来包装它，因为此组件不会在与您的插件相同的 React 树下渲染。

返回值

该方法返回 AppPlugin 实例，以便进行链式调用。

示例

在暴露的组件中访问插件元信息

另请参阅

暴露组件的最佳实践

`getPluginExtensions` ⚠️

此函数可用于获取注册到特定扩展点的扩展（包括链接和组件）。

警告

此函数已被弃用，并将在 Grafana v12 中移除。请改用 usePluginLinks() 或 usePluginComponents() 钩子。

import { getPluginExtensions } from '@grafana/runtime';

const { extensions } = getPluginExtensions({
  extensionPointId: 'grafana/dashboard/panel/menu/v1',
  limitPerPlugin: 2,
  context: {
    panelId: '...',
  },
});

参数

getPluginExtensions() 函数接受一个包含以下属性的 options 对象

属性	描述	必需
`extensionPointId`	用于获取链接扩展的唯一 ID。如果您正在实现新的扩展点，这是插件注册扩展时引用的内容。插件必须以此为其插件 ID 加前缀，而核心 Grafana 扩展点必须使用 `"grafana/"` 前缀。示例：`"grafana/dashboard/panel/menu/v1"`	true
`context?`	您想与扩展共享的任意对象。这可用于向扩展传递数据。	false
`limitPerPlugin?`	- 每个插件返回的最大扩展数。默认为无限制。	false

返回值

该钩子返回以下对象

const {
  // An empty array if no plugins have registered extensions for this extension point yet
  extensions: PluginExtension[];
} = getPluginExtensions(options);

更多信息，请参阅 PluginExtension。

钩子

`usePluginComponent`

信息

在 Grafana >=v11.1.0 中可用。

此 React 钩子可用于获取通过唯一 ID 由插件暴露的单个 React 组件。插件可以使用 AppPlugin.exposeComponent() 方法暴露组件。

import { usePluginComponent } from '@grafana/runtime';

const { component: Component, isLoading } = usePluginComponent('myorg-incidents-app/create-incident-form/v1');

参数

id - 标识组件的唯一 ID。

返回值

该钩子返回以下对象

const {
  // The react component that was exposed by the plugin
  // (`null` if no component is exposed with that id)
  component: React.ComponentType<Props> | undefined | null;

  // `true` until the plugin exposing the component is still loading
  isLoading: boolean;
} = usePluginComponent(id);

示例

如何渲染由另一个插件暴露的组件

`usePluginComponents`

信息

在 Grafana >=v11.1.0 中可用。

此 React 钩子可用于获取注册到特定扩展点的组件。组件扩展可用于渲染自定义 UI 组件。插件可以使用 AppPlugin.addComponent() 方法注册组件。

import { usePluginComponents } from '@grafana/runtime';

const { components, isLoading } = usePluginComponents({
  extensionPointId: 'grafana/user/profile/tab/v1',
  limitPerPlugin: 1,
});

参数

.usePluginComponents() 方法接受一个包含以下属性的 options 对象

属性	描述	必需
`extensionPointId`	用于获取链接扩展的唯一 ID。如果您正在实现新的扩展点，这是插件注册扩展时引用的内容。插件必须以此为其插件 ID 加前缀，而核心 Grafana 扩展点必须使用 `"grafana/"` 前缀。示例：`"grafana/user/profile/tab/v1"`	true
`limitPerPlugin?`	- 每个插件返回的最大扩展数。默认为无限制。	False

返回值

该钩子返回以下对象（更多信息请查看 PluginExtensionComponent）

const {
  // An empty array if no plugins have registered extensions for this extension point yet
  components: PluginExtensionComponent[];

  // `true` until any plugins extending this extension point
  // are still loading
  isLoading: boolean;
} = usePluginComponents(options);

示例

另请参阅

渲染插件添加的组件的最佳实践

`usePluginLinks`

信息

在 Grafana >=v11.1.0 中可用。

此 React 钩子可用于获取注册到特定扩展点的链接。插件可以使用 AppPlugin.addLink() 方法注册链接。

import { usePluginLinks } from '@grafana/runtime';

const { links, isLoading } = usePluginLinks({
  extensionPointId: 'grafana/dashboard/panel/menu/v1',
  limitPerPlugin: 2,
  context: {
    panelId: '...',
  },
});

参数

.usePluginLinks() 方法接受一个包含以下属性的 options 对象

属性	描述	必需
`extensionPointId`	用于获取链接扩展的唯一 ID。如果您正在实现新的扩展点，这是插件注册扩展时引用的内容。插件必须以此为其插件 ID 加前缀，而核心 Grafana 扩展点必须使用 `"grafana/"` 前缀。示例：`"grafana/dashboard/panel/menu/v1"`	true
`context?`	您想与扩展共享的任意对象。这可用于向扩展传递数据。	false
`limitPerPlugin?`	每个插件返回的最大扩展数。默认为无限制。	false

返回值

该钩子返回以下对象（更多信息请查看 PluginExtensionLink）

const {
  // An empty array if no plugins have registered extensions for this extension point yet
  links: PluginExtensionLink[];

  // `true` until any plugins extending this extension point
  // are still loading
  isLoading: boolean;
} = usePluginLinks(options);

示例

另请参阅

渲染插件添加的链接的最佳实践

`usePluginExtensions` ⚠️

此 React 钩子可用于获取注册到特定扩展点的扩展（包括链接和组件）。

警告

此钩子已被弃用，并将在 Grafana v12 中移除。请改用 usePluginLinks() 或 usePluginComponents() 钩子。

import { usePluginExtensions } from '@grafana/runtime';

const { extensions, isLoading } = usePluginExtensions({
  extensionPointId: 'grafana/dashboard/panel/menu/v1',
  limitPerPlugin: 2,
  context: {
    panelId: '...',
  },
});

参数

.usePluginExtensions() 方法接受一个包含以下属性的 options 对象

属性	描述	必需
`extensionPointId`	用于获取链接扩展的唯一 ID。如果您正在实现新的扩展点，这是插件注册扩展时引用的内容。插件必须以此为其插件 ID 加前缀，而核心 Grafana 扩展点必须使用 `"grafana/"` 前缀。示例：`"grafana/dashboard/panel/menu/v1"`	true
`context?`	您想与扩展共享的任意对象。这可用于向扩展传递数据。	false
`limitPerPlugin?`	每个插件返回的最大扩展数。默认为无限制。	false

返回值

该钩子返回以下对象

const {
  // An empty array if no plugins have registered extensions for this extension point yet
  extensions: PluginExtension[];

  // `true` until any plugins extending this extension point
  // are still loading
  isLoading: boolean;
} = usePluginExtensions(options);

更多信息，请参阅 PluginExtension。

Grafana 中的扩展点​

方法​

addComponent​

参数​

返回值​

示例​

另请参阅​

addLink​

参数​

返回值​

示例​

exposeComponent​

参数​

返回值​

示例​

另请参阅​

getPluginExtensions ⚠️​

参数​

返回值​

钩子​

usePluginComponent​

参数​

返回值​

示例​

usePluginComponents​

参数​

返回值​

示例​

另请参阅​

usePluginLinks​

参数​

返回值​

示例​

另请参阅​

usePluginExtensions ⚠️​

参数​

返回值​

Grafana 中的扩展点

方法

`addComponent`

参数

返回值

示例

另请参阅

`addLink`

参数

返回值

示例

`exposeComponent`

参数

返回值

示例

另请参阅

`getPluginExtensions` ⚠️

参数

返回值

钩子

`usePluginComponent`

参数

返回值

示例

`usePluginComponents`

参数

返回值

示例

另请参阅

`usePluginLinks`

参数

返回值

示例

另请参阅

`usePluginExtensions` ⚠️

参数

返回值