dashboard-create-screen

仪表板创建屏幕技能

在 client/dashboard 中创建新屏幕，并自动发现和注册路由。

步骤 1：发现可用路由

首先，查找所有路由器文件并提取可用路由。

查找路由器文件

使用 Glob 查找路由器文件：

client/dashboard/app/router/*.tsx
client/dashboard/app/router/*.ts

从每个文件中提取路由

对于每个路由器文件，使用 Grep 提取路由信息。

查找导出的路由常量：

export\s+const\s+(\w+Route)\s*=\s*createRoute

提取父级关系：

getParentRoute:\s*\(\)\s*=>\s*(\w+Route)

提取路径片段：

path:\s*['"]([^'"]+)['"]

提取组件导入路径：

import\(\s*['"]([^'"]+)['"]\s*\)

构建路由信息

对于发现的每个路由，记录：

• 路由变量名（例如，siteBackupsRoute）
• 父路由名称（例如，siteRoute）
• 路径片段（例如，'backups'）
• 源文件路径
• 组件目录（从导入路径推导）

步骤 2：发现导航菜单（选择路由后）

在用户选择父路由后再发现菜单。根据路由的位置查找菜单。

确定菜单搜索路径

根据所选父路由的导入路径，确定菜单的搜索位置：

1. 从父路由的延迟导入中提取组件目录

   • 示例：import('../../sites/backups') → 在 client/dashboard/sites/ 中搜索
   • 示例：import('../../me/profile') → 在 client/dashboard/me/ 中搜索

2. 使用 Glob 在该区域查找菜单文件：

   client/dashboard/{area}/**/*-menu/index.tsx
   

3. 同时检查应用级菜单中的顶级路由：

   client/dashboard/app/*-menu/index.tsx
   

提取菜单信息

对于发现的每个菜单文件，使用 Grep 查找：

现有菜单项模式：

<ResponsiveMenu\.Item\s+to=

菜单中的路由引用：

to=\{?\s*[`'"/]([^`'"}\s]+)

这有助于了解菜单结构以及添加新项的位置。

菜单项模式

菜单项使用 ResponsiveMenu.Item：

<ResponsiveMenu.Item to="/path/to/screen">
	{ __( 'Menu Label' ) }
</ResponsiveMenu.Item>

条件菜单项会检查功能是否受支持：

{ siteTypeSupports.featureName && (
	<ResponsiveMenu.Item to={ `/sites/${ siteSlug }/feature` }>
		{ __( 'Feature' ) }
	</ResponsiveMenu.Item>
) }

步骤 3：收集用户输入

使用 AskUserQuestion 询问用户以下信息：

1. 父路由：按源文件分组展示发现的路由
2. 屏幕名称：小写并用连字符分隔（例如，custom-settings）
3. 路由路径：URL 路径片段（例如，custom-settings）
4. 页面标题：便于理解的标题（例如，Custom settings）
5. 页面描述（可选）：显示在标题下方的描述
6. 添加到导航菜单？：是或否

步骤 4：确定文件位置

根据所选父路由的导入路径，确定组件的创建位置。

模式： 如果父路由从 ../../sites/backups 导入，新屏幕应放在 client/dashboard/sites/{screen-name}/

对于 sites 区域： client/dashboard/sites/{screen-name}/index.tsx 对于 me 区域： client/dashboard/me/{screen-name}/index.tsx 对于其他区域： 遵循父路由导入路径的相同模式

步骤 5：创建组件文件

使用标准布局生成基础组件。

屏幕模板

import { __ } from '@wordpress/i18n';
import { PageHeader } from '../../components/page-header';
import PageLayout from '../../components/page-layout';

export default function {ComponentName}() {
	return (
		<PageLayout
			header={
				<PageHeader
					title={ __( '{PageTitle}' ) }
					description={ __( '{PageDescription}' ) }
				/>
			}
		>
			{/* Content goes here */}
		</PageLayout>
	);
}

步骤 6：注册路由

将路由定义添加到与父路由相同的路由器文件中。

路由定义模式

在文件中的其他路由导出项之后添加：

export const {routeName}Route = createRoute( {
	head: () => ( {
		meta: [
			{
				title: __( '{PageTitle}' ),
			},
		],
	} ),
	getParentRoute: () => {parentRoute},
	path: '{routePath}',
} ).lazy( () =>
	import( '{componentImportPath}' ).then( ( d ) =>
		createLazyRoute( '{routeId}' )( {
			component: d.default,
		} )
	)
);

接入路由树

找到 create*Routes() 函数中使用父路由的位置，并添加新路由。

对于独立路由（主区域路由的直接子路由）：

// Find the routes array (e.g., siteRoutes, meRoutes)
// Add the new route to the array
siteRoutes.push( newScreenRoute );

对于嵌套路由（功能路由的子路由）：

// Find where parent uses .addChildren()
// Add the new route to the children array
parentRoute.addChildren( [ existingRoute, newScreenRoute ] )

步骤 7：添加导航菜单项（可选）

如果用户要求添加导航菜单项，请将其添加到发现的菜单文件中。

定位目标菜单文件

根据路由所属区域，使用步骤 2 中发现的菜单：

1. 从父路由的导入路径中提取区域（例如，sites、me、plugins）
2. 使用 Glob 查找 client/dashboard/{area}/**/*-menu/index.tsx
3. 如果找到多个菜单，请让用户选择
4. 如果未找到区域专属菜单，则回退到 client/dashboard/app/primary-menu/index.tsx

添加菜单项

读取目标菜单文件，并找到合适的位置（通常在闭合的 </ResponsiveMenu> 标签之前）。

根据父路由路径 + 新页面路径构建路由路径：

• 如果父路径是 /sites/$siteSlug，页面路径是 analytics，则为 /sites/${ siteSlug }/analytics
• 如果父路径是 /me，页面路径是 api-keys，则为 /me/api-keys

插入菜单项：

<ResponsiveMenu.Item to={ `{fullRoutePath}` }>
	{ __( '{PageTitle}' ) }
</ResponsiveMenu.Item>

匹配现有模式

分析现有菜单项，以匹配其模式：

• 如果菜单使用带有 siteSlug 的模板字面量，请使用相同的模式
• 如果菜单使用简单字符串，请使用简单字符串
• 如果菜单项带有条件包装，请询问用户是否需要添加条件

条件菜单项

如果页面需要功能门控（检查菜单中类似的菜单项是否使用了条件）：

{ siteTypeSupports.{featureName} && (
	<ResponsiveMenu.Item to={ `/sites/${ siteSlug }/{routePath}` }>
		{ __( '{PageTitle}' ) }
	</ResponsiveMenu.Item>
) }

编码规范

遵循 client/dashboard/docs/ 中记录的编码规范。