声明式集成搜索插件

免责声明： > 声明式集成正处于试验阶段，不建议用于生产。

本指南可指导您尝试Search在声明式集成 Backstage 前端应用程序中。

主要概念

使用声明式集成，您可以在不编写代码的情况下自定义您的 Backstage 实例，请参阅以下内容RFC了解更多信息。

在新的前台系统中，所有扩展 Backstage 核心功能的东西都被称为扩展，因此扩展可以是任何东西，从应用程序接口到页面组件。

扩展产生输出工件，而这些工件是其他扩展所消耗的输入：

在上图中，一个SearchResultItem扩展会输出一个组件，该组件会作为输入注入到SearchPage"项目 "连接点。SearchPage则使用搜索结果项组成搜索页面元素，并输出路由路径和页面元素，以便将其作为输入连接到CoreRoutes最后CoreRoutes会在位置与搜索页面路径匹配时渲染页面元素。

简要提及的基本概念对于理解声明式版本的Search插件工作。

搜索插件

搜索插件是实现Backstage搜索功能的扩展集合。

安装

只需一个步骤即可开始使用Search插件，因此您只需在声明式集成中安装@backstage/plugin-catalog和@backstage/plugin-search软件包，(例如下一个应用程序):

yarn add @backstage/plugin-catalog @backstage/plugin-search

Search插件取决于Catalog API这就是我们必须安装@backstage/plugin-catalog包装也是。

扩展

Search插件提供以下功能扩展预置:

SearchApi：输出 "Search API "的具体实现，作为输入附加到 "Core "apis holder；SearchPage：输出代表高级 "Search "页面接口的组件，该扩展希望将 "Search "结果项组件作为输入，以自定义方式使用它们呈现结果；SearchNavItem：这是一个扩展，输出代表主应用程序侧边栏中 "Search "项的数据，换句话说，它将侧边栏项输入到 "Core "导航扩展。

配置

Search扩展名可通过app-config.yaml文件中的app.extensions字段，使用分机 ID 作为配置密钥：

禁用搜索页面扩展_示例

# app-config.yaml
app:
  extensions:
    - page:search: false # ✨
    - nav-item:search: false # ✨

设置搜索侧边栏项目标题_示例

# app-config.yaml
app:
  extensions:
    - nav-item:search: # ✨
        config:
          title: 'Search Page'

已知限制： > 目前还无法在侧边栏项目中打开模式，也无法通过配置文件配置不同的图标，但维护者已经在考虑这个问题。

定制

插件开发人员可以使用createSearchResultItemExtension工厂提供的@backstage/plugin-search-react为建立自己的定制Search结果项目扩展。

创建自定义 "TechDocsSearchResultItemExtension"_示例

// plugins/techdocs/alpha.tsx
import { createSearchResultListItemExtension } from '@backstage/plugin-search-react/alpha';

/** @alpha */
export const TechDocsSearchResultListItemExtension =
  createSearchResultListItemExtension({
    id: 'techdocs',
    configSchema: createSchemaFromZod(z =>
      z.object({
        noTrack: z.boolean().default(false),
        lineClamp: z.number().default(5),
      }),
    ),
    predicate: result => result.type === 'techdocs',
    component: async ({ config }) => {
      const { TechDocsSearchResultListItem } = await import(
        './components/TechDocsSearchResultListItem'
      );
      return props => <TechDocsSearchResultListItem {...props} {...config} />;
    },
  });

在上面的代码段中，一位插件开发者提供了一个自定义组件，用于呈现 "techdocs "类型的搜索结果。 默认情况下，一旦@backstage/plugin-techdocs这意味着采用者无需通过配置文件手动启用扩展。

当 Backstage 采用者不想使用自定义的TechDocs后的搜索结果项。TechDocs他们可以通过Backstage配置文件禁用该插件：

# app-config.yaml
app:
  extensions:
    - plugin.search.result.item.techdocs: false # ✨

由于向扩展工厂提供了配置模式，因此 Backstage 的采用者将能够自定义TechDocs搜索结果线夹默认为 3，同时禁用自动分析事件跟踪:

# app-config.yaml
app:
  extensions:
    - plugin.search.result.item.techdocs:
        config: # ✨
          noTrack: true
          lineClamp: 3

createSearchResultItemExtension函数返回 Backstage 的扩展表示，如下所示：

{
  "$$type": "@backstage/Extension", // [1]
  "id": "plugin.search.result.item.techdocs", // [2]
  "at": "plugin.search.page/items", // [3]
  "inputs": {} // [4️]
  "output": { // [5️]
    "item": {
      "$$type": "@backstage/ExtensionDataRef",
      "id": "plugin.search.result.item.data",
      "config": {}
    }
  },
  "configSchema": { // [6️]
    "schema": {
      "type": "object",
      "properties": {
        "noTrack": {
          "type": "boolean",
          "default": false
        },
        "lineClamp": {
          "type": "number",
          "default": 5
        }
      },
      "additionalProperties": false,
      "$schema": "http://json-schema.org/draft-07/schema#"
    }
  },
  "disabled": false, // [7️]
}

在此对象中，您可以清楚地看到安装自定义扩展后会发生什么：

• [1] $$type: declares that the object represents an extension; * [2] id: Is a unique identification for the extension, the plugin.search.result.item.techdocs is the key used to configure the extension in the app-config.yaml file; * [3] at: It represents the extension attachment point, so the value plugin.search.page/items says that the TechDocs's search result item output will be injected as input on the "items" attachment expected by the search page extension; * [4] inputs: in this case is an empty object because this extension doesn't expect inputs; * [5] output: Object representing the artifact produced by the TechDocs result item extension, on the example, it is a react component reference; * [6] configSchema: represents the TechDocs search result item configuration definition, this is the same schema that adopters will use for customizing the extension via app-config.yaml file; * [7] disable: Says that the result item extension will be enable by default when the

要完成创建自定义搜索结果项扩展的开发周期，我们应通过以下方式提供扩展TechDocs插件：

// plugins/techdocs/alpha.tsx
import { createPlugin } from "@backstage/frontend-plugin-api";

// plugins should be always exported as default
export default createPlugin({
  id: 'techdocs'
  extensions: [TechDocsSearchResultItemExtension]
})

以下是plugins/techdocs/alpha.tsx最终版本，您还可以查看实际执行的自定义TechDocs搜索结果项目：

// plugins/techdocs/alpha.tsx
import { createPlugin } from '@backstage/frontend-plugin-api';
import { createSearchResultListItemExtension } from '@backstage/plugin-search-react/alpha';

/** @alpha */
export const TechDocsSearchResultListItemExtension =
  createSearchResultListItemExtension({
    id: 'techdocs',
    configSchema: createSchemaFromZod(z =>
      z.object({
        noTrack: z.boolean().default(false),
        lineClamp: z.number().default(5),
      }),
    ),
    predicate: result => result.type === 'techdocs',
    component: async ({ config }) => {
      const { TechDocsSearchResultListItem } = await import(
        './components/TechDocsSearchResultListItem'
      );
      return props => <TechDocsSearchResultListItem {...props} {...config} />;
    },
  });

/** @alpha */
export default createPlugin({
  // plugins should be always exported as default
  id: 'techdocs',
  extensions: [TechDocsSearchResultListItemExtension],
});

未来的改进机会

Backstage 维护人员目前正在开发扩展替换功能，随着这一版本的发布，采用者也将可以替换插件提供的扩展，请继续关注本文档的未来更新。

第一版SearchPage扩建工程为Search如果您也想就这一想法与插件维护者合作，请立即打开问题并提交拉取请求，我们非常欢迎您的贡献！