umbraco-search-provider

Umbraco 搜索提供程序

这是什么？

搜索提供程序可将自定义搜索功能集成到 Umbraco 的后台搜索栏中。它让用户能够同时搜索自定义数据源以及内置的内容、媒体和成员。该提供程序实现一个 search 方法，返回与用户查询匹配的分页结果。

文档

实现前务必获取最新文档：

• 扩展类型：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types
• 基础知识：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation
• 扩展注册表：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-registry

相关基础技能

• Repository 模式：用于搜索提供程序中的数据访问

  • 参考技能：umbraco-repository-pattern

• Context API：用于在提供程序中访问上下文

  • 参考技能：umbraco-context-api

工作流

1. 获取文档 - 对上述 URL 使用 WebFetch
2. 提问 - 要搜索哪些数据？要返回哪些字段？是否需要自定义结果显示？
3. 生成文件 - 根据最新文档创建清单和提供程序类
4. 说明 - 展示创建的内容以及测试方法

最简示例

清单（manifests.ts）

import type { ManifestSearchProvider } from '@umbraco-cms/backoffice/extension-registry';

const manifest: ManifestSearchProvider = {
  type: 'searchProvider',
  alias: 'My.SearchProvider',
  name: 'My Search Provider',
  api: () => import('./my-search-provider.js'),
  meta: {
    label: 'My Items',
  },
};

export const manifests = [manifest];

提供程序实现（my-search-provider.ts）

import type { UmbSearchProvider, UmbSearchResultItemModel, UmbSearchRequestArgs } from '@umbraco-cms/backoffice/search';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';

export class MySearchProvider extends UmbControllerBase implements UmbSearchProvider {
  constructor(host: UmbControllerHost) {
    super(host);
  }

  async search(args: UmbSearchRequestArgs) {
    const { query } = args;

    // Fetch results from your data source
    const results = await this.#fetchResults(query);

    return {
      data: {
        items: results,
        total: results.length,
      },
    };
  }

  async #fetchResults(query: string): Promise<UmbSearchResultItemModel[]> {
    // Your search logic here - API call, local filtering, etc.
    const response = await fetch(`/api/my-items/search?q=${encodeURIComponent(query)}`);
    const data = await response.json();

    return data.items.map((item: any) => ({
      entityType: 'my-entity',
      unique: item.id,
      name: item.name,
      icon: 'icon-document',
      href: `/section/my-section/workspace/my-workspace/edit/${item.id}`,
    }));
  }
}

export default MySearchProvider;

搜索结果项模型

// Each result must conform to UmbSearchResultItemModel
interface UmbSearchResultItemModel {
  entityType: string;    // Entity type identifier
  unique: string;        // Unique ID
  name: string;          // Display name
  icon?: string | null;  // Icon to display
  href: string;          // URL to navigate when clicked
}

使用 Repository 的提供程序

import type { UmbSearchProvider, UmbSearchResultItemModel, UmbSearchRequestArgs } from '@umbraco-cms/backoffice/search';
import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
import { MyRepository } from './my-repository.js';

export class MySearchProvider extends UmbControllerBase implements UmbSearchProvider {
  #repository: MyRepository;

  constructor(host: UmbControllerHost) {
    super(host);
    this.#repository = new MyRepository(this);
  }

  async search(args: UmbSearchRequestArgs) {
    const { data } = await this.#repository.search(args.query);

    const items: UmbSearchResultItemModel[] = data?.items.map((item) => ({
      entityType: 'my-entity',
      unique: item.id,
      name: item.name,
      icon: item.icon ?? 'icon-document',
      href: `/section/my-section/workspace/my-workspace/edit/${item.id}`,
    })) ?? [];

    return {
      data: {
        items,
        total: data?.total ?? 0,
      },
    };
  }
}

export default MySearchProvider;

使用 Context 进行搜索（例如，从特定位置搜索）

async search(args: UmbSearchRequestArgs) {
  const { query, searchFrom } = args;

  // searchFrom contains the entity to search from (if specified)
  const parentId = searchFrom?.unique;

  const results = await this.#fetchResults(query, parentId);

  return {
    data: {
      items: results,
      total: results.length,
    },
  };
}

搜索请求参数

属性	描述
query	用户输入的搜索词
searchFrom	可选的搜索起始实体（用于范围搜索）

就是这样！务必获取最新文档，保持示例简洁，并生成完整、可运行的代码。