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`	链接	使用自定义操作扩展 Explore 页面上的“添加”按钮。
`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 中可用的扩展点 →	是
`title`	链接的人类可读标题。	是
`description`	链接的人类可读描述。	是
`path?`	当用户单击链接时，您希望将用户发送到的应用程序插件中的路径。（使用 `path` 或 `onClick`。）示例：`"/a/myorg-incidents-app/incidents"`	是
`onClick?`	当用户单击链接时应触发的回调。（使用 `path` 或 `onClick`。）	否
`category?`	应用于将您的链接与其他链接分组的类别。	否
`icon?`	显示链接时应使用的图标。示例：`"edit"` 或 `"bookmark"`。查看所有可用的图标名称 →	否
`configure?`	在显示链接之前调用的函数，使您能够根据其 `context` 动态更改或隐藏链接。	否

返回值

该方法返回 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() hooks。

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

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

参数

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

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

返回值

hook 返回以下对象

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

有关更多信息，请参阅 PluginExtension。

Hooks

`usePluginComponent`

信息

在 Grafana >=v11.1.0 中可用。

此 react hook 可用于获取由插件使用唯一 ID 公开的单个 react 组件。插件可以使用 AppPlugin.exposeComponent() 方法公开组件。

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

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

参数

id - 标识组件的唯一 ID。

返回值

hook 返回以下对象

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 hook 可用于获取注册到某个扩展点的组件。组件扩展可用于渲染自定义 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 为前缀加上其插件 ID，而核心 Grafana 扩展点必须使用 `"grafana/"` 前缀。示例：`"grafana/user/profile/tab/v1"`	是
`limitPerPlugin?`	- 每个插件要返回的最大扩展数。默认情况下没有限制。	否

返回值

hook 返回以下对象（有关更多信息，请查看 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 hook 可用于获取注册到某个扩展点的链接。插件可以使用 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 为前缀加上其插件 ID，而核心 Grafana 扩展点必须使用 `"grafana/"` 前缀。示例：`"grafana/dashboard/panel/menu/v1"`	是
`context?`	您希望与扩展共享的任意对象。这可用于将数据传递给扩展。	否
`limitPerPlugin?`	每个插件要返回的最大扩展数。默认情况下没有限制。	否

返回值

hook 返回以下对象（有关更多信息，请查看 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 hook 可用于获取注册到某个扩展点的扩展（链接和组件）。

警告

此 hook 已弃用，将在 Grafana v12 中删除。请改用 usePluginLinks() 或 usePluginComponents() hooks。

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 为前缀加上其插件 ID，而核心 Grafana 扩展点必须使用 `"grafana/"` 前缀。示例：`"grafana/dashboard/panel/menu/v1"`	是
`context?`	您希望与扩展共享的任意对象。这可用于将数据传递给扩展。	否
`limitPerPlugin?`	每个插件要返回的最大扩展数。默认情况下没有限制。	否

返回值

hook 返回以下对象

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 ⚠️​

参数​

返回值​

Hooks​

usePluginComponent​

参数​

返回值​

示例​

usePluginComponents​

参数​

返回值​

示例​

另请参阅​

usePluginLinks​

参数​

返回值​

示例​

另请参阅​

usePluginExtensions ⚠️​

参数​

返回值​

Grafana 中的扩展点

方法

`addComponent`

参数

返回值

示例

另请参阅

`addLink`

参数

返回值

示例

`exposeComponent`

参数

返回值

示例

另请参阅

`getPluginExtensions` ⚠️

参数

返回值

Hooks

`usePluginComponent`

参数

返回值

示例

`usePluginComponents`

参数

返回值

示例

另请参阅

`usePluginLinks`

参数

返回值

示例

另请参阅

`usePluginExtensions` ⚠️

参数

返回值