HarmonyOS開發(fā)案例：【一次開發(fā)，多端部署-音樂專輯】

簡(jiǎn)介

基于自適應(yīng)和響應(yīng)式布局，實(shí)現(xiàn)一次開發(fā)、多端部署音樂專輯頁面。

相關(guān)概念

• [一次開發(fā)，多端部署]：一套代碼工程，一次開發(fā)上架，多端按需部署。支撐開發(fā)者快速高效的開發(fā)支持多種終端設(shè)備形態(tài)的應(yīng)用，實(shí)現(xiàn)對(duì)不同設(shè)備兼容的同時(shí)，提供跨設(shè)備的流轉(zhuǎn)、遷移和協(xié)同的分布式體驗(yàn)。
• [自適應(yīng)布局]：當(dāng)外部容器大小發(fā)生變化時(shí)，元素可以根據(jù)相對(duì)關(guān)系自動(dòng)變化以適應(yīng)外部容器變化的布局能力。相對(duì)關(guān)系如占比、固定寬高比、顯示優(yōu)先級(jí)等。當(dāng)前自適應(yīng)布局能力有7種：拉伸能力、均分能力、占比能力、縮放能力、延伸能力、隱藏能力、折行能力。自適應(yīng)布局能力可以實(shí)現(xiàn)界面顯示隨外部容器大小連續(xù)變化。
• [響應(yīng)式布局]：當(dāng)外部容器大小發(fā)生變化時(shí)，元素可以根據(jù)斷點(diǎn)、柵格或特定的特征（如屏幕方向、窗口寬高等）自動(dòng)變化以適應(yīng)外部容器變化的布局能力。當(dāng)前響應(yīng)式布局能力有3種：斷點(diǎn)、媒體查詢、柵格布局。
• [GridRow]：柵格容器組件，僅可以和柵格子組件（GridCol）在柵格布局場(chǎng)景中使用。
• [GridCol]：柵格子組件，必須作為柵格容器組件（GridRow）的子組件使用。

環(huán)境搭建

軟件要求

• [DevEco Studio]版本：DevEco Studio 3.1 Release及以上版本。
• OpenHarmony SDK版本：API version 9及以上版本。

硬件要求

• 開發(fā)板類型：[潤(rùn)和RK3568開發(fā)板]。
• OpenHarmony系統(tǒng)：3.2 Release及以上版本。

環(huán)境搭建

完成本篇Codelab我們首先要完成開發(fā)環(huán)境的搭建，本示例以RK3568開發(fā)板為例，參照以下步驟進(jìn)行：

1. [獲取OpenHarmony系統(tǒng)版本]：標(biāo)準(zhǔn)系統(tǒng)解決方案（二進(jìn)制）。以3.2 Release版本為例：
   
2. 搭建燒錄環(huán)境。
   1. [完成DevEco Device Tool的安裝]
   2. [完成RK3568開發(fā)板的燒錄]
3. 搭建開發(fā)環(huán)境。
   1. 開始前請(qǐng)參考[工具準(zhǔn)備]，完成DevEco Studio的安裝和開發(fā)環(huán)境配置。
   2. 開發(fā)環(huán)境配置完成后，請(qǐng)參考[使用工程向?qū)創(chuàng)建工程（模板選擇“Empty Ability”）。
   3. 工程創(chuàng)建完成后，選擇使用[真機(jī)進(jìn)行調(diào)測(cè)]。
   4. 開發(fā)前請(qǐng)熟悉鴻蒙開發(fā)指導(dǎo)文檔：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

代碼結(jié)構(gòu)解讀

本篇Codelab只對(duì)核心代碼進(jìn)行講解，對(duì)于完整代碼，我們會(huì)在gitee中提供。

├──common/src/main/ets               // 公共能力層
│  ├──bean
│  │  └──MenuData.ets                // 菜單數(shù)據(jù)實(shí)體類
│  ├──constants
│  │  ├──BreakpointConstants.ets     // 斷點(diǎn)常量類
│  │  ├──GridConstants.ets           // 柵格常量類
│  │  └──StyleConstants.ets          // 樣式常量類
│  └──utils
│     └──BreakpointSystem.ets        // 斷點(diǎn)工具類
├──features                          // 基礎(chǔ)特性層
│  ├──content/src/main/ets           // 專輯封面和歌曲列表內(nèi)容區(qū)
│  │  ├──components
│  │  │  ├──AlbumComponent.ets       // 自定義專輯封面組件
│  │  │  ├──AlbumCover.ets           // 支持多設(shè)備的自定義專輯封面組件
│  │  │  ├──Content.ets              // 自定義專輯封面和歌曲列表組件
│  │  │  └──PlayList.ets             // 自定義歌曲列表組件
│  │  ├──constants
│  │  │  └──ContentConstants.ets     // 內(nèi)容區(qū)常量類
│  │  └──viewmodel
│  │     ├──SongDataSource.ets       // 懶加載數(shù)據(jù)源
│  │     └──SongListData.ets         // 歌曲列表數(shù)據(jù)類
│  ├──content/src/main/resources     // 資源文件目錄
│  ├──header/src/main/ets            // 頂部標(biāo)題欄
│  │  ├──components
│  │  │  └──Header.ets               // 自定義標(biāo)題欄組件
│  │  └──constants
│  │     └──HeaderConstants.ets      // 標(biāo)題欄常量類
│  ├──header/src/main/resources      // 資源文件目錄
│  └──player/src/main/ets            // 底部播放控制區(qū)
│  │  ├──components
│  │  │  └──Player.ets               // 自定義底部播放控制區(qū)組件
│  │  └──constants
│  │     └──PlayerConstants.ets      // 播放控制區(qū)常量類
│  └──player/src/main/resources      // 資源文件目錄
└──products                          // 產(chǎn)品定制層
   ├──phone/src/main/ets             // 支持手機(jī)、平板
   │  ├──entryability
   │  │  └──EntryAbility.ts          // 程序入口類
   │  └──pages
   │     └──MainPage.ets             // 主界面
   └──phone/src/main/resources       // 資源文件目錄
   
`HarmonyOS與OpenHarmony鴻蒙文檔籽料：mau123789是v直接拿`

工程結(jié)構(gòu)管理

在這個(gè)章節(jié)中，我們需要完成模塊劃分、梳理模塊間依賴關(guān)系并設(shè)計(jì)代碼結(jié)構(gòu)，從而便于后續(xù)復(fù)雜項(xiàng)目的維護(hù)。參考上一章節(jié)頁面設(shè)計(jì)，我們可以將頁面分拆為多個(gè)組成部分：

1. 標(biāo)題欄
2. 專輯封面
3. 歌曲列表
4. 播放控制區(qū)

工程結(jié)構(gòu)建議如下：

• 定義common層（公共能力層）： 用于存放項(xiàng)目的工具類、公共常量等。需編譯成一個(gè)HAR包，只可以被products和features依賴，不可以反向依賴。
• 定義features層（基礎(chǔ)特性層）： 用于存放相對(duì)獨(dú)立的各個(gè)功能單元、自定義UI組件或業(yè)務(wù)實(shí)現(xiàn)邏輯，供產(chǎn)品靈活部署。不需要單獨(dú)部署的feature通常編譯為HAR包，供products或其它features使用。需要單獨(dú)部署的feature通常編譯為Feature類型的HAP包，和products下Entry類型的HAP包進(jìn)行組合部署。features層可以橫向調(diào)用及依賴common層，同時(shí)可以被products層不同設(shè)備形態(tài)的HAP所依賴，但是不能反向依賴products層。
• 定義products層（產(chǎn)品定制層）： 用于針對(duì)不同設(shè)備形態(tài)進(jìn)行功能和特性集成。products層各個(gè)子目錄分別編譯為一個(gè)Entry類型的HAP包，作為應(yīng)用的主入口，products層不可以橫向調(diào)用。

本篇Codelab通過common層管理媒體查詢工具類、柵格常量、公共常量等；按照頁面分組，將標(biāo)題欄定義為header基礎(chǔ)特性，將專輯封面和歌曲列表定義為content基礎(chǔ)特性，將播放控制區(qū)定義為player基礎(chǔ)特性；定義phone產(chǎn)品目錄支持手機(jī)、平板等設(shè)備，集成基礎(chǔ)特性層的能力。products依賴features和common，features依賴common但不互相依賴，工程結(jié)構(gòu)清晰且便于維護(hù)。

├──common               // 公共能力層
├──features             // 基礎(chǔ)特性層
│  ├──content           // 專輯封面和歌曲列表內(nèi)容區(qū)
│  ├──header            // 頂部標(biāo)題欄
│  └──player            // 底部播放控制區(qū)
└──products             // 產(chǎn)品定制層
   └──phone             // 支持手機(jī)、平板

一次開發(fā)，多端部署實(shí)現(xiàn)方案

多標(biāo)題欄

在這個(gè)章節(jié)中，我們需完成頂部標(biāo)題欄的實(shí)現(xiàn)方案。不同設(shè)備的標(biāo)題欄始終只顯示“返回按鈕”、“歌單”以及“更多按鈕”，中間空白區(qū)域通過Blank組件填充，可實(shí)現(xiàn)自適應(yīng)拉伸能力。

// Header.ets
@Component
export struct Header {
  @StorageProp('fontSize') fontSize: number = 0;

  build() {
    Row() {
      Image($r('app.media.ic_back'))
        .width($r('app.float.icon_width'))
        .height($r('app.float.icon_height'))
        .margin({ left: $r('app.float.icon_margin') })
      Text($r('app.string.play_list'))
        .fontSize(this.fontSize + HeaderConstants.TITLE_FONT_SIZE_PLUS)
        .fontWeight(HeaderConstants.TITLE_FONT_WEIGHT)
        .fontColor($r('app.color.title_color'))
        .opacity($r('app.float.title_opacity'))
        .letterSpacing(HeaderConstants.LETTER_SPACING)
        .padding({ left: $r('app.float.title_padding_left') })

      Blank()

      Image($r('app.media.ic_more'))
        .width($r('app.float.icon_width'))
        .height($r('app.float.icon_height'))
        .margin({ right: $r('app.float.icon_margin') })
        .bindMenu(this.getMenu())
    }
    .width(StyleConstants.FULL_WIDTH)
    .height($r('app.float.title_bar_height'))
    .zIndex(HeaderConstants.Z_INDEX)
  }
}

專輯封面

在這個(gè)章節(jié)中，我們需完成專輯封面的實(shí)現(xiàn)方案。專輯封面由圖片、歌單介紹及常用操作（“收藏”“下載”“評(píng)論”“分享”）三部分組成，這三部分的布局可以用柵格實(shí)現(xiàn)。

• 在sm斷點(diǎn)下，圖片占4個(gè)柵格，歌單介紹占8個(gè)柵格，常用操作占12個(gè)柵格。
• 在md斷點(diǎn)下，圖片、歌單介紹和常用操作分別占12個(gè)柵格。
• 在lg斷點(diǎn)下，圖片、歌單介紹和常用操作分別占12個(gè)柵格。

// AlbumComponent.ets
@Component
export struct AlbumComponent {
  @StorageProp('coverMargin') coverMargin: number = 0;
  @StorageProp('currentBreakpoint') currentBreakpoint: string = 'sm';

  ...
  build() {
    Column() {
      GridRow() {
        GridCol({
          span: { sm: GridConstants.SPAN_FOUR, md: GridConstants.SPAN_TWELVE, lg: GridConstants.SPAN_TWELVE }
        }) {
          this.CoverImage()
        }

        GridCol({
          span: { sm: GridConstants.SPAN_EIGHT, md: GridConstants.SPAN_TWELVE, lg: GridConstants.SPAN_TWELVE }
        }) {
          this.CoverIntroduction()
        }

        GridCol({
          span: { sm: GridConstants.SPAN_TWELVE, md: GridConstants.SPAN_TWELVE, lg: GridConstants.SPAN_TWELVE }
        }) {
          this.CoverOptions()
        }
        .padding({
          top: this.currentBreakpoint === BreakpointConstants.BREAKPOINT_SM ? $r('app.float.option_margin') : 0,
          bottom: this.currentBreakpoint === BreakpointConstants.BREAKPOINT_SM ? $r('app.float.option_margin') : 0
        })
      }
      .padding({
        top: this.currentBreakpoint === BreakpointConstants.BREAKPOINT_SM ?
        $r('app.float.cover_padding_top_sm') : $r('app.float.cover_padding_top_other')
      })
    }
    .margin({
      left: this.coverMargin,
      right: this.coverMargin
    })
  }
}

對(duì)于“收藏”、“下載”、“評(píng)論”、“分享”常用操作，通過設(shè)置容器組件的justifyContent屬性為FlexAlign.SpaceEvenly，實(shí)現(xiàn)自適應(yīng)均分能力。對(duì)于專輯圖片，設(shè)置aspectRatio屬性為1，Image組件寬高比固定為1:1，實(shí)現(xiàn)自適應(yīng)縮放能力。

// AlbumComponent.ets
@Component
export struct AlbumComponent {
  ...

  @Builder
  CoverImage() {
    Stack({ alignContent: Alignment.BottomStart }) {
      ...
    }
    .width(StyleConstants.FULL_WIDTH)
    .height(StyleConstants.FULL_HEIGHT)
    .aspectRatio(ContentConstants.ASPECT_RATIO_ALBUM_COVER)
  }

  ...
  @Builder
  CoverOptions() {
    Row() {
      ForEach(optionList, item = > {
        Column({ space: ContentConstants.COVER_OPTION_SPACE }) {
          Image(item.image)
            .height($r('app.float.option_image_size'))
            .width($r('app.float.option_image_size'))
          Text(item.text)
            .fontColor($r('app.color.album_name_introduction'))
            .fontSize(this.fontSize - 1)
        }
      })
    }
    .height($r('app.float.option_area_height'))
    .width(StyleConstants.FULL_WIDTH)
    .justifyContent(FlexAlign.SpaceEvenly)
  }
}

歌曲列表

在這個(gè)章節(jié)中，我們需完成歌曲列表的實(shí)現(xiàn)方案。對(duì)于不同屏幕尺寸的設(shè)備，歌單列表的樣式基本一致，但sm和md斷點(diǎn)下的歌曲列表是單列顯示，lg斷點(diǎn)下的歌曲列表是雙列顯示?？梢酝ㄟ^List組件的lanes屬性實(shí)現(xiàn)這一效果。

// PlayList.ets
@Component
export struct PlayList {
  @Consume coverHeight: number;
  @StorageProp('currentBreakpoint') currentBreakpoint: string = 'sm';
  @StorageProp('fontSize') fontSize: number = 0;

  ...
  build() {
    Column() {
      this.PlayAll()
      List() {
        LazyForEach(new SongDataSource(songList), (item: SongItem) = > {
          ListItem() {
            Column() {
              this.SongItem(item.title, item.label, item.singer)
              Divider()
                .strokeWidth(ContentConstants.DIVIDER_STROKE_WIDTH)
                .color($r('app.color.black'))
                .opacity($r('app.float.divider_opacity'))
            }
            .padding({
              left: $r('app.float.list_item_padding'),
              right: $r('app.float.list_item_padding')
            })
          }
        }, (item, index) = > JSON.stringify(item) + index)
      }
      .width(StyleConstants.FULL_WIDTH)
      .height(StyleConstants.FULL_HEIGHT)
      .backgroundColor($r('app.color.white'))
      .margin({ top: $r('app.float.list_area_margin_top') })
      .lanes(this.currentBreakpoint === BreakpointConstants.BREAKPOINT_LG ?
        ContentConstants.COL_TWO : ContentConstants.COL_ONE)
    }
    .padding({
      top: this.currentBreakpoint === BreakpointConstants.BREAKPOINT_SM ? 0 : $r('app.float.list_area_padding_top'),
      bottom: $r('app.float.list_area_padding_bottom')
    })
  }
  ...
  }
}

播放控制區(qū)

在這個(gè)章節(jié)中，我們需完成底部播放控制區(qū)的實(shí)現(xiàn)方案。對(duì)于不同屏幕尺寸的設(shè)備，播放控制區(qū)顯示的內(nèi)容有差異，sm斷點(diǎn)僅顯示播放按鈕，md斷點(diǎn)顯示上一首、播放和下一首按鈕，lg斷點(diǎn)顯示收藏、上一首、播放、下一首、列表按鈕，可以分別設(shè)置按鈕的displayPriority屬性，通過自適應(yīng)隱藏能力實(shí)現(xiàn)。同時(shí)，歌曲信息與播放控制按鈕之間通過Blank組件自動(dòng)填充，實(shí)現(xiàn)自適應(yīng)拉伸能力。

// Player.ets
@Component
export struct Player {
  ...

  build() {
    Row() {
      ...
    
      Blank()

      Row() {
        Image($r('app.media.ic_favorite'))
          ...
          .displayPriority(PlayerConstants.DISPLAY_PRIORITY_ONE)
        Image($r('app.media.ic_previous'))
          ...
          .displayPriority(PlayerConstants.DISPLAY_PRIORITY_TWO)
        Image($r('app.media.ic_pause'))
          ...
          .displayPriority(PlayerConstants.DISPLAY_PRIORITY_THREE)
        Image($r('app.media.ic_next'))
          ...
          .displayPriority(PlayerConstants.DISPLAY_PRIORITY_TWO)
        Image($r('app.media.ic_music_list'))
          ...
          .displayPriority(PlayerConstants.DISPLAY_PRIORITY_ONE)
      }
      .layoutWeight(PlayerConstants.LAYOUT_WEIGHT_PLAYER_CONTROL)
      .justifyContent(FlexAlign.End)
    }
    ...
  }
}

特性集成

在這個(gè)章節(jié)中，我們將標(biāo)題欄（header基礎(chǔ)特性）、專輯內(nèi)容（content基礎(chǔ)特性）、播放控制區(qū)（player基礎(chǔ)特性）集成到一起，作為應(yīng)用的主入口。同時(shí)，后續(xù)項(xiàng)目如果新增更多的產(chǎn)品例如穿戴設(shè)備、智慧屏等，可定義新的products產(chǎn)品、自由集成不同的features基礎(chǔ)特性，從而達(dá)成代碼盡量復(fù)用、產(chǎn)品自由定制的目標(biāo)。

// MainPage.ets
@Component
struct MainPage {
  ...

  build() {
    Stack({ alignContent: Alignment.Top }) {
      Header()
      Content()
      Player()
    }
    ...
}

解決系統(tǒng)能力差異的兼容性問題

前面章節(jié)主要介紹了如何解決頁面適配、工程管理的問題，本章節(jié)主要介紹應(yīng)用如何解決設(shè)備系統(tǒng)能力差異的兼容問題。

我們以一個(gè)簡(jiǎn)單例子說明：一個(gè)具有音頻設(shè)備管理功能的應(yīng)用，如何兼容地運(yùn)行在有音頻設(shè)備管理和無音頻設(shè)備管理系統(tǒng)能力的設(shè)備上。

從開發(fā)到用戶安裝、運(yùn)行，一般要經(jīng)歷幾個(gè)階段：應(yīng)用分發(fā)和下載->應(yīng)用安裝->應(yīng)用運(yùn)行，要解決上面提到的兼容問題，一般有如下幾種解決思路：

1. 分發(fā)和下載：有音頻設(shè)備管理設(shè)備的用戶才能在應(yīng)用市場(chǎng)可見該應(yīng)用，供用戶下載。
2. 安裝：有音頻設(shè)備管理能力的設(shè)備才允許安裝該應(yīng)用。
3. 運(yùn)行：在運(yùn)行階段通過動(dòng)態(tài)判斷方式，在有音頻設(shè)備管理設(shè)備上功能運(yùn)行正常，在無音頻設(shè)備管理設(shè)備上運(yùn)行不發(fā)生Crash。

所以，對(duì)應(yīng)的解決方案就有：

1. 在分發(fā)階段，上架的應(yīng)用使用的系統(tǒng)能力是設(shè)備系統(tǒng)能力的子集。滿足這個(gè)條件，用戶才能在應(yīng)用市場(chǎng)看到該應(yīng)用。
2. 在安裝階段，安裝的應(yīng)用調(diào)用的系統(tǒng)能力是設(shè)備系統(tǒng)能力的子集。滿足這個(gè)條件，用戶才能安裝該應(yīng)用。
3. 通過canIUse接口判斷是否支持某個(gè)系統(tǒng)能力。

本篇Codelab以音頻設(shè)備管理為例，僅介紹canIUse接口判斷的方式。點(diǎn)擊右上角更多，如果當(dāng)前系統(tǒng)支持音頻設(shè)備管理能力，則顯示“音頻設(shè)備管理”菜單選項(xiàng)，否則不顯示。

// Header.ets
@Component
export struct Header {
  ...

  getMenu(): MenuData[] {
    let menuItem: MenuData = new MenuData();
    let menuDatas: MenuData[] = [];
    if (canIUse(HeaderConstants.SYSCAP_ETHERNET)) {
      menuItem.value = HeaderConstants.AUDIO_DEVICE_SERVICE;
      menuItem.action = () = > {
        promptAction.showToast({
          message: HeaderConstants.AUDIO_DEVICE_SERVICE,
          duration: HeaderConstants.TOAST_DURATION
        });
      };
      menuDatas.push(menuItem);
    }
    return menuDatas;
  }
}

審核編輯 黃宇