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`	组件的可读标题。
`描述`	组件的可读描述。
`组件`	将由扩展点渲染的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
`描述`	链接的可读描述。	true
`path?`	当用户点击链接时，您希望用户发送到您应用程序插件内部的路径。（使用`path`或`onClick`。）示例：`"/a/myorg-incidents-app/incidents"`	true
`onClick?`	当用户点击链接时应触发的回调。（使用`path`或`onClick`。）	false
`category?`	应用于将您的链接与其他链接分组在一起的一组。	false
`icon?`	显示您的链接时应使用的图标。示例：`"edit"`或`"bookmark"`。查看所有可用图标名称→	false
`configure?`	在显示链接之前被调用的函数，它使您能够根据其`上下文`动态更改或隐藏您的链接。	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`	组件的可读标题。
`描述`	组件的可读描述。
`组件`	您暴露的 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。插件必须在其 ID 前加上前缀，而 Grafana 核心扩展点的 ID 必须使用 `"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。插件必须在其 ID 前加上前缀，而 Grafana 核心扩展点的 ID 必须使用 `"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。插件必须在其 ID 前加上前缀，而 Grafana 核心扩展点的 ID 必须使用 `"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。插件必须在其 ID 前加上前缀，而 Grafana 核心扩展点的 ID 必须使用 `"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` ⚠️

参数

返回值