查看ArkTS/JS预览效果

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

说明

• 预览支持Phone、Tablet、2in1、Car设备的ArkTS工程，支持Litewearable设备的JS工程。
• 预览器功能依赖于电脑显卡的OpenGL版本，OpenGL版本要求为3.2及以上。
• 预览时将不会运行Ability生命周期。
• 预览不支持引用HSP。引用了HSP的模块不支持预览，请直接在HSP内预览。
• 预览场景下，不支持通过相对路径及绝对路径的方式访问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为例，使用预览器的方法如下：

1. 创建或打开一个ArkTS应用/服务工程。本示例以打开一个本地ArkTS Demo工程为例。
2. 在工程目录下，打开任意一个.ets文件（JS工程请打开.hml/.css/.js页面）。
3. 可以通过如下任意一种方式打开预览器开关，显示效果如下图所示：
   • 通过菜单栏，单击View>Tool Windows>Previewer打开预览器。
   • 在编辑窗口右上角的侧边工具栏，单击Previewer，打开预览器。

   

ArkUI预览支持页面预览与组件预览，下图中左侧图标

为页面预览，右侧图标

为组件预览。

页面预览

ArkTS应用/服务支持页面预览。页面预览通过在工程的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应用/服务支持组件预览。组件预览支持实时预览，不支持动态图和动态预览。组件预览通过在组件前添加注解@Preview实现，在单个源文件中，最多可以使用10个@Preview装饰自定义组件。

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

@Preview({
  title: 'FoodImage'
})
@Component
struct FoodImageDisplayPreview {
  build() {
    Flex() {
      FoodImageDisplay({ 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注解，以表明将预览该片段中的内容。例如，要预览如下组件：

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

建议按如下方式预览：

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

在Phone和Tablet中运行HarmonyOS应用/服务的操作方法一致，可以采用USB连接方式或者无线调试的连接方式。两种连接方式是互斥的，只能使用一种，无法同时使用两种方式。

前提条件

• 在Phone或Tablet上查看设置 > 系统中开发者模式是否存在，如果不存在，可在设置 > 关于手机/关于平板中，连续七次单击“版本号”，直到提示“开启开发者模式”，点击确认开启后输入PIN码（如果已设置），设备将自动重启，请等待设备完成重启。
• 在设备运行应用/服务需要根据为应用/服务进行签名章节，提前对应用/服务进行签名。

使用USB连接方式

1. 使用USB方式，将Phone或Tablet与PC端进行连接。
2. 在设置 > 系统 > 开发者模式中，打开“USB调试”开关（确保设备已连接USB）。
3. 在Phone或Tablet中会弹出“允许USB调试”的弹框，单击允许。

   

4. 在菜单栏中，单击Run>Run'模块名称'或，或使用默认快捷键Shift+F10（macOS为Control+R）运行应用/服务。

   

5. DevEco Studio启动HAP的编译构建和安装。安装成功后，设备会自动运行安装的HarmonyOS应用/服务。

使用无线调试连接方式

1. 将Phone/Tablet和PC连接到同一WLAN网络。
2. 在开发者模式中，打开“无线调试”开关，并获取Phone/Tablet端的IP地址和端口号。

   

3. 在PC中执行如下命令连接设备。
   1. hdc tconn 设备IP地址:端口号

4. 在菜单栏中，单击Run>Run'模块名称'或，或使用默认快捷键Shift+F10（macOS为Control+R）运行应用/服务。

   

5. DevEco Studio启动HAP的编译构建和安装。安装成功后，Phone/Tablet会自动运行安装的HarmonyOS应用/服务。

常见问题

USB调试无法识别设备

DevEco Studio无法识别到已连接的设备，显示“No device”。

• 常见原因一

  设备未开启“开发者模式”。

  解决措施

  在设备上打开“开发者模式”开关，打开“USB调试”开关或“无线调试”开关。

• 常见原因二

  使用的USB连接线为充电线而非数据线，请更换为满足USB2.0标准的数据线；建议使用直连方式，不要使用拓展坞。

• 常见原因三

  当前的USB数据口可能损坏，请更换另一个USB数据口后重新尝试；检查端口驱动是否正常。

• 常见原因四

  hdc工具的进程或设备存在异常。

  解决措施
  1. 执行如下命令，结束hdc的进程，然后尝试重新连接。

     ./hdc kill

  2. 若按照步骤1操作后还是不能连接，请重启设备，然后尝试重新连接。
• 常见原因五

  场景一：关闭“USB调试”开关，并且断开USB连接，重新打开“USB调试”开关。无法识别到设备。

  场景二：打开“无线调试”开关后，进行无线调试连接，然后关闭“无线调试”开关后，又打开“USB调试”开关，进行USB调试。无法识别到设备。

  解决措施

  重启设备，连接USB，打开“USB调试”开关。
  
  
  使用环境

  模拟器在本地计算机上创建和运行，在运行和调试应用/服务时可以保持良好的流畅性和稳定性，但是需要耗费一定的计算机资源，具体的运行环境要求为：

  系统类型	运行环境要求
  Windows	Windows 10 企业版、专业版或教育版及以上，且操作系统版本不低于10.0.18363。 具有二级地址转换 (SLAT) 的 64 位处理器。 CPU支持AES指令集。 CPU 支持 VM 监视器模式扩展（Intel CPU 的 VT-c 技术）。 系统内存16GB及以上。 不支持在虚拟机系统中运行模拟器。 系统OpenGL版本4.1及以上。 屏幕分辨率1280*800像素以上。
  macOS(ARM)	macOS系统为12.5及以上版本。 系统内存8GB及以上。 不支持在虚拟机系统中运行模拟器。 系统OpenGL版本4.1及以上。 屏幕分辨率1280*800像素以上。