Skip to main content

前台系统命名模式

**注意：新的前台系统处于alpha阶段，只有少数插件支持。

这些命名模式是前端系统中必须遵守的，它们有助于我们在不同软件包中保持导出和 ID 的一致性，并使我们更容易理解导出和 ID 的用途和意图。

原则上，除了插件和扩展 ID 应使用 kebab 大小写外，所有名称都应使用驼峰大小写。

插件​

| 说明 | 模式 | 示例 | | ----------- | ------------ | ------------------------------------- | | ID |'<id>'|'catalog','user-settings'| 符号<id>Plugin|catalogPlugin,userSettingsPlugin|

例如

// This declaration is only for internal usage in tests. This could also be a direct default export.
export const userSettingsPlugin = createPlugin({
  id: 'user-settings',
  ...
})

// The plugin instance should be the default export of the package, typically this is placed in src/index.ts
export { userSettingsPlugin as default } from './plugin';

请注意，虽然我们为插件实例使用了这种命名模式，但这仅用于包的内部使用。 插件始终作为插件包的默认导出导出。

扩展​

| 说明 | 模式 | 示例 | | ----------- | ------------------------------- | ------------------------------------------------------------------- | | 创建者 |create<Kind>Extension|createPageExtension,createEntityCardExtension| | ID | |[<kind>:]<namespace>[/<name>]|'core.nav','page:user-settings','entity-card:catalog/about'| 符号<namespace>[<Name>][<Kind>]|coreNav,userSettingsPage,catalogAboutEntityCard|

创建新扩展时，您从不直接提供 ID，而是间接或直接提供构成 ID 的种类、命名空间和名称部分。 种类总是由用于创建扩展的扩展创建函数提供，唯一的例外是使用createExtension插件提供的任何扩展名默认都会将其命名空间设置为插件 ID，因此通常只有在要覆盖现有扩展名时才需要提供明确的命名空间。 名称也是可选的，主要用于区分同类和命名空间的多个扩展名。 如果插件不需要区分同类的不同扩展名，则可以省略名称。

例如

// This is an extension creator that is used to create an extension of the 'page' kind.
export function createPageExtension(options) {
  return createExtension({
    kind: 'page', // Kinds are kebab-case
    // ...options
  });
}

// The namespace is inferred from the plugin ID, in this case 'catalog'
// The final ID for this extension will be 'page:catalog/entity'
const catalogEntityPage = createPageExtension({
  name: 'entity',
  // ...
});

// The name is omitted, because the catalog plugin only provides a single extension of this kind
// The final ID for this extension will be 'search-result-list-item:catalog'
const catalogSearchResultListItem = createSearchResultListItemExtension({
  // ...
});

// Note that the extensions themselves are not exported, only the plugin instance
export const catalogPlugin = createPlugin({
  id: 'catalog',
  extensions: [catalogEntityPage, catalogSearchResultListItem /* ... */],
});

扩展数据​

| 描述 | 模式 | 示例 | | -------------------- | ------------------------------------- | ----------------------------------------------------------------------------- | | 接口 |<Name>ExtensionData|SearchResultItemExtensionData| | 单机版参考资料<name>ExtensionDataRef|searchResultItemExtensionDataRef| 独立 ID<namespace>.<name>|'search.search-result-item'| | 分组参考<group>ExtensionData.<name>|coreExtensionData.reactElement,catalogFilterExtensionData.functionFilter| 分组 ID<group>.<name>|'core.react-element','catalog-filter.function-filter'| 创建者参考create<Kind>Extension.<name>DataRef|createGraphiQLEndpointExtension.endpointDataRef| 创建者 ID<namespace>.<kind>.<name>|'graphiql.graphiql-endpoint.endpoint'|

扩展数据引用可以根据预期用途以几种不同的方式定义，下文将一一介绍。

独立扩展数据​

定义扩展数据最简单的方法是独立引用。 当你想导出一个与特定扩展类型没有紧密联系的单一引用时，这种方法非常有用。 因为这会为每个引用创建一个额外的导出，所以在可能的情况下，我们更倾向于使用其他两种定义扩展数据的方法。

// A separate named type declaration is only needed for bespoke complex extension data types
export interface SearchResultItemExtensionData {
  /* ... */
}

export const searchResultItemExtensionDataRef =
  createExtensionDataRef<SearchResultItemExtensionData>(
    'search.search-result-item',
  );

分组扩展数据​

这种定义扩展数据的方式与独立定义扩展数据的方式类似，但它用于导出多个分组的扩展数据供一般使用。 这样可以避免单独导出，并有助于更容易地发现相关的扩展数据引用。 分组的名称一般应与导出包的命名空间(通常是插件 ID)相同。 如果分组需要更具体，则应在前缀中加上命名空间。

export const coreExtensionData = {
  reactElement: createExtensionDataRef<ReactElement>('core.react-element'),
  routePath: createExtensionDataRef<string>('core.route-path'),
};

扩展创建器 扩展数据​

当扩展数据仅由特定扩展创建者生成时，这是一种定义扩展数据的便捷方法。 它避免了额外的导出，并清楚地表明该数据属于这一特定类型的扩展。

export function createGraphiQLEndpointExtension(options) {
  /* ... */
}

// Use a TypeScript namespace to merge the extension data references with the extension creator
export namespace createGraphiQLEndpointExtension {
  export const endpointDataRef = createExtensionDataRef</* ... */>(
    'graphiql.graphiql-endpoint.endpoint',
  );
}

扩展输入​

扩展输入法没有针对所有类型输入的命名模式，但在一些特定的使用情况下，我们鼓励使用可识别的输入名称。

| 名称 | 说明 | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | |children| 扩展输入，可接受coreExtensionData.reactElement数据，而不是其他任何东西，其使用方式等同于children属性。