harmonyos-best-practices-mcp 0.1.0

package/data/docs/bpta-multi-music-app-overview.md

@@ -0,0 +1,365 @@
+# 多设备音乐界面
+
+> 来源: https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-multi-music-app-overview
+> 文档标识(fileName): bpta-multi-music-app-overview  
+> 目录(catalogName): best-practices  
+> 语言: cn  
+> 更新时间: 2026-06-23 03:37:31  
+> 导航地址: /hmos/hmos-dp1
+
+---
+#### 概述
+
+本文将介绍如何在音乐播放类应用的实际开发过程中实现“一次开发，多端部署”。收听音乐是大众最受欢迎的日常娱乐方式之一，而音乐播放应用是其核心载体。多设备音乐播放案例围绕首页、歌单详情页和全屏播放页等核心页面展开，覆盖了用户从音乐浏览、歌单查看到沉浸式播放的完整音乐欣赏链路。文章重点介绍关键布局能力及对应实现。当前应用已适配的设备包括：直板机、双折叠（Mate X系列）、三折叠、阔折叠、平板、电脑、智慧屏和智能穿戴。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/51/v3/tpvLFBdnRASZX0Z-CCVP9w/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260623T075611Z&HW-CC-Expire=86400&HW-CC-Sign=84E6FD0EF9D0BAF47990C10AF267171C15A23523DAA48F49830813D38CA7A4BC) 
+
+阅读本文前，建议开发者先了解[ArkUI（方舟UI框架）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkui)和[一次开发，多端部署概览](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-multi-device-overview)相关知识。
+
+下文将从UX设计、工程管理、页面开发三个方面系统介绍音乐播放类应用在实际开发中的最佳实践，为开发者提供可借鉴的实现思路。
+
+- [UX设计](#section1496102654513)：介绍音乐播放类应用的交互逻辑与通用设计要点，开发者可直接参考同类设计要点。
+- [工程管理](#section2146193418540)：介绍“一多”工程所需配置，并推荐采用结构更清晰的三层架构。
+- [移动端页面](#section169906412567)、[电脑端页面](#section3647191712520)、[智慧屏页面](#section13448146153217)、[智能穿戴页面](#section95447563587)：遵循实际应用开发流程，以页面为基本单元，依次讲解窗口适配、页面开发的设计思路与实现方法。
+
+#### UX设计
+
+应用的UX设计可参考[音乐听书](https://developer.huawei.com/consumer/cn/doc/design-guides/responsive-design-examples1-0000001957369849#section12973333171715)的多设备响应式设计指南，设计参考图如下所示。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/46/v3/BUtvy57zQaKxrqadW5CqJQ/zh-cn_image_0000002622170035.png?HW-CC-KV=V1&HW-CC-Date=20260623T075611Z&HW-CC-Expire=86400&HW-CC-Sign=8B90678D211CA6AD91871CCAE947869F176382814C6EA13DFC8C9F04C4AA0D61 "点击放大")
+
+#### 工程管理
+
+为确保“一多”工程代码的复用性与可维护性，建议开发者采用分层架构组织代码工程。该架构将项目划分为产品定制层（products）、基础特性层（features）和公共能力层（common）三个层级，各层级权责明确且功能独立，为开发者提供了清晰、高效且可扩展的设计方案。关于分层架构的具体设计细节，可参考[分层架构设计](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-layered-architecture-design)。
+
+## 创建工程
+
+建议开发者参考[多设备工程部署与发布](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-multi-device-ide)相关内容，掌握分层架构工程的创建与配置方法后，创建模板项目工程。根据多设备音乐的开发需求进行针对性修改，确保工程架构贴合实际业务需求。
+
+## 工程结构
+
+多设备音乐应用采用推荐的分层架构，将代码工程按products、features、common三个层级组织。各层级设计如下：
+
+- products层：针对不同终端形态提供独立入口与页面组装。例如，products/default面向手机/平板类形态；products/watch、products/tv、products/pc分别面向穿戴、智慧屏、电脑等。
+- features层：包含三个核心业务模块——首页、列表页和播放页。为各模块分别创建对应HAR包，供products层按需引用。各模块相对独立，互不依赖，便于后续维护与迭代。
+- common层：为实现代码复用并减少冗余，集中存放公共常量、日志工具类及窗口管理工具等基础能力，供其他模块统一调用。
+
+工程结构如下：
+
+```
+├── common                                                  // 公共能力层目录
+│   └── musicbasic                                          // 基础HAR：歌曲数据、全局状态、断点与窗口工具
+│       └── src/main                                        // 模块标准源码与资源根目录
+│           ├── ets                                         // ArkTS业务源码根目录
+│           │   ├── api                                     // 接口DTO与映射
+│           │   ├── constants                               // 公共常量
+│           │   ├── data                                    // 歌曲/歌单/推荐Feed等行数据模型
+│           │   ├── db                                      // 内存曲库等数据访问
+│           │   ├── model                                   // 全局播控状态、菜单、歌曲实体等
+│           │   └── util                                    // 日志、断点、窗口、持久化门面等工具
+│           └── resources                                   // 字符串、颜色、媒体与rawfile资源
+├── features                                                // 特性HAR：按业务能力拆分
+│   ├── player                                              // 播放器：全屏页、歌词、音频播放封装
+│   │   └── src/main                                        // 模块标准源码与资源根目录
+│   │       ├── ets                                         // ArkTS业务源码根目录
+│   │       │   ├── constant                                // 播放器与歌词相关常量
+│   │       │   ├── model                                   // 播放UI模型、媒体服务、歌词条目
+│   │       │   ├── util                                    // LRC、后台播放、播放意图壳层等
+│   │       │   ├── view                                    // 播放页 UI 组件（含穿戴等形态适配）
+│   │       │   └── viewmodel                               // 播放页ViewModel
+│   │       └── resources                                   // 模块字符串、图标与主题资源
+│   ├── playlist                                            // 歌单：详情页、分栏、迷你播控条
+│   │   └── src/main                                        // 模块标准源码与资源根目录
+│   │       ├── ets                                         // ArkTS业务源码根目录
+│   │       │   ├── model                                   // 歌单与列表UI模型、数据源
+│   │       │   ├── util                                    // 歌单演示数据等工具
+│   │       │   ├── view                                    // 歌单页与迷你条 UI（含穿戴路由相关）
+│   │       │   └── viewmodel                               // 歌单与播控联动ViewModel
+│   │       └── resources                                   // 模块字符串与图标资源
+│   └── recommendation                                      // 推荐首页、宽屏面板、首页迷你条
+│       └── src/main                                        // 模块标准源码与资源根目录
+│           ├── ets                                         // ArkTS业务源码根目录
+│           │   ├── model                                   // 推荐区块UI模型与数据源
+│           │   ├── util                                    // 推荐演示数据工具
+│           │   ├── view                                    // 推荐首页、迷你条、宽屏面板与穿戴首页等 UI
+│           │   └── viewmodel                               // 推荐首页ViewModel
+│           └── resources                                   // 模块字符串、横幅与主题资源
+└── products                                                // 各设备形态HAP产品入口
+    ├── default                                             // 手机/平板应用入口
+    │   └── src/main                                        // 模块标准源码与资源根目录
+    │       ├── ets                                         // ArkTS入口与页面根目录
+    │       │   ├── entryability                            // 主入口Ability
+    │       │   ├── pages                                   // 页面路由（主导航与壳层）
+    │       │   └── phonebackupextability                   // 手机侧备份扩展Ability
+    │       └── resources                                   // 权限声明、页面profile、图标与多语言
+    ├── pc                                                  // PC/2in1应用入口
+    │   └── src/main                                        // 模块标准源码与资源根目录
+    │       ├── ets                                         // ArkTS入口与页面根目录
+    │       │   ├── pages                                   // PC主页与路由页面
+    │       │   ├── pcability                               // PC入口Ability
+    │       │   └── pcbackupability                         // PC备份扩展Ability
+    │       └── resources                                   // 分层图标、页面profile、多语言
+    ├── tv                                                  // 智慧大屏应用入口
+    │   └── src/main                                        // 模块标准源码与资源根目录
+    │       ├── ets                                         // ArkTS入口与页面根目录
+    │       │   ├── pages                                   // TV主页与路由页面
+    │       │   ├── tvability                               // TV入口Ability
+    │       │   └── tvbackupability                         // TV备份扩展Ability
+    │       └── resources                                   // 分层图标、页面profile、多语言
+    └── watch                                               // 智能穿戴应用入口
+        └── src/main                                        // 模块标准源码与资源根目录
+            ├── ets                                         // ArkTS入口与页面根目录
+            │   ├── pages                                   // 穿戴主页路由页面
+            │   ├── watchability                            // 穿戴入口Ability
+            │   └── watchbackupability                      // 穿戴备份扩展Ability
+            └── resources                                   // 表盘图标、路由profile、多语言
+```
+
+#### 移动端页面
+
+本章说明在直板机、折叠机、平板等形态下，如何借助一多布局能力，使首页、歌单详情页、全屏播放页在同一套业务逻辑上完成适配，并概述与本示例相关的窗口适配要点。
+
+## 窗口适配
+
+- 窗口模式
+
+  适配设备支持全屏、分屏、悬浮窗和自由窗口模式，具体参见[窗口模式](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-multi-device-window-mode)。其中，分屏模式与悬浮窗无需特殊设计，可通过系统方式进入。应用内监听窗口尺寸变化，[通过断点刷新UI](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-multi-device-responsive-layout#section175001836203617)，即可自动适配全屏、分屏、悬浮窗和自由窗口模式下的布局。
+- 窗口方向
+
+  在类直板机上推荐仅竖屏显示，在双折叠展开态、三折叠展开态、平板等大屏幕场景下推荐四方向旋转并受控制中心的旋转开关控制。在移动端应用推荐在[module.json5](https://gitcode.com/HarmonyOS_Samples/MusicHome/blob/master/products/default/src/main/module.json5)配置文件中将orientation字段设置为follow_desktop（跟随桌面的旋转模式），具体说明可参考[为应用配置旋转策略](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-multi-device-window-direction#section714419371037)。
+- 窗口沉浸式
+
+  根据UX设计，需实现不同窗口模式（全屏、分屏、悬浮窗、自由窗口）下的沉浸式效果，可参考[窗口沉浸式](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-multi-device-window-immersive)。推荐开发者使用[实现沉浸式效果](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-multi-device-window-immersive#section180431120426)中的组件级沉浸方案（组件设置页面沉浸），同时进行动态安全区避让，确保沉浸式显示效果。自由窗口模式下，使用[window.setWindowDecorVisible(false)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#setwindowdecorvisible11)隐藏标题栏，仅保留右上角三键，使应用页面延伸至标题栏区域，实现沉浸式显示效果。
+
+## 首页
+
+音乐应用首页用于展示推荐信息流与快捷入口，以满足试听与浏览歌单的需求。本示例将首页主要内容组织在RecommendPage中，并由多个分区组件拼装而成。
+
+效果图如下所示：
+
+| 横向（/纵向）断点 | sm/md | sm | md | lg、xl |
+| --- | --- | --- | --- | --- |
+| 首页 |  |  |  |  |
+
+**界面开发**
+
+对各个区域使用多种能力进行分析，实现方案如下表：
+
+| 区域编号 | 简介 | 实现方案 |
+| --- | --- | --- |
+| 1 | 底部页签 | 借助[HdsTabs](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ui-design-hdstabs)实现。同时在api版本低的设备上降级使用[Tabs](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-tabs)组件。 |
+| 2 | 顶部页签及搜索框 | 使用响应式布局实现。通过监听断点变化，实现折行显示。在横向断点为sm时，组件两行显示；在横向断点为md、lg或xl时，组件单行显示。 |
+| 3 | 歌单卡片列表 | 使用响应式组件[Scroll](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-scroll)结合[Row](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-row)组件实现横向滚动。 |
+| 4 | 分类标签区域 |
+| 5 | 为你推荐区域 |
+| 7 | 音乐列表 | 使用[List](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-list)结合[LazyForEach](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-rendering-control-lazyforeach)实现列表渲染，并通过lanes()属性设置响应式列数，根据横向断点为sm展示一列，md展示两列，lg或者xl展示三列。 |
+
+## 列表页
+
+列表页用于展示歌单头图与曲目列表，并在页面内提供迷你播放条以延续播控。对应实现集中在PlaylistDetailPage及相关Section组件。
+
+效果图如下所示：
+
+| 横向（/纵向）断点 | sm/md | sm | md | lg、xl |
+| --- | --- | --- | --- | --- |
+| 列表页 |  |  |  |  |
+
+**界面开发**
+
+列表页通过栅格系统区分窄屏堆叠与宽屏分栏。
+
+- 窄屏（如横向断点sm、md下占满列宽）：封面信息区域与列表区域在[GridRow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-gridrow)中均占据满列，呈现上图下文的布局。
+- 宽屏（如横向断点lg、xl）：同一[GridRow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-gridrow)下封面信息区域与列表区按列跨度分为四列与八列，实现左右分栏。
+
+实现方案如下表：
+
+|  |  |  |
+| --- | --- | --- |
+| **区域编号** | **简介** | **实现方案** |
+| 1 | 标题栏 | 使用[HdsNavDestination](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ui-design-hdsnavdestination)实现，并支持滚动渐变效果 (IMMERSIVE_GRADIENT_BLUR）。 |
+| 2 | 封面信息 | 使用响应式组件[Flex](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-flex)实现，当横向断点为sm、md时采用水平布局，当断点为lg、xl时实现垂直布局。 |
+| 3 | 列表区 | 使用[List](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-list)结合[LazyForEach](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-rendering-control-lazyforeach)实现列表渲染，并通过lanes()属性设置响应式列数，根据横向断点为sm展示一列，md、lg、xl时展示两列。 |
+| 4 | 播放条 | 使用[Row](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-row)组件实现，分为封面区域以及音乐控制区两部分，封面区域通过[Stack](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-stack)层叠环形进度条。 |
+
+## 播放页
+
+播放页用于沉浸式展示封面、进度条与歌词，并提供手势收起等交互功能。
+
+效果图如下所示：
+
+| 横向（/纵向）断点 | sm/md | sm | md | lg、xl |
+| --- | --- | --- | --- | --- |
+| 播放页 |  |  |  |  |
+| 歌词页 |  |  |  |  |
+
+**界面开发**
+
+全屏播放页面综合使用[Swiper](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-swiper)与[GridRow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-gridrow)完成窄宽屏形态切换。
+
+- 窄屏（如横向断点sm下占满列宽）：采用[Swiper](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-swiper)分页方式，分页展示封面、歌曲信息与歌词等内容区域。
+- 宽屏（如横向断点md、lg、xl）：使用[GridRow](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-gridrow)双列排布歌曲信息控制区域与歌词区域。
+
+实现方案如下表：
+
+|  |  |  |
+| --- | --- | --- |
+| **区域编号** | **简介** | **实现方案** |
+| 1 | 顶部栏 | 使用[Row](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-row)组件实现，包含返回图标以及分享按钮。 |
+| 2 | 封面区域 | 使用[Image](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-image)组件实现，并通过scale()属性实现下滑关闭缩放动画。 |
+| 3 | 控制区域 | 采用[Column](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-column)组件实现垂直布局，进度条由[Slider](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-slider)组件实现。 |
+| 4 | 歌词区域 | 使用[Canvas](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-components-canvas-canvas)组件逐行绘制歌词。 |
+
+#### 电脑端页面
+
+本章介绍如何基于现有移动端界面开发方案，实现代码逻辑与布局复用，高效完成音乐类应用在电脑设备上的界面开发。
+
+## 首页
+
+将电脑端首页划分为八个区域。
+
+效果图如下所示：
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/a7/v3/8PPBkAcAQIm4ODxWzcvtrA/zh-cn_image_0000002622249901.png?HW-CC-KV=V1&HW-CC-Date=20260623T075611Z&HW-CC-Expire=86400&HW-CC-Sign=F1EA07CB25A3CB9332715005F08D2FF4DECBCD89429C31204F1C5617225FFB5F "点击放大")
+
+**界面开发**
+
+对各个区域使用的多种能力进行分析，实现方案如下表：
+
+| 区域编号 | 简介 | 实现方案 |
+| --- | --- | --- |
+| 1 | 侧边页签 | 使用侧边栏容器[SideBarContainer](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-sidebarcontainer)实现。 |
+| 2 | 顶部页签及搜索框 | 同移动端[首页](#section29721612105717)对应区域的布局实现方案。 |
+| 3 | 歌单卡片列表 |
+| 4 | 分类标签区域 |
+| 5 | 为你推荐区域 |
+| 7 | 音乐列表 |
+| 8 | 播放条 | 使用[Row](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-row)组件实现，分为封面区域和音乐控制区两部分，封面通过[Stack](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-stack)层叠环形进度条。 |
+
+## 列表页
+
+将电脑端列表划分为五个区域。
+
+效果图如下所示：
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/9e/v3/UhAGtHz0RzKtknbiy5sjTA/zh-cn_image_0000002622170043.png?HW-CC-KV=V1&HW-CC-Date=20260623T075611Z&HW-CC-Expire=86400&HW-CC-Sign=3528F4321F9B421038EFA9D191BBA337267F7D1B97C39E0F4B5EBFE96299B0FD "点击放大")
+
+**界面开发**
+
+实现方案如下表：
+
+|  |  |  |
+| --- | --- | --- |
+| **区域编号** | **简介** | **实现方案** |
+| 1 | 侧边页签 | 使用侧边栏容器[SideBarContainer](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-sidebarcontainer)实现。 |
+| 2 | 标题栏 | 同移动端[列表页](#section15311254145716)对应区域的布局实现方案。 |
+| 3 | 封面信息 |
+| 4 | 列表区 |
+| 5 | 播放条 |
+
+## 播放页
+
+电脑端播放页面与移动端播放页面实现效果一致，可参考移动端[播放页](#section143891320165811)实现。
+
+#### 智慧屏页面
+
+本章介绍如何基于现有移动端界面开发方案，实现代码逻辑与布局复用，以高效完成音乐类应用在智慧屏设备上的界面开发。
+
+## 首页
+
+将智慧屏首页划分为四个区域。
+
+效果图如下所示：
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/7b/v3/qdn9F-KVTaKESvdqiX1rcg/zh-cn_image_0000002591610438.png?HW-CC-KV=V1&HW-CC-Date=20260623T075611Z&HW-CC-Expire=86400&HW-CC-Sign=05DAF90575DC667C2B87348A6A796C3EAB780FCA7DA9A79E9FE7DEBAC159666B "点击放大")
+
+**界面开发**
+
+对各个区域使用的多种能力进行分析，实现方案如下表：
+
+| 区域编号 | 简介 | 实现方案 |
+| --- | --- | --- |
+| 1 | 顶部胶囊导航 | 使用[Row](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-row)组件实现横向布局，使用[List](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-list)组件实现胶囊导航。 |
+| 2 | 歌单卡片列表 | 与移动端[首页](#section29721612105717)对应区域的布局实现方案一致。 |
+| 3 | 为你推荐区域 |
+| 4 | 音乐列表 |
+
+## 列表页
+
+智慧屏列表页与移动端显示效果存在较大差异，建议单独开发智慧屏列表页，并将其划分为两个区域。
+
+效果图如下所示：
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ae/v3/h3ACILv3TeGnUp7PvknQDA/zh-cn_image_0000002591770364.png?HW-CC-KV=V1&HW-CC-Date=20260623T075611Z&HW-CC-Expire=86400&HW-CC-Sign=4D5D81AD51D5887EEC4AF00C249D351F9C1B382EC963C0BCAF6C968C6EA7D8C7 "点击放大")
+
+**界面开发**
+
+实现方案如下表：
+
+|  |  |  |
+| --- | --- | --- |
+| **区域编号** | **简介** | **实现方案** |
+| 1 | 歌单信息 | 使用[Row](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-row)组件实现水平布局。 |
+| 2 | 列表区 | 使用[List](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-list)结合[LazyForEach](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-rendering-control-lazyforeach)实现列表渲染。 |
+
+## 播放页
+
+智慧屏播放页与移动端播放页实现效果一致，参考移动端[播放页](#section143891320165811)实现。
+
+#### 智能穿戴页面
+
+本章将介绍音乐应用如何借助“一多”布局能力，在智能穿戴设备上实现独立应用开发，并以首页、歌曲列表页与播放页等典型页面为例，详细阐述其设计与实现。
+
+## 首页
+
+穿戴首页通过[ArcSwiper](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-arcswiper)实现首页与歌单列表的横向切换，并在首页显示当前播放的音乐以方便用户操作。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/8d/v3/wW3lpJhRR4C0s55Of9oXHQ/zh-cn_image_0000002622249905.png?HW-CC-KV=V1&HW-CC-Date=20260623T075611Z&HW-CC-Expire=86400&HW-CC-Sign=F4B9C551125C64483A4A1DDAE35E3A6BFE9A96862299785612528DD90B6B2D62 "点击放大")
+
+实现方案如下表：
+
+|  |  |  |
+| --- | --- | --- |
+| **区域编号** | **简介** | **实现方案** |
+| 1 | 顶部标题栏 | 使用[Row](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-row)组件实现标题与搜索按钮的水平布局。 |
+| 2 | 播控条 | 使用[Row](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-row)组件实现，分为封面区域和音乐控制区。 |
+| 3 | 推荐区域 | 使用[Stack](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-stack)组件实现图片堆叠效果。 |
+
+## 歌单与曲目列表
+
+穿戴列表页主要展示歌曲列表内容。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/35/v3/Is8PvTkbSlm8u_1R13gWDA/zh-cn_image_0000002622170045.png?HW-CC-KV=V1&HW-CC-Date=20260623T075611Z&HW-CC-Expire=86400&HW-CC-Sign=C5FBA3EACCE3114AD9763B58B2E881BDEF96A5B2BC69CCE08371B97BDFD70782 "点击放大")
+
+实现方案如下表：
+
+|  |  |  |
+| --- | --- | --- |
+| **区域编号** | **简介** | **实现方案** |
+| 1 | 歌单列表页 | 使用[ArcList](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-arclist)实现列表展示。 |
+
+## 播放页
+
+穿戴播放页划分为三个区域。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c7/v3/Hr5Kv3_ZQ0qLfgcXdr4JvQ/zh-cn_image_0000002591610440.png?HW-CC-KV=V1&HW-CC-Date=20260623T075611Z&HW-CC-Expire=86400&HW-CC-Sign=3D72C307570D7CD8887EC6FD8E13BEB75DFB2F5A02FE20ECF492F26B6102AAD1 "点击放大")
+
+实现方案如下表：
+
+|  |  |  |
+| --- | --- | --- |
+| **区域编号** | **简介** | **实现方案** |
+| 1 | 歌曲信息 | 使用[Column](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-column)组件实现歌名与歌手名的垂直布局。 |
+| 2 | 控制区域 | 使用[Row](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-row)组件实现上一首、播放/暂停、下一首的水平布局。 |
+| 3 | 辅助功能区 | 使用[Row](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-row)组件实现水平布局。 |
+
+## 交互开发
+
+智能穿戴设备音乐应用因界面空间有限，在页面中直接添加音量调节功能较为不便，因此可利用表冠监听功能实现音量的调节。
+
+- 表冠调节音量
+
+  穿戴设备支持[onDigitalCrown](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-universal-events-crown#ondigitalcrown)事件，当组件获焦后旋转表冠触发该事件。音乐应用可在播放页面监听此事件，通过旋转表冠调节音量大小，具体交互逻辑请参见[示例代码](#section520865982117)。
+
+#### 示例代码
+
+- [多设备音乐界面](https://gitcode.com/HarmonyOS_Samples/MusicHome)

package/data/docs/bpta-multi-settings-application-page.md

@@ -0,0 +1,163 @@
+# 多设备设置界面
+
+> 来源: https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-multi-settings-application-page
+> 文档标识(fileName): bpta-multi-settings-application-page  
+> 目录(catalogName): best-practices  
+> 语言: cn  
+> 更新时间: 2026-06-23 03:38:15  
+> 导航地址: /hmos/hmos-dp1
+
+---
+#### 概述
+
+本文从当前常见的多设备应用场景中选取设置应用作为典型案例，详细阐述“一多”理念在实际开发中的应用。设置应用主要展示导航页列表及内容页在不同设备上的呈现方式，并介绍路由跳转功能。
+
+当前应用已适配的设备包括：直板机、双折叠（Mate X系列）、三折叠、阔折叠、平板和电脑。
+
+下文将从UX设计、工程管理、移动端页面和电脑端页面四个角度，介绍“一多”设置应用在开发过程中的最佳实践。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/f4/v3/avk8HWdAQm27nOp6iY-k7g/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260623T075614Z&HW-CC-Expire=86400&HW-CC-Sign=7A9F7ECC6BC0ED172C6612983EBCFFBCF18A96DBB33A9BA0A523C57FF078047F) 
+
+阅读本文前，建议开发者先了解[ArkUI（方舟UI框架）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkui)和[一次开发，多端部署概览](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-multi-device-overview)相关知识。
+
+- [UX设计](#section99762271515)：介绍设置应用的交互逻辑与通用设计要点，开发者可直接参考。
+- [工程管理](#section719020851716)：介绍“一多”工程所需配置，并推荐采用结构更清晰的三层架构。
+- [移动端页面](#section202931220101020)和[电脑端页面](#section5748352172710)：遵循实际应用开发流程，以页面为基本单元，依次讲解窗口适配、页面开发及功能开发的设计思路与实现方式。
+
+#### UX设计
+
+设计参考图如下所示。
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/1b/v3/khSoDR5hQ8i0qfW2nc4R7g/zh-cn_image_0000002579408634.png?HW-CC-KV=V1&HW-CC-Date=20260623T075614Z&HW-CC-Expire=86400&HW-CC-Sign=1E82568D7F950BB2C2CDECE567B4D01F3D3D8BE8AF8837B1DBA4B17B07CC80CD "点击放大")
+
+#### 工程管理
+
+为确保“一多”工程代码的复用性与可维护性，推荐开发者采用分层架构组织代码工程。该架构将项目划分为产品定制层（products）、基础特性层（features）和公共能力层（common）三个层级，各层级权责明确且功能独立，为开发者提供了清晰、高效且可扩展的设计方案。关于分层架构的具体设计细节，可参考[分层架构设计](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-layered-architecture-design)。
+
+## 创建工程
+
+建议开发者参考[多设备工程部署与发布](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-multi-device-ide)相关内容，掌握分层架构工程的创建与配置方法后，创建模板项目工程。根据设置应用的开发需求进行针对性修改，确保工程架构贴合实际业务需求。
+
+## 工程结构
+
+应用采用推荐的分层架构，将代码工程按products、features、common三个层级组织代码工程。各层级设计如下：
+
+- products层：应用需适配的设备包括直板机、双折叠（Mate X系列）、三折叠、阔折叠、平板及电脑。由于电脑界面布局与其他设备差异较大，因此单独创建名为“pc”的包作为电脑设备的应用入口；直板机、双折叠（Mate X系列）、三折叠、阔折叠及平板设备的界面布局整体相似，部分差异可通过“一多”[自适应布局](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-multi-device-adaptive-layout)和[响应式布局](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-multi-device-responsive-layout)适配，为此创建名为“default”的包作为这些设备的应用入口。
+- features层：包含一个核心业务模块——网络连接（multisettinglink）。模块对应创建HAR包，供products层按需引用。
+- common层：为实现代码复用并减少冗余，集中存放公共常量、日志工具类及窗口管理工具等基础能力，供其他模块统一调用。
+
+工程结构如下：
+
+```
+├──common                                          // 公共模块层
+│  └──multisettingbase                             // 公共能力模块
+│     ├──src/main/ets                              // 代码区
+│     │  ├──model                                  // 数据模型
+│     │  ├──utils                                  // 工具类
+│     │  └──view                                   // 公共视图组件
+│     └──src/main/resources                        // 资源目录
+├──features                                         // 功能模块层
+│  └──multisettinglink                             // 网络连接功能模块
+│     ├──src/main/ets                              // 代码区
+│     │  ├──model                                  // 数据模型
+│     │  ├──view                                   // 视图组件
+│     │  └──viewmodel                              // 视图模型
+│     └──src/main/resources                        // 资源目录
+└──products                                        // 产品层
+   ├──default                                      // 手机/平板设备入口
+   │  ├──src/main/ets                              // 代码区
+   │  │  ├──common                                 // 公共常量
+   │  │  ├──entryability                           // 应用入口能力
+   │  │  ├──entrybackupability                     // 备份能力
+   │  │  ├──pages                                  // 页面
+   │  │  ├──view                                   // 视图组件
+   │  │  └──viewmodel                              // 视图模型
+   │  └──src/main/resources                        // 资源目录
+   └──pc                                           // 电脑设备入口
+      ├──src/main/ets                              // 代码区
+      │  ├──common                                 // 公共常量
+      │  ├──pages                                  // 页面
+      │  ├──pcability                              // 电脑应用入口能力
+      │  ├──pcbackupability                        // 电脑备份能力
+      │  ├──view                                   // 视图组件
+      │  └──viewmodel                              // 视图模型
+      └──src/main/resources                        // 资源目录
+```
+
+#### 移动端页面
+
+本章介绍如何针对直板机、双折叠（Mate X系列）、三折叠、阔折叠、平板设备上的设置应用，利用“一多”布局能力，实现页面层级“一套代码、多端适配”的目标。同时，阐述这些设备上的窗口适配方案。
+
+## 窗口适配
+
+- 窗口模式
+
+  适配设备支持全屏、分屏、悬浮窗和自由窗口模式，具体参见[窗口模式](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-multi-device-window-mode)。其中，分屏模式与悬浮窗无需特殊设计，可通过系统方式进入。应用内监听窗口尺寸变化，[通过断点刷新UI](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-multi-device-responsive-layout#section175001836203617)，自动适配全屏、分屏、悬浮窗和自由窗口模式下的布局。
+- 窗口方向
+
+  通过[module.json5配置文件](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/module-configuration-file)，将[abilities标签](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/module-configuration-file#abilities标签)的orientation属性设置为跟随桌面的旋转模式（follow_desktop）。
+- 窗口沉浸式
+
+  根据UX设计，需实现不同窗口模式（全屏、分屏、悬浮窗、自由窗口）下的沉浸式效果，可参考[窗口沉浸式](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-multi-device-window-immersive)。推荐开发者使用组件级沉浸方案（组件设置页面沉浸）[实现沉浸式效果](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-multi-device-window-immersive#section180431120426)，同时需进行动态安全区避让，确保沉浸式显示效果。自由窗口模式下，使用[window.setWindowDecorVisible(false)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#setwindowdecorvisible11)隐藏标题栏，仅保留右上角三键，使应用页面延伸至标题栏区域，实现沉浸式显示效果。
+
+## 导航与详情页
+
+设置应用导航与详情页主要展示列表按钮以及对应详情页，点击导航按钮实现详情页跳转。根据功能设计，应用首页相关内容划分为6个区域，效果图如下：
+
+| 横向断点 | sm | md | lg、xl |
+| --- | --- | --- | --- |
+| 首页 |  |  |  |
+
+**界面开发**
+
+具体介绍及实现方案如下表所示：
+
+| 区域编号 | 简介 | 实现方案 |
+| --- | --- | --- |
+| 1 | 导航页标题栏 | 使用[HdsNavigation](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ui-design-hdsnavigation)实现，通过[titleMode](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ui-design-hdsnavigation#titlemode)属性设置为小标题模式，并设置[titleBar](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ui-design-hdsnavigation#titlebar)实现模糊样式及沉浸光感样式。 |
+| 2 | 搜索栏 | 使用[Search](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-search)组件实现，支持文本输入功能。 |
+| 3 | 导航按钮列表 | 列表基于[List](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-list)组件实现，自定义单个按钮组件，支持传入不同参数展示不同样式，并通过系统路由表实现点击跳转至对应目标页。 |
+| 4 | 内容页标题栏 | 使用[HdsNavDestination](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ui-design-hdsnavdestination)实现，通过[titleMode](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ui-design-hdsnavigation#titlemode)属性设置为小标题模式，并设置[titleBar](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ui-design-hdsnavigation#titlebar)实现模糊样式、沉浸光感样式及标题栏按钮。 |
+| 5 | WLAN页设置按钮列表 | 列表基于[List](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-list)组件实现，自定义单个按钮组件，支持传入不同参数展示不同样式，开关按钮使用[Toggle](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-toggle)实现。 |
+| 6 | WLAN列表 | 列表基于[List](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-list)组件实现，自定义WLAN组件显示WLAN信息及图标。 |
+
+**路由跳转**
+
+通过[HdsNavigation](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ui-design-hdsnavigation)组件、[NavPathStack](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-navigation#navpathstack10)对象、[HdsNavDestination](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ui-design-hdsnavdestination)组件及系统路由表实现页面路由跳转。
+
+- HdsNavigation组件用于展示导航按钮列表，按钮通过点击事件调用NavPathStack对象的[pushPathByName](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-basic-components-navigation#pushpathbyname10)方法跳转至指定页面。
+- HdsNavDestination组件用于构建HdsNavigation组件的子页面，组件中需声明@Builder对外实例化方法，用于注册系统路由表。
+- 在系统路由表中注册子页面实例化方法、源码所在路径及唯一标识符，系统路由表文件路径为entry/src/main/resources/base/profile/router_map.json。
+
+更多内容参考[Navigation页面路由](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-navigation-jump)。
+
+#### 电脑端页面
+
+本章介绍如何基于现有移动端界面开发方案，实现代码逻辑与布局复用，高效完成电脑设备上设置应用的界面开发。
+
+## 导航与详情页
+
+设置应用导航与详情页主要展示列表按钮及对应详情页，点击导航按钮实现详情页跳转。根据功能设计，应用首页相关内容划分为6个区域，效果图如下：
+
+![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/6a/v3/LPfTj6ydRoWoiMyG6sgheA/zh-cn_image_0000002579408636.png?HW-CC-KV=V1&HW-CC-Date=20260623T075614Z&HW-CC-Expire=86400&HW-CC-Sign=F7003679407DA2B79E09EF8B194F469C9F3DD27DAF253B9E44EF1A467424F417 "点击放大")
+
+**界面开发**
+
+具体介绍及实现方案如下表所示：
+
+| 区域编号 | 简介 | 实现方案 |
+| --- | --- | --- |
+| 1 | 导航页标题栏 | 使用[window.setWindowDecorVisible(false)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-window-window#setwindowdecorvisible11)隐藏标题栏，并通过自定义组件实现标题功能。 |
+| 2 | 搜索栏 | 复用移动端导航与详情页对应区域的布局实现方案。 |
+| 3 | 导航按钮列表 |
+| 4 | 内容页标题栏 |
+| 5 | WLAN页设置按钮列表 |
+| 6 | WLAN列表 |
+
+**路由跳转**
+
+同移动端页面-[导航与详情页](#section16469195751520)-路由跳转。
+
+#### 示例代码
+
+[多设备设置界面](https://gitcode.com/HarmonyOS_Samples/NavigationSettings)