$Page

• Type:

  function $Page<Data extends Record<string, any>, Custom extends Record<string, any>>(
    name: string,
    options: PageOptions<Data, Custom>,
  ): void;

  Parameters:

  • name: page short name
  • options: page options

Page registrar provided by the framework.

Extensions

onRegister

• Type: (): void

Called just before the page registers.

Warning

Native mini-program methods are not yet mounted on this at this point.

onAppLaunch

• Type: onAppLaunch(options: WechatMiniprogram.App.LaunchShowOption): void | Promise<void>

• Parameters:

  • options: onLaunch parameters from when the app started

Called when App.onLaunch fires.

Warning

The framework only triggers this method when the app starts; it does not inspect or wait for an async return value.

onAwake

• Type: onAwake(time: number): void | Promise<void>

• Parameters:

  • time: duration of the sleep, in ms

Called when the mini-program is brought back from the background.

Warning

The framework only triggers this method; it does not inspect or wait for an async return value.

onPreload

• Type: onPreload(options: PageQuery): void | Promise<void>

• Parameters:

  • options: parameter object generated from the parameters passed when preload was triggered

Preload lifecycle. In another page, use this.$preload(pageNameWithArgs | pageUrlWithArgs) to trigger the preload lifecycle of a specific page.

You can preload and prepare data for a screen based on the user's behavior funnel after a specific action.

Mini-program subpackages

Because pages in each mini-program subpackage are registered when the user first navigates to a page in that subpackage, the first page entered this way cannot trigger the onPreload lifecycle.

onNavigate

• Type: onNavigate(options: PageQuery): void | Promise<void>

• Parameters:

  • options: parameter object generated from the parameters carried by the navigation

Called when the page is about to be navigated to.

During navigation between pages, the target page's onNavigate runs first, and then navigation occurs.

Put low-cost work (< 150 ms) in onNavigate, and check in onLoad whether onNavigate completed successfully.

Tips

To trigger the onNavigate lifecycle, navigation must use the methods wrapped by the framework:

• $go
• $redirect
• $switch
• $reLaunch
• $bindGo
• $bindRedirect
• $bindSwitch
• $bindRelaunch

Warning

Because both synchronous and asynchronous onNavigate are supported, and to prevent long-running methods from blocking navigation and confusing users, the framework force-navigates once maxDelay is reached instead of waiting for onNavigate to finish.

In addition, because pages in each mini-program subpackage are registered when the user first navigates to a page in that subpackage, the first page entered this way cannot trigger the onNavigate lifecycle.

Injected properties

$name

• Type: string

Current page name.

$state

• Type: PageState & Record<string, unknown>

Page state generated by the framework.

Independent per instance

Each page instance receives its own $state at onLoad: the framework copies the state defined on the page options as the initial values of the instance's own object, so you can safely read and write business data in onLoad and later lifecycles, and multiple instances of the same page do not affect each other.

Lifecycles fired before the page instance is created (onAppLaunch / onPreload / onNavigate) use the page options object as this. Synchronous writes to $state there are inherited as initial values by the instance's onLoad, which is useful for preparing data before preload or navigation.

Only synchronous writes are guaranteed to be inherited

Writes to $state in async callbacks such as await / .then / setTimeout happen after the instance is created and are not inherited by the instance's $state. Assign async data directly to the instance in onLoad (or a later lifecycle).

:::

• $state.firstOpen: whether this is the first opened page

Event dispatch

The event dispatch members are all instance properties or methods of $Emitter.

• $on(type:string, handler: (event?:any) => void | Promise<void>): void: listen for the type event

• $emit(type:string, event?:any): void: emit the type event synchronously

• $emitAsync(type:string, event?:any): Promise<void>: emit the type event asynchronously and accept a callback

• $off(type:string, handler?: (event?:any) => void | Promise<void>): void: remove the handler for type, or all handlers when handler is omitted

$refs

• Type: Map<string, ComponentInstance>

Map of child component instances that have a ref; can be used to access child component references.

Example

<custom-component binding="$" ref="customRef1" />

$Page("main", {
  onLoad() {
    this.$refs.get("customRef1"); // get the child component instance by its ref attribute
  },
});

$

Parent-child component communicator.

Provides the ability to establish communication between parent and child components, or between pages and components, through binding="$".

$currentPage

• Type:

  function $currentPage(): PageInstance | undefined;

Get the current page instance.

Warning

Returns undefined when the page stack is empty (for example, during cold start or after all pages have been closed); callers must check for this case.

$getPath

• Type:

  function $getPath(name: string): string;

• Parameters:

  • name: page short name

Get the page path for the given page short name.

The return value is always an absolute path with a leading /: even if defaultPage / pages is configured with a relative path such as pages/main, /pages/main is returned, consistent with the event key used by $go and page registration.

$preload

• Type:

  function $preload(pageName: string): void;

• Parameters:

  • pageName: page short name, optionally with a queryString

Preload the specified page in advance, which triggers its onPreload lifecycle. This method is synchronous and returns void.

$go

• Type:

  function $go(
    pageName: string,
  ): Promise<WechatMiniprogram.NavigateToSuccessCallbackResult | undefined>;

• Parameters:

  • pageName: page short name, optionally with a queryString

Navigate to the specified page.

This function wraps wx.navigateTo.

Navigation lock

To prevent rapid repeated taps from causing duplicate navigation, the framework releases the navigation lock only after the target page of the previous navigation fires onReady (and minInterval has elapsed). While the lock is held, calls to $go (as well as $redirect / $switch / $reLaunch / the home fallback of $back) are ignored: the returned Promise resolves to undefined, without an error and without navigating.

Example

this.$go("play?vid=xxx&cid=xxx");

$redirect

• Type:

  function $redirect(
    pageName: string,
  ): Promise<WechatMiniprogram.GeneralCallbackResult | undefined>;

• Parameters:

  • pageName: page short name, optionally with a queryString

Redirect to the specified page, i.e. replace the page without creating history.

This function wraps wx.redirectTo.

Example

this.$redirect("about?year=2021");

$switch

• Type:

  function $switch(pageName: string): Promise<WechatMiniprogram.GeneralCallbackResult | undefined>;

• Parameters:

  • pageName: page short name, optionally with a queryString

Switch to the specified tabBar page and close all other non-tabBar pages.

This function wraps wx.switchTab.

Warning

The path parameters are only used to trigger onNavigate (wx.switchTab does not support parameters).

Example

this.$switch("main?user=mrhope");

$reLaunch

• Type:

  function $reLaunch(
    pageName: string,
  ): Promise<WechatMiniprogram.GeneralCallbackResult | undefined>;

• Parameters:

  • pageName: page short name, optionally with a queryString

Close all pages, then open a page within the app.

This function wraps wx.reLaunch.

Example

this.$reLaunch("main?user=mrhope");

$back

• Type:

  function $back(delta = 1): Promise<WechatMiniprogram.GeneralCallbackResult | undefined>;

• Parameters:

  • delta: number of levels to go back; defaults to 1

This function is a simple wrapper around wx.navigateBack.

$bindGo

View-layer proxy for $go. Use a data-set in the view layer to bind navigation configuration:

• data-url: target page short name or absolute path, optionally with parameters
• data-before: executed before navigation
• data-after: executed after navigation

Warning

data-after runs only when navigation actually happens (the wx navigation API returns successfully): it does not run when the navigation lock blocks the call (the Promise resolves to undefined) or when navigation fails. Navigation failures are caught and logged as errors, so no unhandled Promise rejection is produced. The other proxies ($bindRedirect / $bindSwitch / $bindRelaunch / $bindBack) behave the same way.

Tips

<button catch:tap="$bindGo" data-url="play" data-before="onClickBefore">click go</button>

$bindRedirect

View-layer proxy for $redirect. Use a data-set in the view layer to bind navigation configuration:

• data-url: target page short name or absolute path, optionally with parameters
• data-before: executed before navigation
• data-after: executed after navigation

Tips

<button catch:tap="$bindRedirect" data-url="/pages/play" data-after="onClickAfter">
  click redirect
</button>

$bindSwitch

View-layer proxy for $switch. Use a data-set in the view layer to bind navigation configuration:

• data-url: target page short name or absolute path, optionally with parameters

  Warning

  Because wx.switchTab() does not support parameters, parameters are only used to trigger the target page's onNavigate lifecycle.

• data-before: executed before navigation

• data-after: executed after navigation

$bindRelaunch

View-layer proxy for $reLaunch. Use a data-set in the view layer to bind navigation configuration:

• data-url: target page short name or absolute path, optionally with parameters
• data-before: executed before navigation
• data-after: executed after navigation

$bindBack

View-layer proxy for $back. Use a dataset in the view layer to bind navigation configuration:

• data-delta: number of levels to go back
• data-before: executed before navigation
• data-after: executed after navigation