feat: export useMatchedRoute hook for theme (#2165)

* feat: export `useMatchRoute` feature hooks

* docs: update

* chore: rename

* docs: update

docs/theme/api.md

@@ -156,6 +156,28 @@ const Example = () => {
 };
 ```
 
+### useMatchedRoute
+
+- 作用：获取当前匹配的路由数据
+- 场景：搭配 getRouteMetaById API 可自定义获取页面元数据
+- 用法：
+
+```ts
+import { useMatchedRoute, getRouteMetaById, type IRouteMeta } from 'dumi';
+import useSWR from 'swr';
+
+export function useMeta() {
+  const route = useMatchedRoute();
+
+  useSWR(route.id, getRouteMetaById, {
+    onSuccess: (meta: IRouteMeta) => {
+      // do something with meta
+      globalThis.console.log(meta);
+    },
+  });
+}
+```
+
 ### useRouteMeta
 
 - 作用：获取当前路由的元数据

src/client/theme-api/index.ts

@@ -31,7 +31,7 @@ export { useLiveDemo } from './useLiveDemo';
 export { useLocale } from './useLocale';
 export { useNavData } from './useNavData';
 export { usePrefersColor } from './usePrefersColor';
-export { useRouteMeta } from './useRouteMeta';
+export { useMatchedRoute, useRouteMeta } from './useRouteMeta';
 export { useFullSidebarData, useSidebarData } from './useSidebarData';
 export { useSiteSearch } from './useSiteSearch';
 export { useTabMeta } from './useTabMeta';

src/client/theme-api/useRouteMeta.ts

@@ -75,9 +75,10 @@ function getCachedRouteMeta(route: IRoutesById[string]) {
 }
 
 /**
- * hook for get matched route meta
+ * hook for get matched route
+ * @internal internal use. Do not use in your production code.
  */
-export const useRouteMeta = () => {
+export const useMatchedRoute = () => {
   const { route } = useRouteData();
   const { pathname } = useLocation();
   const { clientRoutes } = useAppData();
@@ -95,12 +96,21 @@ export const useRouteMeta = () => {
 
     return ret;
   }, [clientRoutes.length, pathname]);
+
   const [matchedRoute, setMatchedRoute] = useState(getter);
-  const meta = getCachedRouteMeta(matchedRoute);
 
   useIsomorphicLayoutEffect(() => {
     setMatchedRoute(getter);
   }, [clientRoutes.length, pathname]);
 
-  return meta;
+  return matchedRoute;
+};
+
+/**
+ * hook for get matched route meta
+ */
+export const useRouteMeta = () => {
+  const route = useMatchedRoute();
+
+  return getCachedRouteMeta(route);
 };