HarmonyOS—使用預覽器查看應用/服務效果

DevEco Studio為開發者提供了UI界面預覽功能，可以查看應用/服務的UI界面效果，方便開發者隨時調整界面UI布局。預覽器支持布局代碼的實時預覽，只需要將開發的源代碼進行保存，就可以通過預覽器實時查看應用/服務運行效果，方便開發者隨時調整代碼。

說明
由于操作系統和真機設備的差異，在預覽界面中可能出現字體、顏色等與真機設備運行的效果存在差異，預覽效果僅作為應用/服務開發過程中的參考，實際最終效果請以真機設備運行效果為準。

為了更好的使用體驗，建議先將DevEco Studio升級至最新版本，然后檢測并更新SDK至最新版本。

查看ArkTS和JS應用/服務預覽效果

預覽器支持JS和ArkTS應用/服務“實時預覽”和“動態預覽”。

說明
預覽Phone、Tablet、TV和Wearable設備的JS/ArkTS工程，預覽器功能依賴于電腦顯卡的OpenGL版本，OpenGL版本要求為3.2及以上。
richtext、web、video、XComponent組件不支持預覽。
不支持調用C++庫的預覽。
har在被應用和元服務使用時真機效果有區別，真機上實際效果應用不顯示menubar，元服務顯示menubar，但預覽器都以不顯示menubar為準。若開發har模塊時，請注意被元服務使用時預覽器效果與真機效果的不同。

實時預覽：在開發界面UI代碼過程中，如果添加或刪除了UI組件，您只需Ctrl+S進行保存，然后預覽器就會立即刷新預覽結果。如果修改了組件的屬性，則預覽器會實時（亞秒級）刷新預覽結果，達到極速預覽的效果（當前版本極速預覽僅支持ArkTS組件。API 8工程的極速預覽僅在非數據綁定場景生效，如涉及數據綁定，仍需要在文件保存后才可以預覽；API 9工程的極速預覽支持部分數據綁定場景，如@State變量）。實時預覽默認開啟，如果不需要實時預覽，請單擊預覽器右上角按鈕，關閉實時預覽功能。

說明

開發者修改resources/base/profile目錄下的配置文件（如main_page.json），不支持觸發實時預覽，開發者需要手動刷新。

在這里插入圖片描述
動態預覽：在預覽器界面，可以在預覽器中操作應用/服務的界面交互動作，如單擊、跳轉、滑動等，與應用/服務運行在真機設備上的界面交互體驗一致。

在這里插入圖片描述
在使用預覽器前，請根據如下項檢查環境信息：

確保File > Settings > SDK >
HarmonyOS/OpenHarmony中，已下載Previewer資源。如果已下載Previewer，但存在新版本的情況，建議升級到最新版本，詳情請參考下載HarmonyOS
SDK。
建議將File > Settings > SDK > HarmonyOS/OpenHarmony中的SDK更新至最新版本。

以ArkTS為例，使用預覽器的方法如下：
1.創建或打開一個ArkTS應用/服務工程。本示例以打開一個本地ArkTS Demo工程為例。
2.在工程目錄下，打開任意一個.ets文件（JS工程請打開.hml/.css/.js頁面）。
3.可以通過如下任意一種方式打開預覽器開關，顯示效果如下圖所示：

通過菜單欄，單擊View>Tool Windows>Previewer打開預覽器。
在編輯窗口右上角的側邊工具欄，單擊Previewer，打開預覽器。

在這里插入圖片描述

查看ArkUI預覽效果

ArkUI預覽支持頁面預覽與組件預覽，下圖中左側圖標為頁面預覽，右側圖標為組件預覽。
在這里插入圖片描述

頁面預覽

ArkTS應用/服務支持頁面預覽，要求compileSdkVersion為7或以上。頁面預覽通過在工程的ets文件頭部添加注解@Entry實現。

@Entry的使用參考如下示例：

@Entry
@Component
struct Index {@State message: string = 'Hello World'build() {Row() {Column() {Text(this.message).fontSize(50).fontWeight(FontWeight.Bold)}.width('100%')}.height('100%')}
}

組件預覽

ArkTS應用/服務支持組件預覽，要求compileSdkVersion為8或以上。組件預覽支持實時預覽，不支持動態圖和動態預覽。組件預覽通過在組件前添加注解@Preview實現，在單個源文件中，最多可以使用10個@Preview裝飾自定義組件。

@Preview的使用參考如下示例

@Preview({title: 'FoodImage'
})
@Component
struct FoodImageDisplayPreview {build() {Flex() {FoodImageDisplay({ foodItem: getDefaultFoodData() })}}
}

以上示例的組件預覽效果如下圖所示：
在這里插入圖片描述
組件預覽默認的預覽設備為Phone，若您想在不同的設備，或者不同的屏幕形狀，或者不同設備語言等情況下的組件預覽效果，可以通過設置@Preview的參數，指定預覽設備的相關屬性。若不設置@Preview的參數，默認的設備屬性如下所示：

@Preview({title: 'Component1',  //預覽組件的名稱deviceType: 'phone',  //指定當前組件預覽渲染的設備類型，默認為Phonewidth: 1080,  //預覽設備的寬度，單位：pxheight: 2340,  //預覽設備的長度，單位：pxcolorMode: 'light',  //顯示的亮/暗模式，取值為light或darkdpi: 480,  //預覽設備的屏幕DPI值locale: 'zh_CN',  //預覽設備的語言，如zh_CN、en_US等orientation: 'portrait',  //預覽設備的橫豎屏狀態，取值為portrait或landscaperoundScreen: false  //設備的屏幕形狀是否為圓形
})

請注意，如果被預覽的組件是依賴參數注入的組件，建議的預覽方式是：定義一個組件片段，在該片段中聲明將要預覽的組件，以及該組件依賴的入參，并在組件片段上標注@Preview注解，以表明將預覽該片段中的內容。例如，要預覽如下組件：

@Component
struct Title {context: stringbuild() {Text(this.context)}
}

建議按如下方式預覽：

@Preview
@Component    //定義組件片段TitlePreview
struct TitlePreview {build() {Title({ context: 'MyTitle' })    //在該片段中聲明將要預覽的組件Title，以及該組件依賴的入參 {context: ’MyTitle’}}
}

查看Java應用/服務預覽效果

Java預覽器支持Phone、Tablet、Car、TV和Wearable設備的Java應用/服務布局預覽。Java應用/服務的布局支持Java代碼布局和XML布局兩種方式，其中Java代碼布局（AbilitySlice.java或Ability.java文件）支持實時預覽界面布局效果，同時還可以動態預覽應用/服務的交互效果，如單擊、跳轉、滑動等互動式操作；XML布局文件可以實時預覽，修改和保存了XML代碼后，預覽器會實時展示應用/服務的布局效果。

說明
Java文件預覽是實驗特性，使用中還存在以下約束。
macOS版本的Java預覽器功能，只支持API Version 5及以上版本。
如果xml依賴Java文件中的數據，當修改了xml布局文件后，需要通過啟動Java文件預覽的方式來查看布局效果。
如果xml中引用了Java的自定義組件，不支持預覽。
只支持中的相關UI組件。
只支持jpeg/jpg、png、bmp和wbmp格式的圖片預覽。
不支持HarmonyOS Library模塊的預覽。
不支持Ability間跳轉的預覽。
不支持通過JNI調用C++庫的預覽。

在使用Java預覽器前，請根據如下項檢查環境信息：

需要確保File > Settings > SDK > HarmonyOS
SDK中，已下載對應版本的Previewer資源，如果已下載Previewer，但存在新版本的情況，需要升級到最新版本。
File > Settings > SDK > HarmonyOS SDK中的Java SDK需要更新至最新版本。

使用Java預覽器的方法如下：

1.創建或打開一個Java應用/服務工程。本示例以創建一個新的Java工程為例，具體請參考創建一個新的工程。

2.在工程目錄下，根據布局方式，打開布局文件：

JavaUI布局：打開一個AbilitySlice.java或Ability.java文件

說明
JavaUI布局預覽功能是實驗特性：
Windows系統：請通過File > Settings > Previewer下勾選“Enable java previewer”開啟。macOS系統：請通過DevEco Studio > Preferences > Previewer下勾選“Enable java previewer”開啟。

XML布局：打開一個resources > base > layout目錄下的xml布局文件。

3.可以通過如下任意一種方式打開預覽器開關，顯示效果如下圖所示：

通過菜單欄，單擊View > Tool Windows > Previewer打開預覽器。
在編輯窗口右上角的側邊工具欄，單擊Previewer，打開預覽器。

Profile Manager

說明
該特性在DevEco Studio V2.2 Beta2及更高版本中支持。

由于真機設備有豐富的設備型號，比如Phone設備，包括Mate30、Mate40、P40、P50等設備，不同設備型號的屏幕分辨率可能不一樣。因此，在HarmonyOS應用/服務開發過程中，由于設備類型繁多，可能不能查看在不同設備上的界面顯示效果。對此，DevEco Studio的預覽器提供了Profile Manager功能，支持開發者自定義預覽設備Profile（包含分辨率和語言），從而可以通過定義不同的預覽設備Profile，查看HarmonyOS應用/服務在不同設備上的預覽顯示效果。當前支持自定義設備分辨率及系統語言，如果是Lite Wearable設備類型，還支持自定義屏幕形狀。

定義設備后，可以在Previewer右上角，單擊按鈕，打開Profile管理器，切換預覽設備。

在這里插入圖片描述

同時，Profile Manager還支持多設備預覽功能，具體請參考查看多端設備預覽效果。

下面以自定義一款Phone設備為例，介紹設備Profile Manager的使用方法。

1.在預覽器界面，打開Profile Manager界面。

在這里插入圖片描述

2.在Profile Manager界面，單擊+ New Profile按鈕，添加設備。

在這里插入圖片描述

3.在Create Profile界面，填寫新增設備的信息，如Profile ID（設備型號）、Device type（設備類型）、Resolution（分辨率）和Language and region（語言和區域）等。其中Device type只能選擇config.json（Stage工程中為module.json5）中deviceType字段已定義的設備。

在這里插入圖片描述
4.設備信息填寫完成后，單擊OK完成創建。

查看多端設備預覽效果

DevEco Studio支持HarmonyOS分布式應用/服務開發，同一個應用/服務可以運行在多個設備上。在HarmonyOS分布式應用/服務的開發階段，因不同設備的屏幕分辨率、形狀、大小等不同，開發者需要在不同的設備上查看應用/服務的UI布局和交互效果，此時便可以使用多端設備預覽器功能，方便開發者在應用/服務開發過程中，隨時查看不同設備上的運行效果。

說明
多端設備預覽最多同時支持4個設備的預覽。

前面介紹了DevEco Studio支持ArkTS、JS和Java應用/服務的預覽器功能，多端設備預覽器支持ArkTS、JS與Java應用/服務在不同設備上的同時預覽。如果兩個設備支持的編碼語言不同，就不能使用多端設備預覽功能，例如，Java語言的Phone的應用/服務，是不支持在LiteWearable上運行的，因為LiteWearable不支持Java語言。

下面以ArkTS應用/服務為例，介紹多端設備預覽器的使用方法，JS和Java應用/服務的多端設備預覽器使用方法相同。

1.在工程目錄中，打開任意一個ets文件（JS請打開hml/css/js文件，Java請打開AbilitySlice.java或Ability.java文件）。
2.可以通過如下任意一種方式打開預覽器開關，顯示效果如下圖所示：