---
title: Cross-Platform API
---

# Multi-platform API

The multi-platform framework provides a unified runtime environment to enable consistent capabilities (including route and lifecycle) across platforms.

Usage:

```js
import { router } from '@ray-js/ray';
```

## APIs

```js
import { usePageEvent, usePageInstance,  withPageLifecycle, router, location } from '@ray-js/ray';
```

### usePageInstance

Page instance hook, which can be used to obtain page instances. Corresponding to `this` in Native Miniapps. This hook can be used when you need to obtain a page instance. This hook can also be used in other scenarios where you need to obtain a page instance.

```js
import { View, usePageEvent, usePageInstance } from '@ray-js/ray';

function Page() {
  const page = usePageInstance();
  
  usePageEvent('onLoad', () => {
    console.log(page.getOpenerEventChannel());
  });
  
  return <View>Page</View>;
}
```

### usePageEvent

A hook used to listen for the page lifecycle.

Signature: `usePageEvent(event: string, callback: Function);`

event:

- `onShow`: Triggered when the page is displayed.
- `onHide`: Triggered when the page is hidden.
- `onPageScroll`: Triggered when the page is scrolled.
- `onPullDownRefresh`: Triggered when the page is pulled down to refresh.
- `onReachBottom`: Triggered when the page reaches the bottom.
- `onResize`: Triggered when the page is resized.
- `onShareAppMessage`: Triggered when the page is shared by users.

By default, the above lifecycles are applied to Class Components that are run in multi-platform mode. Example:

```js
import React from 'react';
import { View } from '@ray-js/ray';

export default class Home extends React.Component {
  onShow() {
    // page show
  }
  render() {
    return <View>Home Page</View>;
  }
}
```

### withPageLifecycle

Extend the lifecycle capability to child components (Class Components) to listen for page lifecycles. Example:

```js
import React from 'react';
import { View } from '@ray-js/ray';
import { withPageLifecycle } from '@ray-js/ray';

class Child extends React.Component {
  onShow() {
    // The page triggers page.onShow
  }
  render() {
    return <View>Child</View>;
  }
}

export default withPageLifecycle(Child);
```

> It is recommended to use Function Components and Hooks API in your project.

### router

The following methods are provided to help you implement unified routing for multi-platform apps.

- `router.push(url: string)`
- `router.replace(url: string)`
- `router.back()`
- `router.go(delta: number)`
- `router.reload()`

### location

location object

- `hash`: The hash (web app only).
- `host`: The URL host name with port (web app only).
- `hostname`: The URL host name (web app only).
- `port`: The URL port (web app only).
- `protocol`: The URL protocol (web app only).
- `href`: The full path of the page.
- `pathname`: The URL path.
- `search`: The URL parameter.
- `query`: `Record<string, string>`, URL parameter object.
- `params`: `Record<string, string>`, the route parameter of the match expression.
   - For example, in the expression route `/detail/:uid`, the `uid` value is accessible via `params`.