Skip to main content

搜索操作指南

如何实现自己的搜索应用程序接口​

默认情况下，搜索插件提供了一个主要应用程序接口的实现，即搜索器负责与搜索后端对话，查询搜索结果。

在某些情况下，您可能需要根据自己的需要自行实施此 API，例如，如果您有自己的搜索后端需要与之对话。 本指南的目的是指导您如何分两步完成此操作。

  1. Implement the SearchApi interface according to your needs. typescript export class SearchClient implements SearchApi { // your implementation } 2. Override the API ref searchApiRef with your new implemented API in the App.tsx using ApiFactories. Read more about App APIs. typescript const app = createApp({ apis: [ // SearchApi createApiFactory({ api: searchApiRef, deps: { discovery: discoveryApiRef }, factory({ discovery }) { return new SearchClient({ discoveryApi: discovery }); }, }), ], });

如何为 TechDocs 文档编制索引​

TechDocs 插件支持与 Search 集成，这意味着它提供了一个可随时使用的默认整理器工厂。

本指南的目的是指导您如何注册....DefaultTechDocsCollatorFactory在您的应用程序中，这样您就可以获得 TechDocs 文档的索引。

如果您经历过搜索入门指南您应该有packages/backend/src/plugins/search.ts如果有，您可以继续按照本指南进行操作，如果没有，请先阅读入门指南。

  1. Import the DefaultTechDocsCollatorFactory from @backstage/plugin-search-backend-module-techdocs. typescript import { DefaultTechDocsCollatorFactory } from '@backstage/plugin-search-backend-module-techdocs'; 2. If there isn't an existing schedule you'd like to run the collator on, be sure to create it first. Something like.. typescript import { Duration } from 'luxon'; const every10MinutesSchedule = env.scheduler.createScheduledTaskRunner({ frequency: Duration.fromObject({ seconds: 600 }), timeout: Duration.fromObject({ seconds: 900 }), initialDelay: Duration.fromObject({ seconds: 3 }), }); 3. Register the DefaultTechDocsCollatorFactory with the IndexBuilder. typescript indexBuilder.addCollator({ schedule: every10MinutesSchedule, factory: DefaultTechDocsCollatorFactory.fromConfig(env.config, { discovery: env.discovery, logger: env.logger, tokenManager: env.tokenManager, }), });

现在，您应该可以将 TechDocs 文档索引到您选择的搜索引擎！

如果您希望用户在搜索时能够筛选出技术文档类型，可以更新您的SearchPage.tsx文件中的packages/app/src/components/search加入techdocs的值列表中的SearchType组件。

packages/app/src/components/search/SearchPage.tsx
<Paper className={classes.filters}>
  <SearchType
    values={['techdocs', 'software-catalog']}
    name="type"
    defaultValue="software-catalog"
  />
  {/* .. */}
</Paper>

请查看[将搜索整合到插件中]的相关文档(../../plugins/integrating-search-into-plugins.md#create-a-collator)，了解如何创建自己的整理器。

如何自定义软件目录或 TechDocs 索引中的字段​

有时，您可能希望能够控制哪些数据会进入目录整理器的搜索索引，或者自定义特定种类的数据。 您可以通过传递一个entityTransformer回调到DefaultCatalogCollatorFactory对于DefaultTechDocsCollatorFactory您可以简单地修改默认行为，甚至编写一个全新的文档(它仍应遵循一些必要的基本结构)。

authorization 和location不能通过entityTransformer修改，location只能通过locationTemplate修改。

packages/backend/src/plugins/search.ts
const catalogEntityTransformer: CatalogCollatorEntityTransformer = (
  entity: Entity,
) => {
  if (entity.kind === 'SomeKind') {
    return {
      // customize here output for 'SomeKind' kind
    };
  }

  return {
    // and customize default output
    ..defaultCatalogCollatorEntityTransformer(entity),
    text: 'my super cool text',
  };
};

indexBuilder.addCollator({
  collator: DefaultCatalogCollatorFactory.fromConfig(env.config, {
    discovery: env.discovery,
    tokenManager: env.tokenManager,
    entityTransformer: catalogEntityTransformer,
  }),
});

const techDocsEntityTransformer: TechDocsCollatorEntityTransformer = (
  entity: Entity,
) => {
  return {
    // add more fields to the index
    ..defaultTechDocsCollatorEntityTransformer(entity),
    tags: entity.metadata.tags,
  };
};

indexBuilder.addCollator({
  collator: DefaultTechDocsCollatorFactory.fromConfig(env.config, {
    discovery: env.discovery,
    tokenManager: env.tokenManager,
    entityTransformer: techDocsEntityTransformer,
  }),
});

如何限制在软件目录中搜索的内容​

软件目录包含大量有关组件、系统、组、用户和软件生态系统其他方面的信息。 不过，您可能并不总是希望每在用户搜索目录时出现的方面。 例子包括：

  • 如果你希望用户和组以不同的方式(或根本不需要)暴露在搜索中，可以使用 "用户 "或 "组 "类型的实体。

可以编写自己的拼版机以精确控制可搜索的内容，(或一个装饰设计师在这里和那里过滤掉一些东西)，但DefaultCatalogCollator由@backstage/plugin-catalog-backend也提供了一些配置！

packages/backend/src/plugins/search.ts
indexBuilder.addCollator({
  defaultRefreshIntervalSeconds: 600,
  collator: DefaultCatalogCollator.fromConfig(env.config, {
    discovery: env.discovery,
    tokenManager: env.tokenManager,
    filter: {
      kind: ['API', 'Component', 'Domain', 'Group', 'System', 'User'],
    },
  }),
});

如上图所示，可以添加目录实体过滤器来缩小搜索引擎索引目录实体的范围。

如何自定义搜索结果的高亮样式​

搜索结果中匹配词语的默认高亮样式是浏览器的默认样式，即<mark>如果您想自定义高亮显示术语的外观，可以按照 Backstage 的指南进行操作。自定义应用程序的外观和感觉来创建重载，并使用您喜欢的样式。

例如，以下内容将导致突出显示的术语以粗体和下划线显示：

const highlightOverride = {
  BackstageHighlightedSearchResultText: {
    highlight: {
      color: 'inherit',
      backgroundColor: 'inherit',
      fontWeight: 'bold',
      textDecoration: 'underline',
    },
  },
};

如何使用扩展功能呈现搜索结果​

搜索结果扩展可让您自定义用于呈现搜索结果项的组件，您可以提供自己的搜索结果项扩展，也可以使用插件包提供的扩展：

1.在插件包中提供扩展功能​

使用下面的示例，您可以提供一个扩展名作为默认结果项：

plugins/your-plugin/src/plugin.ts
import { createPlugin } from '@backstage/core-plugin-api';
import { createSearchResultListItemExtension } from '@backstage/plugin-search-react';

const plugin = createPlugin({ id: 'YOUR_PLUGIN_ID' });

export const YourSearchResultListItemExtension = plugin.provide(
  createSearchResultListItemExtension({
    name: 'YourSearchResultListItem',
    component: () =>
      import('./components').then(m => m.YourSearchResultListItem),
  }),
);

如果您的列表项接受道具，您可以扩展SearchResultListItemExtensionProps组件的特定道具：

export const YourSearchResultListItemExtension: (
  props: SearchResultListItemExtensionProps<YourSearchResultListItemProps>,
) => JSX.Element | null = plugin.provide(
  createSearchResultListItemExtension({
    name: 'YourSearchResultListItem',
    component: () =>
      import('./components').then(m => m.YourSearchResultListItem),
  }),
);

此外，您还可以定义一个谓词函数，用于接收结果并返回是否使用您的扩展来呈现该结果：

plugins/your-plugin/src/plugin.ts
import { createPlugin } from '@backstage/core-plugin-api';
import { createSearchResultListItemExtension } from '@backstage/plugin-search-react';

const plugin = createPlugin({ id: 'YOUR_PLUGIN_ID' });

export const YourSearchResultListItemExtension = plugin.provide(
  createSearchResultListItemExtension({
    name: 'YourSearchResultListItem',
    component: () =>
      import('./components').then(m => m.YourSearchResultListItem),
    // Only results matching your type will be rendered by this extension
    predicate: result => result.type === 'YOUR_RESULT_TYPE',
  }),
);

记得导出新扩展：

plugins/your-plugin/src/index.ts
export { YourSearchResultListItem } from './plugin.ts';

有关详细信息，请参阅创建搜索结果列表项目扩展名API 参考。

2. 在Backstage应用程序中使用扩展功能​

既然知道了搜索结果项是如何提供的，最后让我们来看看它们是如何使用的，例如，如何在应用程序中组成一个页面：

packages/app/src/components/searchPage.tsx
import React from 'react';

import { Grid, Paper } from '@material-ui/core';
import BuildIcon from '@material-ui/icons/Build';

import {
  Page,
  Header,
  Content,
  DocsIcon,
  CatalogIcon,
} from '@backstage/core-components';
import { SearchBar, SearchResult } from '@backstage/plugin-search-react';

// Your search result item extension
import { YourSearchResultListItem } from '@backstage/your-plugin';

// Extensions provided by other plugin developers
import { ToolSearchResultListItem } from '@backstage/plugin-explore';
import { TechDocsSearchResultListItem } from '@backstage/plugin-techdocs';
import { CatalogSearchResultListItem } from '@internal/plugin-catalog-customized';

// This example omits other components, like filter and pagination
const SearchPage = () => (
  <Page themeId="home">
    <Header title="Search" />
    <Content>
      <Grid container direction="row">
        <Grid item xs={12}>
          <Paper>
            <SearchBar />
          </Paper>
        </Grid>
        <Grid item xs={12}>
          <SearchResult>
            <YourSearchResultListItem />
            <CatalogSearchResultListItem icon={<CatalogIcon />} />
            <TechDocsSearchResultListItem icon={<DocsIcon />} />
            <ToolSearchResultListItem icon={<BuildIcon />} />
          </SearchResult>
        </Grid>
      </Grid>
    </Content>
  </Page>
);

export const searchPage = <SearchPage />;

重要：默认结果项扩展名应作为最后一个子项放置，因此只有在没有其他扩展名与正在呈现的结果相匹配时才能使用。 如果指定了非默认扩展名，则将使用 DefaultResultListItem 组件。

再举个例子，下面是一个搜索模式，它可以显示带有扩展名的结果：

packages/app/src/components/searchModal.tsx
import React from 'react';

import { DialogContent, DialogTitle, Paper } from '@material-ui/core';
import BuildIcon from '@material-ui/icons/Build';

import { DocsIcon, CatalogIcon } from '@backstage/core-components';
import { SearchBar, SearchResult } from '@backstage/plugin-search-react';

// Your search result item extension
import { YourSearchResultListItem } from '@backstage/your-plugin';

// Extensions provided by other plugin developers
import { ToolSearchResultListItem } from '@backstage/plugin-explore';
import { TechDocsSearchResultListItem } from '@backstage/plugin-techdocs';
import { CatalogSearchResultListItem } from '@internal/plugin-catalog-customized';

export const SearchModal = ({ toggleModal }: { toggleModal: () => void }) => (
  <>
    <DialogTitle>
      <Paper>
        <SearchBar />
      </Paper>
    </DialogTitle>
    <DialogContent>
      <SearchResult onClick={toggleModal}>
        <CatalogSearchResultListItem icon={<CatalogIcon />} />
        <TechDocsSearchResultListItem icon={<DocsIcon />} />
        <ToolSearchResultListItem icon={<BuildIcon />} />
        {/* As a "default" extension, it does not define a predicate function,
        so it must be the last child to render results that do not match the above extensions */}
        <YourSearchResultListItem />
      </SearchResult>
    </DialogContent>
  </>
);

还有其他更具体的搜索结果布局组件也接受结果项扩展，请查看它们的文档：搜索结果列表和搜索结果组.

如何迁移后端安装，以便与新的后端系统一起使用搜索功能​

最近，Backstage 维护人员宣布推出新的后端系统搜索插件现已迁移，以支持新的后端系统。 在本指南中，您将学习如何更新后端设置。

在 "packages/backend-next/index.ts "中，安装搜索插件[1]搜索引擎[2]以及搜索整理器/装饰器模块[3]:

import { searchPlugin } from '@backstage/plugin-search-backend/alpha';
import { searchModuleElasticsearchEngine } from '@backstage/plugin-search-backend-module-elasticsearch/alpha';
import { searchModuleCatalogCollator } from '@backstage/plugin-search-backend-module-catalog/alpha';
import { searchModuleTechDocsCollator } from '@backstage/plugin-search-backend-module-techdocs/alpha';
import { searchModuleExploreCollator } from '@backstage/plugin-search-backend-module-explore/alpha';

const backend = createBackend();
// [1] adding the search plugin to the backend
backend.add(searchPlugin());
// [2] (optional) the default search engine is Lunr, if you want to extend the search backend with another search engine.
backend.add(searchModuleElasticsearchEngine());
// [3] extending search with collator modules to start index documents, take in optional schedule parameters.
backend.add(searchModuleCatalogCollator());
backend.add(searchModuleTechDocsCollator());
backend.add(searchModuleExploreCollator());

backend.start();

要创建自己的整理器/装饰器模块，请使用搜索模块目录整理器为例，我们建议用插件包(如search-backend-module-<plugin-id>您还可以在 Alpha API 报告中找到可用的搜索引擎和整理/装饰模块文档：

搜索引擎模块

搜索拼贴/装饰模块