自定义视图

视图是构成管理面板的独立页面，例如仪表盘、列表视图和编辑视图。自定义管理面板最强大的方式之一就是创建自定义视图。这些自定义组件既可以替换内置视图，也可以是完全新的页面。

管理面板中有四种类型的视图：

要替换为你自己的自定义视图，首先确定与你目标相符的作用范围，查阅可用组件列表，然后编写你的React组件。

配置

替换视图

要自定义视图，可以在 Payload 配置 中使用 admin.components.views 属性。这是一个对象，包含你想要自定义的每个视图的键名。每个键名对应你想要自定义的视图。

可用键名的具体列表取决于你要自定义的视图范围，可能是 根视图、集合视图 或 全局视图。无论范围如何，其原理都是相同的。

以下是一个替换内置视图的示例：

import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  admin: {
    components: {
      views: {
        // highlight-start
        dashboard: {
          Component: '/path/to/MyCustomDashboard',
        },
        // highlight-end
      },
    },
  },
})

如需更精细的控制，可以传入配置对象而非直接路径。Payload 为每个视图暴露了以下属性：

属性描述
Component *传入当用户导航到此路由时应渲染的组件路径。
path *任何有效的 URL 路径或 path-to-regexp 能理解的路径数组。
exact布尔值。为 true 时，仅当路径与 usePathname() 完全匹配时才生效。
strict为 true 时，带有尾部斜杠的路径仅会匹配同样带有尾部斜杠的 location.pathname。当路径名中包含其他 URL 片段时，此设置无效。
sensitive为 true 时，路径将区分大小写进行匹配。
meta应用于管理面板中此视图的页面元数据覆盖。更多详情。

* 星号表示该属性为必填项。

添加新视图

要在 Admin Panel 中添加_新_视图，只需在 views 对象中添加你自己的键。这适用于所有视图作用域。

新视图至少需要包含 Component 和 path 属性：

import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  admin: {
    components: {
      views: {
        // highlight-start
        myCustomView: {
          Component: '/path/to/MyCustomView#MyCustomViewComponent',
          path: '/my-custom-view',
        },
        // highlight-end
      },
    },
  },
})

注意： 路由是级联的，除非明确指定 exact 属性，否则它们会匹配_以_路由路径_开头_的 URL。 这在创建应用程序中的通配路由时很有帮助。或者，你也可以在父路由之前定义嵌套路由。

构建自定义视图

自定义视图本质上是在页面级别渲染的自定义组件。自定义视图既可以替换现有视图，也可以添加全新的视图。无论你自定义的是哪种类型的视图，流程大体相同。

要了解如何构建自定义视图，请先阅读构建自定义组件指南。准备好自定义组件后，就可以将其用作自定义视图。

import type { CollectionConfig } from 'payload'

export const MyCollectionConfig: CollectionConfig = {
  // ...
  admin: {
    components: {
      views: {
        // highlight-start
        edit: {
          Component: '/path/to/MyCustomView', // highlight-line
        },
        // highlight-end
      },
    },
  },
}

默认属性

你的自定义视图将会接收以下属性：

Prop描述
initPageResult包含 req、payload、permissions 等属性的对象
clientConfig客户端配置对象。更多详情
importMap导入映射对象
params包含动态路由参数的对象
searchParams包含搜索参数的对象
doc正在编辑的文档。仅在文档视图中可用。更多详情
i18n国际化对象
payloadPayload类

注意： 某些视图可能会接收额外的属性，例如集合视图和全局视图。详情请参阅相关章节。

以下是自定义视图组件的示例：

import type { AdminViewServerProps } from 'payload'

import { Gutter } from '@payloadcms/ui'
import React from 'react'

export function MyCustomView(props: AdminViewServerProps) {
  return (
    <Gutter>
      <h1>自定义默认根视图</h1>
      <p>此视图使用默认模板。</p>
    </Gutter>
  )
}

提示： 为了保持一致的布局和导航，你可以考虑使用内置的模板来包裹你的自定义视图。

视图模板

你的自定义根视图可以选择使用 Payload 提供的模板。其中最常用的是 Default Template（默认模板），它提供了基本的布局和导航功能。

以下是如何在自定义视图中使用 Default Template 的示例：

import type { AdminViewServerProps } from 'payload'

import { DefaultTemplate } from '@payloadcms/next/templates'
import { Gutter } from '@payloadcms/ui'
import React from 'react'

export function MyCustomView({
  initPageResult,
  params,
  searchParams,
}: AdminViewServerProps) {
  return (
    <DefaultTemplate
      i18n={initPageResult.req.i18n}
      locale={initPageResult.locale}
      params={params}
      payload={initPageResult.req.payload}
      permissions={initPageResult.permissions}
      searchParams={searchParams}
      user={initPageResult.req.user || undefined}
      visibleEntities={initPageResult.visibleEntities}
    >
      <Gutter>
        <h1>自定义默认根视图</h1>
        <p>此视图使用了 Default Template。</p>
      </Gutter>
    </DefaultTemplate>
  )
}

保护自定义视图

所有自定义视图默认都是公开的。你需要自行保护你的自定义视图。如果你的视图要求用户登录或拥有特定访问权限，你应该在视图组件中自行处理这些逻辑。

以下是保护自定义视图的一种方式：

import type { AdminViewServerProps } from 'payload'

import { Gutter } from '@payloadcms/ui'
import React from 'react'

export function MyCustomView({ initPageResult }: AdminViewServerProps) {
  const {
    req: { user },
  } = initPageResult

  if (!user) {
    return <p>你必须登录才能查看此页面。</p>
  }

  return (
    <Gutter>
      <h1>自定义默认根视图</h1>
      <p>此视图使用了 Default Template。</p>
    </Gutter>
  )
}

根视图

根视图是管理面板的主要视图。这些视图直接位于/admin路由下，例如仪表盘或账户视图。

要替换根视图为你自己的实现，或者创建全新的视图，可以在Payload配置的根级别使用admin.components.views属性：

import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  admin: {
    components: {
      views: {
        // highlight-start
        dashboard: {
          Component: '/path/to/Dashboard',
        },
        // highlight-end
        // 其他可选配置包括:
        // - account
        // - [key: string]
        // 详见下文
      },
    },
  },
})

关于如何构建自定义视图的详细信息，包括所有可用属性，请参阅构建自定义视图。

可用选项如下：

属性描述
account账户视图用于显示当前登录用户的账户页面。
dashboard管理面板的主页。
[key]任何其他键名都可以用来添加全新的根视图。更多详情。

集合视图

集合视图（Collection Views）是指位于 /collections 路由下的视图，例如集合列表视图和文档编辑视图。

要替换集合视图为自定义视图，或创建全新的视图，可以使用集合配置中的 admin.components.views 属性：

import type { CollectionConfig } from 'payload'

export const MyCollectionConfig: CollectionConfig = {
  // ...
  admin: {
    components: {
      views: {
        // highlight-start
        edit: {
          default: {
            Component: '/path/to/MyCustomCollectionView',
          },
        },
        // highlight-end
        // 其他可用选项包括：
        // - list
        // - [key: string]
        // 详见下文
      },
    },
  },
}

提示： edit 键由多个嵌套视图组成，这些视图被称为文档视图（Document Views），它们与同一集合文档相关联。了解更多。

可用选项如下：

属性描述
edit编辑视图对应任意集合中的单个文档，由多个嵌套视图组成。了解更多。
list列表视图用于显示任意集合的文档列表。了解更多。
[key]可以使用任意其他键来添加全新的集合视图。了解更多。

关于如何构建自定义视图的详细信息，包括所有可用属性，请参阅构建自定义视图。

全局视图

全局视图（Global Views）是指位于 /globals 路由下的视图，例如编辑视图（Edit View）。

要替换全局视图为你自定义的视图或创建全新的视图，可以在全局配置中使用 admin.components.views 属性：

import type { SanitizedGlobalConfig } from 'payload'

export const MyGlobalConfig: SanitizedGlobalConfig = {
  // ...
  admin: {
    components: {
      views: {
        // highlight-start
        edit: {
          default: {
            Component: '/path/to/MyCustomGlobalView',
          },
        },
        // highlight-end
        // 其他可选配置包括：
        // - [key: string]
        // 详见下文
      },
    },
  },
}

提醒： edit 键由多个嵌套视图（称为文档视图）组成，这些视图都关联到同一个全局文档。更多详情请参阅文档视图。

可用的配置选项如下：

属性描述
edit编辑视图表示任意全局文档的单个文档视图，由多个嵌套视图组成。更多详情请参阅文档视图。
[key]可以使用任意其他键来添加全新的全局视图。更多详情请参阅添加新视图。

关于如何构建自定义视图的详细信息，包括所有可用的属性，请参阅构建自定义视图。