or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

components.mdcontext.mddevice.mdframework.mdindex.mdlocation.mdmedia.mdnavigation.mdnetwork.mdstorage.mdui-controls.md
tile.json

navigation.mddocs/

Navigation & Routing

Page navigation and routing APIs supporting multiple navigation modes, tab management, and page lifecycle with history stack management.

Capabilities

Navigate To Page

Navigate to a new page while preserving the current page in the navigation stack, allowing users to navigate back.

/**
 * Navigate to a new page
 * @param options - Navigation options
 * @returns Promise with navigation result
 */
function navigateTo(options: NavigateToOptions): Promise<NavigateToResult>;

interface NavigateToOptions {
  url: string;
  success?: (result: NavigateToResult) => void;
  fail?: (result: any) => void;
  complete?: (result: any) => void;
}

interface NavigateToResult {
  errMsg: string;
}

Usage Example:

import { navigateTo } from "@dcloudio/uni-h5";

// Navigate to a detail page with parameters
await navigateTo({
  url: '/pages/detail/detail?id=123&type=product'
});

// Navigate with error handling
try {
  await navigateTo({
    url: '/pages/profile/profile'
  });
  console.log('Navigation successful');
} catch (error) {
  console.error('Navigation failed:', error);
}

Navigate Back

Navigate back to the previous page in the navigation stack, with optional delta to go back multiple pages.

/**
 * Navigate back to previous page
 * @param options - Navigation back options
 * @returns Promise with navigation result
 */
function navigateBack(options?: NavigateBackOptions): Promise<NavigateBackResult>;

interface NavigateBackOptions {
  delta?: number;
  success?: (result: NavigateBackResult) => void;
  fail?: (result: any) => void;
  complete?: (result: any) => void;
}

interface NavigateBackResult {
  errMsg: string;
}

Usage Example:

import { navigateBack } from "@dcloudio/uni-h5";

// Go back one page
await navigateBack();

// Go back multiple pages
await navigateBack({ delta: 2 });

// Go back with error handling
try {
  await navigateBack();
} catch (error) {
  console.error('Cannot navigate back:', error);
}

Redirect To Page

Redirect to a new page, replacing the current page in the navigation stack without preserving navigation history.

/**
 * Redirect to a new page (replaces current page)
 * @param options - Redirect options
 * @returns Promise with redirect result
 */
function redirectTo(options: RedirectToOptions): Promise<RedirectToResult>;

interface RedirectToOptions {
  url: string;
  success?: (result: RedirectToResult) => void;
  fail?: (result: any) => void;
  complete?: (result: any) => void;
}

interface RedirectToResult {
  errMsg: string;
}

Usage Example:

import { redirectTo } from "@dcloudio/uni-h5";

// Redirect to login page (user cannot go back)
await redirectTo({
  url: '/pages/login/login'
});

// Redirect after successful operation
await redirectTo({
  url: '/pages/success/success?message=Operation completed'
});

Relaunch Application

Restart the application and navigate to a specific page, clearing all previous navigation history.

/**
 * Relaunch the application to a specific page
 * @param options - Relaunch options
 * @returns Promise with relaunch result
 */
function reLaunch(options: ReLaunchOptions): Promise<ReLaunchResult>;

interface ReLaunchOptions {
  url: string;
  success?: (result: ReLaunchResult) => void;
  fail?: (result: any) => void;
  complete?: (result: any) => void;
}

interface ReLaunchResult {
  errMsg: string;
}

Usage Example:

import { reLaunch } from "@dcloudio/uni-h5";

// Relaunch to home page (clears all navigation history)
await reLaunch({
  url: '/pages/index/index'
});

// Relaunch after logout
await reLaunch({
  url: '/pages/welcome/welcome'
});

Switch Tab

Navigate to a tab page in applications with tab bar navigation, switching between main application sections.

/**
 * Switch to a tab page
 * @param options - Tab switch options
 * @returns Promise with switch result
 */
function switchTab(options: SwitchTabOptions): Promise<SwitchTabResult>;

interface SwitchTabOptions {
  url: string;
  success?: (result: SwitchTabResult) => void;
  fail?: (result: any) => void;
  complete?: (result: any) => void;
}

interface SwitchTabResult {
  errMsg: string;
}

Usage Example:

import { switchTab } from "@dcloudio/uni-h5";

// Switch to home tab
await switchTab({
  url: '/pages/home/home'
});

// Switch to profile tab
await switchTab({
  url: '/pages/profile/profile'
});

Preload Page

Preload a page to improve navigation performance by loading page resources in advance.

/**
 * Preload a page for faster navigation
 * @param options - Preload options
 */
function preloadPage(options: PreloadPageOptions): void;

interface PreloadPageOptions {
  url: string;
  success?: (result: any) => void;
  fail?: (result: any) => void;
  complete?: (result: any) => void;
}

Usage Example:

import { preloadPage } from "@dcloudio/uni-h5";

// Preload a detail page for faster navigation
preloadPage({
  url: '/pages/detail/detail'
});

// Preload with callback
preloadPage({
  url: '/pages/product/product',
  success: () => {
    console.log('Page preloaded successfully');
  }
});

URL Format and Parameters

Navigation URLs follow a specific format for passing parameters:

// Basic URL
'/pages/detail/detail'

// URL with query parameters
'/pages/detail/detail?id=123&name=product&category=electronics'

// URL with encoded parameters
'/pages/detail/detail?data=' + encodeURIComponent(JSON.stringify(complexData))

Navigation Stack Management

import { getCurrentPages } from "@dcloudio/uni-h5";

// Get current page stack
const pages = getCurrentPages();
console.log('Current page stack length:', pages.length);
console.log('Current page route:', pages[pages.length - 1].route);

// Check if can navigate back
const canGoBack = pages.length > 1;
if (canGoBack) {
  await navigateBack();
}

Error Handling

Navigation APIs may fail for various reasons:

try {
  await navigateTo({ url: '/pages/detail/detail' });
} catch (error) {
  console.error('Navigation error:', error);
  // Handle specific error cases:
  // - Invalid URL format
  // - Page not found
  // - Navigation stack overflow
  // - Tab page accessed with wrong method
}

Best Practices

  • URL Validation: Always validate URLs before navigation
  • Parameter Encoding: Properly encode URL parameters with special characters
  • Stack Management: Monitor navigation stack depth to prevent memory issues
  • Tab Navigation: Use switchTab only for pages configured as tab pages
  • Preloading: Preload frequently accessed pages to improve user experience