tessl/npm-tarojs--router

A routing system for H5 (web) applications in the Taro cross-platform framework, providing compatibility with mini-program routing specifications.

—

Pending

Overview

Eval results

Files

History Management

Name: tessl/npm-tarojs--router
Author: tessl

Browser history abstraction with support for hash, browser, and multi-page modes, providing custom routing behavior and basename management.

Capabilities

setHistoryMode

Set the history mode and create the appropriate history instance with optional basename configuration.

/**
 * Set the history mode and create appropriate history instance
 * @param mode - 'browser', 'hash', or 'multi' (defaults to 'hash')
 * @param base - Base path for all routes (defaults to '/')
 */
function setHistoryMode(mode?: IH5RouterConfig['mode'], base?: string): void;

Usage Examples:

import { setHistoryMode } from "@tarojs/router";

// Hash mode (default) - URLs like /#/page
setHistoryMode("hash", "/");

// Browser mode - URLs like /page (requires server configuration)
setHistoryMode("browser", "/app");

// Multi-page mode - Traditional page navigation
setHistoryMode("multi");

setHistory

Directly set the global history instance and basename for custom history implementations.

/**
 * Set the global history instance and basename
 * @param h - History instance to use globally
 * @param base - Base path for all routes (defaults to '/')
 */
function setHistory(h: History, base?: string): void;

Usage Example:

import { setHistory, createBrowserHistory } from "@tarojs/router";

const customHistory = createBrowserHistory({
  basename: "/my-app",
  window: window
});

setHistory(customHistory, "/my-app");

createMpaHistory

Create a custom multi-page application history implementation that handles page navigation via window.location.

/**
 * Create a multi-page application history implementation
 * @param options - Hash or browser history options (optional)
 * @returns Custom MPA history instance
 */
function createMpaHistory(options?: HashHistoryOptions | BrowserHistoryOptions): MpaHistory;

Usage Example:

import { createMpaHistory } from "@tarojs/router";

const mpaHistory = createMpaHistory();

// MPA history handles navigation via window.location
// - push() uses window.location.assign()
// - replace() uses window.location.replace()
// - Adds .html extension for page routes

prependBasename

Utility function to prepend the configured basename to a URL path.

/**
 * Prepend basename to a URL path
 * @param url - URL to prepend basename to (defaults to empty string)
 * @returns URL with prepended basename
 */
function prependBasename(url?: string): string;

Usage Example:

import { prependBasename } from "@tarojs/router";

// Assuming basename is '/app'
const fullPath = prependBasename("/profile"); // Returns '/app/profile'
const rootPath = prependBasename(); // Returns '/app/'

History Factory Functions

Re-exported history creation functions from the 'history' library for browser and hash modes.

/**
 * Create browser history instance (HTML5 pushState API)
 * @param options - Browser history configuration
 * @returns Browser history instance
 */
function createBrowserHistory(options?: BrowserHistoryOptions): History;

/**
 * Create hash history instance (URL hash fragment)
 * @param options - Hash history configuration  
 * @returns Hash history instance
 */
function createHashHistory(options?: HashHistoryOptions): History;

Usage Examples:

import { createBrowserHistory, createHashHistory } from "@tarojs/router";

// Browser history with custom options
const browserHistory = createBrowserHistory({
  basename: "/my-app",
  window: window
});

// Hash history with custom window object
const hashHistory = createHashHistory({
  window: window
});

MpaHistory Implementation

The MpaHistory class provides a custom history implementation for multi-page applications.

class MpaHistory implements History {
  /** Current browser action type */
  readonly action: Action;
  
  /** Current location object */
  readonly location: Location;
  
  /** Navigate to a new page (uses window.location.assign) */
  push(to: Partial<Path>, state?: Record<string, unknown>): void;
  
  /** Replace current page (uses window.location.replace) */
  replace(to: Partial<Path>, state?: Record<string, unknown>): void;
  
  /** Navigate by delta (-1 = back, 1 = forward) */
  go(delta: number): void;
  
  /** Navigate back one page */
  back(): void;
  
  /** Navigate forward one page */
  forward(): void;
  
  /** Listen to navigation events */
  listen(listener: Listener): () => void;
  
  /** Block navigation (throws error - not implemented) */
  block(blocker: Blocker): () => void;
  
  /** Create href from path object (throws error - not implemented) */
  createHref(to: To): string;
}

History Options

interface BrowserHistoryOptions {
  /** Window object to use (defaults to global window) */
  window?: Window;
  /** Base URL for all locations */
  basename?: string;
}

interface HashHistoryOptions {
  /** Window object to use (defaults to global window) */
  window?: Window;
  /** Hash type ('slash' or 'noslash') */
  hashType?: 'slash' | 'noslash';
}