当前位置：首页 > news >正文

DevEco Studio 预览器的使用

news 2025/9/28 10:13:43

查看ArkTS/JS预览效果

预览器支持ArkTS/JS应用/元服务“实时预览”和“动态预览”。

说明

预览支持Phone、Tablet、2in1、Car、Wearable、TV设备的ArkTS工程，支持LiteWearable和Wearable设备的JS工程。
预览器功能依赖于电脑显卡的OpenGL版本，OpenGL版本要求为3.2及以上。
预览时将不会运行Ability生命周期。
从DevEco Studio 6.0.0 Beta3版本开始，HAP/HSP引用HSP时支持预览，HAR模块引用HSP不支持预览，请直接在HSP内预览或为该HSP设置Mock实现。
预览场景下，不支持通过相对路径及绝对路径的方式访问resources目录下的文件。
预览不支持组件拖拽。
部分API不支持预览，如Ability、App、MultiMedia等模块。
Richtext、Web、Video、XComponent组件不支持预览。
不支持调用C++库的预览。
har在被应用/元服务使用时真机效果有区别，真机上实际效果应用不显示menubar，元服务显示menubar，但预览器都以不显示menubar为准。若开发har模块时，请注意被元服务使用时预览器效果与真机效果的不同。
实时预览

：在开发界面UI代码过程中，如果添加或删除了UI组件，您只需

Ctrl+S

进行保存，然后预览器就会立即刷新预览结果。如果修改了组件的属性，则预览器会实时（亚秒级）刷新预览结果，达到极速预览的效果（当前版本极速预览仅支持ArkTS组件。支持部分数据绑定场景，如@State装饰的变量）。实时预览默认开启，如果不需要实时预览，请单击预览器右上角

按钮，关闭实时预览功能。

说明

开发者修改resources/base/profile目录下的配置文件（如main_pages.json/form_config.json），不支持触发实时预览，开发者需要点击重新加载。
动态预览

：在预览器界面，可以在预览器中操作应用/元服务的界面交互动作，如单击、跳转、滑动等，与应用/元服务运行在真机设备上的界面交互体验一致。

以ArkTS为例，使用预览器的方法如下：

创建或打开一个ArkTS应用/元服务工程。本示例以打开一个本地ArkTS Demo工程为例。
在工程目录下，打开任意一个.ets文件（JS工程请打开.hml/.css/.js页面）。
可以通过如下任意一种方式打开预览器，启动预览。
- 通过菜单栏，单击View > Tool Windows > Previewer打开预览器。
- 在编辑窗口右上角的侧边工具栏，单击Previewer，打开预览器。
点击按钮，停止预览。

查看ArkUI预览效果

ArkUI预览支持页面预览、组件预览和卡片预览，下图中左侧图标为页面预览，右侧图标为组件预览，卡片预览在创建卡片文件后可直接预览。

页面预览

ArkTS应用/元服务支持页面预览。页面预览通过在工程的ets文件头部添加@Entry实现。

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

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

组件预览

ArkTS应用/元服务支持组件预览。组件预览支持实时预览，不支持动态图和动态预览。组件预览通过在组件前添加注解@Preview实现，在单个源文件中，最多可以使用10个@Preview装饰自定义组件。

@Preview的使用参考如下示例：

@Preview({  title: 'ContentTable'})@Componentstruct ContentTablePreview {  build() {    Flex() {      ContentTable({ foodItem: getDefaultFoodData() })    }  }}

以上示例的组件预览效果如下图所示：

组件预览默认的预览设备为Phone，若您想查看不同的设备，或者不同的屏幕形状，或者不同设备语言等情况下的组件预览效果，可以通过设置@Preview的参数，指定预览设备的相关属性。若不设置@Preview的参数，默认的设备属性如下所示：

@Preview({  title: 'Component1',  //预览组件的名称  deviceType: 'phone',  //指定当前组件预览渲染的设备类型，默认为Phone  width: 1080,  //预览设备的宽度，单位：px  height: 2340,  //预览设备的长度，单位：px  colorMode: 'light',  //显示的亮暗模式，当前支持取值为light  dpi: 480,  //预览设备的屏幕DPI值  locale: 'zh_CN',  //预览设备的语言，如zh_CN、en_US等  orientation: 'portrait',  //预览设备的横竖屏状态，取值为portrait或landscape  roundScreen: false  //设备的屏幕形状是否为圆形})

请注意，如果被预览的组件是依赖参数注入的组件，建议的预览方式是：定义一个组件片段，在该片段中声明将要预览的组件，以及该组件依赖的入参，并在组件片段上标注@Preview注解，以表明将预览该片段中的内容。例如，要预览如下组件：

@Componentstruct Title {  @Prop context: string;   build() {    Text(this.context)  }}

建议按如下方式预览：

@Preview@Component    //定义组件片段TitlePreviewstruct TitlePreview {  build() {    Title({ context: 'MyTitle' })    //在该片段中声明将要预览的组件Title，以及该组件依赖的入参 {context: 'MyTitle'}  }}

卡片预览

创建卡片并选中卡片文件后，点击右侧边栏Previewer按钮即可预览卡片。

Profile Manager

由于真机设备有丰富的设备型号，不同设备型号的屏幕分辨率可能不一样。因此，在HarmonyOS应用/元服务开发过程中，由于设备类型繁多，可能需要查看在不同设备上的界面显示效果。对此，DevEco Studio的预览器提供了Profile Manager功能，支持开发者自定义预览设备Profile（包含分辨率和语言），从而可以通过定义不同的预览设备Profile，查看HarmonyOS应用/元服务在不同设备上的预览显示效果。当前支持自定义设备分辨率及系统语言。

定义设备后，可以在Previewer右上角，单击按钮，打开Profile管理器，切换预览设备。

同时，Profile Manager还支持多设备预览功能，具体请参考查看多端设备预览效果。

下面以自定义一款Phone设备为例，介绍设备Profile Manager的使用方法。

在预览器界面，打开Profile Manager界面。
在Profile Manager界面，单击**+ New Profile**按钮，添加设备。
在Create Profile界面，填写新增设备的信息，如Profile ID（设备型号）、Device type（设备类型）、Resolution（分辨率）和Language and region（语言和区域）等。其中Device type只能选择module.json5中deviceTypes字段已定义的设备。
设备信息填写完成后，单击OK完成创建。

查看多端设备预览效果

DevEco Studio支持HarmonyOS分布式应用/元服务开发，同一个应用/元服务可以运行在多个设备上。在HarmonyOS分布式应用/元服务的开发阶段，因不同设备的屏幕分辨率、形状、大小等不同，开发者需要在不同的设备上查看应用/元服务的UI布局和交互效果，此时便可以使用多端设备预览器功能，方便开发者在应用/元服务开发过程中，随时查看不同设备上的界面显示效果。

说明

多端设备预览最多同时支持4个设备的预览。

前面介绍了DevEco Studio支持ArkTS、JS应用/元服务的预览器功能，多端设备预览器支持ArkTS、JS应用/元服务在不同设备上的同时预览。如果两个设备支持的编码语言不同，就不能使用多端设备预览功能。

下面以ArkTS应用/元服务为例，介绍多端设备预览器的使用方法，JS应用/元服务的多端设备预览器使用方法相同。
1. 在工程目录中，打开任意一个ets文件（JS请打开hml/css/js文件）。
2. 可以通过如下任意一种方式打开预览器开关，显示效果如下图所示：
  - 通过菜单栏，单击View > Tool Windows > Previewer，打开预览器。
  - 在编辑窗口右上角的侧边工具栏，单击Previewer，打开预览器。
3. 在Previewer窗口中，打开Profile Manager中的Multi-profile preview开关，同时查看多设备上的应用/元服务运行效果。
  
  说明
  
  多端设备预览不支持动画的预览，如果需要查看动画在设备上的预览效果，请关闭Multi-profile preview功能后在单设备预览界面进行查看。
  
  多设备预览效果如下图所示：
  
  Inspector双向预览
  
  DevEco Studio提供HarmonyOS应用/元服务的UI预览界面与源代码文件间的双向预览功能，支持ets文件与预览器界面的双向预览。使用双向预览功能时，需要在预览器界面单击图标打开双向预览功能。
  
  说明
  
  不支持服务卡片的双向预览功能。
  
  开启双向预览功能后，支持代码编辑器、UI界面和Component Tree组件树三者之间的联动：
  - 选中预览器UI界面中的组件，则组件树上对应的组件将被选中，同时代码编辑器中的布局文件中对应的代码块高亮显示。
  - 选中布局文件中的代码块，则在UI界面会高亮显示，组件树上的组件节点也会呈现被选中的状态。
  - 选中组件树中的组件，则对应的代码块和UI界面也会高亮显示。
  在预览界面还可以通过组件的属性面板修改可修改的属性或样式，在预览界面修改后，预览器会自动同步到代码编辑器中修改源码，并实时的刷新UI界面；同样的，如果在代码编辑器中修改源码，也会实时刷新UI界面，并更新组件树信息及组件属性。
  
  说明
  - 如果组件有做数据绑定，则其属性不支持在属性面板修改。
  - 如果界面有使用动画效果或者带动画效果组件，则其属性不支持在属性面板修改。
  - 多设备预览时，不支持双向预览。

预览数据模拟

说明

仅API 11及以上版本的Stage工程支持。

在预览场景中，由于代码的运行环境与真机设备上的运行环境不同，调用部分接口时无法获取到有效的返回值（例如获取电池电量信息等，在预览场景下batteryInfo.voltage返回的是一个固定的值0），这样开发者就无法在预览时查看到不同返回值带来的界面变化。因此，Hamock提供了预览场景的模拟功能，在不改变业务运行逻辑的同时，开发者可以模拟UI组件上的属性或方法，或模拟import的模块接口。

使用前提

使用Hamock在预览场景模拟，需要在工程或模块的oh-package.json5中添加该依赖，然后重新同步工程。

"devDependencies": {    "@ohos/hamock": "1.0.0"}

UI组件上的Mock

Hamock提供了@MockSetup用于修饰Mock方法，仅支持声明式范式的组件。当开发者预览该组件时，预览运行时将在组件初始化时执行被@MockSetup修饰的方法。因此，开发者可以在这个被修饰的方法内重定义组件的方法或重赋值组件的属性，其将在预览时生效。

说明

@MockSetup修饰的方法仅在预览场景会自动触发，并先于组件的aboutToAppear执行。

UI组件的方法

在ArkTS页面代码中引入Hamock。

import { MockKit, when, MockSetup } from '@ohos/hamock';

在目标组件中定义一个方法，并用@MockSetup修饰该方法。在这个方法中，使用MockKit模拟目标方法。

import { MockKit, when, MockSetup } from '@ohos/hamock';
@Entry@Componentstruct Index { ... @MockSetup randomName() {  let mocker: MockKit = new MockKit();  let mockfunc: Object = mocker.mockFunc(this, this.method1);  // mock 指定的方法在指定入参的返回值  when(mockfunc)('test').afterReturn(1); } ... // 业务场景调用方法 const result = this.method1('test'); // in previewer, result = 1}

UI组件的属性

在ArkTS页面代码中引入Hamock。

import { MockSetup } from '@ohos/hamock';

在目标组件中定义一个方法，并用@MockSetup修饰该方法。在这个方法中，对于需要Mock的属性，可以重新赋值。

import { MockSetup } from '@ohos/hamock';
@Componentstruct Person { @Prop species: string; // 在@MockSetup片段中，定义对象属性 @MockSetup randomName() {  this.species = 'primates' } ... // 业务场景调用属性（如果从初始化到调用期间，该属性无变化） const result = this.species // in previewer, result = primates}

说明

ArkUI部分类型属性不支持Mock，如readonly、@ObjectLink。
被@Link/@Consume/@Prop/@BuilderParam装饰器修饰的变量，ArkUI语法要求父容器需要有对应属性的定义，因此更推荐开发者通过定义⼀个预览场景父容器（并通过父容器传递合适的数据）来预览这⼀类的组件。

模块的Mock

模块的Mock支持对系统模块、依赖模块及本地模块的Mock，通过新建ArkTS文件定义Mock实现代码，并在mock-config.json5配置文件中定义目标模块与Mock实现代码文件的映射关系。目标模块与Mock实现代码文件为一对一的关系，即对于同一目标模块，仅支持一份Mock实现代码，预览运行时，所有页面import目标模块都将指向这一份Mock实现代码。

系统模块/依赖的模块

在src/mock目录下新建一个ArkTS文件，在这个文件内定义目标模块的Mock实现。

// src/mock/MeasureText.mock.etsimport MeasureText from '@ohos.measure'
// 类的mock使用继承(extends)的方式实现class MockMeasureText extends MeasureText {  // 定义mock实现  static measureText(): number {    console.log('Return value of the mock measureText function')    return 100;  }};
export default MockMeasureText;

说明

用户在对类定义Mock的实现时，需要使用继承(extends)的方式实现。

在Mock配置文件src/mock/mock-config.json5中定义目标模块与Mock实现的替换关系。该替换关系会在预览场景下生效。

{  "@ohos.measure": { // 待替换的moduleName    "source": "src/mock/MeasureText.mock.ets" // Mock代码的路径，相对于模块根目录  }, ...}

在原调用处中添加Hilog日志，方便在预览时，在Log中打印获取返回值，从而验证Mock是否生效。
```
hilog.debug(DomainNumber, logTag, 'Mock %{public}s', `${MeasureText.measureText({textContent: 'Hello World'})}`)
```

本地模块

在src/mock目录下新建一个ArkTS文件，在这个文件内定义目标模块的Mock实现。

// src/mock/module/utils/CommonUtils.mock.ts// import local moduleimport LibDefaultExport from '../../../main/ets/utils/CommonUtils'; // get origin default exportimport { methodA, ObjectB } from '../../../main/ets/utils/CommonUtils'; // get origin export on demand
class DefaultExportMock extends LibDefaultExport {  // 定义mock实现  public static getName(): String {    return "Mocked Name";  }};
export {  methodA,  ObjectB,}
export default DefaultExportMock;

其中CommonUtils.ets文件示例如下：

export default class CommonUtils {  public static getName(): String {    return "origin name";  }public static getTitle(): String {    return "origin title";  }}
export const methodA = (): string => {  return "methodA"}
export const ObjectB: Object = new Object();

说明

本地模块的Mock仅支持src/main/ets目录下的ArkTS或TS文件。

在Mock配置文件src/mock/mock-config.json5中定义目标模块与Mock实现的替换关系。该替换关系会在预览场景下生效。

{ "utils/CommonUtils.ets": { // 本地模块只支持ets/xxx的相对路径，并需明确文件后缀  "source": "src/mock/module/utils/CommonUtils.mock.ts" }, ...}

在原调用处中添加Hilog日志，方便在预览时，在Log中打印获取返回值，从而验证Mock是否生效。
```
hilog.debug(DomainNumber, logTag, 'Mock %{public}s', CommonUtils.getName());
```
支持使用预览器的API清单

组件

ArkTS组件

组件	API
基础组件	AlphabetIndexer
	Blank
Button
Checkbox
CheckboxGroup
DataPanel
DatePicker
Divider
Gauge
Image
ImageAnimator
ImageSpan
LoadingProgress
Marquee
Menu
MenuItem
MenuItemGroup
Navigation
NavRouter
NavDestination
PatternLock
Progress
QRCode
Radio
Rating
ScrollBar
Search
Select
Slider
Span
Stepper
StepperItem
Text
TextArea
TextClock
TextInput
TextPicker
TextTimer
Toggle
容器组件	Badge
Column
ColumnSplit
Counter
Flex
FlowItem
GridCol
GridRow
List
ListItem
ListItemGroup
Navigator
Panel
Refresh
RelativeContainer
Row
RowSplit
Scroll
SideBarContainer
Stack
Swiper
Tabs
TabContent
WaterFlow
绘制组件	Circle
Ellipse
Line
Polyline
Path
Rect
Shape
画布组件	Canvas
CanvasGradient
CanvasPattern
CanvasRenderingContext2D
ImageBitmap
ImageData
Matrix2D
OffscreenCanvasRenderingContext2D
Path2D

JS组件

组件	API
基础组件	button
chart
divider
image
image-animator
input
label
marquee
menu
option
picker
picker-view
piece
progress
qrcode
rating
search
select
slider
span
switch
text
textarea
toolbar
toolbar-item
toggle
容器组件	badge
dialog
div
form
list
list-item
list-item-group
panel
popup
refresh
stack
stepper
stepper-item
swiper
tabs
tab-bar
tab-content
画布组件	canvas
CanvasRenderingContext2D
Image
CanvasGradient
ImageData
Path2D
ImageBitmap
OffscreenCanvas
OffscreenCanvasRenderingContext2D
栅格组件	grid-container
grid-row
grid-col
svg组件	svg
rect
circle
ellipse
path
line
polyline
polygon
text
tspan
textPath
animate
animateMotion
animateTransform

接口

UI界面

模块	API
@ohos.animator (动画)	Animator
AnimatorResult
AnimatorOptions
@ohos.mediaquery (媒体查询)	matchMediaSync
MediaQueryResult
MediaQueryListener
@ohos.promptAction (弹窗)	showToast
showDialog
showActionMenu
ShowToastOptions
Button
ShowDialogSuccessResponse
ShowDialogOptions
ActionMenuSuccessResponse
ActionMenuOptions
@ohos.router (页面路由)	pushUrl
replaceUrl
back
clear
getLength
getState
enableAlertBeforeBackPage
disableAlertBeforeBackPage
getParams
RouterMode
RouterOptions
RouterState
EnableAlertOptions

网络管理

模块	API
@ohos.net.http (数据请求)	http.createHttp如果Http请求需要配置代理才能访问，API 12及以上的预览器支持使用系统的http_proxy/https_proxy/no_proxy环境变量。

数据管理

模块	API
@ohos.data.preferences (用户首选项)	data_preferences.getPreferences
data_preferences.deletePreferences
data_preferences.removePreferencesFromCache
Preferences
ValueType