---
title: "路由"

doc_type: static
doc_category: static
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/apps/development-tool/app-bridge/actions/routing'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/apps/development-tool/app-bridge/actions/routing.md'
---
# 路由

路由机制使应用能够轻松跳转至 SHOPLINE 商家后台内的任意页面，同时也支持通过调用相关的 API 在新的标签页中打开指定页面。举例来说，如果你的应用是支付应用，在授权安装完成后进入你的应用，你可以通过调用路由机制的相关 API 来实现无缝跳转到支付应用的激活页面。

下文将介绍相关的 API 方法。

## replaceTo

替换当前浏览器地址并跳转到指定的外部 URL。

### 方法签名

```typescript
replaceTo(url: string): void
```

### 参数说明

| 参数 | 类型   | 说明                    | 必填 |
| ---- | ------ | ----------------------- | ---- |
| url  | string | 要跳转的完整 URL 地址。 | 是   |

### 使用示例

```typescript
import { Redirect } from '@shoplineos/app-bridge';

const redirect = Redirect.create(app);

// 跳转到 SHOPLINE 官网
redirect.replaceTo('https://www.shopline.com');

// 跳转到应用外部页面
redirect.replaceTo('https://****app.com/dashboard');
```

---

## routerTo

在 SHOPLINE 商家后台内部进行路由跳转，用于导航到商店后台的不同页面（如订单页、商品页等）。跳转后保持在同一个标签页内。

### 方法签名

```typescript
routerTo(path: string): void
```

### 参数说明

| 参数 | 类型   | 说明                                       | 必填 |
| ---- | ------ | ------------------------------------------ | ---- |
| path | string | SHOPLINE 商家后台的路由路径，以 `/` 开头。 | 是   |

### 常用路由路径

| 路径              | 说明           |
| ----------------- | -------------- |
| `/orders`         | 订单列表页     |
| `/products`       | 商品列表页     |
| `/customers`      | 客户列表页     |
| `/apps/${appKey}` | 指定应用的页面 |

### 使用示例

```typescript
import { Redirect } from '@shoplineos/app-bridge';

const redirect = Redirect.create(app);

// 跳转到订单列表页
redirect.routerTo('/orders');

// 跳转到商品列表页
redirect.routerTo('/products');

// 跳转到应用页面
const yourAppHandle = 'your-app-handle';
redirect.routerTo(`/apps/${yourAppHandle}`);
```

---

## toAdminPage

跳转到 SHOPLINE 商家后台的特定业务页面（如详情页、创建页），并支持更丰富的参数配置，例如可以设置是否在新标签页中打开等。此方法适用于需要精确控制跳转行为的场景。

### 方法签名

```typescript
toAdminPage(
  section: ADMIN_SECTION,
  options?: RedirectParam | RedirectOauthParam | RedirectPurchaseParam
): void
```

### 参数说明

| 参数    | 类型                                                               | 说明                                     | 必填 |
| ------- | ------------------------------------------------------------------ | ---------------------------------------- | ---- |
| section | `ADMIN_SECTION`                                                    | 要跳转的业务页面类型。                   | 是   |
| options | `RedirectParam` \| `RedirectOauthParam` \| `RedirectPurchaseParam` | 跳转参数配置（根据业务类型不同而不同）。 | 否   |

#### ADMIN_SECTION 枚举值

| 枚举值             | 说明       | 适用的 options 参数类型 | 备注             |
| ------------------ | ---------- | ----------------------- | ---------------- |
| `SALES`            | 折扣列表页 | `RedirectParam`         | -                |
| `ORDERS`           | 订单列表页 | `RedirectParam`         | -                |
| `PRODUCTS`         | 商品列表页 | `RedirectParam`         | -                |
| `CUSTOMER`         | 客户列表页 | `RedirectParam`         | -                |
| `CATEGORIES`       | 分类列表页 | `RedirectParam`         | -                |
| `OAUTH`            | 授权页     | `RedirectOauthParam`    | 用于应用授权流程 |
| `PACKAGE_PURCHASE` | 套餐购买页 | `RedirectPurchaseParam` | appKey 必填      |

#### RedirectParam 参数类型

用于跳转到列表页、详情页或创建页。

| 参数       | 类型    | 说明                                                                                        | 必填 |
| ---------- | ------- | ------------------------------------------------------------------------------------------- | ---- |
| id         | string  | 资源 ID，传入后跳转到对应的详情页。例如：传入商品 ID 会跳转到 SHOPLINE 商家后台商品详情页。 | 否   |
| newContext | boolean | 是否在新标签页中打开。<br/>• `true`：在新标签页中打开<br/>• `false`：在当前标签页跳转       | 否   |
| create     | boolean | 是否跳转到创建页。<br/>• `true`：跳转到创建页<br/>• `false`：根据 `id` 跳转到详情页或列表页 | 否   |

#### RedirectOauthParam 参数类型

用于跳转到授权页面。

| 参数      | 类型          | 说明           | 必填 |
| --------- | ------------- | -------------- | ---- |
| oauthInfo | `OauthConfig` | 授权配置信息。 | 是   |

关于 `OauthConfig` 类型，参见如下表格：

| 参数        | 类型   | 说明                                                                                                                                                                                                          | 必填 |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| scope       | string | 权限范围。申请多个权限时用 `,` 分隔，例如：`read_products,read_orders`。完整权限列表请参考 [权限点列表](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/access-scope.md)。          | 是   |
| appKey      | string | 应用的唯一标识。                                                                                                                                                                                              | 是   |
| redirectUri | string | 授权完成后的回调地址，需与 SHOPLINE 合作伙伴后台配置的 [应用回调地址](https://developer.shopline.com/zh-hans-cn/docs/apps/application-management/creating-an-app.md#%E5%AD%97%E6%AE%B5%E5%AE%9A%E4%B9%89) 一致。 | 是   |

#### RedirectPurchaseParam 参数类型

用于跳转到套餐购买页面。

| 参数   | 类型   | 说明             | 必填 |
| ------ | ------ | ---------------- | ---- |
| appKey | string | 应用的唯一标识。 | 是   |

### 使用示例

```typescript
import {
  Redirect,
  ADMIN_SECTION,
  type RedirectParam,
  type RedirectOauthParam,
  type RedirectPurchaseParam,
  type OauthConfig,
} from '@shoplineos/app-bridge';

const redirect = Redirect.create(app);

// 示例 1：跳转到分类详情页
const categoryParams: RedirectParam = {
  id: '1000001', // 分类 ID
  newContext: true, // 在新标签页打开
};
redirect.toAdminPage(ADMIN_SECTION.CATEGORIES, categoryParams);

// 示例 2：跳转到商品创建页
const createProductParams: RedirectParam = {
  create: true, // 跳转到创建页
};
redirect.toAdminPage(ADMIN_SECTION.PRODUCTS, createProductParams);

// 示例 3：跳转到授权页
const oauthParams: RedirectOauthParam = {
  oauthInfo: {
    appKey: 'your-app-key',
    scope: 'read_products,write_products',
    redirectUri: 'https://your-app.com/callback',
  },
};
redirect.toAdminPage(ADMIN_SECTION.OAUTH, oauthParams);

// 示例 4：跳转到套餐购买页
const purchaseParams: RedirectPurchaseParam = {
  appKey: 'your-app-key',
};
redirect.toAdminPage(ADMIN_SECTION.PACKAGE_PURCHASE, purchaseParams);
```