--- title: Functional Page --- # Functional Page Refers to a specific type of interface function, such as: login page, registration page, forgot password page, payment page, etc. The characteristic of such pages is that they have a single function, complete process, can be accessed independently, and have clear business entry and exit points. Functional pages are registered through the framework function Page(), just like ordinary pages. After publishing, functional pages can be opened in other mini programs, enabling application page sharing and reuse. Application example: - Mini Program A - Has requirements for registration page, login page, forgot password page, etc. - Mini Program B - Has requirements for registration page, login page, forgot password page, etc. The registration page, login page, forgot password page, etc., of Mini Program A can be developed in the functional page mode. They can be self-referenced and provided to Mini Program B for introduction and use, achieving the capability of shared pages, and if other mini programs have such business needs later, they can also be introduced and used. **Environment Requirements** - Base library version: `>= 2.12.0` - Container version: `>= 3.5.0` - App public version: `>= 5.0.0` - IDE version: `>= 0.7.1` ## Terminology ### Host Mini Program Refers to the main mini program application that can import other functional mini programs for use. The source code path is `miniprogramRoot`. ### Functional Mini Program Refers to mini-programs that can be imported into the host mini program. The source code path is `funtionalRoot`. ### Functional Page Examples #### Device Details Device details provide a page carrying basic device information, including device name, device icon, device status, and device control. Each panel business should add the device details configuration. ```typescript { functionalPages: { settings: { appid: "tycryc71qaug8at6yt", entryCode: "entryyvaqnocapvsl1" }, }, } ``` #### Cool Play Bar The Cool Play Bar is a page that combines features like scenario music rhythm, and the lighting device foundation and advanced capability sections, and it belongs to the type of value-added services. ```typescript { functionalPages: { rayPlayCoolFunctional: { appid: "tyg0szxsm3vog8nf6n" }, }, } ``` #### Timer Countdown Timer countdown is a basic device capability for timed switching of devices, timer countdown, and other functions. ```typescript { functionalPages: { rayPlayCoolFunctional: { appid: "tyjks565yccrej3xvo" }, }, } ``` #### Circadian Rhythm The circadian rhythm function can simulate the changes of natural light brightness and color temperature throughout a day, allowing us to feel the return to natural light. ```typescript { functionalPages: { rayPlayCoolFunctional: { appid: "ty53odnmk2cxnzcxm6" }, }, } ``` ## Functional Page Development There is a separate directory for the source code of the functional page, and files including js, tyml, tyss, images, etc., in the `miniprogramRoot` `widgetRoot` directories cannot be referenced internally. ## Getting Started Quickly ### Build Environment and Mini Program Development Process For functional page development, you **must use a smart mini program to create a project, do not use a non-smart mini program**. The project creation process is consistent with each smart mini program, and for specific instructions, please refer to [Getting Started with Smart Mini Program](/en/miniapp/develop/ray/guide/start/smart). ### Project Configuration project.tuya.json To develop a functional page, you need to declare `miniprogramRoot` and `functionalRoot` in the project.tuya.json file to correspond respectively to the mini program code directory and functional page code directory. For businesses developed based on the native mini program syntax, you need to specify the development directory, and for businesses developed by the ray framework, you need to specify the ray compilation output directory. - Configuration content ```javascript { projectname: 'functional-demo', i18n: true, miniprogramRoot: 'dist/tuya/miniprogram', // Mini program compiled source code functionalRoot: 'dist/tuya/functional', // Functional page compiled source code directory projectId: 'your_project_id', baseversion: '2.12.0', dependencies: { // ... }, } ``` - Corresponding directory structure ```bash dist/ #compiled output |--functional/ #compiled functional page source code └──├── functional.json # Functional page configuration file ├── functional.tyss # Functional page global styles ├── theme.json # Functional page theme configuration, if any ├── assets/ │ └── logo.png # Resources inside the functional page |--miniprogram/ # Compiled mini program source code functional/ # Functional page ray source code. The directory name is fixed as functional └──├── functional.config.ts # Functional page configuration file ├── functional.tyss # Functional page global styles └── theme.json # Functional page theme configuration, if any src/ # Mini program functional page directory project.tuya.json # Project configuration file ``` ### Functional Page Configuration `functional.config.ts` Used to describe information about the current functional page mini program. #### Configuration Fields | Field | Type | Required | Description | | --------------- | ------- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | pages | Array | Yes | The list of pages within the functional page, consistent with the `app.json` of the mini program. Declare the page addresses contained in the current functional page, which can have multiple entries, with at least one. | | publicPages | Object | Yes | Only published pages can be accessed by the host mini program. The access route is: `functional://{name}/{pageName}`. Once published, the page name cannot be changed; otherwise, it might cause the host mini program to access incorrect routes. Determine the published page name before releasing. Publish it to the functional page mini program document for reference by the introducers. | | themeLocation | string | No | [Refer to app.json](/en/miniapp/develop/miniapp/framework/app/app-json#themelocation) | | usingComponents | Object | No | [Refer to app.json](/en/miniapp/develop/miniapp/framework/app/app-json#usingcomponents) | | dependencies | Object | No | [Refer to project.tuya.json](/en/miniapp/develop/miniapp/framework/app/config) | | darkmode | boolean | No | Whether to support dark mode, default is `true` | | themeLocation | string | No | The relative path of the theme configuration file | #### Example ```typescript export default { routes: [ { name: 'detail', // Publish detail page corresponding to the key under publicPages in the app.json file isPublic: true, // Whether to release externally route: '/detail', path: 'pages/detail/index', }, { name: 'third', isPublic: false, route: '/third', path: '/pages/third/index', }, ], }; ``` In the example above, the detail page is externally published, and you can navigate to the detail page using this route in the business. Example: ```javascript // Correct call ty.navigateTo({ url: `functional://settings/detail?${deviceId}`, success: (res) => { console.log('Navigate to functional page success', `functional://settings/detail?${query}`, res); }, fail: (err) => { console.error('Navigate to functional page fail', `functional://settings/detail?${query}`, err); } }); // Since only detail is registered under publicPages, the following route cannot navigate ty.navigateTo({ url: `functional://settings/third?${deviceId}`, success: (res) => { console.log('Navigate to functional page success', `functional://settings/third?${deviceId}`, res); }, fail: (err) => { console.error('Navigate to functional page fail', `functional://settings/third?${deviceId}`, err); } }); ``` ### Development and Debugging of Functional Pages #### Declare Dependencies of Functional Pages in app.json In the host mini program, import the functional page mini program through the `functionalPages` field in `global.config.ts`. Use key-value format, where the key is the name of the functional page plugin and the value is the configuration information for the functional page. ```typescript { functionalPages: { settings: { appid: "tycryc71qaug8at6yt", entryCode: "entryyvaqnocapvsl1", }, }, } ``` `appid` is the mini program ID. If it is consistent with the `projectId` in the current mini program (project.tuya.json), it indicates the functionality page is referencing itself. #### Navigate to Functional Page Use the routing API to navigate, only supporting the three methods: ty.navigateTo, ty.redirectTo, ty.reLaunch. The format is `functional://{Functional Page Plugin Name}/{Publicly Exposed Page Name}`, supporting query parameters. For example, the name of the device detail functional page is: settings (as introduced above, fixed name, business party cannot change it); external address: detail (fixed name, named by the developer of the device detail functional page) ```html Navigate to Functional Page ``` ```javascript ty.navigateTo({ url: 'functional://settings/detail?deviceId=xxxxx', }); ``` #### Internal Navigation in Functional Pages Within the functional page, use relative paths for navigation. ```javascript ty.navigateTo({ url: '../detail/index', }); ``` ### Publishing Functional Pages After development is completed, publish the mini program that the functional page belongs to. The upload function has been removed internally from the IDE, and internal developers need to package and upload in the panel management platform. ## Advanced Development ### Overall Architecture #### Same Business Architecture As shown in the figure above, the loading structure of functional pages in the same business is relatively simple, and the logic exists in one mini program package. - Business Mini Program: Used to carry the entry of functional pages and multi-language. - Business Logic: Conventional business logic without special restrictions. The dependency on the functional page plugin and its name must be declared in the mini program. - Multi-language: Contains the multi-language used in the mini program and functional pages, using the same multi-language package as the functional page. - Business Functional Pages: - During business development, extract public logic that can be used across businesses. Except for necessary parameters and multi-language, there are no other dependencies on business mini programs. - Multi-language: Uses the multi-language package of the belonging mini program. - External Routes: Declare in publicPages for pages to be released externally. #### Different Business Architecture As shown in the figure above, a mini program business may use functional pages other than those extracted from itself and depend on other functional pages. - Business Mini Program: Carries business functions and business multi-language. - Business Logic: Regular business logic with no special restrictions. The dependency and configuration of functional page plugins need to be declared in the mini program, and different plugins need to be configured for different functional pages. - Multi-language: Contains the multi-language used in the mini program and functional pages, using the same multi-language package as the functional page. - Business Functional Pages: During business development, extract public logic usable across businesses. Except for necessary parameters and multi-language, they have no other dependencies on business mini programs. They are not necessary. - Multi-language: Uses the belonging mini program’s multi-language package. - External Routes: Declare in publicPages for pages to be released externally. - Other Functional Pages: They carry some common business logic, generally for common business logic, with no mandatory dependency on host business. - Multi-language: The multi-language exists in the multi-language package of the functional page’s belonging mini program. - Multi-language priority: Host mini-program multi-language > Functional page multi-language. - If the host mini-program includes the functional page, the multi-language package of the functional page is shared with the host mini-program. - When using functional pages that are not included in the host mini-program, the multi-language package of the functional page is independent of the multi-language package of the host mini-program. - When the field key value in the multi-language package of the functional page is the same as the field key value in the multi-language package of the host mini-program, the field value in the multi-language package of the host mini-program is taken. - Multi-language packages between multiple functional pages are independent and will not affect each other. - Add prefix: When developing functional pages, in order to avoid the multi-language in the functional pages from being unconsciously covered by the host multi-language. It is recommended to add a specific prefix to the multi-language field key value, and it is recommended to start with the abbreviation of the project name: for example, the Lamp Mutation Functional page uses `lmf_` as the prefix of the multi-language key value. ### Experience Version Dependency The experience version dependency allows functional page developers to validate relevant features before release, improving the development experience. In `global.config.ts`, the version control related fields in `functionalPages` can be configured selectively according to requirements: - `versionType`: Indicates the version type of the dependent functional page. The optional values are `release` and `preview`. The default is `release`. - `version`: Indicates the version number of the dependent functional page. After configuration, only the functional page of the specified version will be loaded. By default, it is not configured, and the latest online version is loaded. ```typescript { functionalPages: { settings: { appid: "tycryc71qaug8at6yt", entryCode: "entryyvaqnocapvsl1", versionType: "preview", version: "1.0.0" }, }, } ``` Note: 1. `versionType`: Only takes effect when the loaded mini program is the trial version. After the mini program is officially released, this field will no longer be effective for jumping to the functional page. The official version will be used for the jump.
2. `version`: After being designated as a fixed version number, if the functional page of this version is taken offline, the related functions of the functional page will not be loaded, and there are certain risks. It is recommended to use it with caution.
3. App version >= 5.18 ### Loading Strategy In actual business development, a mini program might rely on multiple functional pages, if reliance is excessive, the download time will be longer. Therefore, the loading strategy needs to be specified to ensure the effect of loading functional pages. The `strategy` field in `global.config.ts` under `functionalPages` indicates which strategy to use for loading functional pages. Optional values are `lazyload` and `preload`, with `preload` as the default. **lazyload**: Lazy loading mode, download when navigating to functional pages. **preload**: Preloading mode, download when opening host mini program, default value. Example: ```typescript { functionalPages: { settings: { appid: "tycryc71qaug8at6yt", entryCode: "entryyvaqnocapvsl1", strategy: "lazyload" }, }, } ``` App version >= 5.18 ### Cross-Page Event Communication Supports the eventChannel communication mode. For specifics, refer to [getOpenerEventChannel](/en/miniapp/develop/miniapp/framework/api/page#pageprototypegetopenereventchannel). Reserve specific event names in functional page development in advance for host mini program calls. ### Preset Functional Page Initialization Data When custom functional page data is needed or if many parameters need to be passed during page navigation causing the URL to possibly exceed its maximum length, you can use the `ty.presetFunctionalData` API. It is used to set the initialization page data of functional pages. Once set, it takes effect permanently unless actively cleared. ```javascript // Custom data ty.presetFunctionalData({ url: 'functional://mySettings/home', data: { name: 'pre' } }) // Execute navigation ty.navigateTo({ url: 'functional://mySettings/home'}) // Clear data ty.presetFunctionalData({ url: 'functional://mySettings/home', data: null }) ``` After presetting data, functional page instances use Page instances' this.getPresetData() to obtain data: ```javascript import { usePageInstance } from '@ray-js/ray'; export default Index() { const page = usePageInstance(); const presetData = page.getPresetData(); // {name:'pre'} return ... } ``` ## Notes 1. Not affected by app.tyss styles, functional pages have their own styling. 2. Light / Dark development mode follows the host configuration. 3. Returns of getApp, getCurrentPages interfaces can only access data within their own space. 4. Multi-language in functional pages will merge with the host mini program's multi-language, with priority host multi-language > functional page multi-language. 5. Real machine debugging requires App version >= 5.18. IDE version requires >= 0.7.1. 6. When configuring the function pages that a business mini-program depends on, there may be cases where the version number of a specified function page is specified: ```typescript { functionalPages: { settings: { // Load the specified version of the function page appid: "tycryc71qaug8at6yt", }, settings: { // Loading the feature page of version 1.0.0 appid: "tycryc71qaug8at6yt", version: "1.0.0" }, settings: { // Find the appid through the entryCode and load the latest available functional page online. entryCode takes precedence over appid entryCode: "entryyvaqnocapvsl1", // The appid and version fields will be ignored at this time. appid: "tycryc71qaug8at6yt", version: "1.0.0" }, }, } ``` The following situations or exceptions may be encountered in this scenario: - Only specify appid: In this case, the latest available version of the function page will be loaded. If no available version exists, it will be impossible to jump to the function page, and the jump interface will throw an exception. - Specify appid and version: In this case, the specified version of the function page will be loaded. If the version does not exist, it will be impossible to jump to the function page, and the jump interface will throw an exception. - Specify entryCode: In this case, the appid and version fields will be ignored. The appid will be found through entryCode. If found, the latest available version of the function page will be loaded; if not found, it will be impossible to jump to the function page, and the jump interface will throw an exception.