跳到主要内容

将插件从 Grafana 9.x 版本迁移到 10.x 版本

按照以下说明将插件从 Grafana 9.x 版本迁移到 10.x 版本。

验证插件在 React 18 下的行为​

Grafana 10 包含我们对 React 18 的升级以及新 React 客户端渲染 API 的使用。这些更改已通过 PR 64428 合并到核心 grafana 仓库中。

尽管这些更新带来了许多显著的好处，但它们可能会影响您的插件工作方式。特别是，围绕改进 useEffect 时序一致性以及状态更新的自动批处理所做的更改可能会导致意外的副作用。

推荐操作

数据帧字段值现在仅为数组​

在 Grafana 10 中，数据帧中的值现在作为简单的 JavaScript 数组进行管理（参见 PR #66480）。不再需要将值包装在 Vector<T> 实现中。c

大多数针对 9.x 的代码将继续正常工作。一个例外是现有代码直接实现了 Vector<T> 而非继承或使用基类的情况。在这种情况下，代码应该返回一个数组或继承 FunctionalVector<T>。所有 Vector 实现已被弃用，并将在未来移除。

在编写应在 9.x 上运行的插件时，请继续使用 Vector 接口。在这种情况下，当针对 10+ 版本时，您现在可以使用简单的数组而不是包装类。

为了使此过渡无缝，我们使用了原始 JavaScript 罪孽™。也就是说，我们通过多个 Vector 方法 扩展了原生的 Array prototype。

更新到 React Router v6​

从 Grafana 10 开始，插件可以使用 react-router 的 v6 版本。总的来说，react-router v6 旨在简化路由配置，并为开发者提供更灵活、更直观的 API。

如果您当前的插件版本需要与 Grafana v9 保持兼容性，那么您可以在 Grafana v10 中继续使用 react-router@v5。两个版本都可用于插件。但是，我们强烈建议开发者尽快更新其插件以使用 react-router 的 v6 版本，因为 v5 版本将在 Grafana v11 中弃用并随后移除。

有关更多一般信息，请参阅 官方 React Router v5 到 v6 迁移指南。

使用 @grafana/create-plugin 更新​

按照以下步骤开始在您的插件中使用 react-router v6

通过在 <project-root>/.cprc.json 中设置以下功能标志来启用使用 react-router@v6

<项目根目录>/.cprc.json
{
  "features": {
    "useReactRouterV6": true
  }
}

现在使用 create-plugin 工具更新构建配置

npx @grafana/create-plugin@latest update

更新构建配置后，您可能需要对插件进行额外更新。为此，请按照以下步骤操作

2. 使用 <Routes> 替代 <Switch>​

src/Routes.tsx
// Using <Routes> instead of <Switch> in `react-router` v6
import { Routes } from 'react-router-dom';

// ...

return (
  <Routes>
    <Route path="/" element={<Home />} />
  </Routes>
);

3. 从 <Route> 组件中移除 exact 属性​

src/Routes.tsx
return (
  <Routes>
    {/* BAD (Until v5) */}
    <Route exact path="/" element={<Home />} />

    {/* GOOD (From v6) */}
    {/* (Routes are "exact" by default, you need to use the "*" to match sub-routes) */}
    <Route path="/" element={<Home />} />
  </Routes>
);

4. 修复 location service 方法导致的测试失败​

当使用 locationService.replace()、locationService.push() 或来自 @grafana/runtime 的类似方法时，迁移到 React Router v6 后您的测试可能会失败。通过在测试中使用 <LocationServiceProvider /> 组件（在 Grafana 11.2.0 中引入）为 location service 创建一个 provider 来解决此问题。

test/test-utils.tsx
import { locationService, LocationServiceProvider } from '@grafana/runtime';
import React, { useEffect, useState } from 'react';
import { Router } from 'react-router-dom';

const history = locationService.getHistory();

export function TestRoutesProvider({ children }: { children: React.ReactNode }) {
  const [location, setLocation] = useState(history.location);

  useEffect(() => {
    history.listen(setLocation);
  }, []);

  return (
    <LocationServiceProvider service={locationService}>
      <Router navigator={history} location={location}>
        {children}
      </Router>
    </LocationServiceProvider>
  );
}

5. 按照原始的 react-router 迁移指南进行更深入的更改​

访问 官方 react-router v5 到 v6 迁移指南 了解更多信息。