• 时间:
  • 分类:

我给这组 API 起个更“好记”的名字：ArkUI 参数类型工具箱。
原因很简单：你在写 ArkUI 的时候，真正高频碰到的不是某个组件，而是这些“参数类型”——它们决定了你属性方法能不能传、传了有没有效果、资源引用会不会报错/不生效。

1）Resource：资源引用（$r / $rawfile），写对了才会生效

Resource 就是“引用资源文件”的类型。它一般用在颜色、字符串、尺寸、媒体资源这些地方。

1.1 两种常见写法

① $r：引用 sys/app 的资源表

$r('belonging.type.name')
  • belonging：'sys' 或 'app'
  • type：'boolean' | 'color' | 'float' | 'intarray' | 'integer' | 'pattern' | 'plural' | 'strarray' | 'string' | 'media'
  • name：资源名（你在资源里定义的）

例子：

Text($r('app.string.app_name'))
Text('hello').fontColor($r('sys.color.font_primary'))

② $rawfile：引用 rawfile 目录文件

$rawfile('filename')

例子：

Image($rawfile('banner.png'))

1.2 Resource 这块最常见的坑

坑 1：类型不匹配
比如某个属性支持 string | Resource，你用 $r 引用的资源必须也能被当成 string 用。
你要是拿个 color 的资源去喂给 string 参数，最后基本就是“看起来没报错，但效果等于没写”。

坑 2：用法不被这个属性支持
有些属性虽然类型签名看着支持 Resource，但具体实现并不一定对所有 Resource 用法都生效。遇到“设置了但没效果”，优先怀疑这个。

2）Length：长度单位（最常用，但也最容易写乱）

Length 你每天都在用：width/height/padding/margin/fontSize/...

它本质就是：数字 + 单位规则。

2.1 Length 支持三种输入

① string：可以写单位或百分比

'10px'
'10vp'
'10fp'
'100%'

② number：默认单位是 vp

10   // 等同于 10vp

③ Resource：引用尺寸资源

$r('app.float.page_padding')

2.2 一个特别容易忽略的小规则

string 不写单位时，默认也是 vp。

'10'  // 等同于 10vp（很多人以为是 px）

所以我个人建议：

  • number 就当 vp 用
  • string 就写清单位（特别是 px/fp 这种）

3）ResourceStr：字符串参数“既能传字符串也能传资源”

你会在很多地方看到这种写法：某个属性入参是 string | Resource。
那这个参数类型通常就叫 ResourceStr。

Text('标题')
Text($r('app.string.title'))

这种类型的核心价值就是：国际化时不改代码结构，只换资源。

4）Padding / Margin：内外边距（四方向版）

这俩就不多废话了，你懂的：

.padding({ top: 12, right: 16, bottom: 12, left: 16 })
.margin({ top: 8 })
  • Padding / Margin 里每个方向都是 Length
  • 不写的方向就当默认 0

4.1 LocalizedPadding / LocalizedMargin（API 12+）：支持 RTL 的 start/end

这个是很多人做国际化后才发现的坑：
在 RTL（从右到左）语言模式下，left/right 语义可能不对。

所以 API 12+ 给了：

  • start/end（会跟随 LTR/RTL 自动翻转）
  • top/bottom 不变

你可以理解成：

  • 想写“逻辑上的左边距” → 用 start
  • 想写“逻辑上的右边距” → 用 end

5）边框相关：EdgeWidths / EdgeColors / EdgeStyles / BorderRadiuses

边框这块参数挺多，但其实记住一句话就行：

边框就是：宽度 + 颜色 + 样式 + 圆角

5.1 分方向的写法（EdgeXXX）

比如只想让上边框更粗：

.borderWidth({ top: 2, right: 0, bottom: 0, left: 0 })
  • EdgeWidths：四边宽度（Length）
  • EdgeColors：四边颜色（ResourceColor）
  • EdgeStyles：四边样式（BorderStyle）
  • BorderRadiuses：四角圆角（Length）

5.2 LocalizedEdgeXXX / LocalizedBorderRadiuses（API 12+）

同样是为了 RTL：

  • start/end 会随语言方向翻转
  • top/bottom 不变

6）BorderOptions：边框“合并包”（我自己最爱用这个）

很多组件支持你直接传一个对象，把边框一次性写全：

.border({
  width: 1,
  color: '#e5e5e5',
  radius: 12,
  style: BorderStyle.Solid
})

BorderOptions 里可以写：

  • width：Length 或 EdgeWidths 或 LocalizedEdgeWidths
  • color：ResourceColor 或 EdgeColors 或 LocalizedEdgeColors
  • radius：Length 或 BorderRadiuses 或 LocalizedBorderRadiuses
  • style：BorderStyle 或 EdgeStyles
  • dashGap/dashWidth（虚线专用，API 12+，并且不支持百分比）

小提醒： 虚线那俩只有当你样式是虚线时才会生效，不然写了也等于没写。

7）ResourceColor：颜色入参“万能类型”

ResourceColor = Color | number | string | Resource

你可以随便挑一种习惯：

  • Color.Red（枚举）
  • 0xffff0000（number，rgb/argb）
  • '#ff0000' / 'rgba(...)'（string）
  • $r('sys.color.font_primary')（Resource）

我自己习惯：

  • 写 demo / 临时样式用 string
  • 做统一主题/规范用资源 $r(...)

8）Offset / Position / Area / RectResult：坐标与区域信息

这几个一般出现在相对布局、测量回调、位置信息获取里。

  • Offset：偏移量 { dx, dy }（都是 Length）
  • Position：坐标点 { x, y }（都是 Length）
  • Area：元素区域信息（宽高 + position/globalPosition）
  • RectResult：更偏“测量结果”的 { x, y, width, height }（数字）

简单记法：

  • Position/Offset 更像“你要怎么摆”
  • Area/RectResult 更像“系统告诉你摆完是什么结果”

9）Font：字体配置（别全塞 Text 上，整理成对象更清爽）

Font 是文本样式对象，常见字段：

Text('Hello')
  .font({
    size: 16,
    weight: 400,
    family: 'HarmonyOS Sans',
    style: FontStyle.Normal
  })

注意一个细节：

  • size 如果是 number，单位是 fp（不是 vp）
  • 不支持百分比

10）Dimension / PX / VP / FP / LPX / Percentage / Degree：更“严格”的单位类型

如果你看到某些属性不收普通 Length，而是收 Dimension 或更具体的 PX/VP/FP，可以理解成：

这个属性想让单位表达更明确、更严格。

比如：

  • 10px、10vp、10fp、10lpx、10%、10deg

你只要按要求写就行，不要想着偷懒传个 '10' 过去。

11）CustomBuilder：给组件塞一段自定义 UI（配合 @Builder）

这个就是“插槽”的感觉：属性里让你传一个函数，内部会调用它来渲染自定义内容。

你会在一些组件的属性方法里看到需要 CustomBuilder 的参数类型。

12）一些“看起来冷门但会突然用上”的类型

我把这几个当成“备用工具”：

  • ColorFilter：4*5 矩阵的颜色滤镜（做颜色处理会用）
  • ModalTransition：全屏模态转场方式（NONE/DEFAULT/ALPHA）
  • OutlineOptions + EdgeOutlineWidths/OutlineRadiuses/EdgeOutlineStyles：外描边（有时做高亮边框很好用）
  • VoidCallback / Callback<T>：回调类型（看签名就知道怎么传）
  • Configuration：颜色模式、字体缩放倍数（做适配时用）
  • Bias：锚点约束下的偏移比例（相对布局更精细控制）
  • ChainWeightOptions：链中组件权重（布局分配）
  • CacheCountInfo：缓存数量信息（更偏性能调参）
  • ResponsiveFillType / ItemFillPolicy：响应式填充（WaterFlow/Grid/List/Swiper）

这些不一定每天用，但你看到类型名时不至于懵。

13）最后给一个“我自己的写法习惯”（省事还不容易踩坑）

  1. 尺寸：能用 number 就用 number（默认 vp）
  2. 需要明确单位的：用 string 写清楚 vp/px/fp/%
  3. 国际化/主题：优先用 $r 走资源
  4. RTL 适配：能用 start/end 就别写 left/right
  5. 边框：优先用 border({...}) 这种对象写法，少写四条边到处散落
  6. 遇到“设置没效果”：先怀疑类型不匹配 or 该属性不支持这种 Resource 用法

标签: none

添加新评论