route-hook.ts

Overview

The route-hook.ts file provides a collection of React hooks tailored for managing and interacting with URL routes and query parameters within a React application that uses the umi routing framework. These hooks facilitate extracting specific segments of the URL path, retrieving and setting query parameters (notably for pagination and knowledge-related identifiers), and performing navigation with state management.

This file primarily aims to abstract and simplify common routing and query parameter operations related to a knowledge base or dataset context, enhancing code reuse and readability across the application.

Detailed Documentation

Enumerations

SegmentIndex

export enum SegmentIndex {
  Second = '2',
  Third = '3',
}

• Purpose: Defines indexes (as string literals) to access specific segments of a URL path.

• Usage: Used by hooks that extract particular segments of the URL pathname.

• Values:

  • Second: Represents the second segment in the path (index 2).

  • Third: Represents the third segment in the path (index 3).

Hooks

useSegmentedPathName

export const useSegmentedPathName = (index: SegmentIndex) => string

• Purpose: Extracts and returns a segment of the current URL pathname based on the provided index.

• Parameters:

  • index (SegmentIndex): The segment index to extract from the path.

• Returns: The path segment as a string or an empty string if the segment does not exist.

• Usage Example:

  const secondSegment = useSegmentedPathName(SegmentIndex.Second);
  console.log(secondSegment); // e.g., "knowledge" if path is /app/knowledge/dataset
  

• Implementation Detail: The pathname string is split by '/' and the segment at the given index is returned.

useSecondPathName

export const useSecondPathName = () => string

• Purpose: Convenience hook that returns the second segment of the current URL pathname.

• Returns: The second path segment as a string or empty string if not present.

• Usage Example:

  const secondSegment = useSecondPathName();
  

• Internally calls: useSegmentedPathName(SegmentIndex.Second)

useThirdPathName

export const useThirdPathName = () => string

• Purpose: Convenience hook that returns the third segment of the current URL pathname.

• Returns: The third path segment as a string or empty string if not present.

• Usage Example:

  const thirdSegment = useThirdPathName();
  

• Internally calls: useSegmentedPathName(SegmentIndex.Third)

useGetKnowledgeSearchParams

export const useGetKnowledgeSearchParams = () => {
  documentId: string;
  knowledgeId: string;
}

• Purpose: Extracts knowledge-related query parameters from the current URL.

• Returns: An object containing:

  • documentId: String value of the DocumentId query parameter; empty string if not present.

  • knowledgeId: String value of the KnowledgeId query parameter; empty string if not present.

• Usage Example:

  const { documentId, knowledgeId } = useGetKnowledgeSearchParams();
  console.log(documentId, knowledgeId);
  

• Implementation Detail: Uses useSearchParams hook from umi to access URL search parameters.

useNavigateWithFromState

export const useNavigateWithFromState = () => (path: string) => void

• Purpose: Returns a callback function to navigate to a specified path, while preserving the from state indicating the current path.

• Returns: A function that accepts a path string and navigates to it with state: { from: path }.

• Usage Example:

  const navigateWithFrom = useNavigateWithFromState();
  navigateWithFrom('/knowledge/dataset');
  

• Implementation Detail: Uses useNavigate from umi and React's useCallback for memoization.

useNavigateToDataset

export const useNavigateToDataset = () => () => void

• Purpose: Returns a callback function that navigates to the dataset page of a knowledge base, using the current knowledgeId query parameter.

• Returns: A function that triggers navigation to /knowledge/dataset?id=${knowledgeId}.

• Usage Example:

  const navigateToDataset = useNavigateToDataset();
  navigateToDataset();
  

• Implementation Detail:

  • Retrieves knowledgeId via useGetKnowledgeSearchParams.

  • Uses useNavigate for navigation.

  • Constructs the URL dynamically.

useGetPaginationParams

export const useGetPaginationParams = () => {
  page: string | number;
  size: string | number;
}

• Purpose: Retrieves pagination-related query parameters (page and size) from the URL.

• Returns: An object containing:

  • page: Current page number as a string or 1 if not specified.

  • size: Page size as a string or 10 if not specified.

• Usage Example:

  const { page, size } = useGetPaginationParams();
  console.log(page, size);
  

• Implementation Detail: Uses useSearchParams to read URL search parameters.

useSetPaginationParams

export const useSetPaginationParams = () => {
  setPaginationParams: (page?: number, pageSize?: number) => void;
  page: number;
  size: number;
}

• Purpose: Provides functionality to update pagination parameters (page and size) in the URL's query string and returns the current pagination values.

• Returns:

  • setPaginationParams: A function to set pagination parameters.

    • Parameters:

      • page (optional, default = 1): The page number to set.

      • pageSize (optional): The number of items per page.

  • page: Current page number as a number (default 1).

  • size: Current page size as a number (default 50).

• Usage Example:

  const { setPaginationParams, page, size } = useSetPaginationParams();
  setPaginationParams(2, 20);
  

• Implementation Details:

  • Uses useSearchParams to get and set URL query parameters.

  • Updates the page and optionally size parameters in the URL.

  • Converts string parameters to numbers when returning page and size.

  • Uses useCallback to memoize the setter function.

Important Implementation Details and Algorithms

• Path Segmentation: The hooks split the pathname string by '/' and access the segment by numeric index, allowing flexible retrieval of URL path parts.

• React & Umi Integration: Heavy use of umi routing hooks (useLocation, useNavigate, useSearchParams) and React hooks (useCallback) to ensure performance and seamless routing behavior.

• Stateful Navigation: useNavigateWithFromState adds navigation state to track the origin path, useful for UI flows requiring back-navigation or source awareness.

• Query Parameter Management: Both reading and updating URL query parameters are handled cleanly, enabling pagination and knowledge-related parameters to sync with the URL.

Interaction with Other Parts of the System

• Constants: Relies on constants imported from @/constants/knowledge, specifically:

  • KnowledgeRouteKey — likely an enum or object defining route keys like Dataset.

  • KnowledgeSearchParams — keys for query parameters such as DocumentId and KnowledgeId.

• Routing System: Integrates tightly with the umi routing framework for location and navigation management.

• Knowledge Base Application: The hooks are designed specifically to support knowledge base-related routing and parameter management, indicating usage in components/pages dealing with knowledge documents and datasets.

Visual Diagram

classDiagram
    class route-hook {
        <<hooks module>>
    }
    
    class SegmentIndex {
        <<enum>>
        +Second: '2'
        +Third: '3'
    }
    
    route-hook ..> SegmentIndex : uses
    
    route-hook : +useSegmentedPathName(index: SegmentIndex) : string
    route-hook : +useSecondPathName() : string
    route-hook : +useThirdPathName() : string
    route-hook : +useGetKnowledgeSearchParams() : {documentId: string, knowledgeId: string}
    route-hook : +useNavigateWithFromState() : (path: string) => void
    route-hook : +useNavigateToDataset() : () => void
    route-hook : +useGetPaginationParams() : {page: string | number, size: string | number}
    route-hook : +useSetPaginationParams() : {setPaginationParams: (page?: number, pageSize?: number) => void, page: number, size: number}

Summary

The route-hook.ts file is a utility module providing React hooks for streamlined access and management of URL paths and query parameters within a umi-based React application. It abstracts common routing logic related to knowledge management and pagination, enhancing developer productivity and maintaining consistency across the app's navigation and URL state handling.