DEV Community: vi lu

【HarmonyOS 5】如何给未知类型对象定义类型并使用递归打印所有的Key

vi lu — Fri, 23 May 2025 07:01:16 +0000

关键词：嵌套对象、类型、递归、未知类型

使用 Record 与 ESObject 定义未知对象类型

递归打印未知类型对象的key

在鸿蒙应用开发中，所有的数据都必须定义类型，且不存在 any 类型，那么我们当遇到 key 值可能随时变化的情况时，如何获取该 object 中每一个 key 对应的数据呢？

本期以如下 object 为例，下方对象报文可能会根据使用时间或服务商的变化，"153" 字段可能会变成 "278" 等未知字符串、"5G" 字段可能会变成 "4G"，那么当 key 值不断变化的同时应如何获取 "isShow" 字段的 "Y" 值？

"cfg": {
  "153": {
    "5G": {
      "isShow": "Y"
    }
  }
}

使用 Record 与 ESObject 定义未知对象类型

在鸿蒙中，已经不支持索引签名的类型写法（如：[key: string]: string | number），所以需要使用提供的 Record 与 ESObject 类型，在复杂类型场景使用，所以我们可以直接嵌套定义如下类型即可。

type objType = Record<string, Record<string, Record<string, Record<string, string>>>>
let obj: objType = {
  "cfg": {
    "153": {
      "5G": {
        "isShow": "Y"
      }
    }
  }
}

注：其他明确 key 与 value 类型的场景不建议使用 Record 与 ESObject 类型，养成良好开发习惯，标注好对应数据类型。

递归打印未知类型对象的key

鸿蒙中不支持 for... in 形式的打印，所以对于该种复杂嵌套对象，我们可以自行编写简单的 for 循环，递归调用即可。

/**
 * 打印对象所有的 key
 * @param obj
 */
handleKey(obj: objType | string) {
  let keys = Object.keys(obj);
  for (let i = 0; i < keys.length; i++) {
    console.log("luvi > " + keys[i]);
    if (typeof obj[keys[i]] === "object") {
      this.handleKey(obj[keys[i]])
      continue
    }
    // 打印 isShow 最终值
    if (keys[i] === "isShow") {
      console.log("luvi > isShow最终值：" + obj[keys[i]]);
      break
    }
  }
}

// 调用
this.handleKey(obj)

输出结果：

该篇文章为开发时临时记录，开发经验如上，若对 TS 基础类型写法存在疑惑可查看 TS 官方文档，Record 与 ESObject 类型为鸿蒙的 ArkTS 类型，详细用法可前往 HarmonyOS 开发者官网了解。

【HarmonyOS 5】一次开发多端部署

vi lu — Thu, 22 May 2025 07:39:45 +0000

关键词：一多、响应式、媒体查询、栅格布局、断点、UI

随着设备形态的逐渐增多，应用界面适配也面临着很大问题，在以往的安卓应用开发过程中，往往需要重新开发一套适用于大屏展示的应用，耗时又耗力，而鸿蒙提供响应式开发的解决方案，提供系统级的接口供开发者调用，从而使得一款应用一套代码能同时运行在不同形态的设备上，也能给用户带来很好的交互体验。

本期文章以轮播图、Tab栏、列表为例，配合栅格布局与媒体查询，进行 UI 的一多开发。

1. 了解断点、媒体查询、栅格布局

断点

媒体查询

栅格布局

2. 封装媒体查询监听断点工具类

3. 配合媒体查询做 Swiper() 轮播图分割效果

4. 配合媒体查询做 Tab 栏 UI 展示位置变动

5. 配合栅格布局做列表展示数量控制

总结

效果预览

1. 了解断点、媒体查询、栅格布局

断点

鸿蒙提供断点以应用窗口宽度为切入点，将应用窗口在宽度维度上分成了几个不同的区间即不同的断点，不同设备会进入到不同的断点区间，在不同的区间下，我们可以可根据需要实现不同的页面布局效果。具体的断点对应的设备尺寸如下所示。

断点名称	取值范围（vp）
xs	[0, 320）
sm	[320, 600)
md	[600, 840)
lg	[840, +∞)

媒体查询

媒体查询支持监听窗口宽度、横竖屏、深浅色、设备类型等多种媒体特征，当媒体特征发生改变时同步调整页面布局。我们可以借助媒体查询能力，监听断点的变化。

栅格布局

栅格组件默认提供xs、sm、md、lg四个断点，除了默认的四个断点，还支持启用 xl 和 xxl 两个额外的断点，我们只需要在 GridRow() 组件的 breakpoints 属性中依次设置对应断点的尺寸，可自行对断点设备的尺寸进行设置从而满足自己尺寸的业务需求，当然还是更推荐使用默认的断点尺，如果使用到媒体查询，和自定义尺寸保持一致即可。

breakpoints 数组中最大可写 5 个尺寸，对应 6 个断点范围，且断点值后面必须加上vp单位。

reference 属性代表 GridRow 宽度变化随屏幕变化，还是随当前局部区域尺寸变化（因为在实际场景中，存在应用窗口尺寸不变但是局部区域尺寸发生了变化的情况，栅格组件支持以自身宽度为参照物响应断点变化具有更大的灵活性。）

栅格布局详细介绍请参考：文档中心

示例代码：

@Entry
@Component
struct GridRowSample1 {
  @State private currentBreakpoint: string = 'unknown'
  build() {
    // 修改断点的取值范围同时启用更多断点，注意，修改的断点值后面必须加上vp单位。
    GridRow({breakpoints: {value: ['600vp', '700vp', '800vp', '900vp', '1000vp'],
      reference: BreakpointsReference.WindowSize}}) {
      GridCol({span:{xs: 12, sm: 12, md: 12, lg:12, xl: 12, xxl:12}}) {
        Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
          Text(this.currentBreakpoint).fontSize(50).fontWeight(FontWeight.Medium)
        }
      }
    }.onBreakpointChange((currentBreakpoint: string) => {
      this.currentBreakpoint = currentBreakpoint
    })
  }
}

2. 封装媒体查询监听断点工具类

给我们的业务封装媒体查询监听断点工具类，以便后续使用，在首页生命周期过程中进行调用初始化，利用 LocalStorage 或 AppStorage 保存当前屏幕断点的名称，在应用的任意页面内通过 StorageProp 获取并动态观察屏幕设备形态状态的变化从而更新页面 UI 的展示效果，如折叠屏形态下窄屏变宽屏的使用场景，这时的断点会由 sm 变为 md。

如下代码，监听了 sm、md、lg 三种设备形态，当设备形态变化，会重新写入 storage 数据，配合状态变量即可动态更新 UI。

import mediaQuery from '@ohos.mediaquery';

@Observed
export class MediaWatching {
  private sm: string = '(width<600vp)'
  private md: string = "(600vp<=width<840vp)"
  private lg: string = "(840vp<=width)"
  private type: 'sm' | 'md' | 'lg' = 'sm'

  init() {
    console.log("luvi > mediaQueryResult change " + this.type)
    // 小尺寸屏
    const smListener = mediaQuery.matchMediaSync(this.sm)
    smListener.on('change', (mediaQueryResult) => {
      this.onPortrait(mediaQueryResult)
    })
    // 中等尺寸屏
    const mdListener = mediaQuery.matchMediaSync(this.md)
    mdListener.on('change', (mediaQueryResult) => {
      this.onPortrait(mediaQueryResult)
    })
    // 大尺寸屏
    const lgListener = mediaQuery.matchMediaSync(this.lg)
    lgListener.on('change', (mediaQueryResult) => {
      this.onPortrait(mediaQueryResult)
    })
  }

  onPortrait(mediaQueryResult: mediaQuery.MediaQueryResult) {
    console.log("luvi > mediaQueryResult " + JSON.stringify(mediaQueryResult))
    if (mediaQueryResult.matches) {
      switch (mediaQueryResult.media as string) {
        case this.sm:
          this.type = 'sm'
          break
        case this.md:
          this.type = 'md'
          break
        case this.lg:
          this.type = 'lg'
          break
        default:
          break
      }
      console.log("luvi > mediaQueryResult change " + this.type)
      AppStorage.setOrCreate("currentMediaType", this.type)
    }
  }
}

3. 配合媒体查询做 Swiper() 轮播图分割效果

在上一步的媒体查询封装及初始化后，屏幕设备形态变化后的名称会保存在 AppStorage 中，所以我们在自定义组件中可及时获取存入的 currentMediaType ，配合 Swiper 相关接口，使用 .displayCount() 设置 Swiper 视窗内元素显示个数达到分割效果。

@Component
export struct MySwiper {
  swiperList: number[] = [1, 2, 3, 4, 5]
  // 获取当前设备断点形态
  @StorageProp("currentMediaType") currentMediaType: 'sm' | 'md' | 'lg' = 'sm'

  build() {
    Column() {
      Swiper() {
        ForEach(this.swiperList, (item: number, idx: number) => {
          Row() {
            Text(`图片${item}`)
              .textAlign(TextAlign.Center)
              .width("100%")
          }
          .borderRadius(10)
          .width("100%")
          .height(250)
          .backgroundColor(idx % 2 == 0 ? "#ddd" : "#ffb0b0b0")
        })
      }
      .itemSpace(10)
      // 根据断点设置分割个数
      // sm 小屏形态只展示 1 个，其他形态展示 2 个
      .displayCount(this.currentMediaType == "sm" ? 1 : 2)
      .autoPlay(true)
      .borderRadius(10)
      .clip(true)
    }
  }
}

4. 配合媒体查询做 Tab 栏 UI 展示位置变动

Tab 栏位置的变化与轮播图分栏同理，配合 storage 状态变量获取设备形态，对不同设备形态更改 Tab 栏标签的排列方向即可。

详细 Tab 代码可参考 gitee 源代码

// 获取当前设备断点形态
@StorageProp("currentMediaType") currentMediaType: 'sm' | 'md' | 'lg' = 'sm'

Tabs({ barPosition: BarPosition.End }) {
    TabContent() {
      // 标签页
      ...
    }

    TabContent() {
      // 标签页
      ...
    }

    TabContent() {
      // 标签页
      ...
    }
  }
  // 对不同设备形态设置不同排列方向
  .vertical(this.currentMediaType == 'sm' || this.currentMediaType == 'md' ? false : true)

5. 配合栅格布局做列表展示数量控制

栅格布局拥有独立的断点能力，不依赖与媒体查询接口，所以直接使用栅格布局的特性进行开发即可。

栅格布局主要由行和列组成，每一行可以分为若干列，在不同断点状态下展示不同数量的列数，根据这一特性，即可制作成在小屏幕上展示一列文本，在大屏幕上展示两列甚至多列文本。

所以我们可以直接对 GridRow 设置对应断点时展示的 GridCol 个数即可，无需对 GridCol 设置额外参数

GridRow({
   columns: {
     xs: 1, // 超小屏幕 1 列（如手表）
     sm: 1, // 小屏幕 1 列
     md: 2, // 中等屏幕 2 列
     lg: 3  // 大屏幕 3 列
   },
   gutter: 15 // gutter 表示各元素直接间隙尺寸
 }) {
   ForEach(this.dataList, (item: number, idx: number) => {
     GridCol() {
       Row() {
         Text(`列表${item}`)
           .textAlign(TextAlign.Center)
           .width("100%")
       }
       .borderRadius(10)
       .width("100%")
       .height(130)
       .backgroundColor("#eee")
     }
   })
 }

总结

栅格布局拥有独立的断点能力，不依赖与媒体查询接口，所以直接使用栅格布局的特性进行开发即可。

轮播图的分割效果与 Tab 栏的排列方式变化，同样可使用栅格布局进行实现，不用依赖媒体查询接口，因为栅格布局的 GridRow 组件有 onBreakpointChange 断点变化回调，可直接返回当组件宽度所在的断点区间。

GridRow(){
   ...
}
.onBreakpointChange((bp: string) => {
  // 此处回调打印 xs / sm / md ...
})

【HarmonyOS 5】关键资产存储开发案例

vi lu — Thu, 22 May 2025 07:09:38 +0000

在 iOS 开发中 Keychain 是一个非常安全的存储系统，用于保存敏感信息，如密码、证书、密钥等。与文件系统不同，Keychain 提供了更高的安全性，因为它对数据进行了加密，并且只有经过授权的应用程序才能访问存储的数据。那么在鸿蒙里面对应的是什么呢？

1、关键资产(@ohos.security.asset)

在鸿蒙里面也有类似的东西，叫做关键资产(@ohos.security.asset)，关键资产存储服务提供了用户短敏感数据的安全存储及管理能力。其中，短敏感数据可以是密码类（账号/密码）、Token类（应用凭据）、其他关键明文（如银行卡号）等长度较短的用户敏感数据。

关键资产的安全存储，依赖底层的通用密钥库系统。具体来说，关键资产的加/解密操作以及访问控制校验，都由通用密钥库系统在安全环境（如可信执行环境）中完成，即使系统被攻破，也能保证用户敏感数据不发生泄露。其中，关键资产的加/解密使用AES256-GCM算法。

2、关键资产使用与 asset 的常用操作

关键资产的访问可分为 4 类（可查看本文第4章节），基于属主的访问控制、基于锁屏状态的访问控制、基于锁屏密码设置状态的访问控制、基于用户认证的访问控制，业务可根据实际情况决定是否开启（如扫脸验证、解锁验证、密码验证等），本次文章举例的开发案例均采用默认保护等级。

2.1 使用关键资产需要导入模块 `AssetStoreKit：`

import { asset } from '@kit.AssetStoreKit';

2.2 常用操作：

方法	描述
asset.add	新增一条关键资产。
asset.remove	删除符合条件的一条或多条关键资产。
asset.update	更新符合条件的一条关键资产。
asset.query	查询一条或多条符合条件的关键资产。若查询需要用户认证的关键资产，则需要在本函数前调用asset.preQuery，在本函数后调用asset.postQuery。
asset.preQuery	查询的预处理，用于需要用户认证的关键资产。在用户认证成功后，应当随后调用asset.query、asset.postQuery。
asset.postQuery	查询的后置处理，用于需要用户认证的关键资产。需与asset.preQuery函数成对出现。

3、常规方法封装

3.1 addSync 设置数据

/**
   * 新增一条关键资产
   * @param key
   * @param value
   * @returns
   */
  add(key: string, value: string) {
    let result: Boolean
    let attr: asset.AssetMap = new Map();
    // 关键资产别名，每条关键资产的唯一索引。
    // 类型为Uint8Array，长度为1-256字节。
    attr.set(asset.Tag.SECRET, this.string2Array(value));
    // 关键资产明文。
    // 类型为Uint8Array，长度为1-1024字节
    attr.set(asset.Tag.ALIAS, this.string2Array(key))
    // 关键资产同步类型>THIS_DEVICE只在本设备进行同步，如仅在本设备还原的备份场景。
    attr.set(asset.Tag.SYNC_TYPE, asset.SyncType.THIS_DEVICE);

    //枚举，新增关键资产时的冲突（如：别名相同）处理策略。OVERWRITE》抛出异常，由业务进行后续处理。
    // attr.set(asset.Tag.CONFLICT_RESOLUTION,asset.ConflictResolution.THROW_ERROR)
    // 在应用卸载时是否需要保留关键资产。
    // 需要权限： ohos.permission.STORE_PERSISTENT_DATA。
    // 类型为bool。
    // attr.set(asset.Tag.IS_PERSISTENT, true);//我项目里面没有使用就先注释了，后续有需要这个再打开，并且要设置对应权限

    if (this.isHasKey(key)) {
      result = this.updateAssetMap(attr);
    } else {
      try {
        if (canIUse("SystemCapability.Security.Asset")) {
          asset.addSync(attr);
          result = true
        }
        result = false
      } catch (error) {
        let err = error as BusinessError;
        LogUtil.e(`Failed to add Asset. Code is ${err.code}, message is ${err.message}`);
        result = false
      }
    }
    return result
  }

3.2 querySync 获取数据

/**
   * 查询
   * @param key
   * @returns
   */
  query(key: string) {
    let query: asset.AssetMap = new Map();
    // 关键资产别名，每条关键资产的唯一索引。
    // 类型为Uint8Array，长度为1-256字节。
    query.set(asset.Tag.ALIAS, this.string2Array(key));
    //  关键资产查询返回的结果类型。
    query.set(asset.Tag.RETURN_TYPE, asset.ReturnType.ALL);
    // query.set(asset.Tag.RETURN_TYPE, asset.ReturnType.ATTRIBUTES); // 此处表示仅返回关键资产属性，不包含关键资产明文

    try {
      if (canIUse("SystemCapability.Security.Asset")) {
        let res: Array<asset.AssetMap> = asset.querySync(query);
        for (let i = 0; i < res.length; i++) {
          // parse the attribute.
          if (res[i] != null) {
            // parse the secret.
            let secret: Uint8Array = res[0].get(asset.Tag.SECRET) as Uint8Array;
            // parse uint8array to string
            let secretStr: string = this.array2String(secret);
            return secretStr;
          }
        }
      }
    } catch (error) {
      let err = error as BusinessError;
      LogUtil.e(TAG, `Failed to query Asset. Code is ${err.code}, message is ${err.message}`);
      return "";
    }
    return ""
  }

3.3 querySync 查询 key 数据是否存在

/**
   * 查询资产key是否存在
   * @param key
   * @returns
   */
  isHasKey(key: string): Boolean {
    if (canIUse("SystemCapability.Security.Asset")) {
      let query: asset.AssetMap = new Map();
      // 关键资产别名，每条关键资产的唯一索引。
      // 类型为Uint8Array，长度为1-256字节。
      query.set(asset.Tag.ALIAS, this.string2Array(key));
      //  关键资产查询返回的结果类型。
      query.set(asset.Tag.RETURN_TYPE, asset.ReturnType.ALL);
      const res = this.queryAssetMap(query);
      if (!res || res.length < 1) {
        return false;
      }
      return true;
    }
    return false;
  }

/**
   * 查询资产 key 的 assetMaps 数据
   * @param query
   * @returns
   */
  queryAssetMap(query: asset.AssetMap): Array<asset.AssetMap> {
    const assetMaps: asset.AssetMap[] = [];
    try {
      if (canIUse("SystemCapability.Security.Asset")) {
        const res: asset.AssetMap[] = asset.querySync(query);
        return res;
      }
      return assetMaps;
    } catch (error) {
      const err = error as BusinessError;
      LogUtil.e(TAG, `Failed to query Asset. Code is ${err.code}, message is ${err.message}`);
      return assetMaps;
    }
  }

3.4 updateSync 修改资产数据

/**
   * 修改资产数据
   * @param q
   * @returns
   */
  updateAssetMap(q: asset.AssetMap): Boolean {
    try {
      if (canIUse("SystemCapability.Security.Asset")) {
        let query: asset.AssetMap = new Map();
        query.set(asset.Tag.ALIAS, q.get(asset.Tag.ALIAS)!);
        let attrsToUpdate: asset.AssetMap = new Map();
        attrsToUpdate.set(asset.Tag.SECRET, q.get(asset.Tag.SECRET)!);
        asset.updateSync(query, attrsToUpdate);
        return true
      }
      return false
    } catch (error) {
      const err = error as BusinessError;
      LogUtil.e(TAG, `Failed to update Asset. Code is ${err.code}, message is ${err.message}`);
      return false;
    }
  }

3.5 removeSync 删除资产数据

/**
   * 删除一条关键资产
   * @param key
   */
  remove(key: string) {
    let query: asset.AssetMap = new Map();
    // 关键资产别名，每条关键资产的唯一索引。
    query.set(asset.Tag.ALIAS, this.string2Array(key));
    try {
      if (canIUse("SystemCapability.Security.Asset")) {
        asset.removeSync(query);
        return true;
      }
      return false;
    } catch (error) {
      let err = error as BusinessError;
      LogUtil.e(TAG, `Failed to remove Asset. Code is ${err.code}, message is ${err.message}`);
      return false;
    }
  }

3.6 string 与 Uint8Array 数据互转换

  string2Array(str: string): Uint8Array {
    let textEncoder = new util.TextEncoder();
    return textEncoder.encodeInto(str);
  }

  array2String(str: Uint8Array): string {
    let textDecoder = new util.TextDecoder();
    return textDecoder.decodeToString(str);
  }

4、关键资产的访问控制

基于属主的访问控制： 所有的关键资产都受属主访问控制保护，业务无需设置。
- 只允许关键资产被其属主（写入该关键资产的业务）访问。
- 关键资产属主身份由ASSET从系统服务中获取，即使业务身份被仿冒，仿冒者也无法获取到其他业务的数据。
- 关键资产加/解密时，其属主身份参与了完整性保护，即使关键资产属主身份被篡改，攻击者也无法获取到其他业务的数据。
基于锁屏状态的访问控制： 分为以下三种保护等级（安全性依次递增），业务可根据实际情况设置任意一种，若不设置，则默认保护等级为“首次解锁后可访问”。
- 开机后可访问：关键资产在开机后被允许访问。
- 首次解锁后可访问：关键资产在首次解锁后被允许访问。
- 解锁时可访问：关键资产仅在处于解锁状态时被允许访问。
基于锁屏密码设置状态的访问控制： 该访问控制默认不开启，业务可根据实际情况决定是否开启。
- 在用户设置了锁屏密码后，关键资产才被允许访问。
基于用户认证的访问控制： 该访问控制默认不开启，业务可根据实际情况决定是否开启。
- 关键资产在用户身份认证通过后被允许访问。
- 任意一种认证方式（指纹、人脸、PIN码）通过，均可授权本次关键资产的访问。
- 业务可通过设置认证有效期，达成一次用户认证、授权多个关键资产访问的效果。认证有效期最长可设置10分钟。

5、参考

华为官网：@ohos.security.asset (关键资产存储服务)

【HarmonyOS 5】多目标产物构建实践

vi lu — Thu, 22 May 2025 07:05:38 +0000

什么是多产物构建

在鸿蒙应用开发中，一个应用可定义多个 product，每一个 product 对应一个定制的 APP 包，每个 product 中支持对 bundleName、bundleType、输出产物名称、icon 和 label 以及包含的 target 资源文件等内容进行定制。与此同时，也可以将环境配置和签名信息通过 product 进行隔离，通过选项切换环境进行构建，避免频繁的手动修改关键参数而造成打包遗漏的情况。

如何定义多个构建产物

在项目最外层的 build-profile.json5 文件中的 products 字段中新增 product，字段解释可参考文章：工程级build-profile.json5文件。

这里我们针对环境控制做演示，需要用到 buildOption / arkOptions / buildProfileFields 字段，该字段中的参数设置后，切换产物后会重新生成一份 BuildProfile.ets 文件，该文件可被项目导入并使用。

需要注意的是：在定制 product 时，必须存在 "default" 的 product，否则编译时会出现错误。

示例 JSON：

{ 
  "app": { 
    "signingConfigs": [
      {
        "name": "default",    // debug类型签名配置
        "type": "HarmonyOS",
        "material": {
          "storePassword": "xxxxxxxxxx",
          "certpath": "C:/Users/pc/xxxxxxxxxx.cer",
          "keyAlias": "xxxxxxxxxx",
          "keyPassword": "xxxxxxxxxx",
          "profile": "C:/Users/pc/xxxxxxxxxx.p7b",
          "signAlg": "SHA256withECDSA",
          "storeFile": "C:/Users/pc/xxxxxxxxxx.p12"
        }
      },
      {
        "name": "release",    // release类型签名配置
        "type": "HarmonyOS",
        "material": {
          "storePassword": "xxxxxxxxxx",
          "certpath": "C:/Users/pc/xxxxxxxxxx.cer",
          "keyAlias": "xxxxxxxxxx",
          "keyPassword": "xxxxxxxxxx",
          "profile": "C:/Users/pc/xxxxxxxxxx.p7b",
          "signAlg": "SHA256withECDSA",
          "storeFile": "C:/Users/pc/xxxxxxxxxx.p12"
        }
      }
    ], 
    "products": [ 
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.1(13)",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          },
          "arkOptions": {
            "buildProfileFields": {
              // 接口base
              "baseApiUrl": "https://default.test.cn"
            }
          }
        }
      }, 
      // dev开发产物（测试环境）
      { 
        "name": "start_develop", // 产物名称
        "compatibleSdkVersion": "5.0.2(14)", 
        "runtimeOS": "HarmonyOS", 
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.1(13)",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          },
          "arkOptions": {
            "buildProfileFields": { // 构建配置自定义参数
              // 接口base
              "baseApiUrl": "https://debug.develop.cn"
            }
          }
        }
      }, 
      // release开发产物（生产环境）
      { 
        "name": "start_release", // 产物名称 
        "compatibleSdkVersion": "5.0.2(14)", 
        "runtimeOS": "HarmonyOS", 
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.1(13)",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          },
          "arkOptions": {
            "buildProfileFields": { // 构建配置自定义参数
              // 接口base
              "baseApiUrl": "https://release.produce.cn"
            }
          }
        }
      }, 
      // release打包产物（生产环境构建release版本）
      { 
        "name": "start_release_build", // 产物名称 
        "compatibleSdkVersion": "5.0.2(14)", 
        "runtimeOS": "HarmonyOS", 
        "signingConfig": "release",
        "compatibleSdkVersion": "5.0.1(13)",
        "runtimeOS": "HarmonyOS",
        "output": { 
          "artifactName": "customizedProductOutputNameB" // 自定义打包后的app产物名称
        }, 
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          },
          "arkOptions": {
            "buildProfileFields": { // 构建配置自定义参数
              // 接口base
              "baseApiUrl": "https://release.produce.cn"
            }
          }
        }
      } 
    ], 
    "buildModeSet": [ 
      { 
        "name": "debug", 
      }, 
      { 
        "name": "release" 
      } 
    ] 
  }, 
}

上方 JSON 中配置了 3 个产物与 2 个签名，3 个产物分别为 develop 开发环境产物， release 生产环境产物，release 生产环境构建产物。其中生产构建产物绑定了 "release" 签名，这样做的好处是，当我们切换环境选项时，签名相关配置也将一同被改变，无需手动更换签名。

如何在项目中使用产物

在第一步配置完 product 后，还需在 modules 中的 applyToProducts 字段添加刚才配置的 product 产物，项目中创建的其他 hsp 也需一同配置，不然编译报错。

配置完 products 与 modules 后，重新运行项目后，每个模块下均会生成新的 BuildProfile.ets 文件，在项目中使用相对路径导入即可。

// 导入
import BuildProfile from '../../../../BuildProfile'

// 使用
let BASE_URL: string = BuildProfile.baseApiUrl

参考文章

配置APP多目标构建产物

【HarmonyOS 5】App Linking 应用间跳转详解

vi lu — Thu, 22 May 2025 07:03:54 +0000

什么是 App Linking

App Linking 是一款创建跨平台的深度聚合链接。通过为用户提供无缝的内容浏览体验，提升用户转化率。

若用户已安装应用，点击点击链接后将直达应用内指定页面。
若未安装，且已配置跳转应用市场，则跳转应用市场进行下载，待安装完成后用户首次打开应用，仍将跳转至该页面（可查看文章结尾如何配置）。如果未配置跳转应用市场，则自动打开浏览器加载对应的网页内容。

链接分享

扫码直达
使用场景
扫码直达、短信链接直达、社交平台卡片分享等场景。

工作原理

如何开发

开发前注意事项：使用 App Linking 需使用手动生成签名，自动签名将无法启动应用。

1.开通 App Linking

登录AppGallery Connect，点击“我的项目”。
在项目列表中打开对应项目。
在左侧导航栏中选择“增长 > App Linking”，进入App Linking页面，点击“立即开通”。

2.确定域名

在配置前需确定域名，并确保域名完成https配置且能正常访问，后续在 AGC 与项目中需进行相关配置。

3.服务端部署 applinking.json 文件

在服务端部署 applinking.json 文件至指定目录，这里我们手动创建即可，确保能通过我们配置的域名地址：https://域名/.well-known/applinking.json 访问到 applinking 配置，如何获取应用ID可查看文章末尾。

{
    "applinking": {
        "apps": [
            {
                "appIdentifier": "你的应用id"
            }
        ]
    }
}

4.AGC绑定域名

在第 1 步开通 App Linking 后，选择“应用链接-创建”，填入域名地址进行发布，发布后，若第 3 步的配置文件可正常访问，等待几分钟后看到“成功”状态，则代表域名配置成功。若出现其他错误状态，需检查配置文件是否可被访问。

5.项目配置

进入项目的 entry 模块下的 module.json5 文件，新增 App Linking 的 skills 配置。

示例代码：

{
  "entities": [
    // entities必须包含"entity.system.browsable"
    "entity.system.browsable"
  ],
  "actions": [
    // actions必须包含"ohos.want.action.viewData"
    "ohos.want.action.viewData"
  ],
  "uris": [
    {
      // scheme须配置为https
      "scheme": "https",
      // host须配置为关联的域名，替换为你AGC配置的域名
      "host": "www.eeeo.cc",
      // path可选，表示域名服务器上的目录或文件路径，例如www.example.com/path1中的path1
      // 如果应用只能处理部分特定的path，则此处应该配置应用所支持的path，避免出现应用不能处理的path链接也被引流到应用中的问题，替换为你的二级path，用于精确分流
      "path": "share"
    }
  ],
  // domainVerify须设置为true
  "domainVerify": true
}

6.组装聚合链接

上述配置中，path用于精确分流，可用于指定二级地址，当前项目中配置的path为share，即当我们在鸿蒙设备中点击链接 https://www.eeeo.cc/share 后会优先启动应用，当我们需要传递参数时，可使用 ? + & 的形式拼接 KeyValue 即可。

https://www.eeeo.cc/share?pageId=2025&channel=web

7.解析聚合链接中的参数

通过聚合链接启动应用后，参数会进入到 Ability 的 onCreate 生命周期的 Want.uri 中，若应用已经启动，则会进入到 onNewWant 生命周期的 Want.uri 中。此时我们解析 uri 中的 KeyValue 即可。

示例代码如下：

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { url } from '@kit.ArkTS';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 从want中获取传入的链接信息。
    // 如传入的url为：https://www.example.com/programs?action=showall
    let uri = want?.uri 
    if (uri) {
      // 从链接中解析query参数，拿到参数后，可根据自己的业务需求进行后续的处理。
      let urlObject = url.URL.parseURL(want?.uri);
      let pageId = urlObject.params.get('pageId')
      let channel= urlObject.params.get('channel')      
    }
  }
}

其他

如何获取应用ID

登录AppGallery Connect，点击“我的项目”，若已创建项目，可直接在首页查看到应用ID。若未创建项目，手动创建后则会自动生成。

如何在应用未安装时点击链接跳转至应用市场

项目的 module.json5 配置完 AppLinking 的 skills 后，等待应用上架，上架后前往 AGC 配置AppLinking 域名的地方，点击“直达应用市场”的选项，开启直达应用市场即可。

【HarmonyOS 5】一次开发多端部署

vi lu — Thu, 22 May 2025 06:56:06 +0000

关键词：一多、响应式、媒体查询、栅格布局、断点、UI

本期文章以轮播图、Tab栏、列表为例，配合栅格布局与媒体查询，进行 UI 的一多开发。

本期完整代码已提交至gitee：one2More

1. 了解断点、媒体查询、栅格布局

断点

断点名称	取值范围（vp）
xs	[0, 320）
sm	[320, 600)
md	[600, 840)
lg	[840, +∞)

媒体查询

栅格布局

breakpoints 数组中最大可写 5 个尺寸，对应 6 个断点范围，且断点值后面必须加上vp单位。

reference 属性代表 GridRow 宽度变化随屏幕变化，还是随当前局部区域尺寸变化（因为在实际场景中，存在应用窗口尺寸不变但是局部区域尺寸发生了变化的情况，栅格组件支持以自身宽度为参照物响应断点变化具有更大的灵活性。）

栅格布局详细介绍请参考：文档中心

示例代码：

@Entry
@Component
struct GridRowSample1 {
  @State private currentBreakpoint: string = 'unknown'
  build() {
    // 修改断点的取值范围同时启用更多断点，注意，修改的断点值后面必须加上vp单位。
    GridRow({breakpoints: {value: ['600vp', '700vp', '800vp', '900vp', '1000vp'],
      reference: BreakpointsReference.WindowSize}}) {
      GridCol({span:{xs: 12, sm: 12, md: 12, lg:12, xl: 12, xxl:12}}) {
        Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
          Text(this.currentBreakpoint).fontSize(50).fontWeight(FontWeight.Medium)
        }
      }
    }.onBreakpointChange((currentBreakpoint: string) => {
      this.currentBreakpoint = currentBreakpoint
    })
  }
}

2. 封装媒体查询监听断点工具类

如下代码，监听了 sm、md、lg 三种设备形态，当设备形态变化，会重新写入 storage 数据，配合状态变量即可动态更新 UI。

import mediaQuery from '@ohos.mediaquery';

@Observed
export class MediaWatching {
  private sm: string = '(width<600vp)'
  private md: string = "(600vp<=width<840vp)"
  private lg: string = "(840vp<=width)"
  private type: 'sm' | 'md' | 'lg' = 'sm'

  init() {
    console.log("luvi > mediaQueryResult change " + this.type)
    // 小尺寸屏
    const smListener = mediaQuery.matchMediaSync(this.sm)
    smListener.on('change', (mediaQueryResult) => {
      this.onPortrait(mediaQueryResult)
    })
    // 中等尺寸屏
    const mdListener = mediaQuery.matchMediaSync(this.md)
    mdListener.on('change', (mediaQueryResult) => {
      this.onPortrait(mediaQueryResult)
    })
    // 大尺寸屏
    const lgListener = mediaQuery.matchMediaSync(this.lg)
    lgListener.on('change', (mediaQueryResult) => {
      this.onPortrait(mediaQueryResult)
    })
  }

  onPortrait(mediaQueryResult: mediaQuery.MediaQueryResult) {
    console.log("luvi > mediaQueryResult " + JSON.stringify(mediaQueryResult))
    if (mediaQueryResult.matches) {
      switch (mediaQueryResult.media as string) {
        case this.sm:
          this.type = 'sm'
          break
        case this.md:
          this.type = 'md'
          break
        case this.lg:
          this.type = 'lg'
          break
        default:
          break
      }
      console.log("luvi > mediaQueryResult change " + this.type)
      AppStorage.setOrCreate("currentMediaType", this.type)
    }
  }
}

3. 配合媒体查询做 Swiper() 轮播图分割效果

@Component
export struct MySwiper {
  swiperList: number[] = [1, 2, 3, 4, 5]
  // 获取当前设备断点形态
  @StorageProp("currentMediaType") currentMediaType: 'sm' | 'md' | 'lg' = 'sm'

  build() {
    Column() {
      Swiper() {
        ForEach(this.swiperList, (item: number, idx: number) => {
          Row() {
            Text(`图片${item}`)
              .textAlign(TextAlign.Center)
              .width("100%")
          }
          .borderRadius(10)
          .width("100%")
          .height(250)
          .backgroundColor(idx % 2 == 0 ? "#ddd" : "#ffb0b0b0")
        })
      }
      .itemSpace(10)
      // 根据断点设置分割个数
      // sm 小屏形态只展示 1 个，其他形态展示 2 个
      .displayCount(this.currentMediaType == "sm" ? 1 : 2)
      .autoPlay(true)
      .borderRadius(10)
      .clip(true)
    }
  }
}

4. 配合媒体查询做 Tab 栏 UI 展示位置变动

Tab 栏位置的变化与轮播图分栏同理，配合 storage 状态变量获取设备形态，对不同设备形态更改 Tab 栏标签的排列方向即可。

详细 Tab 代码可参考 gitee 源代码

// 获取当前设备断点形态
@StorageProp("currentMediaType") currentMediaType: 'sm' | 'md' | 'lg' = 'sm'

Tabs({ barPosition: BarPosition.End }) {
    TabContent() {
      // 标签页
      ...
    }

    TabContent() {
      // 标签页
      ...
    }

    TabContent() {
      // 标签页
      ...
    }
  }
  // 对不同设备形态设置不同排列方向
  .vertical(this.currentMediaType == 'sm' || this.currentMediaType == 'md' ? false : true)

5. 配合栅格布局做列表展示数量控制

栅格布局拥有独立的断点能力，不依赖与媒体查询接口，所以直接使用栅格布局的特性进行开发即可。

所以我们可以直接对 GridRow 设置对应断点时展示的 GridCol 个数即可，无需对 GridCol 设置额外参数

GridRow({
   columns: {
     xs: 1, // 超小屏幕 1 列（如手表）
     sm: 1, // 小屏幕 1 列
     md: 2, // 中等屏幕 2 列
     lg: 3  // 大屏幕 3 列
   },
   gutter: 15 // gutter 表示各元素直接间隙尺寸
 }) {
   ForEach(this.dataList, (item: number, idx: number) => {
     GridCol() {
       Row() {
         Text(`列表${item}`)
           .textAlign(TextAlign.Center)
           .width("100%")
       }
       .borderRadius(10)
       .width("100%")
       .height(130)
       .backgroundColor("#eee")
     }
   })
 }

总结

栅格布局拥有独立的断点能力，不依赖与媒体查询接口，所以直接使用栅格布局的特性进行开发即可。

GridRow(){
   ...
}
.onBreakpointChange((bp: string) => {
  // 此处回调打印 xs / sm / md ...
})

【HarmonyOS 5】hdc环境变量配置

vi lu — Thu, 22 May 2025 06:54:56 +0000

hdc（HarmonyOS Device Connector）是 HarmonyOS 为开发人员提供的用于调试的命令行工具，通过该工具可以在 windows/linux/mac 系统上与真实设备或者模拟器进行交互。

hdc命令列表与全局参数

全局参数是指运行部分hdc命令时，可以跟随在hdc后面的参数，例如：选择指定的设备执行命令，使用-t参数：

hdc -t connect-key shell echo "Hello world"
shell

参数	说明
-t	连接指定的目标设备，连接一台设备时为可选参数，连接多台设备时为必选参数。
-l	可选参数，指定运行时日志等级，范围为数字0-6，默认为3（LOG_INFO）。
-s	可选参数，指定客户端连接服务端时，服务进程的网络监听参数，格式为ip:port。
-p	可选参数，绕过对服务进程的查询步骤，用于快速执行客户端命令。
-m	可选参数，使用前台启动模式启动服务进程。

命令列表

命令	说明
list targets	查询已连接的所有目标设备。
wait	等待设备正常连接。
tmode usb	该命令已经废弃，不会实际操作设备连接通道，需要在设备设置界面通过USB调试开关进行设置。
tmode port	打开设备网络连接通道。
tmode port close	关闭设备网络连接通道。
tconn	指定连接设备：通过“IP地址：端口号”来指定连接的设备。
shell	在设备侧执行单次命令。
install	安装指定的应用文件。
uninstall	卸载指定的应用包。
file send	从本地发送文件至远端设备。
file recv	从远端设备发送文件至本地。
fport ls	列出全部转发端口转发任务。
fport	设置正向端口转发任务：监听“主机端口”，接收请求并进行转发，转发到“设备端口”。
rport	设置反向端口转发任务：监听“设备端口”，接收请求并进行转发，转发到“主机端口”。
fport rm	删除指定的端口转发任务。
start	启动hdc服务进程。
kill	终止hdc服务进程。
hilog	打印设备端的日志信息。
jpid	显示设备上所有开启了JDWP调试协议的应用的PID。
track-jpid	实时显示设备上开启了JDWP调试协议的应用的PID和应用名。
target boot	重启目标设备。
target mount	以读写模式挂载系统分区（非root的设备不可用）。
smode	授予设备端hdc后台服务进程root权限，使用-r参数取消授权（非root的设备不可用）。
keygen	生成一个新的秘钥对。
version	打印hdc版本信息，也可使用hdc -v打印版本信息。
checkserver	获取客户进程与服务进程版本信息。

开始

找到dev eco安装地址中的toolchains目录复制即可
配置环境变量，直接在菜单搜索“环境”二字即可，打开“编辑账户的环境变量”，双击“系统变量”中的Path，点击新建，粘入刚才复制的hdc目录地址，点击确认。
重新打开cmd窗口，输入 hdc -v 出现内容即代表hdc环境变量配置成功。

【HarmonyOS 5】华为分享-碰一碰开发分享

vi lu — Thu, 22 May 2025 06:49:50 +0000

什么是多产物构建

如何定义多个构建产物

在项目最外层的 build-profile.json5 文件中的 products 字段中新增 product，字段解释可参考文章：工程级build-profile.json5文件。

需要注意的是：在定制 product 时，必须存在 "default" 的 product，否则编译时会出现错误。

示例 JSON：

{ 
  "app": { 
    "signingConfigs": [
      {
        "name": "default",    // debug类型签名配置
        "type": "HarmonyOS",
        "material": {
          "storePassword": "xxxxxxxxxx",
          "certpath": "C:/Users/pc/xxxxxxxxxx.cer",
          "keyAlias": "xxxxxxxxxx",
          "keyPassword": "xxxxxxxxxx",
          "profile": "C:/Users/pc/xxxxxxxxxx.p7b",
          "signAlg": "SHA256withECDSA",
          "storeFile": "C:/Users/pc/xxxxxxxxxx.p12"
        }
      },
      {
        "name": "release",    // release类型签名配置
        "type": "HarmonyOS",
        "material": {
          "storePassword": "xxxxxxxxxx",
          "certpath": "C:/Users/pc/xxxxxxxxxx.cer",
          "keyAlias": "xxxxxxxxxx",
          "keyPassword": "xxxxxxxxxx",
          "profile": "C:/Users/pc/xxxxxxxxxx.p7b",
          "signAlg": "SHA256withECDSA",
          "storeFile": "C:/Users/pc/xxxxxxxxxx.p12"
        }
      }
    ], 
    "products": [ 
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.1(13)",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          },
          "arkOptions": {
            "buildProfileFields": {
              // 接口base
              "baseApiUrl": "https://default.test.cn"
            }
          }
        }
      }, 
      // dev开发产物（测试环境）
      { 
        "name": "start_develop", // 产物名称
        "compatibleSdkVersion": "5.0.2(14)", 
        "runtimeOS": "HarmonyOS", 
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.1(13)",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          },
          "arkOptions": {
            "buildProfileFields": { // 构建配置自定义参数
              // 接口base
              "baseApiUrl": "https://debug.develop.cn"
            }
          }
        }
      }, 
      // release开发产物（生产环境）
      { 
        "name": "start_release", // 产物名称 
        "compatibleSdkVersion": "5.0.2(14)", 
        "runtimeOS": "HarmonyOS", 
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.1(13)",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          },
          "arkOptions": {
            "buildProfileFields": { // 构建配置自定义参数
              // 接口base
              "baseApiUrl": "https://release.produce.cn"
            }
          }
        }
      }, 
      // release打包产物（生产环境构建release版本）
      { 
        "name": "start_release_build", // 产物名称 
        "compatibleSdkVersion": "5.0.2(14)", 
        "runtimeOS": "HarmonyOS", 
        "signingConfig": "release",
        "compatibleSdkVersion": "5.0.1(13)",
        "runtimeOS": "HarmonyOS",
        "output": { 
          "artifactName": "customizedProductOutputNameB" // 自定义打包后的app产物名称
        }, 
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          },
          "arkOptions": {
            "buildProfileFields": { // 构建配置自定义参数
              // 接口base
              "baseApiUrl": "https://release.produce.cn"
            }
          }
        }
      } 
    ], 
    "buildModeSet": [ 
      { 
        "name": "debug", 
      }, 
      { 
        "name": "release" 
      } 
    ] 
  }, 
}

如何在项目中使用产物

在第一步配置完 product 后，还需在 modules 中的 applyToProducts 字段添加刚才配置的 product 产物，项目中创建的其他 hsp 也需一同配置，不然编译报错。

配置完 products 与 modules 后，重新运行项目后，每个模块下均会生成新的 BuildProfile.ets 文件，在项目中使用相对路径导入即可。

// 导入
import BuildProfile from '../../../../BuildProfile'

// 使用
let BASE_URL: string = BuildProfile.baseApiUrl

参考文章

配置APP多目标构建产物

DEV Community: vi lu

【HarmonyOS 5】如何给未知类型对象定义类型并使用递归打印所有的Key

使用 Record 与 ESObject 定义未知对象类型

递归打印未知类型对象的key

【HarmonyOS 5】一次开发多端部署

效果预览

1. 了解断点、媒体查询、栅格布局

断点

媒体查询

栅格布局

2. 封装媒体查询监听断点工具类

3. 配合媒体查询做 Swiper() 轮播图分割效果

4. 配合媒体查询做 Tab 栏 UI 展示位置变动

5. 配合栅格布局做列表展示数量控制

总结

【HarmonyOS 5】关键资产存储开发案例

1、关键资产(@ohos.security.asset)

2、关键资产使用与 asset 的常用操作

2.1 使用关键资产需要导入模块 AssetStoreKit：

2.2 常用操作：

3、常规方法封装

3.1 addSync 设置数据

3.2 querySync 获取数据

3.3 querySync 查询 key 数据是否存在

3.4 updateSync 修改资产数据

3.5 removeSync 删除资产数据

3.6 string 与 Uint8Array 数据互转换

4、关键资产的访问控制

5、参考

【HarmonyOS 5】多目标产物构建实践

什么是多产物构建

如何定义多个构建产物

如何在项目中使用产物

参考文章

【HarmonyOS 5】App Linking 应用间跳转详解

什么是 App Linking

工作原理

如何开发

1.开通 App Linking

2.确定域名

3.服务端部署 applinking.json 文件

4.AGC绑定域名

5.项目配置

6.组装聚合链接

7.解析聚合链接中的参数

其他

如何获取应用ID

如何在应用未安装时点击链接跳转至应用市场

【HarmonyOS 5】一次开发多端部署

1. 了解断点、媒体查询、栅格布局

断点

媒体查询

栅格布局

2. 封装媒体查询监听断点工具类

3. 配合媒体查询做 Swiper() 轮播图分割效果

4. 配合媒体查询做 Tab 栏 UI 展示位置变动

5. 配合栅格布局做列表展示数量控制

总结

【HarmonyOS 5】hdc环境变量配置

hdc命令列表与全局参数

命令列表

开始

【HarmonyOS 5】华为分享-碰一碰开发分享

什么是多产物构建

如何定义多个构建产物

如何在项目中使用产物

参考文章

2.1 使用关键资产需要导入模块 `AssetStoreKit：`