# Page routing

In Mini Programs, all page creation, destruction and state transitions are expressed and controlled by page routing. The following content will briefly introduce the page routing logic of the Mini Program.

# Timing of routing

Routing will be expressed in the form of events, distributed by the WeChat client to the Mini Program base library, after the distribution of the client and the base library will be respectively simultaneous processing of this one routing event. The initiation of routing events can be broadly divided into the following two categories:

  1. Initiated by a user's action, such as pressing the back button. When initiated in this way, the routed event is issued directly by the client to the base library for execution

  2. By the developer through the API (such as wx.navigateTo) or components (such as <navigator>) initiated. When initiated in this way, the base library will first initiate a routing request to the client, and the client will confirm that the routing can be executed, and then issue the routing event to the base library. Where, if the route is determined to be executed, the API of success Callback function or component success Event will be triggered, otherwise it will be fail

When a route is determined to be executed (API Or Component Notification success), there is no action to cancel the route this time.

When multiple routes are initiated successively, if the current route event has not been processed, subsequent route events will wait for the current route to be processed and queued until all pending routes have been executed.

A simple example: the user clicking the Back button triggers the navigateBack, Mini Programs on the top page of the current stack of the page stack onUnload Call in wx.redirectToIt can't. Redirects the page currently being destroyed to a new page, instead completing the page return and redirecting the new stack top page after the page return to the new page.

# Page stack

Currently, the Mini Programs' pages are organized as a combination of a page stack and a number of dangling pages that are not in the stack. Where the page stack holds the pages that are opened sequentially through the jump, and the currently created but inactive pages tabBar Page and in picture-in-picture mode (such as [video]((component/video#Small window characteristics))、[live-player]((component/live-player#Small window characteristics)) Etc.) will exist in the form of a dangling page.

Global interface getCurrentPages Can be used to get the current page stack.

After the cold start of the Mini Program is completed, at least one page will exist in the page stack during the entire life of the Mini Program (except for the intermediate state when a route is executed to half).

The specific behavior of the page stack can be described in detail in the specific routing behavior below.

# Route Monitoring and Response

# Page life periodic function

Each Mini Program page has several life - periodic functions, such as onLoad, onShow, onRouteDone, onHide, onUnload Etc. They can be defined at page registration and will be triggered at the appropriate time. All life periodic functions and their respective meanings and timing can be found in [Page interface]((Reference/api/Page#Lifecycle callback function)), the following also details how each route triggers the page's life periodic function.

# Page route monitor

From the base library version 3.5.5 To begin with, the base library provides a set of listening functions for routing events. They are more responsive to a particular route than page lifetime periodic functions. See also Page route monitor

# Route Type

The current routing types of Mini programs can be roughly divided into the following seven types:

# 1. Mini Program start

  • openType: appLaunch

Mini Program start routing appLaunch Indicates that a new Mini Program starts and loads the first page.appLaunch Occurs once and only once in each Mini Program instance, and the first routing event on startup of each Mini Program instance must be appLaunch

Triggering mode

appLaunch It can only be passively triggered by the cold start of the Mini Program, not actively triggered by the developer, and cannot be triggered by other users after starting.

Page stack and lifecycle handling

Because appLaunch It must be the first route at startup, and no page exists before the route, so the page stack must be empty.appLaunch The page specified by the routing event is created and pushed onto the page stack as the only page in the stack. In the process, this page's onLoad, onShow The two lifetimes will be triggered in turn.

# 2. Open a new page

  • openType: navigateTo

Open a new page Route navigateTo Means to open a new page and push it into the page stack.

Triggering mode

  1. call API [wx.navigateTo](<(wx.navigateTo )>), Router.navigateTo
  2. Using components <navigator open-type="navigateTo"/>
  3. The user clicks on a small video window (such as [video]((component/video#Small window characteristics)))

navigateTo The target must be non tabBar Page.

Page stack and lifecycle handling

navigateTo Event occurs, the current top page of the stack will be hidden first, triggering the onHide life cycleThe framework then creates the page specified by the routing event and pushes it onto the page stack as the new top of the stack. In the process, this new page's onLoad, onShow The two lifetimes will be triggered in turn.

As a special case, if navigateTo When the event occurs, the current top page of the page stack meets the logic of the small window mode, or the event is initiated by the user clicking the video window, then the processing of the page stack and the life cycle will be different.。

# 3. Page redirection

  • openType: redirectTo

Page redirection route redirectTo Means to replace the current top page of the page stack with a new page.

Triggering mode

  1. call API wx.redirectTo, Router.redirectTo
  2. Using components <navigator open-type="redirectTo"/>

redirectTo The target must be non tabBar Page.

Page stack and lifecycle handling

redirectTo Event occurs, the current top page of the stack will be first popped up and destroyed. onUnload The life cycle will be triggeredThe framework then creates the page specified by the routing event and pushes it onto the page stack as the new top of the stack. In the process, this new page's onLoad, onShow The two lifetimes will be triggered in turn.

# 4. Return to page

  • openType: navigateBack

Page Return Route navigateBack Indicates that several pages on the top of the current stack will be popped up and destroyed in turn.

Triggering mode

  1. call API [wx.navigateBack](<(wx.navigateBack )>), Router.navigateBack
  2. Using components <navigator open-type="navigateBack"/>
  3. The user presses the top left return button, or triggers the action of the operating system to return (such as pressing the system return key, swiping the screen edge inward, etc.)
  4. The user clicks on a small video window (such as [video]((component/video#Small window characteristics)))

If there is currently only one page in the page stack,navigateBack The call request will fail regardless of the specified delta How much)

If the current number of pages in the page stack is less than the number specified at call delta + 1 (i.e. the number of pages will be less than one after the call),navigateBack Will pop up to only the page at the bottom of the current page stack (that is, at least one page).

Page stack and lifecycle handling

navigateBack Event occurs, the current top page of the stack will be popped up and destroyed, triggering the onUnload life cycleThe above operation is repeated several times until the number of pages that pop up equals the number of pages specified, or there is only one page left in the current page stack. After that, the page stack of the new stack top page of the onShow The life cycle will be triggered.

A special case is that if navigateBack When the current top page of the page stack meets the window mode logic, or the event is initiated by the user clicking on the video window, then the page stack and life cycle will be handled differently.。

# 5. Tab to switch over

  • openType: switchTab

Tab Handoff route switchTab Represents a switch to the specified tab Page.

Triggering mode

  1. call API wx.switchTab, Router.switchTab
  2. Using components <navigator open-type="switchTab"/>
  3. The user clicks Tab Bar to hit the target Tab Button

switchTab The objectives must be tabBar Page.

Page stack and lifecycle handling

Because navigateTo and redirectTo Cannot specify tabBar Page as the target, so when a tabBar When a page appears on the page stack, it must be the first page on the page stack (i.e. the bottom page).At the same time, the framework will guarantee that either tabBar Page There is at most one page instance in the Mini Program.switchTab The behavior is mainly based on these two points.

switchTab Event occurs, if there is more than one page in the current page stack, the current top page of the stack will be popped up and destroyed, and the onUnload life cycleThis will be repeated several times until there is only one page left in the stack. After that, different processing is done depending on the pages left in the page stack:

  • If this page is the target tabBar Pages:
    • If more than one page exists in the page stack at the start of the routing event (i.e. the target tabBar Page is not the top of the stack), triggering the target tabBar Page's onShow life cycle
    • Otherwise (the target at the start of the routing event tabBar Page is the top of the stack), does not trigger any life cycle, the end of the
  • Otherwise (this page is not the target tabBar Page when):
    1. Pop this page out of the page stack
      • If this page is for other tabBar Page, which becomes a dangling page and:
        • If there is only one page in the page stack when the routing event begins (that is, the tabBar Page is the top of the stack), triggering its onHide life cycle
        • Otherwise (the routing event starts with the tabBar Page is not the top of the stack), does not trigger any of its life cycle
      • Otherwise (this page is not tabBar Page), destroys the page, triggers the onUnload life cycle
      • If the target tabBar Page has been created before (now a dangling page), pushing it onto the page stack, triggering the onShow life cycle
      • Otherwise (Target tabBar Page does not exist for instance), create the target tabBar Page and pushed into the page stack, which in turn triggers onLoad, onShow Life cycle.

# 6. Reload

  • openType: reLaunch, autoReLaunch

Reload route reLaunch or autoReLaunch Destroys all current pages and loads a new page.

Two Types of Reload Routes openType The main difference is whether it is initiated by the developer (or triggered by the user). openType The routing logic is basically consistent.

Triggering mode

  1. reLaunch) Call API wx.reLaunch, Router.reLaunch
  2. reLaunch) Use Components <navigator open-type="reLaunch"/>
  3. autoReLaunch) When the Mini Program is in the background, the user re-enters the Mini Program from scenes such as scanning codes or sharing.

reLaunch Can specify any page as the destination page, whether it is the front page of the Mini Program or whether tabBar Pages.

Please note:reLaunch and autoReLaunch Represents only one route,Does not equal to a reboot of the Mini Program, which will open in the current AppService Continue to run on, neither will restart AppService of JavaScript Runtime environment, nor does it re-inject Mini Program code or trigger App.onLaunch Life Cycle, Various JS The global variable or global state of the.

Page stack and lifecycle handling

reLaunch or autoReLaunch Event occurs, all pages in the page stack will be popped from top to bottom and destroyed, triggering a onUnload life cycleAll dangling pages are then destroyed one by one in an indeterminate order, triggering the onUnload Life cycle. After all pages have been destroyed, the target page will be created and pushed onto the stack to become the only page on the stack. onLoad and onShow Two life cycles.

# 7. Close Window Page

  • openType: dismissPip

Close Window Page Routing dismissPip Close a page that is in window mode。

# Note appended

switchTab The logic for handling events is complex, and the following table shows what happens in various situations. switchTab The trigger of the life cycle is used as an auxiliary explanation. In this table, we assume that:

  • Taba, tabB for tabBar page
  • C Is a non tabBar Page, and that we will only start from the Taba Page Open It
  • D Is a non tabBar Page, and that we will only start from the tabB Page Open It
Current page switchTab Target page Triggered life cycle (in order)
Taba Taba Nothing happened
Taba tabB tabA.onHide(), tabB.onLoad(), tabB.onShow()
Taba tabB(Open again) tabA.onHide(), tabB.onShow()
C Taba C.onUnload(), tabA.onShow()
C tabB C.onUnload(), tabB.onLoad(), tabB.onShow()
D tabB D.onUnload(), C.onUnload(), tabB.onLoad(), tabB.onShow()
D(Enter from Forward) Taba D.onUnload(), tabA.onLoad(), tabA.onShow()
D(Enter from Forward) tabB D.onUnload(), tabB.onLoad(), tabB.onShow()