• 时间:
  • 分类:

做 ArkTS / ArkUI 时，把“运行-看效果”的成本降下来，最省事的方式之一就是用 DevEco 的预览器（Previewer）。它能让你在不装包、不跑真机的情况下，快速验证 UI 结构、布局、样式与适配问题。

组件预览的核心价值不是“看一眼 UI”，而是把预览变成一种工作流：每写一个组件，就配一组稳定可复用的预览场景，后续调样式、做适配、做重构，都能快速回归验证。

1）先搞清：页面预览 vs 组件预览（别混用）

很多同学一开始会把这两种预览混在一起用，导致预览行为“看起来不对”。

  • 页面预览：以“页面”为单位，通常在页面组件上加 @Entry，适合看整体页面结构与导航。
  • 组件预览：以“自定义组件”为最小单位，靠 @Preview 装饰器触发，更适合做组件库、模块化 UI、局部迭代调试。

你如果正在做组件化（卡片、列表项、通用按钮、弹窗、空状态等），优先用组件预览，效率更高。

2）环境准备清单（预览器能不能跑，先看这几项）

如果预览器打不开、白屏、显示异常，先按这几条排：

  1. 显卡/图形能力要满足预览器要求：有些机器 OpenGL 能力不够时，预览器会异常或非常卡。
  2. DevEco 的 Previewer 资源要下载完整：SDK、预览器组件没装齐，经常会出现“能编译但无法预览”。
  3. 部分组件或能力天然不适合预览：例如 Web、Video、XComponent 等更依赖运行态环境的组件，预览里容易出现空白或异常。

3）@Preview 最小可用写法：先跑通“无参组件”

建议你先用一个不依赖外部参数、状态可控的组件验证预览链路，确保预览器能正常工作：

@Preview
@Component
struct HelloPreview {
  @State message: string = 'default Preview';

  build() {
    Column() {
      Text(this.message).fontSize(40).fontWeight(FontWeight.Bold)
    }
    .width('100%')
    .height('100%')
  }
}

小提醒：别在一个文件里堆太多预览

一个源文件里预览太多，会让维护成本上升，也容易让预览器负担变大。建议一个文件控制在“够用就好”。

4）PreviewParams：把预览“调成你想要的设备/语言/方向”

当你开始做多端适配或国际化时，@Preview({...}) 的参数就特别有用。你可以把预览设备的关键属性固定下来，比如屏幕大小、语言、方向、圆屏等。

常用参数解释（按实际开发最常用的理解方式）：

  • title：预览名称，同文件多个预览时用来区分。
  • width / height：预览设备分辨率（px），快速模拟不同屏幕尺寸。
  • dpi：屏幕密度，用于验证字体/间距在不同密度下的表现。
  • locale：语言地区，如 zh_CN、en_US，用于验证国际化布局溢出。
  • colorMode：亮暗模式（注意不同设备类型可能有默认限制）。
  • deviceType：设备类型，如 Phone/Tablet/TV/Wearable，用于多端渲染差异验证。
  • orientation：横竖屏，portrait 或 landscape。
  • roundScreen：是否圆屏，用于手表类布局验证。

示例（传参预览）：

@Preview({
  title: 'PreviewParams',
  width: 540,
  height: 1170,
  locale: 'zh_CN',
  orientation: 'portrait'
})
@Component
struct Test {
  @State message: string = 'PreviewParams';

  build() {
    Column() {
      Text(this.message).fontSize(36).fontWeight(FontWeight.Bold)
    }
    .width('100%')
    .height('100%')
  }
}

5）实战建议：把预览做成“3 套固定组合”，效率会高很多

我更建议你别每次临时改参数，而是固定三套预览，当成组件的“标准工位”：

  1. Phone 竖屏 + 中文
    主战场：布局、字号、间距先在这里定。
  2. Phone 横屏 + 英文
    很容易暴露英文文案溢出、按钮变形、间距不够等问题。
  3. 圆屏或小尺寸设备
    专门抓边距、圆角、安全区、内容被裁切的问题。

当你把这三套组合固定下来，后面组件改版基本就是“一眼能看出问题”。

6）“预览不显示/白屏”排查口诀（社区里最常见）

遇到预览器不显示，按这个顺序排，命中率很高：

  1. 先确认是不是用了不适合预览的组件
    先临时注释 Web/Video/XComponent 等组件，验证是不是它们导致的空白。
  2. 组件是否依赖运行态数据
    例如必须等网络请求、路由参数、注入对象才能渲染。预览模式下经常会卡住或无内容。
    更稳的做法是：用“预览包装组件”把入参写死，让预览组件能独立渲染。
  3. 资源加载是否写得太“运行态”
    比如路径、资源引用方式不规范，导致预览场景拿不到资源。
  4. SDK / 预览器资源 / 项目配置是否一致
    预览器资源没下载好、SDK 版本不匹配，都会导致预览异常。

把 @Preview 当成“组件单测”，你会越写越快

组件预览最爽的一点是：它能把“改一点 → 看一下 → 再改一点”的循环速度拉到极致。

当你开始把预览当成固定资产（多端、语言、方向、圆屏都覆盖），你写组件会越来越像做“可回归的模块开发”：
改动可控、验证快速、适配心里有底。

标签: none

添加新评论