---
title: 功能页
summary: "介绍功能页的概念、开发配置及跨小程序页面共享复用的能力。"
questions:
  - 什么是功能页，它有什么特点？
  - 功能页与普通小程序页面的主要区别是什么？
  - 如何在 project.tuya.json 中配置功能页源码目录？
  - functional.json 配置文件中有哪些关键字段？
  - 宿主小程序如何在 app.json 中声明依赖的功能页？
  - 如何跳转到功能页页面，支持哪些路由 API？
  - 功能页的 publicPages 字段有什么作用和限制？
  - 功能页是否受宿主小程序 app.tyss 样式影响？
  - 功能页中 getApp() 和 getCurrentPages() 的行为有什么限制？
  - 功能页支持哪些跨页面事件通信方式？
---

# 功能页

表示一类特定的功能界面，如：登录页、注册页、忘记密码页、支付页等。此类页面的特点的功能单一、流程完整，可独立访问，具有明确的业务入口与出口。

功能页与普通的页面相同，通过框架函数 `Page()` 注册。功能页经发布后可在其他小程序内打开。实现应用页面共享、复用的能力。

应用案例：

- A 小程序 - 存在注册页、登录页、忘记密码页等需求。
- B 小程序 - 存在注册页、登录页、忘记密码页等需求。

可将 A 小程序的注册页、登录页、忘记密码页等以功能页模式开发。自身引用且可提供给 B 小程序引入使用，实现共享页面的能力，以及后续其他小程序也有此业务需求，也可引入使用。

**环境要求**

- 基础库版本: `>= 2.12.0`
- 容器版本：`>= 3.5.0`
- App 公版： `>= 5.0.0`

## 术语

### 宿主小程序

表示主体小程序应用，可导入其他功能页小程序进行使用。源码路径为 `miniprogramRoot`。

### 功能页小程序

表示可被导入到宿主小程序内的小程序。源码路径为 `funtionalRoot`。

## 功能页开发

功能页源码有独立的目录，其源码内部不可引用（`miniprogramRoot` `widgetRoot`）目录内的文件，包括 js、tyml、tyss、图片等。

### 工程配置

功能页源码通过 `funtionalRoot` 字段在 `project.tuya.json` 内进行声明。

```json5
{
  projectname: 'functional-demo',
  i18n: true,
  miniprogramRoot: 'app/', // 小程序源码
  functionalRoot: 'app-func/', // 功能页源码目录
  projectId: 'your_project_id',
  baseversion: '2.12.0',
  dependencies: {
    // ...
  },
}
```

一个完整的功能页工程目录结构如下：

```bash
app/ # 主小程序源码
app-func/ # 功能页小程序源码
├── functional.json  # 功能页配置文件
├── functional.tyss # 功能页全局样式
├── theme.json # 功能页主题配置，如有
├── assets/
│   └── logo.png  # 功能页内的资源
└── pages/         # 功能页内的页面
    └── settings/
        ├── index.js
        ├── index.json
        ├── index.tyml
        └── index.tyss
```

**注意事项**

- 与小程序的差别是不存在 `app.js` 等逻辑，同时在逻辑代码中调用 `getApp()` 也无法访问到宿主小程序的信息。只是返回当前运行环境共享的一个对象。
- 同时 `getCurrentPages()` 返回的页面队列，只可访问功能页页面实例，其他宿主小程序的页面，只可访问对应路由信息。

### 功能页配置 `functional.json`

用于描述当前功能页小程序的信息。

#### 配置字段

| 字段            | 类型    | 必填 | 说明                                                                                                                                                                                                                                     |
| --------------- | ------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pages           | Array   | 是   | 功能页内的页面列表，与小程序的 `app.json` 一致。 申明当前功能页包含的页面地址，可以有多个，至少存在一个。                                                                                                                                |
| publicPages     | Object  | 是   | 只有发布的页面才可被宿主小程序访问，访问路由为： `functional://{name}/{pageName} `一经发布的页面，页面名不可更改，否则会造成宿主小程序访问到错误路由的问题，应在发布前确定好发布的页面名。并发布到功能页小程序文档中，提供给引入方查阅。 |
| themeLocation   | string  | 否   | [参考 app.json](/cn/miniapp/develop/miniapp/framework/app/app-json#themelocation)                                                                                                                                                        |
| usingComponents | Object  | 否   | [参考 app.json](/cn/miniapp/develop/miniapp/framework/app/app-json#usingcomponents)                                                                                                                                                      |
| dependencies    | Object  | 否   | [参考 project.tuya.json](/cn/miniapp/develop/miniapp/framework/app/config)                                                                                                                                                               |
| darkmode        | boolean | 否   | 是否支持暗黑模式, 默认 `true`                                                                                                                                                                                                            |
| themeLocation   | string  | 否   | 主题配置文件相对路径                                                                                                                                                                                                                     |

配置示例：

```json5
{
  pages: [
    'pages/settings/index', // 功能设置页
    'pages/detail/index', //  功能详情页
  ],
  publicPages: {
    settings: 'pages/settings/index', // 发布 settings 页面
  },
  dependencies: {
    // 环境要求, 提示宿主小程序的环境要求
    MiniKit: '3.0.0',
  },
  darkmode: true,
  themeLocation: '../app/theme.json',
}
```

### 功能页开发调试

#### 1. app.json 文件中声明依赖的功能页

宿主小程序中 `app.json` 中通过 `functionalPages` 字段导入功能页小程序。使用 key-value 的形式，key 为功能页的插件名，value 为功能页的配置信息。

```json5
{
  pages: ['pages/index/index'],
  functionalPages: {
    my_func: {
      appid: 'ty-xxxxxx',
    },
  },
}
```

> 其中 appid 为小程序 ID。
>
> 与当前小程序的 projectId (project.tuya.jons) 中一致时，则表示引用自身的功能页。

#### 2. 跳转到功能页页面

使用路由 API 跳转， 仅支持 `ty.navigateTo` `ty.redirectTo` `ty.reLaunch` 三个方法

格式为 `functional://{功能页插件名}/{对外暴露的页面名}` 支持 query 参数

```html
<navigator url="functional://my_func/settings" open-type="navigate">
  跳转到功能页
</navigator>
```

```js
ty.navigateTo({
  url: 'functional://my_func/settings',
});
```

#### 3. 跨页面事件通信

支持 eventChannel 通信模式，具体参考 [getOpenerEventChannel](/cn/miniapp/develop/miniapp/framework/api/page#pageprototypegetopenereventchannel)

需要功能页开发时提前预留特定的事件名，供宿主小程序调用。

## 功能页开发注意事项

1. 不受 app.tyss 样式影响，功能页内聚自身样式。
2. light / dark 开发模式，跟随宿主配置。
3. getApp, getCurrentPages 接口的返回只可访问自身空间数据。
4. 功能页多语言会合并宿主小程序多语言，多语言优先级宿主多语言 > 功能页多语言。