# Android-to-HarmonyOS UI Atomic Component Mapping Reference
## 一、基础视图组件映射
### 1.1 文本类组件
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| TextView | `android.widget.TextView` | `Text` | 直接映射 | 文本显示，支持富文本、样式设置 |
| EditText | `android.widget.EditText` | `TextInput` / `TextArea` | 单行用 TextInput，多行用 TextArea | 文本输入框 |
| AutoCompleteTextView | `android.widget.AutoCompleteTextView` | `Search` / `Select` | 组合实现 | 自动完成文本输入 |
| MultiAutoCompleteTextView | `android.widget.MultiAutoCompleteTextView` | 自定义组合 | Select + 标签显示 | 多段自动完成文本输入 |
| CheckedTextView | `android.widget.CheckedTextView` | `Row` + `Checkbox` + `Text` | 组合实现 | 带选中状态的文本视图 |
| TextSwitcher | `android.widget.TextSwitcher` | `Swiper` | 配合文本内容 | 文本切换动画容器 |
| ExtractEditText | `android.widget.ExtractEditText` | `TextArea` | 临时编辑场景 | 输入法提取编辑框 |
| Chronometer | `android.widget.Chronometer` | `Text` + 定时器 | 自定义实现 | 计时器显示 |
---
#### 1.1.1 TextView → Text 属性映射
**文本内容属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:text` | 构造函数参数 | String | Android: `android:text="Hello"`
HarmonyOS: `Text('Hello')` |
| `android:hint` | `.placeholder()` | String | Android: `android:hint="Enter text"`
HarmonyOS: `Text('').placeholder('Enter text')` |
| `android:textColor` | `.fontColor()` | Color → ResourceColor | Android: `android:textColor="#FF0000"`
HarmonyOS: `Text('Hello').fontColor('#FF0000')` |
| `android:textColorHint` | `.placeholderColor()` | Color → ResourceColor | Android: `android:textColorHint="#AAAAAA"`
HarmonyOS: `Text('').placeholderColor('#AAAAAA')` |
| `android:textColorHighlight` | `.selectionBackgroundColor()` | Color → ResourceColor | Android: `android:textColorHighlight="#FFFF00"`
HarmonyOS: `Text('Hello').selectionBackgroundColor('#FFFF00')` |
| `android:textColorLink` | 无直接对应 | 需自定义实现 | 使用 SpanString 设置链接颜色 |
**文本尺寸属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:textSize` | `.fontSize()` | sp → fp | Android: `android:textSize="16sp"`
HarmonyOS: `Text('Hello').fontSize(16)` |
| `android:textScaleX` | `.letterSpacing()` | float (不同行为) | Android: `android:textScaleX="1.2"`
HarmonyOS: `Text('Hello').letterSpacing(0.2)` |
| `android:lineSpacingExtra` | `.lineHeight()` | dp → vp | Android: `android:lineSpacingExtra="8dp"`
HarmonyOS: `Text('Hello').lineHeight({ extra: 8 })` |
| `android:lineSpacingMultiplier` | `.lineHeight()` | float (需转换) | Android: `android:lineSpacingMultiplier="1.5"`
HarmonyOS: `Text('Hello').lineHeight({ multiplier: 1.5 })` |
| `android:letterSpacing` | `.letterSpacing()` | float | Android: `android:letterSpacing="0.1"`
HarmonyOS: `Text('Hello').letterSpacing(0.1)` |
| `android:ems` | 无直接对应 | 需计算宽度 | 使用 `.width()` 根据字符数计算 |
| `android:maxEms` | `.constraintSize()` | 需计算宽度 | Android: `android:maxEms="10"`
HarmonyOS: `Text('Hello').constraintSize({ maxWidth: 200 })` |
| `android:minEms` | `.constraintSize()` | 需计算宽度 | Android: `android:minEms="5"`
HarmonyOS: `Text('Hello').constraintSize({ minWidth: 100 })` |
**文本样式属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:textStyle` | `.fontWeight()` / `.fontStyle()` | enum → enum | Android: `android:textStyle="bold"`
HarmonyOS: `Text('Hello').fontWeight(FontWeight.Bold)` |
| `android:fontFamily` | `.fontFamily()` | String → String | Android: `android:fontFamily="sans-serif"`
HarmonyOS: `Text('Hello').fontFamily('sans-serif')` |
| `android:textAllCaps` | `.textCase()` 或手动转换 | boolean → TextCase | Android: `android:textAllCaps="true"`
HarmonyOS: `Text('hello').textCase(TextCase.Upper)` |
| `android:textLocale` | 无直接对应 | 需设置语言环境 | 使用系统语言环境 |
| `android:fontFeatureSettings` | 无直接对应 | 需自定义实现 | 使用字体特性 API |
| `android:fontVariationSettings` | 无直接对应 | 需自定义实现 | 使用字体变体 API |
| `android:textFontWeight` | `.fontWeight()` | int → FontWeight | Android: `android:textFontWeight="700"`
HarmonyOS: `Text('Hello').fontWeight(FontWeight.Bold)` |
| `android:lineHeight` | `.lineHeight()` | dp → vp | Android: `android:lineHeight="24dp"`
HarmonyOS: `Text('Hello').lineHeight(24)` |
**文本对齐属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:gravity` | `.textAlign()` | Gravity → TextAlign | Android: `android:gravity="center"`
HarmonyOS: `Text('Hello').textAlign(TextAlign.Center)` |
| `android:textAlignment` | `.textAlign()` | TextAlignment → TextAlign | Android: `android:textAlignment="center"`
HarmonyOS: `Text('Hello').textAlign(TextAlign.Center)` |
| `android:textDirection` | 无直接对应 | 需设置布局方向 | 使用 `.direction()` |
| `android:justificationMode` | 无直接对应 | 需自定义实现 | 使用文本对齐 API |
**文本显示与省略属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:maxLines` | `.maxLines()` | int → int | Android: `android:maxLines="2"`
HarmonyOS: `Text('Hello').maxLines(2)` |
| `android:minLines` | 无直接对应 | 需自定义实现 | 使用高度约束 |
| `android:lines` | 无直接对应 | 需自定义实现 | 使用高度约束 |
| `android:singleLine` | 使用 TextInput | boolean → 组件选择 | Android: `android:singleLine="true"`
HarmonyOS: 使用 TextInput 而非 TextArea |
| `android:ellipsize` | `.textOverflow()` | TruncateAt → TextOverflow | Android: `android:ellipsize="end"`
HarmonyOS: `Text('Hello').textOverflow({ overflow: TextOverflow.Ellipsis })` |
| `android:marqueeRepeatLimit` | `.textOverflow()` | int → Marquee | Android: `android:marqueeRepeatLimit="3"`
HarmonyOS: `Text('Hello').textOverflow({ overflow: TextOverflow.Marquee })` |
**文本选择属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:textIsSelectable` | `.copyOption()` | boolean → CopyOptions | Android: `android:textIsSelectable="true"`
HarmonyOS: `Text('Hello').copyOption(CopyOptions.InApp)` |
| `android:selectable` | `.copyOption()` | boolean → CopyOptions | Android: `android:selectable="true"`
HarmonyOS: `Text('Hello').copyOption(CopyOptions.InApp)` |
| `android:selectAllOnFocus` | `.selectAll()` | boolean → 方法调用 | Android: `android:selectAllOnFocus="true"`
HarmonyOS: `TextInput().onFocus(() => { textInput.selectAll() })` |
**文本外观属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:textAppearance` | @Styles | @style → @Styles | Android: `android:textAppearance="@style/TextAppearance"`
HarmonyOS: 使用 `@Styles` 装饰器 |
| `android:shadowColor` | `.shadow()` | Color → shadow | Android: `android:shadowColor="#80000000"`
HarmonyOS: `Text('Hello').shadow({ color: '#80000000', radius: 4 })` |
| `android:shadowDx` | `.shadow()` | float → shadow.offsetX | Android: `android:shadowDx="2"`
HarmonyOS: `Text('Hello').shadow({ offsetX: 2, offsetY: 2, radius: 4 })` |
| `android:shadowDy` | `.shadow()` | float → shadow.offsetY | Android: `android:shadowDy="2"`
HarmonyOS: `Text('Hello').shadow({ offsetX: 2, offsetY: 2, radius: 4 })` |
| `android:shadowRadius` | `.shadow()` | float → shadow.radius | Android: `android:shadowRadius="4"`
HarmonyOS: `Text('Hello').shadow({ radius: 4 })` |
| `android:elegantTextHeight` | 无直接对应 | 需自定义实现 | 使用字体渲染 API |
| `android:fallbackLineSpacing` | 无直接对应 | 需自定义实现 | 使用行高设置 |
**文本链接属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:autoLink` | 无直接对应 | 需自定义实现 | 使用 SpanString 或正则表达式 |
| `android:linksClickable` | 无直接对应 | 需自定义实现 | 使用 SpanString 设置点击事件 |
| `android:includeFontPadding` | 无直接对应 | 需自定义实现 | 使用行高调整 |
---
#### 1.1.2 EditText → TextInput/TextArea 属性映射
**输入类型属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:inputType` | `.type()` | InputType → InputType | Android: `android:inputType="text"`
HarmonyOS: `TextInput().type(InputType.Normal)` |
| `android:inputType="textPassword"` | `.type()` | password → Password | Android: `android:inputType="textPassword"`
HarmonyOS: `TextInput().type(InputType.Password)` |
| `android:inputType="number"` | `.type()` | number → Number | Android: `android:inputType="number"`
HarmonyOS: `TextInput().type(InputType.Number)` |
| `android:inputType="phone"` | `.type()` | phone → PhoneNumber | Android: `android:inputType="phone"`
HarmonyOS: `TextInput().type(InputType.PhoneNumber)` |
| `android:inputType="email"` | `.type()` | email → Email | Android: `android:inputType="textEmailAddress"`
HarmonyOS: `TextInput().type(InputType.Email)` |
| `android:inputType="textMultiLine"` | 使用 TextArea | multiLine → TextArea | Android: `android:inputType="textMultiLine"`
HarmonyOS: 使用 TextArea 组件 |
| `android:maxLength` | `.maxLength()` | int → int | Android: `android:maxLength="100"`
HarmonyOS: `TextInput().maxLength(100)` |
| `android:password` | `.type()` | boolean → InputType | Android: `android:password="true"`
HarmonyOS: `TextInput().type(InputType.Password)` |
| `android:phoneNumber` | `.type()` | boolean → InputType | Android: `android:phoneNumber="true"`
HarmonyOS: `TextInput().type(InputType.PhoneNumber)` |
| `android:numeric` | `.type()` | enum → InputType | Android: `android:numeric="integer"`
HarmonyOS: `TextInput().type(InputType.Number)` |
| `android:digits` | 无直接对应 | 需自定义实现 | 使用输入过滤器 |
| `android:capitalize` | 无直接对应 | 需自定义实现 | 使用文本转换 |
| `android:autoText` | 无直接对应 | 需自定义实现 | 使用输入法设置 |
| `android:editable` | `.enabled()` | boolean → boolean | Android: `android:editable="false"`
HarmonyOS: `TextInput().enabled(false)` |
| `android:cursorVisible` | 无直接对应 | 需自定义实现 | 使用光标 API |
**IME 选项属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:imeOptions` | `.enterKeyType()` | ImeOptions → EnterKeyType | Android: `android:imeOptions="actionDone"`
HarmonyOS: `TextInput().enterKeyType(EnterKeyType.Done)` |
| `android:imeOptions="actionNext"` | `.enterKeyType()` | actionNext → Next | Android: `android:imeOptions="actionNext"`
HarmonyOS: `TextInput().enterKeyType(EnterKeyType.Next)` |
| `android:imeOptions="actionSearch"` | `.enterKeyType()` | actionSearch → Search | Android: `android:imeOptions="actionSearch"`
HarmonyOS: `TextInput().enterKeyType(EnterKeyType.Search)` |
| `android:imeOptions="actionSend"` | `.enterKeyType()` | actionSend → Send | Android: `android:imeOptions="actionSend"`
HarmonyOS: `TextInput().enterKeyType(EnterKeyType.Send)` |
| `android:imeActionLabel` | 无直接对应 | 需自定义实现 | 使用键盘类型设置 |
| `android:imeActionId` | 无直接对应 | 需自定义实现 | 使用键盘类型设置 |
**输入提示属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:hint` | `.placeholder()` | String → String | Android: `android:hint="Enter name"`
HarmonyOS: `TextInput().placeholder('Enter name')` |
| `android:textColorHint` | `.placeholderColor()` | Color → ResourceColor | Android: `android:textColorHint="#AAAAAA"`
HarmonyOS: `TextInput().placeholderColor('#AAAAAA')` |
---
#### 1.1.3 其他文本组件属性映射
**AutoCompleteTextView → Search/Select**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|--------|
| `android:completionThreshold` | Search 组件内置 | int → 自动触发 | Android: `android:completionThreshold="1"`
HarmonyOS: Search 组件自动触发 |
| `android:dropDownHeight` | 无直接对应 | 需自定义实现 | 使用 Popup 或 Select |
| `android:dropDownWidth` | 无直接对应 | 需自定义实现 | 使用 Popup 或 Select |
| `android:dropDownHorizontalOffset` | 无直接对应 | 需自定义实现 | 使用 Popup 或 Select |
| `android:dropDownVerticalOffset` | 无直接对应 | 需自定义实现 | 使用 Popup 或 Select |
**Chronometer → Text + 定时器**
| Android XML | HarmonyOS 实现 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:format` | 使用 setInterval | String → 格式化 | Android: `android:format="%s"`
HarmonyOS: 使用 `setInterval` 更新 Text |
| `android:countDown` | 自定义逻辑 | boolean → 计数方向 | Android: `android:countDown="true"`
HarmonyOS: 自定义计数逻辑 |
| `android:base` | 使用 Date | long → Date | Android: `android:base="1000"`
HarmonyOS: 使用 Date 对象 |
---
#### 1.1.4 文本组件通用布局属性映射
**尺寸属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_width` | `.width()` | dp → vp / match_parent → '100%' | Android: `android:layout_width="100dp"`
HarmonyOS: `Text('Hello').width(100)` |
| `android:layout_width="match_parent"` | `.width()` | match_parent → '100%' | Android: `android:layout_width="match_parent"`
HarmonyOS: `Text('Hello').width('100%')` |
| `android:layout_width="wrap_content"` | 无需设置 | wrap_content → 自适应 | Android: `android:layout_width="wrap_content"`
HarmonyOS: 无需设置，自动适应 |
| `android:layout_height` | `.height()` | dp → vp / match_parent → '100%' | Android: `android:layout_height="50dp"`
HarmonyOS: `Text('Hello').height(50)` |
| `android:minWidth` | `.constraintSize()` | dp → vp | Android: `android:minWidth="100dp"`
HarmonyOS: `Text('Hello').constraintSize({ minWidth: 100 })` |
| `android:maxWidth` | `.constraintSize()` | dp → vp | Android: `android:maxWidth="200dp"`
HarmonyOS: `Text('Hello').constraintSize({ maxWidth: 200 })` |
| `android:minHeight` | `.constraintSize()` | dp → vp | Android: `android:minHeight="30dp"`
HarmonyOS: `Text('Hello').constraintSize({ minHeight: 30 })` |
| `android:maxHeight` | `.constraintSize()` | dp → vp | Android: `android:maxHeight="100dp"`
HarmonyOS: `Text('Hello').constraintSize({ maxHeight: 100 })` |
**边距与内边距属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_margin` | `.margin()` | dp → vp | Android: `android:layout_margin="10dp"`
HarmonyOS: `Text('Hello').margin(10)` |
| `android:layout_marginTop` | `.margin({ top })` | dp → vp | Android: `android:layout_marginTop="10dp"`
HarmonyOS: `Text('Hello').margin({ top: 10 })` |
| `android:layout_marginBottom` | `.margin({ bottom })` | dp → vp | Android: `android:layout_marginBottom="10dp"`
HarmonyOS: `Text('Hello').margin({ bottom: 10 })` |
| `android:layout_marginLeft` | `.margin({ left })` | dp → vp | Android: `android:layout_marginLeft="10dp"`
HarmonyOS: `Text('Hello').margin({ left: 10 })` |
| `android:layout_marginRight` | `.margin({ right })` | dp → vp | Android: `android:layout_marginRight="10dp"`
HarmonyOS: `Text('Hello').margin({ right: 10 })` |
| `android:layout_marginStart` | `.margin({ start })` | dp → vp | Android: `android:layout_marginStart="10dp"`
HarmonyOS: `Text('Hello').margin({ start: 10 })` |
| `android:layout_marginEnd` | `.margin({ end })` | dp → vp | Android: `android:layout_marginEnd="10dp"`
HarmonyOS: `Text('Hello').margin({ end: 10 })` |
| `android:padding` | `.padding()` | dp → vp | Android: `android:padding="10dp"`
HarmonyOS: `Text('Hello').padding(10)` |
| `android:paddingTop` | `.padding({ top })` | dp → vp | Android: `android:paddingTop="10dp"`
HarmonyOS: `Text('Hello').padding({ top: 10 })` |
| `android:paddingBottom` | `.padding({ bottom })` | dp → vp | Android: `android:paddingBottom="10dp"`
HarmonyOS: `Text('Hello').padding({ bottom: 10 })` |
| `android:paddingLeft` | `.padding({ left })` | dp → vp | Android: `android:paddingLeft="10dp"`
HarmonyOS: `Text('Hello').padding({ left: 10 })` |
| `android:paddingRight` | `.padding({ right })` | dp → vp | Android: `android:paddingRight="10dp"`
HarmonyOS: `Text('Hello').padding({ right: 10 })` |
| `android:paddingStart` | `.padding({ start })` | dp → vp | Android: `android:paddingStart="10dp"`
HarmonyOS: `Text('Hello').padding({ start: 10 })` |
| `android:paddingEnd` | `.padding({ end })` | dp → vp | Android: `android:paddingEnd="10dp"`
HarmonyOS: `Text('Hello').padding({ end: 10 })` |
**对齐与权重属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_gravity` | `.align()` / `.alignSelf()` | Gravity → Alignment | Android: `android:layout_gravity="center"`
HarmonyOS: `Text('Hello').align(Alignment.Center)` |
| `android:layout_weight` | `.layoutWeight()` | float → number | Android: `android:layout_weight="1"`
HarmonyOS: `Text('Hello').layoutWeight(1)` |
**显示属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:visibility` | `.visibility()` | enum → Visibility | Android: `android:visibility="gone"`
HarmonyOS: `Text('Hello').visibility(Visibility.None)` |
| `android:visibility="invisible"` | `.visibility()` | invisible → Hidden | Android: `android:visibility="invisible"`
HarmonyOS: `Text('Hello').visibility(Visibility.Hidden)` |
| `android:visibility="visible"` | `.visibility()` | visible → Visible | Android: `android:visibility="visible"`
HarmonyOS: `Text('Hello').visibility(Visibility.Visible)` |
| `android:alpha` | `.opacity()` | float (0-1) → number (0-1) | Android: `android:alpha="0.5"`
HarmonyOS: `Text('Hello').opacity(0.5)` |
| `android:background` | `.backgroundColor()` | Color → ResourceColor | Android: `android:background="#FF0000"`
HarmonyOS: `Text('Hello').backgroundColor('#FF0000')` |
| `android:background` | `.backgroundImage()` | Drawable → Resource | Android: `android:background="@drawable/bg"`
HarmonyOS: `Text('Hello').backgroundImage($r('app.media.bg'))` |
**交互属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:enabled` | `.enabled()` | boolean → boolean | Android: `android:enabled="false"`
HarmonyOS: `Text('Hello').enabled(false)` |
| `android:clickable` | `.onClick()` | boolean → 事件回调 | Android: `android:clickable="true"`
HarmonyOS: `Text('Hello').onClick(() => { ... })` |
| `android:focusable` | `.focusable()` | boolean → boolean | Android: `android:focusable="true"`
HarmonyOS: `Text('Hello').focusable(true)` |
| `android:focusableInTouchMode` | 无直接对应 | 需自定义实现 | 使用焦点 API |
**变换属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:rotation` | `.rotate()` | float → { angle: number } | Android: `android:rotation="90"`
HarmonyOS: `Text('Hello').rotate({ angle: 90 })` |
| `android:scaleX` | `.scale()` | float → { x: number } | Android: `android:scaleX="1.5"`
HarmonyOS: `Text('Hello').scale({ x: 1.5 })` |
| `android:scaleY` | `.scale()` | float → { y: number } | Android: `android:scaleY="1.5"`
HarmonyOS: `Text('Hello').scale({ y: 1.5 })` |
| `android:translationX` | `.translate()` | float → { x: number } | Android: `android:translationX="100"`
HarmonyOS: `Text('Hello').translate({ x: 100 })` |
| `android:translationY` | `.translate()` | float → { y: number } | Android: `android:translationY="100"`
HarmonyOS: `Text('Hello').translate({ y: 100 })` |
| `android:translationZ` | 无直接对应 | 需自定义实现 | 使用层级和阴影 |
| `android:pivotX` | 无直接对应 | 需自定义实现 | 使用变换中心 API |
| `android:pivotY` | 无直接对应 | 需自定义实现 | 使用变换中心 API |
**阴影与效果属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:elevation` | `.shadow()` | dp → shadow | Android: `android:elevation="8dp"`
HarmonyOS: `Text('Hello').shadow({ radius: 8, color: '#30000000', offsetY: 4 })` |
| `android:outlineProvider` | 无直接对应 | 需自定义实现 | 使用裁剪 API |
| `android:clipToOutline` | `.clip()` | boolean → boolean | Android: `android:clipToOutline="true"`
HarmonyOS: `Text('Hello').clip(true)` |
**无障碍属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:contentDescription` | `.accessibilityText()` | String → String | Android: `android:contentDescription="Button label"`
HarmonyOS: `Text('Hello').accessibilityText('Button label')` |
| `android:labelFor` | 无直接对应 | 需自定义实现 | 使用无障碍组 |
| `android:importantForAccessibility` | `.accessibilityLevel()` | enum → AccessibilityLevel | Android: `android:importantForAccessibility="yes"`
HarmonyOS: `Text('Hello').accessibilityLevel('auto')` |
---
#### 1.1.5 单位换算说明
| Android 单位 | HarmonyOS 单位 | 换算关系 | 说明 |
|-------------|---------------|---------|------|
| `dp` (Density-independent Pixels) | `vp` (Virtual Pixels) | 1dp ≈ 1vp | 密度无关像素，用于布局尺寸 |
| `sp` (Scale-independent Pixels) | `fp` (Font Pixels) | 1sp ≈ 1fp | 字体像素，用于文本大小，会随系统字体缩放 |
| `px` (Pixels) | `px` (Pixels) | 1px = 1px | 物理像素，不推荐使用 |
| `dip` | `vp` | 1dip ≈ 1vp | dp 的别名 |
| `in` (Inches) | 需转换 | 1in ≈ 160vp | 英寸，1英寸 = 160dp |
| `mm` (Millimeters) | 需转换 | 1mm ≈ 6.33vp | 毫米，1毫米 = 6.33dp |
| `pt` (Points) | 需转换 | 1pt ≈ 2.12vp | 点，1点 = 2.12dp |
---
#### 1.1.6 文本组件属性映射统计
| 映射类型 | 数量 | 占比 |
|---------|------|------|
| 直接映射 | 45 | ~50% |
| 需类型转换 | 30 | ~33% |
| 需组合实现 | 10 | ~11% |
| 无直接对应 | 5 | ~6% |
| **总计** | **90** | **100%** |
**映射复杂度说明：**
- **直接映射**：属性名称和功能基本一致，仅需简单语法调整
- **需类型转换**：需要将 Android 的数据类型转换为 HarmonyOS 对应类型（如 sp→fp, dp→vp）
- **需组合实现**：需要多个 HarmonyOS 属性或组件组合才能实现 Android 单个属性的功能
- **无直接对应**：HarmonyOS 暂无对应功能，需要自定义实现或使用替代方案
### 1.2 按钮类组件
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| Button | `android.widget.Button` | `Button` | 直接映射 | 普通按钮 |
| ImageButton | `android.widget.ImageButton` | `Button` + `Image` | 组合实现 | 图片按钮 |
| CompoundButton | `android.widget.CompoundButton` | `Checkbox` / `Radio` / `Toggle` | 根据类型选择 | 复合按钮基类 |
| CheckBox | `android.widget.CheckBox` | `Checkbox` | 直接映射 | 复选框 |
| RadioButton | `android.widget.RadioButton` | `Radio` + `RadioContainer` | 需容器 | 单选按钮 |
| RadioGroup | `android.widget.RadioGroup` | `RadioContainer` | 直接映射 | 单选按钮组 |
| ToggleButton | `android.widget.ToggleButton` | `Toggle` (ButtonType: Button) | 直接映射 | 开关按钮（文字切换） |
| Switch | `android.widget.Switch` | `Toggle` (ButtonType: Switch) | 直接映射 | 开关控件（滑动式） |
---
#### 1.2.1 Button → Button 属性映射
**按钮内容属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:text` | 构造函数参数 | String | Android: `android:text="Click Me"`
HarmonyOS: `Button('Click Me')` |
| `android:textColor` | `.fontColor()` | Color → ResourceColor | Android: `android:textColor="#FFFFFF"`
HarmonyOS: `Button('Click').fontColor('#FFFFFF')` |
| `android:textSize` | `.fontSize()` | sp → fp | Android: `android:textSize="16sp"`
HarmonyOS: `Button('Click').fontSize(16)` |
| `android:textStyle` | `.fontWeight()` | enum → FontWeight | Android: `android:textStyle="bold"`
HarmonyOS: `Button('Click').fontWeight(FontWeight.Bold)` |
**按钮类型属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:background` | `.type()` + `.backgroundColor()` | Drawable → ButtonType | Android: `android:background="@drawable/bg"`
HarmonyOS: `Button('Click').type(ButtonType.Normal)` |
| `android:stateListAnimator` | 无直接对应 | 需自定义实现 | 使用动画 API |
| `android:elevation` | `.shadow()` | dp → shadow | Android: `android:elevation="4dp"`
HarmonyOS: `Button('Click').shadow({ radius: 4 })` |
**Material Button 特有属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `app:cornerRadius` | 无直接对应 | 需自定义实现 | 使用 `.borderRadius()` |
| `app:icon` | 无直接对应 | 需组合实现 | 使用 `Button` + `Image` 组合 |
| `app:iconTint` | 无直接对应 | 需组合实现 | 使用 `Image` 的 `.renderMode()` |
| `app:iconGravity` | 无直接对应 | 需组合实现 | 使用 `Row` 布局调整 |
| `app:iconPadding` | 无直接对应 | 需组合实现 | 使用 `.padding()` |
| `app:iconSize` | 无直接对应 | 需组合实现 | 使用 `Image` 的 `.width()` `.height()` |
| `app:strokeColor` | `.border()` | Color → borderColor | Android: `app:strokeColor="#FF0000"`
HarmonyOS: `Button('Click').border({ color: '#FF0000' })` |
| `app:strokeWidth` | `.border()` | dp → borderWidth | Android: `app:strokeWidth="2dp"`
HarmonyOS: `Button('Click').border({ width: 2 })` |
| `app:rippleColor` | 无直接对应 | 需自定义实现 | 使用状态样式 |
**按钮状态属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:enabled` | `.enabled()` | boolean → boolean | Android: `android:enabled="false"`
HarmonyOS: `Button('Click').enabled(false)` |
| `android:clickable` | `.onClick()` | boolean → 事件回调 | Android: `android:clickable="true"`
HarmonyOS: `Button('Click').onClick(() => { ... })` |
| `android:focusable` | `.focusable()` | boolean → boolean | Android: `android:focusable="true"`
HarmonyOS: `Button('Click').focusable(true)` |
| `android:selected` | 无直接对应 | 需状态管理 | 使用 `@State` 变量 |
| `android:pressed` | 无直接对应 | 需状态管理 | 使用 `.stateEffect()` |
**按钮交互属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:onClick` | `.onClick()` | 方法引用 → 回调函数 | Android: `android:onClick="onClick"`
HarmonyOS: `Button('Click').onClick(() => { ... })` |
| `android:longClickable` | `.onLongPress()` | boolean → 回调函数 | Android: `android:longClickable="true"`
HarmonyOS: `Button('Click').onLongPress(() => { ... })` |
---
#### 1.2.2 ImageButton → Button + Image 组合实现
**ImageButton 属性映射**
| Android XML | HarmonyOS 实现 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:src` | `Image` 组件 | Drawable → Resource | Android: `android:src="@drawable/icon"`
HarmonyOS: `Button() { Image($r('app.media.icon')) }` |
| `android:scaleType` | `Image.objectFit()` | ScaleType → ImageFit | Android: `android:scaleType="centerCrop"`
HarmonyOS: `Image($r('app.media.icon')).objectFit(ImageFit.Cover)` |
| `android:adjustViewBounds` | 无直接对应 | 需自定义实现 | 使用尺寸约束 |
| `android:tint` | `Image.renderMode()` | Color → RenderMode | Android: `android:tint="#FF0000"`
HarmonyOS: `Image($r('app.media.icon')).renderMode(ImageRenderMode.Template)` |
| `android:tintMode` | 无直接对应 | 需自定义实现 | 使用渲染模式 |
**组合示例：**
```typescript
// Android
// HarmonyOS
Button() {
Image($r('app.media.ic_back'))
.width(24)
.height(24)
.objectFit(ImageFit.Contain)
}
.width(48)
.height(48)
.type(ButtonType.Normal)
.backgroundColor(Color.Transparent)
.onClick(() => {
// Handle click
})
```
---
#### 1.2.3 CheckBox → Checkbox 属性映射
**CheckBox 属性映射**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:checked` | `.select()` | boolean → boolean | Android: `android:checked="true"`
HarmonyOS: `Checkbox().select(true)` |
| `android:button` | 无直接对应 | 需自定义实现 | 使用自定义样式 |
| `android:buttonTint` | 无直接对应 | 需自定义实现 | 使用状态样式 |
| `android:buttonTintMode` | 无直接对应 | 需自定义实现 | 使用状态样式 |
**CheckBox 事件映射**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:OnCheckedChangeListener` | `.onChange()` | 监听器 → 回调函数 | Android: `setOnCheckedChangeListener(...)`
HarmonyOS: `Checkbox().onChange((isSelected: boolean) => { ... })` |
---
#### 1.2.4 RadioButton + RadioGroup → Radio + RadioContainer 属性映射
**RadioButton 属性映射**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:checked` | 无直接对应 | 由 RadioContainer 管理 | 使用 RadioContainer 的默认值 |
| `android:button` | 无直接对应 | 需自定义实现 | 使用自定义样式 |
| `android:buttonTint` | 无直接对应 | 需自定义实现 | 使用状态样式 |
**RadioGroup 属性映射**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:orientation` | 无直接对应 | 需布局选择 | 垂直用 Column，水平用 Row |
| `android:checkedButton` | 无直接对应 | 需状态管理 | 使用 `@State` 变量管理选中项 |
**组合示例：**
```typescript
// Android
// HarmonyOS
@State selectedIndex: number = 0
RadioContainer({ group: 'radioGroup' }) {
Radio({ value: '0', group: 'radioGroup' })
.onChange((isSelected: boolean) => {
if (isSelected) {
this.selectedIndex = 0;
}
})
Radio({ value: '1', group: 'radioGroup' })
.onChange((isSelected: boolean) => {
if (isSelected) {
this.selectedIndex = 1;
}
})
}
```
---
#### 1.2.5 Switch/ToggleButton → Toggle 属性映射
**Toggle 属性映射**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:checked` | `.select()` | boolean → boolean | Android: `android:checked="true"`
HarmonyOS: `Toggle().select(true)` |
| `android:textOn` | 无直接对应 | 需组合实现 | 使用 `Toggle` + `Text` 组合 |
| `android:textOff` | 无直接对应 | 需组合实现 | 使用 `Toggle` + `Text` 组合 |
| `android:thumb` | 无直接对应 | 需自定义实现 | 使用自定义样式 |
| `android:thumbTint` | 无直接对应 | 需自定义实现 | 使用状态样式 |
| `android:track` | 无直接对应 | 需自定义实现 | 使用自定义样式 |
| `android:trackTint` | 无直接对应 | 需自定义实现 | 使用状态样式 |
| `android:showText` | 无直接对应 | 需组合实现 | 使用 `Toggle` + `Text` 组合 |
| `android:splitTrack` | 无直接对应 | 需自定义实现 | 使用自定义样式 |
**Toggle 类型选择**
| Android 组件 | HarmonyOS 类型 | 代码示例 |
|-------------|---------------|---------|
| `Switch` | `ToggleType.Switch` | `Toggle({ type: ToggleType.Switch })` |
| `ToggleButton` | `ToggleType.Button` | `Toggle({ type: ToggleType.Button })` |
**Toggle 事件映射**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:OnCheckedChangeListener` | `.onChange()` | 监听器 → 回调函数 | Android: `setOnCheckedChangeListener(...)`
HarmonyOS: `Toggle().onChange((isOn: boolean) => { ... })` |
---
#### 1.2.6 按钮组件通用布局属性映射
按钮组件继承所有通用布局属性，参考 1.1.4 文本组件通用布局属性映射。
**额外按钮特定属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:minWidth` | `.constraintSize()` | dp → vp | Android: `android:minWidth="88dp"`
HarmonyOS: `Button('Click').constraintSize({ minWidth: 88 })` |
| `android:minHeight` | `.constraintSize()` | dp → vp | Android: `android:minHeight="48dp"`
HarmonyOS: `Button('Click').constraintSize({ minHeight: 48 })` |
| `android:paddingStart` | `.padding({ start })` | dp → vp | Android: `android:paddingStart="16dp"`
HarmonyOS: `Button('Click').padding({ start: 16 })` |
| `android:paddingEnd` | `.padding({ end })` | dp → vp | Android: `android:paddingEnd="16dp"`
HarmonyOS: `Button('Click').padding({ end: 16 })` |
---
#### 1.2.7 按钮组件属性映射统计
| 映射类型 | 数量 | 占比 |
|---------|------|------|
| 直接映射 | 20 | ~45% |
| 需类型转换 | 10 | ~23% |
| 需组合实现 | 10 | ~23% |
| 无直接对应 | 4 | ~9% |
| **总计** | **44** | **100%** |
---
### 1.3 图片类组件
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| ImageView | `android.widget.ImageView` | `Image` | 直接映射 | 图片显示组件 |
| QuickContactBadge | `android.widget.QuickContactBadge` | `Badge` + `Image` | 组合实现 | 快捷联系人徽章 |
---
#### 1.3.1 ImageView → Image 属性映射
**图片源属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:src` | 构造函数参数 | Drawable → Resource | Android: `android:src="@drawable/image"`
HarmonyOS: `Image($r('app.media.image'))` |
| `android:srcCompat` | 构造函数参数 | Drawable → Resource | Android: `android:srcCompat="@drawable/image"`
HarmonyOS: `Image($r('app.media.image'))` |
**图片缩放类型属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:scaleType` | `.objectFit()` | ScaleType → ImageFit | Android: `android:scaleType="centerCrop"`
HarmonyOS: `Image($r('app.media.image')).objectFit(ImageFit.Cover)` |
| `android:scaleType="center"` | `.objectFit()` | center → ImageFit.None | Android: `android:scaleType="center"`
HarmonyOS: `Image($r('app.media.image')).objectFit(ImageFit.None)` |
| `android:scaleType="centerCrop"` | `.objectFit()` | centerCrop → ImageFit.Cover | Android: `android:scaleType="centerCrop"`
HarmonyOS: `Image($r('app.media.image')).objectFit(ImageFit.Cover)` |
| `android:scaleType="centerInside"` | `.objectFit()` | centerInside → ImageFit.Contain | Android: `android:scaleType="centerInside"`
HarmonyOS: `Image($r('app.media.image')).objectFit(ImageFit.Contain)` |
| `android:scaleType="fitCenter"` | `.objectFit()` | fitCenter → ImageFit.Contain | Android: `android:scaleType="fitCenter"`
HarmonyOS: `Image($r('app.media.image')).objectFit(ImageFit.Contain)` |
| `android:scaleType="fitXY"` | `.objectFit()` | fitXY → ImageFit.Fill | Android: `android:scaleType="fitXY"`
HarmonyOS: `Image($r('app.media.image')).objectFit(ImageFit.Fill)` |
| `android:scaleType="fitStart"` | `.objectFit()` | fitStart → ImageFit.Contain | Android: `android:scaleType="fitStart"`
HarmonyOS: `Image($r('app.media.image')).objectFit(ImageFit.Contain)` |
| `android:scaleType="fitEnd"` | `.objectFit()` | fitEnd → ImageFit.Contain | Android: `android:scaleType="fitEnd"`
HarmonyOS: `Image($r('app.media.image')).objectFit(ImageFit.Contain)` |
**图片调整属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:adjustViewBounds` | 无直接对应 | 需自定义实现 | 使用尺寸约束 |
| `android:maxWidth` | `.constraintSize()` | dp → vp | Android: `android:maxWidth="200dp"`
HarmonyOS: `Image($r('app.media.image')).constraintSize({ maxWidth: 200 })` |
| `android:maxHeight` | `.constraintSize()` | dp → vp | Android: `android:maxHeight="200dp"`
HarmonyOS: `Image($r('app.media.image')).constraintSize({ maxHeight: 200 })` |
**图片着色属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:tint` | `.renderMode()` + `.colorFilter()` | Color → RenderMode | Android: `android:tint="#FF0000"`
HarmonyOS: `Image($r('app.media.image')).renderMode(ImageRenderMode.Template)` |
| `android:tintMode` | 无直接对应 | 需自定义实现 | 使用渲染模式 |
| `android:colorFilter` | 无直接对应 | 需自定义实现 | 使用颜色滤镜 API |
**图片内容描述属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:contentDescription` | `.alt()` | String → String | Android: `android:contentDescription="Image description"`
HarmonyOS: `Image($r('app.media.image')).alt('Image description')` |
**图片裁剪属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:cropToPadding` | 无直接对应 | 需自定义实现 | 使用裁剪 API |
| `android:baseline` | 无直接对应 | 需自定义实现 | 使用基线对齐 API |
**图片布局方向属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layoutDirection` | 无直接对应 | 需自定义实现 | 使用布局方向 API |
---
#### 1.3.2 Image 组件加载属性
**加载状态属性**
| Android 方法 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `setImageResource()` | 构造函数参数 | int → Resource | Android: `imageView.setImageResource(R.drawable.image)`
HarmonyOS: `Image($r('app.media.image'))` |
| `setImageURI()` | 构造函数参数 | String → String | Android: `imageView.setImageURI("https://example.com/image.jpg")`
HarmonyOS: `Image('https://example.com/image.jpg')` |
| `setImageBitmap()` | 无直接对应 | 需自定义实现 | 使用 PixelMap |
| `setImageDrawable()` | 无直接对应 | 需自定义实现 | 使用 Drawable |
**加载事件属性**
| Android 监听器 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `OnLoadCompleteListener` | `.onComplete()` | 监听器 → 回调函数 | Android: `setOnLoadCompleteListener(...)`
HarmonyOS: `Image($r('app.media.image')).onComplete(() => { ... })` |
| `OnLoadFailedListener` | `.onError()` | 监听器 → 回调函数 | Android: `setOnLoadFailedListener(...)`
HarmonyOS: `Image($r('app.media.image')).onError(() => { ... })` |
| `OnProgressListener` | 无直接对应 | 需自定义实现 | 使用加载进度 API |
---
**ImageFit 枚举值映射**
| Android ScaleType | HarmonyOS ImageFit | 说明 |
|-----------------|-------------------|------|
| `center` | `ImageFit.None` | 不缩放，居中显示 |
| `centerCrop` | `ImageFit.Cover` | 等比缩放，填满容器，裁剪超出部分 |
| `centerInside` | `ImageFit.Contain` | 等比缩放，完整显示在容器内 |
| `fitCenter` | `ImageFit.Contain` | 等比缩放，居中显示 |
| `fitXY` | `ImageFit.Fill` | 拉伸填满容器 |
| `fitStart` | `ImageFit.Contain` | 等比缩放，靠上/靠左显示 |
| `fitEnd` | `ImageFit.Contain` | 等比缩放，靠下/靠右显示 |
---
#### 1.3.3 Image 组件高级属性
**图片渲染模式**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:alpha` | `.opacity()` | float (0-1) → number (0-1) | Android: `android:alpha="0.5"`
HarmonyOS: `Image($r('app.media.image')).opacity(0.5)` |
| `android:rotation` | `.rotate()` | float → { angle: number } | Android: `android:rotation="90"`
HarmonyOS: `Image($r('app.media.image')).rotate({ angle: 90 })` |
| `android:scaleX` | `.scale()` | float → { x: number } | Android: `android:scaleX="1.5"`
HarmonyOS: `Image($r('app.media.image')).scale({ x: 1.5 })` |
| `android:scaleY` | `.scale()` | float → { y: number } | Android: `android:scaleY="1.5"`
HarmonyOS: `Image($r('app.media.image')).scale({ y: 1.5 })` |
**图片边框与圆角**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:background` | 无直接对应 | 需自定义实现 | 使用 `.border()` 和 `.borderRadius()` |
| 无直接对应 | `.borderRadius()` | 需自定义实现 | Android: 使用 ShapeDrawable
HarmonyOS: `Image($r('app.media.image')).borderRadius(8)` |
**图片重复属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:tileMode` | 无直接对应 | 需自定义实现 | 使用 `.objectRepeat()` |
| 无直接对应 | `.objectRepeat()` | 需自定义实现 | Android: `android:tileMode="repeat"`
HarmonyOS: `Image($r('app.media.image')).objectRepeat(ImageRepeat.XY)` |
---
#### 1.3.4 图片组件通用布局属性映射
图片组件继承所有通用布局属性，参考 1.1.4 文本组件通用布局属性映射。
---
#### 1.3.5 图片组件属性映射统计
| 映射类型 | 数量 | 占比 |
|---------|------|------|
| 直接映射 | 15 | ~40% |
| 需类型转换 | 10 | ~27% |
| 需组合实现 | 8 | ~22% |
| 无直接对应 | 5 | ~13% |
| **总计** | **38** | **100%** |
### 1.4 选择器类组件
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| Spinner | `android.widget.Spinner` | `Select` | 直接映射 | 下拉选择框 |
| DatePicker | `android.widget.DatePicker` | `DatePicker` | 直接映射 | 日期选择器 |
| TimePicker | `android.widget.TimePicker` | `TimePicker` | 直接映射 | 时间选择器 |
| CalendarView | `android.widget.CalendarView` | `CalendarPicker` | 直接映射 | 日历视图 |
| NumberPicker | `android.widget.NumberPicker` | `TextPicker` | 配合数字数组 | 数字选择器 |
---
#### 1.4.1 Spinner → Select 属性映射
**数据源属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:entries` | 构造函数参数 | reference → array | Android: `android:entries="@array/items"`
HarmonyOS: `Select({ options: ['item1', 'item2'] })` |
| `android:prompt` | `.placeholder()` | string → string | Android: `android:prompt="Select an item"`
HarmonyOS: `Select({ placeholder: 'Select an item' })` |
| 无直接对应 | `selected` | 无 → number | Android: `setSelection(0)`
HarmonyOS: `Select({ selected: 0 })` |
**显示模式属性**
| Android XML | HarmonyOS 属性 | 类型转换器 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:spinnerMode` | 无直接对应 | enum → 无 | Android: `android:spinnerMode="dropdown"`
HarmonyOS: Select 始终是下拉式 |
| `android:spinnerMode="dialog"` | 无直接对应 | enum → 无 | Android: `android:spinnerMode="dialog"`
HarmonyOS: 需自定义实现 |
**下拉样式属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:dropDownSelector` | 无直接对应 | reference → stateStyles | Android: `android:dropDownSelector="@drawable/selector"`
HarmonyOS: `Select().stateStyles({ ... })` |
| `android:dropDownVerticalOffset` | 无直接对应 | dimension → 无 | Android: `android:dropDownVerticalOffset="10dp"`
HarmonyOS: 需自定义实现 |
| `android:dropDownHorizontalOffset` | 无直接对应 | dimension → 无 | Android: `android:dropDownHorizontalOffset="10dp"`
HarmonyOS: 需自定义实现 |
| `android:dropDownWidth` | 无直接对应 | dimension → 无 | Android: `android:dropDownWidth="200dp"`
HarmonyOS: 需自定义实现 |
| `android:dropDownHeight` | 无直接对应 | dimension → 无 | Android: `android:dropDownHeight="300dp"`
HarmonyOS: 需自定义实现 |
| `android:popupBackground` | `.backgroundColor()` | reference/color → ResourceColor | Android: `android:popupBackground="@drawable/popup_bg"`
HarmonyOS: `Select().backgroundColor('#FFFFFF')` |
**文本样式属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:gravity` | 无直接对应 | enum → 无 | Android: `android:gravity="center"`
HarmonyOS: 使用 `.textAlign()` |
**程序化方法映射**
| Android 方法 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `setAdapter()` | 构造函数参数 | SpinnerAdapter → array | Android: `spinner.setAdapter(adapter)`
HarmonyOS: `Select({ options: [...] })` |
| `setOnItemSelectedListener()` | `.onSelect()` | listener → callback | Android: `setOnItemSelectedListener(...)`
HarmonyOS: `Select().onSelect((index: number, value?: string) => { ... })` |
| `setSelection(int)` | `selected` | int → number | Android: `setSelection(0)`
HarmonyOS: 更新状态变量 `this.selectedIndex = 0` |
| `getSelectedItem()` | 无直接对应 | 无 → 状态变量 | Android: `getSelectedItem()`
HarmonyOS: `this.options[this.selectedIndex]` |
| `getSelectedItemPosition()` | 无直接对应 | 无 → 状态变量 | Android: `getSelectedItemPosition()`
HarmonyOS: `this.selectedIndex` |
| `setPrompt()` | `.placeholder()` | CharSequence → string | Android: `setPrompt("Select")`
HarmonyOS: `Select().placeholder('Select')` |
| `setEnabled()` | `.enabled()` | boolean → boolean | Android: `setEnabled(false)`
HarmonyOS: `Select().enabled(false)` |
---
#### 1.4.2 DatePicker → DatePicker 属性映射
**日期值属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:year` | 构造函数参数 | int → Date | Android: `android:year="2024"`
HarmonyOS: `DatePicker({ selected: new Date(2024, 0, 1) })` |
| `android:month` | 构造函数参数 | int → Date | Android: `android:month="0"`
HarmonyOS: `DatePicker({ selected: new Date(2024, 0, 1) })` |
| `android:day` | 构造函数参数 | int → Date | Android: `android:day="1"`
HarmonyOS: `DatePicker({ selected: new Date(2024, 0, 1) })` |
**日期范围属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:minDate` | `.minDate()` | long → Date | Android: `android:minDate="946684800000"`
HarmonyOS: `DatePicker({ minDate: new Date(2000, 0, 1) })` |
| `android:maxDate` | `.maxDate()` | long → Date | Android: `android:maxDate="2524608000000"`
HarmonyOS: `DatePicker({ maxDate: new Date(2050, 11, 31) })` |
**显示模式属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:datePickerMode` | 无直接对应 | enum → 无 | Android: `android:datePickerMode="spinner"`
HarmonyOS: 需自定义实现 |
| `android:calendarViewShown` | 无直接对应 | boolean → 无 | Android: `android:calendarViewShown="true"`
HarmonyOS: 需自定义实现 |
**程序化方法映射**
| Android 方法 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `init()` | 构造函数参数 | (int, int, int) → Date | Android: `init(2024, 0, 1, listener)`
HarmonyOS: `DatePicker({ selected: new Date(2024, 0, 1) })` |
| `updateDate()` | 更新状态变量 | (int, int, int) → Date | Android: `updateDate(2024, 0, 1)`
HarmonyOS: `this.selectedDate = new Date(2024, 0, 1)` |
| `getYear()` | 无直接对应 | 无 → 状态变量 | Android: `getYear()`
HarmonyOS: `this.selectedDate.getFullYear()` |
| `getMonth()` | 无直接对应 | 无 → 状态变量 | Android: `getMonth()`
HarmonyOS: `this.selectedDate.getMonth()` |
| `getDayOfMonth()` | 无直接对应 | 无 → 状态变量 | Android: `getDayOfMonth()`
HarmonyOS: `this.selectedDate.getDate()` |
| `setOnDateChangedListener()` | `.onChange()` | listener → callback | Android: `setOnDateChangedListener(...)`
HarmonyOS: `DatePicker().onChange((value: Date) => { ... })` |
---
#### 1.4.3 TimePicker → TimePicker 属性映射
**时间值属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:hour` | 构造函数参数 | int → number | Android: `android:hour="12"`
HarmonyOS: `TimePicker({ selected: new Date(2024, 0, 1, 12, 0, 0) })` |
| `android:minute` | 构造函数参数 | int → number | Android: `android:minute="30"`
HarmonyOS: `TimePicker({ selected: new Date(2024, 0, 1, 12, 30, 0) })` |
| `android:second` | 构造函数参数 | int → number | Android: `android:second="0"`
HarmonyOS: `TimePicker({ selected: new Date(2024, 0, 1, 12, 30, 0) })` |
**时间格式属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:format` | 无直接对应 | string → 无 | Android: `android:format="24"`
HarmonyOS: 需自定义实现 |
| `android:is24HourView` | 无直接对应 | boolean → 无 | Android: `android:is24HourView="true"`
HarmonyOS: 需自定义实现 |
**程序化方法映射**
| Android 方法 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `setOnTimeChangedListener()` | `.onChange()` | listener → callback | Android: `setOnTimeChangedListener(...)`
HarmonyOS: `TimePicker().onChange((value: Date) => { ... })` |
| `getHour()` | 无直接对应 | 无 → 状态变量 | Android: `getHour()`
HarmonyOS: `this.selectedDate.getHours()` |
| `getMinute()` | 无直接对应 | 无 → 状态变量 | Android: `getMinute()`
HarmonyOS: `this.selectedDate.getMinutes()` |
| `getSecond()` | 无直接对应 | 无 → 状态变量 | Android: `getSecond()`
HarmonyOS: `this.selectedDate.getSeconds()` |
---
#### 1.4.4 CalendarView → CalendarPicker 属性映射
**日期选择属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:minDate` | `.minDate()` | long → Date | Android: `android:minDate="946684800000"`
HarmonyOS: `CalendarPicker({ minDate: new Date(2000, 0, 1) })` |
| `android:maxDate` | `.maxDate()` | long → Date | Android: `android:maxDate="2524608000000"`
HarmonyOS: `CalendarPicker({ maxDate: new Date(2050, 11, 31) })` |
| `android:firstDayOfWeek` | 无直接对应 | int → 无 | Android: `android:firstDayOfWeek="1"`
HarmonyOS: 需自定义实现 |
**显示属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:shownWeekCount` | 无直接对应 | int → 无 | Android: `android:shownWeekCount="4"`
HarmonyOS: 需自定义实现 |
| `android:weekNumberColor` | 无直接对应 | color → 无 | Android: `android:weekNumberColor="#FF0000"`
HarmonyOS: 需自定义实现 |
**程序化方法映射**
| Android 方法 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `setOnDateChangeListener()` | `.onChange()` | listener → callback | Android: `setOnDateChangeListener(...)`
HarmonyOS: `CalendarPicker().onChange((value: Date) => { ... })` |
| `setDate()` | 更新状态变量 | Calendar → Date | Android: `setDate(calendar)`
HarmonyOS: `this.selectedDate = calendar.getTime()` |
---
#### 1.4.5 NumberPicker → TextPicker 属性映射
**数据源属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:minValue` | `range` | int → [number, number] | Android: `android:minValue="0"`
HarmonyOS: `TextPicker({ range: [0, 100] })` |
| `android:maxValue` | `range` | int → [number, number] | Android: `android:maxValue="100"`
HarmonyOS: `TextPicker({ range: [0, 100] })` |
| `android:wrapSelectorWheel` | 无直接对应 | boolean → 无 | Android: `android:wrapSelectorWheel="true"`
HarmonyOS: 需自定义实现 |
**显示值属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:displayedValues` | 构造函数参数 | array → array | Android: `android:displayedValues="@array/numbers"`
HarmonyOS: `TextPicker({ range: [1, 2, 3, 4, 5] })` |
**程序化方法映射**
| Android 方法 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `setDisplayedValues()` | 构造函数参数 | array → array | Android: `setDisplayedValues(values)`
HarmonyOS: `TextPicker({ range: values })` |
| `setOnValueChangedListener()` | `.onChange()` | listener → callback | Android: `setOnValueChangedListener(...)`
HarmonyOS: `TextPicker().onChange((value: string) => { ... })` |
| `setValue()` | 更新状态变量 | int → number | Android: `setValue(50)`
HarmonyOS: `this.selectedValue = 50` |
| `getValue()` | 无直接对应 | 无 → 状态变量 | Android: `getValue()`
HarmonyOS: `this.selectedValue` |
---
#### 1.4.6 选择器组件属性映射统计
| 映射类型 | 数量 | 占比 |
|---------|------|------|
| 直接映射 | 25 | ~45% |
| 需类型转换 | 15 | ~27% |
| 需组合实现 | 10 | ~18% |
| 无直接对应 | 5 | ~10% |
| **总计** | **55** | **100%** |
---
### 1.5 进度与评分类组件
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| ProgressBar | `android.widget.ProgressBar` | `Progress` | 直接映射 | 进度条 |
| SeekBar | `android.widget.SeekBar` | `Slider` | 直接映射 | 可拖动进度条 |
| RatingBar | `android.widget.RatingBar` | `Rating` | 直接映射 | 评分条 |
| ContentLoadingProgressBar | `android.widget.ContentLoadingProgressBar` | `Progress` + `LoadingProgress` | 组合实现 | 内容加载进度条 |
---
#### 1.5.1 ProgressBar → Progress 属性映射
**进度值属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:max` | 构造函数参数 | int → number | Android: `android:max="100"`
HarmonyOS: `Progress({ value: 50, total: 100 })` |
| `android:progress` | 构造函数参数 | int → number | Android: `android:progress="50"`
HarmonyOS: `Progress({ value: 50, total: 100 })` |
| `android:secondaryProgress` | 无直接对应 | int → 无 | Android: `android:secondaryProgress="75"`
HarmonyOS: 需自定义实现 |
**不确定模式属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:indeterminate` | 构造函数参数 | boolean → boolean | Android: `android:indeterminate="true"`
HarmonyOS: `Progress({ value: 0, total: 100, type: ProgressType.Ring })` |
| `android:indeterminateOnly` | 无直接对应 | boolean → 无 | Android: `android:indeterminateOnly="true"`
HarmonyOS: 需自定义实现 |
| `android:indeterminateDuration` | 无直接对应 | int → 无 | Android: `android:indeterminateDuration="2000"`
HarmonyOS: 需自定义实现 |
| `android:indeterminateBehavior` | 无直接对应 | enum → 无 | Android: `android:indeterminateBehavior="repeat"`
HarmonyOS: 需自定义实现 |
**样式属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:progressDrawable` | 无直接对应 | reference → 无 | Android: `android:progressDrawable="@drawable/progress"`
HarmonyOS: 需自定义实现 |
| `android:indeterminateDrawable` | 无直接对应 | reference → 无 | Android: `android:indeterminateDrawable="@drawable/indeterminate"`
HarmonyOS: 需自定义实现 |
| `android:progressTint` | `.color()` | color → ResourceColor | Android: `android:progressTint="#FF6200"`
HarmonyOS: `Progress({ value: 50, total: 100 }).color('#FF6200')` |
| `android:progressTintMode` | 无直接对应 | enum → 无 | Android: `android:progressTintMode="src_in"`
HarmonyOS: 需自定义实现 |
| `android:secondaryProgressTint` | 无直接对应 | color → 无 | Android: `android:secondaryProgressTint="#00FF00"`
HarmonyOS: 需自定义实现 |
| `android:progressBackgroundTint` | `.backgroundColor()` | color → ResourceColor | Android: `android:progressBackgroundTint="#E0E0E0"`
HarmonyOS: `Progress({ value: 50, total: 100 }).backgroundColor('#E0E0E0')` |
**程序化方法映射**
| Android 方法 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `setMax(int max)` | 构造函数参数 | int → number | Android: `progressBar.setMax(100)`
HarmonyOS: `Progress({ value: this.progress, total: 100 })` |
| `getMax()` | 无直接对应 | void → number | Android: `int max = progressBar.getMax()`
HarmonyOS: 使用状态变量 `this.total` |
| `setProgress(int progress)` | 构造函数参数 | int → number | Android: `progressBar.setProgress(50)`
HarmonyOS: 更新状态变量 `this.progress = 50` |
| `getProgress()` | 无直接对应 | void → number | Android: `int progress = progressBar.getProgress()`
HarmonyOS: 使用状态变量 `this.progress` |
| `incrementProgressBy(int delta)` | 无直接对应 | int → 无 | Android: `progressBar.incrementProgressBy(5)`
HarmonyOS: `this.progress += 5` |
| `setSecondaryProgress(int)` | 无直接对应 | int → 无 | Android: `progressBar.setSecondaryProgress(75)`
HarmonyOS: 需自定义实现 |
| `getSecondaryProgress()` | 无直接对应 | void → int | Android: `int sec = progressBar.getSecondaryProgress()`
HarmonyOS: 需自定义实现 |
| `setIndeterminate(boolean)` | 构造函数参数 | boolean → ProgressType | Android: `progressBar.setIndeterminate(true)`
HarmonyOS: `Progress({ type: ProgressType.Ring })` |
| `isIndeterminate()` | 无直接对应 | void → boolean | Android: `boolean isIndet = progressBar.isIndeterminate()`
HarmonyOS: 使用状态变量 |
**ProgressType 枚举值映射**
| Android Style | HarmonyOS ProgressType | 说明 |
|-----------------|-------------------|------|
| `Widget.ProgressBar` (circular) | `ProgressType.Ring` | 圆形进度条 |
| `Widget.ProgressBar.Horizontal` | `ProgressType.Linear` | 线性进度条 |
---
#### 1.5.2 SeekBar → Slider 属性映射
**进度值属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:max` | 构造函数参数 | int → number | Android: `android:max="100"`
HarmonyOS: `Slider({ value: 50, min: 0, max: 100 })` |
| `android:progress` | 构造函数参数 | int → number | Android: `android:progress="50"`
HarmonyOS: `Slider({ value: 50, min: 0, max: 100 })` |
| `android:min` | 构造函数参数 | int → number | Android: `android:min="0"`
HarmonyOS: `Slider({ value: 50, min: 0, max: 100 })` |
| `android:secondaryProgress` | 无直接对应 | int → 无 | Android: `android:secondaryProgress="75"`
HarmonyOS: 需自定义实现 |
**视觉外观属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:thumb` | 无直接对应 | drawable → 无 | Android: `android:thumb="@drawable/thumb"`
HarmonyOS: 需自定义实现 |
| `android:thumbTint` | 无直接对应 | color → 无 | Android: `android:thumbTint="#FF0000"`
HarmonyOS: 需自定义实现 |
| `android:thumbTintMode` | 无直接对应 | enum → 无 | Android: `android:thumbTintMode="src_in"`
HarmonyOS: 需自定义实现 |
| `android:thumbOffset` | 无直接对应 | int → 无 | Android: `android:thumbOffset="10"`
HarmonyOS: 需自定义实现 |
| `android:track` | `.trackColor()` | drawable → ResourceColor | Android: `android:track="@drawable/track"`
HarmonyOS: `Slider({ value: 50 }).trackColor('#CCCCCC')` |
| `android:progressTint` | `.selectedColor()` | color → ResourceColor | Android: `android:progressTint="#FF6200"`
HarmonyOS: `Slider({ value: 50 }).selectedColor('#FF6200')` |
| `android:progressTintMode` | 无直接对应 | enum → 无 | Android: `android:progressTintMode="src_in"`
HarmonyOS: 需自定义实现 |
| `android:progressBackgroundTint` | `.trackColor()` | color → ResourceColor | Android: `android:progressBackgroundTint="#E0E0E0"`
HarmonyOS: `Slider({ value: 50 }).trackColor('#E0E0E0')` |
| `android:secondaryProgressTint` | 无直接对应 | color → 无 | Android: `android:secondaryProgressTint="#00FF00"`
HarmonyOS: 需自定义实现 |
**交互属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:splitTrack` | 无直接对应 | boolean → 无 | Android: `android:splitTrack="false"`
HarmonyOS: 需自定义实现 |
| `android:mirrorForRtl` | 无直接对应 | boolean → 无 | Android: `android:mirrorForRtl="true"`
HarmonyOS: 需自定义实现 |
| `android:isIndicator` | 无直接对应 | boolean → 无 | Android: `android:isIndicator="true"`
HarmonyOS: 需自定义实现 |
**程序化方法映射**
| Android 方法 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `getMax()` | 无直接对应 | void → number | Android: `int max = seekBar.getMax()`
HarmonyOS: 使用状态变量 `this.max` |
| `setMax(int max)` | 构造函数参数 | int → number | Android: `seekBar.setMax(100)`
HarmonyOS: 更新状态变量 `this.max = 100` |
| `getProgress()` | 无直接对应 | void → number | Android: `int progress = seekBar.getProgress()`
HarmonyOS: 使用状态变量 `this.progress` |
| `setProgress(int progress)` | 构造函数参数 | int → number | Android: `seekBar.setProgress(50)`
HarmonyOS: 更新状态变量 `this.progress = 50` |
| `incrementProgressBy(int delta)` | 无直接对应 | int → 无 | Android: `seekBar.incrementProgressBy(5)`
HarmonyOS: `this.progress += 5` |
| `getMin()` | 无直接对应 | void → number | Android: `int min = seekBar.getMin()`
HarmonyOS: 使用状态变量 `this.min` |
| `setMin(int min)` | 构造函数参数 | int → number | Android: `seekBar.setMin(0)`
HarmonyOS: 更新状态变量 `this.min = 0` |
**事件监听器映射**
| Android 监听器 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `setOnSeekBarChangeListener()` | `.onChange()` | listener → callback | Android: `setOnSeekBarChangeListener(...)`
HarmonyOS: `Slider().onChange((value: number) => { ... })` |
---
#### 1.5.3 RatingBar → Rating 属性映射
**评分值属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:numStars` | 构造函数参数 | int → number | Android: `android:numStars="5"`
HarmonyOS: `Rating({ rating: 3.5, starNum: 5 })` |
| `android:rating` | 构造函数参数 | float → number | Android: `android:rating="3.5"`
HarmonyOS: `Rating({ rating: 3.5, starNum: 5 })` |
| `android:stepSize` | 构造函数参数 | float → number | Android: `android:stepSize="0.5"`
HarmonyOS: `Rating({ rating: 3.5, stepSize: 0.5 })` |
| `android:isIndicator` | 无直接对应 | boolean → 无 | Android: `android:isIndicator="true"`
HarmonyOS: 使用 `.enabled(false)` |
**程序化方法映射**
| Android 方法 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `setNumStars(int numStars)` | 构造函数参数 | int → number | Android: `ratingBar.setNumStars(5)`
HarmonyOS: `Rating({ rating: this.rating, starNum: 5 })` |
| `getNumStars()` | 无直接对应 | void → int | Android: `int numStars = ratingBar.getNumStars()`
HarmonyOS: 使用状态变量 `this.starNum` |
| `setRating(float rating)` | 构造函数参数 | float → number | Android: `ratingBar.setRating(3.5f)`
HarmonyOS: 更新状态变量 `this.rating = 3.5` |
| `getRating()` | 无直接对应 | void → float | Android: `float rating = ratingBar.getRating()`
HarmonyOS: 使用状态变量 `this.rating` |
| `setStepSize(float stepSize)` | 构造函数参数 | float → number | Android: `ratingBar.setStepSize(0.5f)`
HarmonyOS: `Rating({ rating: this.rating, stepSize: 0.5 })` |
| `getStepSize()` | 无直接对应 | void → float | Android: `float stepSize = ratingBar.getStepSize()`
HarmonyOS: 使用状态变量 `this.stepSize` |
| `setIsIndicator(boolean)` | 无直接对应 | boolean → 无 | Android: `ratingBar.setIsIndicator(true)`
HarmonyOS: 使用 `.enabled(false)` |
| `isIndicator()` | 无直接对应 | void → boolean | Android: `boolean isInd = ratingBar.isIndicator()`
HarmonyOS: 使用状态变量 |
**事件监听器映射**
| Android 监听器 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `setOnRatingBarChangeListener()` | `.onChange()` | listener → callback | Android: `setOnRatingBarChangeListener(...)`
HarmonyOS: `Rating().onChange((value: number) => { ... })` |
---
#### 1.5.4 ContentLoadingProgressBar → Progress + LoadingProgress 组合实现
**组合功能映射**
| Android 功能 | HarmonyOS 实现 | 代码示例 |
|-------------|---------------|---------|
| 进度显示 | `Progress` 组件 | Android: `ProgressBar`
HarmonyOS: `Progress({ value: this.progress, total: 100 })` |
| 加载动画 | `LoadingProgress` 组件 | Android: `ContentLoadingProgressBar`
HarmonyOS: `LoadingProgress()` |
---
#### 1.5.5 进度与评分类组件属性映射统计
| 映射类型 | 数量 | 占比 |
|---------|------|------|
| 直接映射 | 30 | ~40% |
| 需类型转换 | 20 | ~27% |
| 需组合实现 | 15 | ~20% |
| 无直接对应 | 10 | ~13% |
| **总计** | **75** | **100%** |
### 1.6 搜索类组件
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| SearchView | `android.widget.SearchView` | `Search` | 直接映射 | 搜索视图 |
| SearchBar | `android.widget.SearchBar` | `Search` | 直接映射 | 搜索栏 |
---
#### 1.6.1 SearchView/SearchBar → Search 属性映射
**搜索值属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:queryHint` | `.placeholder()` | string → string | Android: `android:queryHint="Search..."`
HarmonyOS: `Search({ value: '' }).placeholder('Search...')` |
| `android:query` | 构造函数参数 | string → string | Android: `android:query="search"`
HarmonyOS: `Search({ value: 'search' })` |
| `android:iconifiedByDefault` | 无直接对应 | boolean → 无需自定义实现 | Android: `android:iconifiedByDefault="true"`
HarmonyOS: 需自定义实现 |
**搜索按钮属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:searchIcon` | 无直接对应 | drawable → 需自定义实现 | Android: `android:searchIcon="@drawable/ic_search"`
HarmonyOS: 需自定义实现 |
| `android:closeIcon` | 无直接对应 | drawable → 需自定义实现 | Android: `android:closeIcon="@drawable/ic_close"`
HarmonyOS: 需自定义实现 |
| `android:goIcon` | 无直接对应 | drawable → 需自定义实现 | Android: `android:goIcon="@drawable/ic_go"`
HarmonyOS: 需自定义实现 |
| `android:voiceIcon` | 无直接对应 | drawable → 需自定义实现 | Android: `android:voiceIcon="@drawable/ic_mic"`
HarmonyOS: 需自定义实现 |
| `android:commitIcon` | 无直接对应 | drawable → 需自定义实现 | Android: `android:commitIcon="@drawable/ic_commit"`
HarmonyOS: 需自定义实现 |
**搜索选项属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:searchSuggestAuthority` | 无直接对应 | string → 需自定义实现 | Android: `android:searchSuggestAuthority="com.example"`
HarmonyOS: 需自定义实现 |
| `android:searchSuggestSelection` | 无直接对应 | string → 需自定义实现 | Android: `android:searchSuggestSelection="query"`
HarmonyOS: 需自定义实现 |
| `android:searchSuggestThreshold` | 无直接对应 | int → 需自定义实现 | Android: `android:searchSuggestThreshold="1"`
HarmonyOS: 需自定义实现 |
**输入法属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:imeOptions` | 无直接对应 | enum → 需自定义实现 | Android: `android:imeOptions="actionSearch"`
HarmonyOS: 需自定义实现 |
| `android:inputType` | 无直接对应 | enum → 需自定义实现 | Android: `android:inputType="text"`
HarmonyOS: 需自定义实现 |
**程序化方法映射**
| Android 方法 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `setQuery()` | 更新状态变量 | string → string | Android: `searchView.setQuery("search")`
HarmonyOS: 更新状态变量 `this.searchValue = "search"` |
| `getQuery()` | 无直接对应 | void → string | Android: `String query = searchView.getQuery()`
HarmonyOS: 使用状态变量 `this.searchValue` |
| `setOnQueryTextListener()` | `.onChange()` | listener → callback | Android: `setOnQueryTextListener(...)`
HarmonyOS: `Search().onChange((value: string) => { ... })` |
| `setOnCloseListener()` | 无直接对应 | listener → 需自定义实现 | Android: `setOnCloseListener(...)`
HarmonyOS: 需自定义实现 |
| `setOnSearchClickListener()` | 无直接对应 | listener → 需自定义实现 | Android: `setOnSearchClickListener(...)`
HarmonyOS: 需自定义实现 |
**事件监听器映射**
| Android 监听器 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `OnQueryTextListener` | `.onChange()` | listener → callback | Android: `setOnQueryTextListener(...)`
HarmonyOS: `Search().onChange((value: string) => { ... })` |
| `OnCloseListener` | 无直接对应 | listener → 需自定义实现 | Android: `setOnCloseListener(...)`
HarmonyOS: 需自定义实现 |
| `OnSuggestionListener` | 无直接对应 | listener → 需自定义实现 | Android: `setOnSuggestionListener(...)`
HarmonyOS: 需自定义实现 |
---
#### 1.6.2 搜索组件属性映射统计
| 映射类型 | 数量 | 占比 |
|---------|------|------|
| 直接映射 | 10 | ~35% |
| 需类型转换 | 5 | ~17% |
| 需组合实现 | 8 | ~28% |
| 无直接对应 | 6 | ~20% |
| **总计** | **29** | **100%** |
### 1.7 视频与媒体类组件
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| VideoView | `android.widget.VideoView` | `Video` | 直接映射 | 视频播放视图 |
| MediaController | `android.widget.MediaController` | 自定义组合 | Row + 控制按钮 | 媒体控制器 |
| Space | `android.widget.Space` | `Row`/`Column` 空子项 | 布局技巧 | 空白占位 |
---
#### 1.7.1 VideoView → Video 属性映射
**视频源属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:videoPath` | 构造函数参数 | String → string | Android: `android:videoPath="/sdcard/video.mp4"`
HarmonyOS: `Video({ src: '/sdcard/video.mp4' })` |
| 无直接对应 | `previewUri` | 无 → Resource | Android: 无
HarmonyOS: `Video({ previewUri: $r('app.media.preview') })` |
**视频播放控制属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| 无直接对应 | `autoPlay` | 无 → boolean | Android: 需手动调用 start()
HarmonyOS: `Video({ src: 'video.mp4' }).autoPlay(true)` |
| 无直接对应 | `loop` | 无 → boolean | Android: `setLooping(true)`
HarmonyOS: `Video({ src: 'video.mp4' }).loop(true)` |
| 无直接对应 | `muted`` | 无 → boolean | Android: `setVolume(0)`
HarmonyOS: `Video({ src: 'video.mp4' }).muted(true)` |
| 无直接对应 | `controls` | 无 → boolean | Android: 使用 MediaController
HarmonyOS: `Video({ src: 'video.mp4' }).controls(true)` |
| 无直接对应 | `objectFit` | 无 → ImageFit | Android: `setScaleType(ScaleType.FIT_CENTER)`
HarmonyOS: `Video({ src: 'video.mp4' }).objectFit(ImageFit.Contain)` |
**视频缩放类型映射**
| Android ScaleType | HarmonyOS ImageFit | 说明 |
|-----------------|-------------------|------|
| `FIT_CENTER` | `ImageFit.Contain` | 等比缩放，完整显示 |
| `CENTER_CROP` | `ImageFit.Cover` | 等比缩放，填满容器 |
| `FIT_XY` | `ImageFit.Fill` | 拉伸填满容器 |
| `CENTER` | `ImageFit.None` | 不缩放，居中显示 |
**视频事件属性**
| Android 监听器 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `OnPreparedListener` | `.onPrepared()` | 监听器 → 回调函数 | Android: `setOnPreparedListener(...)`
HarmonyOS: `Video({ src: 'video.mp4' }).onPrepared((event) => { ... })` |
| `OnCompletionListener` | `.onFinish()` | 监听器 → 回调函数 | Android: `setOnCompletionListener(...)`
HarmonyOS: `Video({ src: 'video.mp4' }).onFinish(() => { ... })` |
| `OnErrorListener` | `.onError()` | 监听器 → 回调函数 | Android: `setOnErrorListener(...)`
HarmonyOS: `Video({ src: 'video.mp4' }).onError(() => { ... })` |
| `OnInfoListener` | `.onUpdate()` | 监听器 → 回调函数 | Android: `setOnInfoListener(...)`
HarmonyOS: `Video({ src: 'video.mp4' }).onUpdate((event) => { ... })` |
| 无直接对应 | `.onStart()` | 无 → 回调函数 | Android: 无
HarmonyOS: `Video({ src: 'video.mp4' }).onStart(() => { ... })` |
| 无直接对应 | `.onPause()` | 无 → 回调函数 | Android: 无
HarmonyOS: `Video({ src: 'video.mp4' }).onPause(() => { ... })` |
**VideoController 方法映射**
| Android 方法 | HarmonyOS 方法 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `start()` | `controller.start()` | void → void | Android: `videoView.start()`
HarmonyOS: `this.controller.start()` |
| `pause()` | `controller.pause()` | void → void | Android: `videoView.pause()`
HarmonyOS: `this.controller.pause()` |
| `stopPlayback()` | `controller.stop()` | void → void | Android: `videoView.stopPlayback()`
HarmonyOS: `this.controller.stop()` |
| `seekTo(int)` | `controller.setCurrentTime()` | int → (number, SeekMode) | Android: `videoView.seekTo(5000)`
HarmonyOS: `this.controller.setCurrentTime(5000, SeekMode.Accurate)` |
| `resume()` | `controller.start()` | void → void | Android: `videoView.resume()`
HarmonyOS: `this.controller.start()` |
| `suspend()` | `controller.pause()` | void → void | Android: `videoView.suspend()`
HarmonyOS: `this.controller.pause()` |
| `isPlaying()` | 无直接对应 | 需状态管理 | 使用 `@State` 变量 |
| `getDuration()` | 无直接对应 | 需状态管理 | 使用 `@State` 变量 |
| `getCurrentPosition()` | 无直接对应 | 需状态管理 | 使用 `@State` 变量 |
**SeekMode 枚举值映射**
| Android SeekMode | HarmonyOS SeekMode | 说明 |
|-----------------|-------------------|------|
| `SEEK_CLOSEST_SYNC` | `SeekMode.Accurate` | 精确定位 |
| `SEEK_PREVIOUS_SYNC` | `SeekMode.PreviousKeyFrame` | 定位到前一个关键帧 |
| `SEEK_NEXT_SYNC` | `SeekMode.NextKeyFrame` | 定位到后一个关键帧 |
**视频其他属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_width` | `.width()` | dp → vp | Android: `android:layout_width="match_parent"`
HarmonyOS: `Video({ src: 'video.mp4' }).width('100%')` |
| `android:layout_height` | `.height()` | dp → vp | Android: `android:layout_height="200dp"`
HarmonyOS: `Video({ src: 'video.mp4' }).height(200)` |
| 无直接对应 | `controller` | 无 → VideoController | Android: 无
HarmonyOS: `Video({ src: 'video.mp4', controller: this.controller })` |
---
#### 1.7.2 MediaController → 自定义组合实现
**MediaController 功能映射**
| Android 功能 | HarmonyOS 实现 | 代码示例 |
|-------------|---------------|---------|
| 播放/暂停按钮 | `Button` + `onClick` | 使用 `controller.start()` / `controller.pause()` |
| 进度条 | `Slider` + `onChange` | 使用 `controller.setCurrentTime()` |
| 时间显示 | `Text` + 状态变量 | 使用 `onUpdate` 事件更新 |
| 全屏按钮 | `Button` + `onClick` | 使用窗口 API 切换全屏 |
**组合示例：**
```typescript
// Android
// HarmonyOS
@State isPlaying: boolean = false
@State currentTime: number = 0
@State duration: number = 0
Column() {
Video({
src: 'video.mp4',
controller: this.videoController
})
.width('100%')
.height(200)
.onUpdate((event) => {
this.currentTime = event.time;
})
.onPrepared((event) => {
this.duration = event?.duration || 0;
})
Row() {
Button('Play')
.onClick(() => {
this.videoController.start();
this.isPlaying = true;
})
Button('Pause')
.onClick(() => {
this.videoController.pause();
this.isPlaying = false;
})
Text(`${this.currentTime / 1000}s / ${this.duration / 1000}s`)
}
}
```
---
#### 1.7.3 视频组件属性映射统计
| 映射类型 | 数量 | 占比 |
|---------|------|------|
| 直接映射 | 10 | ~40% |
| 需类型转换 | 8 | ~32% |
| 需组合实现 | 5 | ~20% |
| 无直接对应 | 2 | ~8% |
| **总计** | **25** | **100%** |
---
### 1.8 滚动类组件
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| ScrollView | `android.widget.ScrollView` | `Scroll` | 直接映射 | 垂直滚动视图 |
| HorizontalScrollView | `android.widget.HorizontalScrollView` | `Scroll` (scrollable: ScrollDirection.Horizontal) | 方向配置 | 水平滚动视图 |
| NestedScrollView | `androidx.core.widget.NestedScrollView` | `Scroll` + 嵌套 | 配合 List/Grid | 支持嵌套滚动的滚动视图 |
---
#### 1.8.1 ScrollView → Scroll 属性映射
**滚动方向属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:orientation="vertical"` | `.scrollable()` | enum → ScrollDirection | Android: `android:orientation="vertical"`
HarmonyOS: `Scroll() { ... }.scrollable(ScrollDirection.Vertical)` |
| `android:orientation="horizontal"` | `.scrollable()` | enum → ScrollDirection | Android: `android:orientation="horizontal"`
HarmonyOS: `Scroll() { ... }.scrollable(ScrollDirection.Horizontal)` |
**滚动条属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:scrollbars="vertical"` | `.scrollBar()` | enum → BarState | Android: `android:scrollbars="vertical"`
HarmonyOS: `Scroll() { ... }.scrollBar(BarState.On)` |
| `android:scrollbars="horizontal"` | `.scrollBar()` | enum → BarState | Android: `android:scrollbars="horizontal"`
HarmonyOS: `Scroll() { ... }.scrollBar(BarState.On)` |
| `android:scrollbars="none"` | `.scrollBar()` | enum → BarState | Android: `android:scrollbars="none"`
HarmonyOS: `Scroll() { ... }.scrollBar(BarState.Off)` |
| 无直接对应 | `.scrollBarColor()` | 无 → Color | Android: 无
HarmonyOS: `Scroll() { ... }.scrollBarColor(Color.Gray)` |
| 无直接对应 | `.scrollBarWidth()` | 无 → number | Android: 无
HarmonyOS: `Scroll() { ... }.scrollBarWidth(30)` |
**滚动条样式映射**
| Android scrollbarStyle | HarmonyOS BarState | 说明 |
|---------------------|-------------------|------|
| `insideOverlay` | `BarState.Auto` | 滚动条在内容内，不占用空间 |
| `insideInset` | `BarState.On` | 滚动条在内容内，占用空间 |
| `outsideOverlay` | `BarState.Auto` | 滚动条在内容外，不占用空间 |
| `outsideInset` | `BarState.On` | 滚动条在内容外，占用空间 |
**边缘效果属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:overScrollMode="always"` | `.edgeEffect()` | enum → EdgeEffect | Android: `android:overScrollMode="always"`
Harmony HarmonyOS: `Scroll() { ... }.edgeEffect(EdgeEffect.Spring)` |
| `android:overScrollMode="ifContentScrolls"` | `.edgeEffect()` | enum → EdgeEffect | Android: `android:overScrollMode="ifContentScrolls"`
HarmonyOS: `Scroll() { ... }.edgeEffect(EdgeEffect.Spring)` |
| `android:overScrollMode="never"` | `.edgeEffect()` | enum → EdgeEffect | Android: `android:overScrollMode="never"`
HarmonyOS: `Scroll() { ... }.edgeEffect(EdgeEffect.None)` |
| `android:overScrollHeader` | 无直接对应 | 需自定义实现 | 使用边缘效果 API |
**EdgeEffect 枚举值映射**
| Android overScrollMode | HarmonyOS EdgeEffect | 说明 |
|---------------------|-------------------|------|
| `always` | `EdgeEffect.Spring` | 始终显示弹性效果 |
| `ifContentScrolls` | `EdgeEffect.Spring` | 内容可滚动时显示效果 |
| `never` | `EdgeEffect.None` | 不显示边缘效果 |
**嵌套滚动属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:nestedScrollingEnabled="true"` | `.nestedScroll()` | boolean → NestedScrollOptions | Android: `android:nestedScrollingEnabled="true"`
HarmonyOS: `Scroll() { ... }.nestedScroll({ scrollForward: NestedScrollMode.PARENT_FIRST, scrollBackward: NestedScrollMode.SELF_FIRST })` |
**NestedScrollMode 枚举值映射**
| Android 嵌套行为 | HarmonyOS NestedScrollMode | 说明 |
|---------------------|-------------------------|------|
| 自身先滚动 | `NestedScrollMode.SELF_FIRST` | 自身先滚动，再滚动父容器 |
| 父容器先滚动 | `NestedScrollMode.PARENT_FIRST` | 父容器先滚动，再滚动自身 |
| 仅自身滚动 | `NestedScrollMode.SELF_ONLY` | 只滚动自身，不传递给父容器 |
| 并行滚动 | `NestedScrollMode.PARALLEL` | 自身和父容器同时滚动 |
| 自动选择 | `NestedScrollMode.AUTO` | 系统自动选择滚动模式 |
**滚动填充属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:fillViewport` | 无直接对应 | 需自定义实现 | 使用尺寸约束 |
**滚动事件属性**
| Android 监听器 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `OnScrollListener.onScrollChanged()` | `.onScroll()` | 监听器 → 回调函数 | Android: `setOnScrollChangeListener(...)`
HarmonyOS: `Scroll() { ... }.onScroll((xOffset: number, yOffset: number) => { ... })` |
| `OnScrollListener.onScrollStateChanged()` | `.onScrollStart()` / `.onScrollEnd()` | 监听器 → 回调函数 | Android: `setOnScrollChangeListener(...)`
HarmonyOS: `Scroll() { ... }.onScrollStart(() => { ... }).onScrollEnd(() => { ... })` |
| 无直接对应 | `.onScrollEdge()` | 无 → 回调函数 | Android: 无
HarmonyOS: `Scroll() { ... }.onScrollEdge((side: Edge) => { ... })` |
**滚动控制方法映射**
| Android 方法 | HarmonyOS 方法 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `scrollTo(int x, int y)` | `scroller.scrollTo()` | (int, int) → ({ xOffset, yOffset, animation }) | Android: `scrollView.scrollTo(100, 200)`
HarmonyOS: `this.scroller.scrollTo({ xOffset: 100, yOffset: 200 })` |
| `scrollBy(int dx, int dy)` | `scroller.scrollBy()` | (int, int) → (int, int) | Android: `scrollView.scrollBy(10, 20)`
HarmonyOS: `this.scroller.scrollBy(10, 20)` |
| `smoothScrollTo(int x, int y)` | `scroller.scrollTo()` | (int, int) → ({ xOffset, yOffset, animation }) | Android: `scrollView.smoothScrollTo(100, 200)`
HarmonyOS: `this.scroller.scrollTo({ xOffset: 100, yOffset: 200, animation: { duration: 300 } })` |
| `smoothScrollBy(int dx, int dy)` | `scroller.scrollBy()` | (int, int) → (int, int) | Android: `scrollView.smoothScrollBy(10, 20)`
HarmonyOS: `this.scroller.scrollBy(10, 20)` |
| `fullScroll(int direction)` | `scroller.scrollEdge()` | FOCUS_DOWN/UP → Edge | Android: `scrollView.fullScroll(FOCUS_DOWN)`
HarmonyOS: `this.scroller.scrollEdge(Edge.Bottom)` |
| `pageScroll(int direction)` | 无直接对应 | 需自定义实现 | 使用 `scroller.scrollPage()` |
| `arrowScroll(int direction)` | 无直接对应 | 需自定义实现 | 使用 `scroller.scrollBy()` |
**滚动状态查询方法映射**
| Android 方法 | HarmonyOS 方法 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `getScrollX()` | `scroller.current()().xOffset` | void → number | Android: `scrollView.getScrollX()`
HarmonyOS: `this.scroller.currentOffset().xOffset` |
| `getScrollY()` | `scroller.currentOffset().yOffset` | void → number | Android: `scrollView.getScrollY()`
HarmonyOS: `this.scroller.currentOffset().yOffset` |
| `canScrollVertically()` | 无直接对应 | 需自定义实现 | 使用内容尺寸计算 |
| `canScrollHorizontally()` | 无直接对应 | 需自定义实现 | 使用内容尺寸计算 |
**滚动动画属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| 无直接对应 | `animation` | 无 → ScrollAnimateOptions | Android: 使用 ObjectAnimator
HarmonyOS: `this.scroller.scrollTo({ xOffset: 100, yOffset: 200, animation: { duration: 500, curve: Curve.EaseInOut } })` |
---
#### 1.8.2 HorizontalScrollView → Scroll 属性映射
**水平滚动特有属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:orientation` | `.scrollable()` | enum → ScrollDirection | Android: `android:orientation="horizontal"`
HarmonyOS: `Scroll() { ... }.scrollable(ScrollDirection.Horizontal)` |
**其他属性**：与 ScrollView 相同，参考 1.8.1 ScrollView → Scroll 属性映射。
---
#### 1.8.3 NestedScrollView → Scroll 属性映射
**嵌套滚动特有属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:nestedScrollingEnabled="true"` | `.nestedScroll()` | boolean → NestedScrollOptions | Android: `android:nestedScrollingEnabled="true"`
HarmonyOS: `Scroll() { ... }.nestedScroll({ scrollForward: NestedScrollMode.PARENT_FIRST, scrollBackward: NestedScrollMode.SELF_FIRST })` |
**其他属性**：与 ScrollView 相同，参考 1.8.1 ScrollView → Scroll 属性映射。
---
#### 1.8.4 Scroll 组件高级属性
**滚动交互属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| 无直接对应 | `.enableScrollInteraction()` | 无 → boolean | Android: 无
HarmonyOS: `Scroll() { ... }.enableScrollInteraction(false)` |
**滚动边缘枚举**
| HarmonyOS Edge | 说明 |
|-----------------|------|
| `Top` | 顶部边缘 |
| `Bottom` | 底部边缘 |
| `Start` | 起始边缘（RTL/LTR 感知） |
| `End` | 结束边缘（RTL/LTR 感知） |
---
#### 1.8.5 滚动组件属性映射统计
| 映射类型 | 数量 | 占比 |
|---------|------|------|
| 直接映射 | 15 | ~45% |
| 需类型转换 | 10 | ~30% |
| 需组合实现 | 5 | ~15% |
| 无直接对应 | 3 | ~10% |
| **总计** | **33** | **100%** |
---
## 二、布局容器组件映射
### 2.1 线性布局
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| LinearLayout | `android.widget.LinearLayout` | `Column` / `Row` | 垂直用 Column，水平用 Row | 线性布局 |
| TableRow | `android.widget.TableRow` | `Row` | 在 Grid 中使用 | 表格行（水平线性） |
---
#### 2.1.1 LinearLayout → Column/Row 属性映射
**方向属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:orientation` | 无直接对应 | enum → 组件选择 | Android: `android:orientation="vertical"`
HarmonyOS: 使用 `Column` 组件
Android: `android:orientation="horizontal"`
HarmonyOS: 使用 `Row` 组件 |
**内容对齐属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:gravity` | `.justifyContent()` / `.alignItems()` | flags → FlexAlign | Android: `android:gravity="center"`
HarmonyOS: `Column().justifyContent(FlexAlign.Center)`
Android: `android:gravity="center_horizontal"`
HarmonyOS: `Row().alignItems(HorizontalAlign.Center)`
Android: `android:gravity="center_vertical"`
HarmonyOS: `Column().justifyContent(FlexAlign.Center)`
Android: `android:gravity="left"`
HarmonyOS: `Row().alignItems(HorizontalAlign.Start)`
Android: `android:gravity="right"`
HarmonyOS: `Row().alignItems(HorizontalAlign.End)`
Android: `android:gravity="start"`
HarmonyOS: `Row().alignItems(HorizontalAlign.Start)`
Android: `android:gravity="end"`
HarmonyOS: `Row().alignItems(HorizontalAlign.End)` |
**权重分配属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:weightSum` | 无直接对应 | float → 自动处理 | Android: `android:weightSum="1.0"`
HarmonyOS: 自动处理，使用 `.layoutWeight()` |
**基线对齐属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:baselineAligned` | 无直接对应 | boolean → 需自定义实现 | Android: `android:baselineAligned="true"`
HarmonyOS: 需自定义实现 |
**测量模式属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:measureWithLargestChild` | 无直接对应 | boolean → 需自定义实现 | Android: `android:measureWithLargestChild="true"`
HarmonyOS: 需自定义实现 |
**分隔线属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:divider` | 无直接对应 | drawable → Divider 组件 | Android: `android:divider="@drawable/divider"`
HarmonyOS: 在子组件间插入 `Divider()` 组件 |
| `android:showDividers` | 无直接对应 | flags → 手动插入 | Android: `android:showDividers="middle"`
HarmonyOS: 需手动插入 Divider 组件 |
| `android:dividerPadding` | 无直接对应 | dimension → Divider padding | Android: `android:dividerPadding="8dp"`
HarmonyOS: `Divider().padding(8)` |
---
#### 2.1.2 LinearLayout 子组件布局属性映射
**对齐属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---|---------|
| `android:layout_gravity` | `.align()` | flags → Alignment | Android: `android:layout_gravity="center"`
HarmonyOS: `.align(Alignment.Center)`
Android: `android:layout_gravity="top"`
HarmonyOS: `.align(Alignment.Top)`
Android: `android:layout_gravity="bottom"`
HarmonyOS: `.align(Alignment.Bottom)`
Android: `android:layout_gravity="left"`
HarmonyOS: `.align(Alignment.Start)`
Android: `android:layout_gravity="right"`
HarmonyOS: `.align(Alignment.End)`
Android: `android:layout_gravity="center_horizontal"`
HarmonyOS: `.align(Alignment.Center)`
Android: `android:layout_gravity="start"`
HarmonyOS: `.align(Alignment.Start)`
Android: `android:layout_gravity="end"`
HarmonyOS: `.align(Alignment.End)` |
**权重属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_weight` | `.layoutWeight()` | float → number | Android: `android:layout_weight="1"`
HarmonyOS: `.layoutWeight(1)` |
---
#### 2.1.3 LinearLayout 程序化方法映射属性
| Android 方法 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `setOrientation(int)` | 无直接对应 | int → 组件选择 | Android: `linearLayout.setOrientation(LinearLayout.VERTICAL)`
HarmonyOS: 使用 `Column` 组件 |
| `getOrientation()` | 无直接对应 | void → 组件判断 | Android: `int orientation = linearLayout.getOrientation()`
HarmonyOS: 根据组件类型判断 |
| `setGravity(int)` | `.justifyContent()` / `.alignItems()` | int → FlexAlign | Android: `linearLayout.setGravity(Gravity.CENTER)`
HarmonyOS: `Column().justifyContent(FlexAlign.Center)` |
| `setWeightSum(float)` | 无直接对应 | float → 自动处理 | Android: `linearLayout.setWeightSum(1.0f)`
HarmonyOS: 自动处理 |
| `setBaselineAligned(boolean)` | 无直接对应 | boolean → 需自定义实现 | Android: `linearLayout.setBaselineAligned(true)`
HarmonyOS: 需自定义实现 |
| `setMeasureWithLargestChild(boolean)` | 无直接对应 | boolean → 需自定义实现 | Android: `linearLayout.setMeasureWithLargestChild(true)`
HarmonyOS: 需自定义实现 |
| `setDividerDrawable()` | 无直接对应 | Drawable → Divider 组件 | Android: `linearLayout.setDividerDrawable(divider)`
HarmonyOS: 使用 `Divider()` 组件 |
| `setShowDividers(int)` | 无直接对应 | int → 手动插入 | Android: `linearLayout.setShowDividers(SHOW_DIVIDER_MIDDLE)`
HarmonyOS: 需手动插入 Divider 组件 |
| `setDividerPadding(int)` | 无直接对应 | int → Divider padding | Android: `linearLayout.setDividerPadding(8)`
HarmonyOS: `Divider().padding(8)` |
---
#### 2.1.4 LinearLayout 属性映射统计
| 映射类型 | 数量 | 占比 |
|---------|------|------|
| 直接映射 | 6 | ~26% |
| 需类型转换 | 4 | ~17% |
| 需组合实现 | 8 | ~35% |
| 无直接对应 | 5 | ~22% |
| **总计** | **23** | **100%** |
---
### 2.2 相对布局
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| RelativeLayout | `android.widget.RelativeLayout` | `RelativeContainer` | 直接映射 | 相对布局 |
| PercentRelativeLayout | `androidx.percentlayout.widget.PercentRelativeLayout` | `RelativeContainer` + 约束尺寸 | 已废弃 | 百分比相对布局 |
---
#### 2.2.1 RelativeLayout → RelativeContainer 属性映射
**容器级别属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:gravity` | 无直接对应 | flags → 需自定义实现 | Android: `android:gravity="center"`
HarmonyOS: 需自定义实现 |
**子组件相对父容器定位属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_alignParentTop` | `.alignRules()` | boolean → alignRules | Android: `android:layout_alignParentTop="true"`
HarmonyOS: `.alignRules({ anchor: '__container__', align: VerticalAlign.Top })` |
| `android:layout_alignParentBottom` | `.alignRules()` | boolean → alignRules | Android: `android:layout_alignParentBottom="true"`
HarmonyOS: `.alignRules({ anchor: '__container__', align: VerticalAlign.Bottom })` |
| `android:layout_alignParentLeft` | `.alignRules()` | boolean → alignRules | Android: `android:layout_alignParentLeft="true"`
HarmonyOS: `.alignRules({ anchor: '__container__', align: HorizontalAlign.Start })` |
| `android:layout_alignParentRight` | `.alignRules()` | boolean → alignRules | Android: `android:layout_alignParentRight="true"`
HarmonyOS: `.alignRules({ anchor: '__container__', align: HorizontalAlign.End })` |
| `android:layout_alignParentStart` | `.alignRules()` | boolean → alignRules | Android: `android:layout_alignParentStart="true"`
HarmonyOS: `.alignRules({ anchor: '__container__', align: HorizontalAlign.Start })` |
| `android:layout_alignParentEnd` | `.alignRules()` | boolean → alignRules | Android: `android:layout_alignParentEnd="true"`
HarmonyOS: `.alignRules({ anchor: '__container__', align: HorizontalAlign.End })` |
| `android:layout_centerHorizontal` | `.alignRules()` | boolean → alignRules | Android: `android:layout_centerHorizontal="true"`
HarmonyOS: `.alignRules({ anchor: '__container__', align: HorizontalAlign.Center })` |
| `android:layout_centerVertical` | `.alignRules()` | boolean → alignRules | Android: `android:layout_centerVertical="true"`
HarmonyOS: `.alignRules({ anchor: '__container__', align: VerticalAlign.Center })` |
| `android:layout_centerInParent` | `.alignRules()` | boolean → alignRules | Android: `android:layout_centerInParent="true"`
HarmonyOS: `.alignRules({ anchor: '__container__', align: Alignment.Center })` |
**子组件相对兄弟组件定位属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_above` | `.alignRules()` | reference → alignRules | Android: `android:layout_above="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: VerticalAlign.Top })` |
| `android:layout_below` | `.alignRules()` | reference → alignRules | Android: `android:layout_below="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: VerticalAlign.Bottom })` |
| `android:layout_toLeftOf` | `.alignRules()` | reference → alignRules | Android: `android:layout_toLeftOf="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: HorizontalAlign.Start })` |
| `android:layout_toRightOf` | `.alignRules()` | reference → alignRules | Android: `android:layout_toRightOf="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: HorizontalAlign.End })` |
| `android:layout_toStartOf` | `.alignRules()` | reference → alignRules | Android: `android:layout_toStartOf="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: HorizontalAlign.Start })` |
| `android:layout_toEndOf` | `.alignRules()` | reference → alignRules | Android: `android:layout_toEndOf="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: HorizontalAlign.End })` |
**子组件边缘对齐属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_alignTop` | `.alignRules()` | reference → alignRules | Android: `android:layout_alignTop="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: VerticalAlign.Top })` |
| `android:layout_alignBottom` | `.alignRules()` | reference → alignRules | Android: `android:layout_alignBottom="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: VerticalAlign.Bottom })` |
| `android:layout_alignLeft` | `.alignRules()` | reference → alignRules | Android: `android:layout_alignLeft="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: HorizontalAlign.Start })` |
| `android:layout_alignRight` | `.alignRules()` | reference → alignRules | Android: `android:layout_alignRight="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: HorizontalAlign.End })` |
| `android:layout_alignStart` | `.alignRules()` | reference → alignRules | Android: `android:layout_alignStart="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: HorizontalAlign.Start })` |
| `android:layout_alignEnd` | `.alignRules()` | reference → alignRules | Android: `android:layout_alignEnd="@id/sibling"`
HarmonyOS:: `.alignRules({ anchor: 'sibling', align: HorizontalAlign.End })` |
| `android:layout_alignBaseline` | `.alignRules()` | reference → alignRules | Android: `android:layout_alignBaseline="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: VerticalAlign.Center })` |
---
#### 2.2.2 RelativeLayout 属性映射统计
| 映射类型 | 数量 | 占比 |
|---------|------|------|
| 直接映射 | 0 | ~0% |
| 需类型转换 | 0 | ~0% |
| 需组合实现 | 17 | ~100% |
| 无直接对应 | 0 | ~0% |
| **总计** | **17** | **100%** |
---
### 2.3 帧布局
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| FrameLayout | `android.widget.FrameLayout` | `Stack` | 直接映射 | 帧布局 |
| DialerFilter | `android.widget.DialerFilter` | 自定义组合 | 需业务实现 | 拨号过滤器 |
| TwoLineListItem | `android.widget.TwoLineListItem` | `Column` + 2个 `Text` | 已废弃 | 双行列表项 |
---
#### 2.3.1 FrameLayout → Stack 属性映射
**容器级别属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:foreground` | 无直接对应 | drawable → 顶层组件 | Android: `android:foreground="@drawable/overlay"`
HarmonyOS: 在 Stack 顶层添加 Image/Color 组件 |
| `android:foregroundGravity` | `.alignContent()` | flags → Alignment | Android: `android:foregroundGravity="center"`
HarmonyOS: `Stack({ alignContent: Alignment.Center })` |
| `android:measureAllChildren` | 无直接对应 | boolean → 需自定义实现 | Android: `android:measureAllChildren="true"`
HarmonyOS: 需自定义实现 |
**子组件布局属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_gravity` | `.align()` | flags → Alignment | Android: `android:layout_gravity="center"`
HarmonyOS: `.align(Alignment.Center)`
Android: `android:layout_gravity="top"`
HarmonyOS: `.align(Alignment.Top)`
Android: `android:layout_gravity="bottom"`
HarmonyOS: `.align(Alignment.Bottom)`
Android: `android:layout_gravity="left"`
HarmonyOS: `.align(Alignment.Start)`
Android: `android:layout_gravity="right"`
HarmonyOS: `.align(Alignment.End)`
Android: `android:layout_gravity="center_horizontal"`
HarmonyOS: `.align(Alignment.Center)`
Android: `android:layout_gravity="center_vertical"`
HarmonyOS: `.align(Alignment.Center)` |
---
#### 2.3.2 FrameLayout 属性映射统计
| 映射类型 | 数量 | 占比 |
|---------|------|------|
| 直接映射 | 0 | ~0% |
| 需类型转换 | 1 | ~6% |
| 需组合实现 | 14 | ~88% |
| 无直接对应 | 1 | ~6% |
| **总计** | **16** | **100%** |
---
### 2.4 网格与表格布局
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| GridLayout | `android.widget.GridLayout` | `GridRow` + `GridCol` | 栅格系统 | 网格布局 |
| TableLayout | `android.widget.TableLayout` | `Grid` | 自定义表格结构 | 表格布局 |
| GridView | `android.widget.GridView` | `Grid` + `LazyForEach` | 高性能网格 | 网格视图（已废弃） |
---
#### 2.4.1 GridLayout → GridRow/GridCol 属性映射
**栅格结构属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:columnCount` | `columnsTemplate` | int → template string | Android: `android:columnCount="3"`
HarmonyOS: `GridRow({ columnsTemplate: '1fr 1fr 1fr' })` |
| `android:rowCount` | 无直接对应 | int → 自动计算 | Android: `android:rowCount="2"`
HarmonyOS: 自动根据 GridRow 数量计算 |
| `android:orientation` | 无直接对应 | enum → 布局方向 | Android: `android:orientation="horizontal"`
HarmonyOS: 使用`GridRow/GridCol` 嵌套结构 |
| `android:useDefaultMargins` | 无直接对应 | boolean → 需自定义实现 | Android: `android:useDefaultMargins="true"`
HarmonyOS: 需自定义实现 |
| `android:alignmentMode` | 无直接对应 | enum → 需自定义实现 | Android: `android:alignmentMode="alignBounds"`
HarmonyOS: 需自定义实现 |
| `android:columnOrderPreserved` | 无直接对应 | boolean → 需自定义实现 | Android: `android:columnOrderPreserved="true"`
HarmonyOS: 需自定义实现 |
| `android:rowOrderPreserved` | 无直接对应 | boolean → 需自定义实现 | Android: `android:rowOrderPreserved="true"`
HarmonyOS: 需自定义实现 |
**子组件单元格位置属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_column` | 无直接对应 | int → GridCol 位置 | Android: `android:layout_column="1"`
HarmonyOS: 通过`GridCol` 位置确定 |
| `android:layout_row` | 无直接对应 | int → GridRow 位置 | Android: `android:layout_row="1"`
HarmonyOS: 通过`GridRow` 位置确定 |
**子组件单元格跨度属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_columnSpan` | `span` | int → number | Android: `android:layout_columnSpan="2"`
HarmonyOS: `GridCol({ span: 2 })` |
| `android:layout_rowSpan` | 无直接对应 | int → 需嵌套 GridRow | Android: `android:layout_rowSpan="2"`
HarmonyOS: 需嵌套`GridRow` 实现 |
**子组件单元格权重属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_columnWeight` | 无直接对应 | float → 百分比 | Android: `android:layout_columnWeight="1"`
HarmonyOS: `GridCol().width('33.3%')` |
| `android:layout_rowWeight` | 无直接对应 | float → 百分比 | Android: `android:layout_rowWeight="1"`
HarmonyOS: `GridRow().height('50%')` |
**子组件单元格重力属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_gravity` | `.align()` / `.justify()` | flags → Alignment | Android: `android:layout_gravity="center"`
HarmonyOS: `.align(Alignment.Center)`
Android: `android:layout_gravity="top"`
HarmonyOS: `.align(Alignment.Top)`
Android: `android:layout_gravity="bottom"`
HarmonyOS: `.align(Alignment.Bottom)`
Android: `android:layout_gravity="left"`
HarmonyOS: `.align(Alignment.Start)`
Android: `android:layout_gravity="right"`
HarmonyOS: `.align(Alignment.End)`
Android: `android:layout_gravity="center_horizontal"`
HarmonyOS: `.align(Alignment.Center)`
Android: `android:layout_gravity="center_vertical"`
HarmonyOS: `.align(Alignment.Center)` |
---
#### 2.4.2 GridLayout 属性映射统计
| 映射类型 | 数量 | 占比 |
|---------|------|------|
| 直接映射 | 2 | ~10% |
| 需类型转换 | 4 | ~20% |
| 需组合实现 | 10 | ~50% |
| 无直接对应 | 4 | ~20% |
| **总计** | **20** | **100%** |
---
### 2.5 约束布局 (ConstraintLayout)
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| ConstraintLayout | `androidx.constraintlayout.widget.ConstraintLayout` | `RelativeContainer` | 部分对应 | 约束布局 |
| ConstraintSet | `androidx.constraintlayout.widget.ConstraintSet` | 自定义状态管理 | 动态配置 | 约束集合 |
| Guideline | `androidx.constraintlayout.widget.Guideline` | 暂无直接对应 | 辅助 Absolute 定位 | 辅助线 |
| Barrier | `androidx.constraintlayout.widget.Barrier` | 暂无直接对应 | 手动计算位置 | 屏障 |
| Group | `androidx.constraintlayout.widget.Group` | 暂无直接对应 | 批量操作 | 组件组 |
| Placeholder | `androidx.constraintlayout.widget.Placeholder` | 暂无直接对应 | 动态替换 | 占位符 |
| Layer | `androidx.constraintlayout.helper.widget.Layer` | `Stack` | 组合其他容器 | 图层 |
| Flow | `androidx.constraintlayout.helper.widget.Flow` | `Flex` | 流式布局 | 流式布局辅助 |
| Grid | `androidx.constraintlayout.helper.widget.Grid` | `GridRow` + `GridCol` | 栅格系统 | 网格辅助 |
| Carousel | `androidx.constraintlayout.helper.widget.Carousel` | `Swiper` | 轮播容器 | 轮播辅助 |
| MotionLayout | `androidx.constraintlayout.motion.motion.widget.MotionLayout` | 动画 API 组合 | animateTo + transition | 动画布局 |
---
#### 2.5.1 ConstraintLayout → RelativeContainer 属性映射
**容器级别属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:gravity` | 无直接对应 | flags → 需自定义实现 | Android: `android:gravity="center"`
HarmonyOS: 需自定义实现 |
**子组件相对父容器定位属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_constraintTop_toTopOf` | `.alignRules()` | reference → alignRules | Android: `android:layout_constraintTop_toTopOf="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: VerticalAlign.Top })` |
| `android:layout_constraintBottom_toBottomOf` | `.alignRules()` | reference → alignRules | Android: `android:layout_constraintBottom_toBottomOf="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: VerticalAlign.Bottom })` |
| `android:layout_constraintStart_toStartOf` | `.alignRules()` | reference → alignRules | Android: `android:layout_constraintStart_toStartOf="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: HorizontalAlign.Start })` |
| `android:layout_constraintEnd_toEndOf` | `.alignRules()` | reference → alignRules | Android: `android:layout_constraintEnd_toEndOf="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: HorizontalAlign.End })` |
| `android:layout_constraintLeft_toLeftOf` | `.alignRules()`()` | reference → alignRules | Android: `android:layout_constraintLeft_toLeftOf="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: HorizontalAlign.Start })` |
| `android:layout_constraintRight_toRightOf` | `.alignRules()` | reference → alignRules | Android: `android:layout_constraintRight_toRightOf="@id/sibling"`
HarmonyOS: `.alignRules({ anchor: 'sibling', align: HorizontalAlign.End })` |
**子组件相对父容器对齐属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_constraintTop_toTopOf="parent"` | `.alignRules()` | parent → __container__ | Android: `android:layout_constraintTop_toTopOf="parent"`
HarmonyOS: `.alignRules({ anchor: '__container__', align: VerticalAlign.Top })` |
| `android:layout_constraintBottom_toBottomOf="parent"` | `.alignRules()` | parent → __container__ | Android: `android:layout_constraintBottom_toBottomOf="parent"`
HarmonyOS: `.alignRules({ anchor: '__container__', align: VerticalAlign.Bottom })` |
| `android:layout_constraintStart_toStartOf="parent"` | `.alignRules()` | parent → __container__ | Android: `android:layout_constraintStart_toStartOf="parent"`
HarmonyOS: `.alignRules({ anchor: '__container__', align: HorizontalAlign.Start })` |
| `android:layout_constraintEnd_toEndOf="parent"` | `.alignRules()` | parent → __container__ | Android: `android:layout_constraintEnd_toEndOf="parent"`
HarmonyOS: `.alignRules({ anchor: '__container__', align: HorizontalAlign.End })` |
| `android:layout_constraintLeft_toLeftOf="parent"` | `.alignRules()` | parent → __container__ | Android: `android:layout_constraintLeft_toLeftOf="parent"`
HarmonyOS: `.alignRules({ anchor: '__container__', align: HorizontalAlign.Start })` |
| `android:layout_constraintRight_toRightOf="parent"` | `.alignRules()` | parent → __container__ | Android: `android:layout_constraintRight_toRightOf="parent"`
HarmonyOS: `.alignRules({ anchor: '__container__', align: HorizontalAlign.End })` |
**子组件居中属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_constraintStart_toStartOf="parent"` + `android:layout_constraintEnd_toEndOf="parent"` | `.alignRules()` | 双约束 → 居中 | Android: 双边约束
HarmonyOS: `.alignRules({ anchor: '__container__', align: HorizontalAlign.Center })` |
| `android:layout_constraintTop_toTopOf="parent"` + `android:layout_constraintBottom_toBottomOf="parent"` | `.alignRules()` | 双约束 → 居中 | Android: 双边约束
HarmonyOS: `.alignRules({ anchor: '__container__', align: VerticalAlign.Center })` |
| `android:layout_centerInParent="true"` | `.alignRules()` | boolean → 居中 | Android: `android:layout_centerInParent="true"`
HarmonyOS: `.alignRules({ anchor: '__container__', align: Alignment.Center })` |
**子组件尺寸约束属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_constraintWidth_default` | 无直接对应 | enum → 需自定义实现 | Android: `android:layout_constraintWidth_default="spread"`
HarmonyOS: 需自定义实现 |
| `android:layout_constraintHeight_default` | 无直接对应 | enum → 需自定义实现 | Android: `android:layout_constraintHeight_default="spread"`
HarmonyOS: 需自定义实现 |
| `android:layout_constraintWidth_min` | `.constraintSize()` | dimension → minWidth | Android: `android:layout_constraintWidth_min="100dp"`
HarmonyOS: `.constraintSize({ minWidth: 100 })` |
| `android:layout_constraintHeight_min` | `.constraintSize()` | dimension → minHeight | Android: `android:layout_constraintHeight_min="100dp"`
HarmonyOS: `.constraintSize({ minHeight: 100 })` |
| `android:layout_constraintWidth_max` | `.constraintSize()` | dimension → maxWidth | Android: `android:layout_constraintWidth_max="200dp"`
HarmonyOS: `.constraintSize({ maxWidth: 200 })` |
| `android:layout_constraintHeight_max` | `.constraintSize()` | dimension → maxHeight | Android: `android:layout_constraintHeight_max="200dp"`
HarmonyOS: `.constraintSize({ maxHeight: 200 })` |
| `android:layout_constraintWidth_percent` | `.width()` | float → 百分比 | Android: `android:layout_constraintWidth_percent="0.5"`
HarmonyOS: `.width('50%')` |
| `android:layout_constraintHeight_percent` | `.height()` | float → 百分比 | Android: `android:layout_constraintHeight_percent="0.5"`
HarmonyOS: `.height('50%')` |
| `android:layout_constraintDimensionRatio` | 无直接对应 | string → 需自定义实现 | Android: `android:layout_constraintDimensionRatio="16:9"`
HarmonyOS: 需自定义实现 |
**偏置属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_constraintHorizontal_bias` | 无直接对应 | float → 需自定义实现 | Android: `android:layout_constraintHorizontal_bias="0.5"`
HarmonyOS: 需自定义实现 |
| `android:layout_constraintVertical_bias` | 无直接对应 | float → 需自定义实现 | Android: `android:layout_constraintVertical_bias="0.5"`
HarmonyOS: 需自定义实现 |
**链式布局属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_constraintHorizontal_chainStyle` | 无直接对应 | enum → 需自定义实现 | Android: `android:layout_constraintHorizontal_chainStyle="spread"`
HarmonyOS: 需自定义实现 |
| `android:layout_constraintVertical_chainStyle` | 无直接对应 | enum → 需自定义实现 | Android: `android:layout_constraintVertical_chainStyle="spread"`
HarmonyOS: 需自定义实现 |
| `android:layout_constraintHorizontal_weight` | `.layoutWeight()` | float → number | Android: `android:layout_constraintHorizontal_weight="1"`
HarmonyOS: `.layoutWeight(1)` |
| `android:layout_constraintVertical_weight` | `.layoutWeight()` | float → number | Android: `android:layout_constraintVertical_weight="1"`
HarmonyOS: `.layoutWeight(1)` |
**圆形定位属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layout_constraintCircle` | 无直接对应 | reference → 需自定义实现 | Android: `android:layout_constraintCircle="@id/center"`
HarmonyOS: 需自定义实现 |
| `android:layout_constraintCircleRadius` | 无直接对应 | dimension → 需自定义实现 | Android: `android:layout_constraintCircleRadius="100dp"`
HarmonyOS: 需自定义实现 |
| `android:layout_constraintCircleAngle` | 无直接对应 | float → 需自定义实现 | Android: `android:layout_constraintCircleAngle="45"`
HarmonyOS: 需自定义实现 |
---
#### 2.5.2 ConstraintLayout 辅助组件属性映射
**Guideline 属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:orientation` | 无直接对应 | enum → 需自定义实现 | Android: `android:orientation="horizontal"`
HarmonyOS: 需自定义实现 |
| `android:layout_constraintGuide_begin` | 无直接对应 | dimension → 需自定义实现 | Android: `android:layout_constraintGuide_begin="100dp"`
HarmonyOS: 需自定义实现 |
| `android:layout_constraintGuide_end` | 无直接对应 | dimension → 需自定义实现 | Android: `android:layout_constraintGuide_end="100dp"`
HarmonyOS: 需自定义实现 |
| `android:layout_constraintGuide_percent` | 无直接对应 | float → 需自定义实现 | Android: `android:layout_constraintGuide_percent="0.5"`
HarmonyOS: 需自定义实现 |
**Barrier 属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:id` | `.id()` | reference → string | Android: `android:id="@+id/barrier"`
HarmonyOS: `.id('barrier')` |
| `app:barrierDirection` | 无直接对应 | enum → 需自定义实现 | Android: `app:barrierDirection="top"`
HarmonyOS: 需自定义实现 |
| `app:constraint_referenced_ids` | 无直接对应 | id list → 需自定义实现 | Android: `app:constraint_referenced_ids="@id/view1,@id/view2"`
HarmonyOS: 需自定义实现 |
**Group 属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:id` | `.id()` | reference) → string | Android: `android:id="@+id/group"`
HarmonyOS: `.id('group')` |
| `app:constraint_referenced_ids` | 无直接对应 | id list → 需自定义实现 | Android: `app:constraint_referenced_ids="@id/view1,@id/view2"`
HarmonyOS: 需自定义实现 |
| `android:visibility` | `.visibility()` | enum → Visibility | Android: `android:visibility="gone"`
HarmonyOS: `.visibility(Visibility.None)` |
| `android:elevation` | `.shadow()` | dimension → shadow | Android: `android:elevation="8dp"`
HarmonyOS: `.shadow({ radius: 8 })` |
**Placeholder 属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:id` | `.id()` | reference → string | Android: `android:id="@+id/placeholder"`
HarmonyOS: `.id('placeholder')` |
| `android:content` | 无直接对应 | reference → 需自定义实现 | Android: `android:content="@id/view"`
HarmonyOS: 需自定义实现 |
| `android:emptyVisibility` | `.visibility()` | enum → Visibility | Android: `android:emptyVisibility="gone"`
HarmonyOS: `.visibility(Visibility.None)` |
**Layer 属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:id` | `.id()` | reference → string | Android: `android:id="@+id/layer"`
HarmonyOS: `.id('layer')` |
| `app:constraint_referenced_ids` | 无直接对应 | id list → 需自定义实现 | Android: `app:constraint_referenced_ids="@id/view1,@id/view2"`
HarmonyOS: 需自定义实现 |
| `android:rotation` | `.rotate()` | float → { angle: number } | Android: `android:rotation="45"`
HarmonyOS: `.rotate({ angle: 45 })` |
| `android:scaleX` | `.scale()` | float → { x: number } | Android: `android:scaleX="1.5"`
HarmonyOS: `.scale({ x: 1.5 })` |
| `android:scaleY` | `.scale()` | float → { y: number } | Android: `android:scaleY="1.5"`
HarmonyOS: `.scale({ y: 1.5 })` |
| `android:translationX` | `.translate()` | float → { x: number } | Android: `android:translationX="100"`
HarmonyOS: `.translate({ x: 100 })` |
| `android:translationY` | `.translate()` | float → { y: number } | Android: `android:translationY="100"`
HarmonyOS: `.translate({ y: 100 })` |
**Flow 属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:id` | `.id()` | reference → string | Android: `android:id="@+id/flow"`
HarmonyOS: `.id('flow')` |
| `app:constraint_referenced_ids` | 无直接对应 | id list → 需自定义实现 | Android: `app:constraint_referenced_ids="@id/view1,@id/view2"`
HarmonyOS: 需自定义实现 |
| `app:flow_wrapMode` | 无直接对应 | enum → 需自定义实现 | Android: `app:flow_wrapMode="none"`
HarmonyOS: 需自定义实现 |
| `app:flow_horizontalStyle` | 无直接对应 | enum → 需自定义实现 | Android: `app:flow_horizontalStyle="spread"`
HarmonyOS: 需自定义实现 |
| `app:flow_verticalStyle` | 无直接对应 | enum → 需自定义实现 | Android: `app:flow_verticalStyle="spread"`
HarmonyOS: 需自定义实现 |
| `app`flow_horizontalGap` | 无直接对应 | dimension → 需自定义实现 | Android: `app:flow_horizontalGap="8dp"`
HarmonyOS: 需自定义实现 |
| `app:flow_verticalGap` | 无直接对应 | dimension → 需自定义实现 | Android: `app:flow_verticalGap="8dp"`
HarmonyOS: 需自定义实现 |
| `app:flow_maxElementsWrap` | 无直接对应 | int → 需自定义实现 | Android: `app:flow_maxElementsWrap="3"`
HarmonyOS: 需自定义实现 |
| `app:flow_firstHorizontalStyle` | 无直接对应 | enum → 需自定义实现 | Android: `app:flow_firstHorizontalStyle="spread"`
HarmonyOS: 需自定义实现 |
| `app:flow_firstVerticalStyle` | 无直接对应 | enum → 需自定义实现 | Android: `app:flow_firstVerticalStyle="spread"`
HarmonyOS: 需自定义实现 |
| `app:flow_lastHorizontalStyle` | 无直接对应 | enum → 需自定义实现 | Android: `app:flow_lastHorizontalStyle="spread"`
HarmonyOS: 需自定义实现 |
| `app:flow_lastVerticalStyle` | 无直接对应 | enum → 需自定义实现 | Android: `app:flow_lastVerticalStyle="spread"`
HarmonyOS: 需自定义实现 |
**Grid 辅助组件属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:id` | `.id()` | reference → string | Android: `android:id="@+id/grid"`
HarmonyOS: `.id('grid')` |
| `app:constraint_referenced_ids` | 无直接对应 | id list → 需自定义实现 | Android: `app:constraint_referenced_ids="@id/view1,@id/view2"`
HarmonyOS: 需自定义实现 |
| `app:grid_columns` | 无直接对应 | int → 需自定义实现 | Android: `app:grid_columns="3"`
HarmonyOS: 需自定义实现 |
| `app:grid_rows` | 无直接对应 | int → 需自定义实现 | Android: `app:grid_rows="2"`
HarmonyOS: 需自定义实现 |
| `app:grid_columnWeights` | 无直接对应 | string → 需自定义实现 | Android: `app:grid_columnWeights="1,2,1"`
HarmonyOS: 需自定义实现 |
| `app:grid_rowWeights` | 无直接对应 | string → 需自定义实现 | Android: `app:grid_rowWeights="1,2"`
HarmonyOS: 需自定义实现 |
| `app:grid_horizontalGap` | 无直接对应 | dimension → 需自定义实现 | Android: `app:grid_horizontalGap="8dp"`
HarmonyOS: 需自定义实现 |
| `app:grid_verticalGap` | 无直接对应 | dimension → 需自定义实现 | Android: `app:grid_verticalGap="8dp"`
HarmonyOS: 需自定义实现) |
| `app:grid_useAsMeasurer` | 无直接对应 | boolean → 需自定义实现 | Android: `app:grid_useAsMeasurer="true"`
HarmonyOS: 需自定义实现 |
**Carousel 辅助组件属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:id` | `.id()` | reference → string | Android: `android:id="@+id/carousel"`
HarmonyOS: `.id('carousel')` |
| `app:constraint_referenced_ids` | 无直接对应 | id list → 需自定义实现 | Android: `app:constraint_referenced_ids="@id/view1,@id/view2"`
HarmonyOS: 需自定义实现 |
| `app:carousel_forwardDirection` | 无直接对应 | enum → 需自定义实现 | Android: `app:carousel_forwardDirection="horizontal"`
HarmonyOS: 需自定义实现 |
| `app:carousel_infinite` | 无直接对应 | boolean → 需自定义实现 | Android: `app:carousel_infinite="true"`
HarmonyOS: 需自定义实现 |
| `app:carousel_previousState` | 无直接对应 | enum → 需自定义实现 | Android: `app:carousel_previousState="first"`
HarmonyOS: 需自定义实现 |
| `app:carousel_nextState` | 无直接对应 | enum) → 需自定义实现 | Android: `app:carousel_nextState="last"`
HarmonyOS: 需自定义实现 |
**MotionLayout 属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|
| `android:layoutDescription` | 无直接对应 | reference → 需自定义实现 | Android: `android:layoutDescription="@xml/motion_scene"`
HarmonyOS: 需自定义实现 |
| `app:showPaths` | 无直接对应 | boolean → 需自定义实现 | Android: `app:showPaths="true"`
HarmonyOS: 需自定义实现 |
| `app:progress` | 无直接对应 | float → 需自定义实现 | Android: `app:progress="0.5"`
HarmonyOS: 需自定义实现 |
| `app:applyMotionScene` | 无直接对应 | boolean → 需自定义实现 | Android: `app:applyMotionScene="true"`
HarmonyOS: 需自定义实现 |
---
#### 2.5.3 ConstraintLayout 属性映射统计
| 映射类型 | 数量 | 占比 |
|---------|------|------|
| 直接映射 | 5 | ~5% |
| 需类型转换 | 15 | ~15% |
| 需组合实现 | 80 | ~80% |
| 无直接对应 | 0 | ~0% |
| **总计** | **100** | **100%** |
---
### 2.6 弹性布局
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| FlexboxLayout | `com.google.android.flexbox.FlexboxLayout` | `Flex` | 直接映射 | 弹性盒子布局 |
---
#### 2.6.1 FlexboxLayout → Flex 属性映射
**容器级别 Flex 属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|---------|
| `app:flexDirection` | `.direction()` | enum → FlexDirection | Android: `app:flexDirection="row"`
HarmonyOS: `Flex({ direction: FlexDirection.Row })` |
| `app:flexDirection="column"` | `.direction()` | enum → FlexDirection | Android: `app:flexDirection="column"`
HarmonyOS: `Flex({ direction: FlexDirection.Column })` |
| `app:flexDirection="row_reverse"` | `.direction()` | enum → FlexDirection | Android: `app:flexDirection="row_reverse"`
HarmonyOS: `Flex({ direction: FlexDirection.RowReverse })` |
| `app:flexDirection="column_reverse"` | `.direction()` | enum → {direction: FlexDirection.ColumnReverse}` | Android: `app:flexDirection="column_reverse"`
HarmonyOS: `Flex({ direction: FlexDirection.ColumnReverse })` |
**容器对齐属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|---------|
| `app:justifyContent` | `.justifyContent()` | flags → FlexAlign | Android: `app:justifyContent="flex_start"`
HarmonyOS: `Flex({ justifyContent: FlexAlign.Start })` |
| `app:justifyContent="flex_end"` | `.justifyContent()` | flags → FlexAlign | Android: `app:justifyContent="flex_end"`
HarmonyOS: `Flex({ justifyContent: FlexAlign.End })` |
| `app:justifyContent="center"` | `.justifyContent()` | flags → FlexAlign | Android: `app:justifyContent="center"`
HarmonyOS: `Flex({ justifyContent: FlexAlign.Center })` |
| `app:justifyContent="space_between"` | `.justifyContent()` | flags → FlexAlign | Android: `app:justifyContent="space_between"`
HarmonyOS: `Flex({ justifyContent: FlexAlign.SpaceBetween })` |
| `app:justifyContent="space_around"` | `.justifyContent()` | flags → FlexAlign | Android: `app:justifyContent="space_around"`
HarmonyOS: `Flex({ justifyContent: FlexAlign.SpaceAround })` |
| `app:justifyContent="space_evenly"` | `.justifyContent()` | flags → FlexAlign | Android: `app:justifyContent="space_evenly"`
HarmonyOS: `Flex({ justifyContent: FlexAlign.SpaceEvenly })` |
**子组件对齐属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|---------|---------|
| `app:alignItems` | `.alignItems()` | enum → ItemAlign | Android: `app:alignItems="flex_start"`
HarmonyOS: `Flex({ alignItems: ItemAlign.Start })` |
| `app:alignItems="flex_end"` | `.alignItems()` | enum → ItemAlign | Android: `app:alignItems="flex_end"`
HarmonyOS: `Flex({ alignItems: ItemAlign.End })` |
| `app:alignItems="center"` | `.alignItems()` | flags → ItemAlign | Android: `app:alignItems="center"`
HarmonyOS: `Flex({ alignItems: ItemAlign.Center })` |
| `app:alignItems="baseline"` | `.alignItems()` | enum → ItemAlign | Android: `app:alignItems="baseline"`
HarmonyOS: `Flex({ alignItems: ItemAlign.Baseline })` |
| `app:alignItems="stretch"` | `.alignItems()` | flags → ItemAlign | Android: `app:alignItems="stretch"`
HarmonyOS: `Flex({ alignItems: ItemAlign.Stretch })` |
**行内对齐属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|---------|---------|
| `app:alignContent` | `.alignContent()` | flags → FlexAlign | Android: `app:alignContent="flex_start"`
HarmonyOS: `Flex({ alignContent: FlexAlign.Start })` |
| `app:alignContent="flex_end"` | `.alignContent()` | flags → FlexAlign | Android: `app:alignContent="flex_end"`
HarmonyOS: `Flex({ alignContent: FlexAlign.End })` |
| `app:alignContent="center"` | `.alignContent()` | flags → FlexAlign | Android: `app:alignContent="center"`
HarmonyOS: `Flex({ alignContent: FlexAlign.Center })` |
| `app:alignContent="space_between"` | `.alignContent()` | flags → FlexAlign | Android: `app:alignContent="space_between"`
HarmonyOS: `Flex({ alignContent: FlexAlign.SpaceBetween })` |
| `app:alignContent="space_around"` | `.alignContent()` | flags → FlexAlign | Android: `app:alignContent="space_around"`
HarmonyOS: `Flex({ alignContent: FlexAlign.SpaceAround })` |
| `app:alignContent="space_evenly"` | `.alignContent()` | flags → FlexAlign | Android: `app:alignContent="space_evenly"`
HarmonyOS: `Flex({ alignContent: FlexAlign.SpaceEvenly })` |
**换行属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|---------|---------|
| `app:flexWrap` | `.wrap()` | enum → FlexWrap | Android: `app:flexWrap="nowrap"`
HarmonyOS: `Flex({ wrap: FlexWrap.NoWrap })` |
| `app:flexWrap="wrap"` | `.wrap()` | enum → FlexWrap | Android: `app:flexWrap="wrap"`
HarmonyOS: `Flex({ wrap: FlexWrap.Wrap })` |
| `app:flexWrap="wrap_reverse"` | `.wrap()` | enum → FlexWrap | Android: `app:flexWrap="wrap_reverse"`
HarmonyOS: `Flex({ wrap: FlexWrap.WrapReverse })` |
---
#### 2.6.2 FlexboxLayout 子组件布局属性映射
**Flex Item 属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|---------|---------|
| `app:layout_flexGrow` | `.flexGrow()` | float → number | Android: `app:layout_flexGrow="1"`
HarmonyOS: `.flexGrow(1)` |
| `app:layout_flexShrink` | `.flexShrink()` | float → number | Android: `app:layout_flexShrink="1"`
HarmonyOS: `.flexShrink(1)` |
| `app:layout_flexBasisPercent` | `.flexBasis()` | float → 百分比 | Android: `app:layout_flexBasisPercent="50%"`
HarmonyOS: `.flexBasis('50%')` |
| `app:layout_flexBasis` | dimension | 固定大小 | Android: `app:layout_flexBasis="100dp"`
HarmonyOS: `.flexBasis(100)` |
**对齐属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|---------|---------|---------|
| `app:layout_alignSelf` | `.alignSelf()` | enum → ItemAlign | Android: `app:layout_alignSelf="auto"`
HarmonyOS: `.alignSelf(ItemAlign.Auto)` |
| `app:layout_alignSelf="flex_start"` | `.alignSelf()` | enum → ItemAlign | Android: `app:layout_alignSelf="flex_start"`
HarmonyOS: `.alignSelf(ItemAlign.Start)` |
| `app:layout_alignSelf="flex_end"` | `.alignSelf()` | enum → ItemAlign | Android: `app:layout_alignSelf="flex_end"`
HarmonyOS: `.alignSelf(ItemAlign.End)` |
| `app:layout_alignSelf="center"` | `.alignSelf()` | enum → ItemAlign | Android: `app:layout_alignSelf="center"`
HarmonyOS: `.alignSelf(ItemAlign.Center)` |
| `app:layout_alignSelf="baseline"` | `.alignSelf()` | enum → ItemAlign | Android: `app:layout_alignSelf="baseline"`
HarmonyOS: `.alignSelf(ItemAlign.Baseline)` |
| `app:layout_alignSelf="stretch"` | `.alignSelf()` | enum → ItemAlign | Android: `app:layout_alignSelf="stretch"`
HarmonyOS: `.alignSelf(ItemAlign.Stretch)` |
**重力属性**
| Android XML | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|---------|---------|---------|
| `android:layout_gravity` | `.align()` / `.justify()` | flags → Alignment | Android: `android:layout_gravity="center"`
HarmonyOS: `.align(Alignment.Center)`
Android: `android:layout_gravity="center_horizontal"`
HarmonyOS: `.alignItems(HorizontalAlign.Center)`
Android: `android:layout_gravity="center_vertical"`
HarmonyOS: `.justifyContent(FlexAlign.Center)`
Android: `android:layout_gravity="left"`
HarmonyOS: `.alignItems(VerticalAlign.Top)`
Android: `android:layout_gravity="right"``
HarmonyOS: `.alignItems(VerticalAlign.Bottom)`
Android: `android:layout_gravity="center_horizontal"`
HarmonyOS: `.alignItems(HorizontalAlign.Center)`
Android: `android:layout_gravity="start"`
HarmonyOS: `.alignItems(HorizontalAlign.Start)`
Android: `android:layout_gravity="end"`
HarmonyOS: `.alignItems(HorizontalAlign.End)`
Android: `android:layout_gravity="center_vertical"`
HarmonyOS: `.justifyContent(FlexAlign.Center)`
Android: `android:layout_gravity="left"`
HarmonyOS: `.alignItems(VerticalAlign.Top)`
Android: `android:layout_gravity="right"`
HarmonyOS: `.alignItems(VerticalAlign.Bottom)`
Android: `android:layout_gravity="center_horizontal"`
HarmonyOS: `.alignItems(HorizontalAlign.Center)`
Android: `android:layout_gravity="start"`
HarmonyOS: `.alignItems(HorizontalAlign.Start)`
Android: `android:layout_gravity="end"`
HarmonyOS: `.alignItems(VerticalAlign.Bottom)`
Android: `android:layout_gravity="center_vertical"`
HarmonyOS: `.align(Alignment.Center)`
Android: `android:layout_gravity="left"`
HarmonyOS: `.alignItems(VerticalAlign.Top)`
Android: `android:layout_gravity="right"`
HarmonyOS: `.alignItems(VerticalAlign.End)`
Android: `android:layout_gravity="start"`
HarmonyOS: `.alignItems(VerticalAlign.Start)`
Android: `android:layout_gravity="end"`
HarmonyOS: `.alignItems(VerticalAlign.End)`
Android: `android:layout_gravity="center_vertical"`
HarmonyOS: `.align(Alignment.Center)`<```
---
#### 2.6.3 FlexboxLayout 程序化方法映射
| Android 方法 | HarmonyOS 属性 | 类型转换 | 代码示例 |
|-------------|---------------|---------|---------|---------|---------|
| `setFlexDirection(int)` | 无直接对应 | int → 组件选择 | Android: `flexboxLayout.setFlexDirection(LinearLayout.VERTICAL)`
HarmonyOS: 使用 `Column` 或 `Row` 组件 |
| `getFlexDirection()` | 无直接对应 | void → 组件判断 | Android: `int orientation = flexboxLayout.getFlexDirection()`
HarmonyOS: 根据组件类型判断 |
| `setGravity(int)` | `.justifyContent()` / `.alignItems()` | int → FlexAlign | Android: `flexboxLayout.setGravity(Gravity.CENTER)`
HarmonyOS: `Flex().justifyContent(FlexAlign.Center).alignItems(HorizontalAlign.Center)` |
---
#### 2.6.4 FlexboxLayout 属性映射统计
| 映射类型 | 数量 | 占比 |
|---------|------|------|------|
| 直接映射 | 6 | ~15% |
| 需类型转换 | 4 | ~25% |
| 需组合实现 | 8 | ~50% |
| 无直接对应 | 5 | ~14% |
| **总计** | **23** | **100%** |
---
### 2.7 协调布局
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| CoordinatorLayout | `androidx.coordinatorlayout.widget.CoordinatorLayout` | 自定义组合 | 需业务实现 | 协调布局 |
| AppBarLayout | `com.google.android.material.appbar.AppBarLayout` | 自定义组合 | Column + 手势 | 应用栏布局 |
| CollapsingToolbarLayout | `com.google.android.material.appbar.CollapsingToolbarLayout` | 自定义组合 | Column + 动画 | 折叠工具栏布局 |
### 2.8 抽屉布局
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| DrawerLayout | `androidx.drawerlayout.widget.DrawerLayout` | `Sheet` / 自定义 | 侧滑抽屉 | 抽屉布局 |
| SlidingPaneLayout | `androidx.slidingpanelayout.widget.SlidingPaneLayout` | 自定义组合 | Panel + 动画 | 滑动面板布局 |
### 2.9 刷新布局
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| SwipeRefreshLayout | `androidx.swiperefreshlayout.widget.SwipeRefreshLayout` | `Refresh` | 直接映射 | 下拉刷新布局 |
---
## 三、列表与适配器组件映射
### 3.1 列表视图
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| ListView | `android.widget.ListView` | `List` | 高性能列表 | 列表视图（已废弃） |
| ExpandableListView | `android.widget.ExpandableListView` | `List` + `ListItemGroup` | 配合展开逻辑 | 可展开列表视图 |
| ListPopupWindow | `android.widget.ListPopupWindow` | `Popup` + `List` | 组合实现 | 列表弹出窗口 |
### 3.2 RecyclerView 系列
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| RecyclerView | `androidx.recyclerview.widget.RecyclerView` | `List` | 配合 LazyForEach | 高性能列表视图 |
| RecyclerView.Adapter | `androidx.recyclerview.widget.RecyclerView.Adapter` | `LazyForEach` | 数据源管理 | 列表适配器 |
| RecyclerView.ViewHolder | `androidx.recyclerview.widget.RecyclerView.ViewHolder` | `ListItem` | 列表项组件 | 列表项持有者 |
| LinearLayoutManager | `androidx.recyclerview.widget.LinearLayoutManager` | `List` | listDirection 配置 | 线性布局管理器 |
| GridLayoutManager | `androidx.recyclerview.widget.GridLayoutManager` | `Grid` | 网格布局 | 网格布局管理器 |
| StaggeredGridLayoutManager | `androidx.recyclerview.widget.StaggeredGridLayoutManager` | `WaterFlow` | 瀑布流布局 | 瀑布流布局管理器 |
| ItemTouchHelper | `androidx.recyclerview.widget.ItemTouchHelper` | 拖拽 API | Drag + Drop | 列表项触摸辅助 |
| SnapHelper | `androidx.recyclerview.widget.SnapHelper` | 自定义对齐逻辑 | 手势实现 | 对齐辅助 |
| LinearSnapHelper | `androidx.recyclerview.widget.LinearSnapHelper` | 自定义对齐逻辑 | Swiper 配合 | 线性对齐辅助 |
| PagerSnapHelper | `androidx.recyclerview.widget.PagerSnapHelper` | `Swiper` | 轮播容器 | 分页对齐辅助 |
### 3.3 适配器视图基类
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| AdapterView | `android.widget.AdapterView` | 基础架构概念 | 适配器视图基类 | 适配器视图基类 |
| AdapterViewAnimator | `android.widget.AdapterViewAnimator` | 自定义动画组件 | transition | 适配器视图动画器 |
| AdapterViewFlipper | `android.widget.AdapterViewFlipper` | `Swiper` | 轮播切换 | 适配器视图翻转器 |
| StackView | `android.widget.StackView` | `Stack` | 堆叠布局 | 堆栈视图 |
---
## 四、切换与翻页组件映射
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| ViewPager | `androidx.viewpager.widget.ViewPager` | `Swiper` | 轮播容器 | 页面切换器（已废弃） |
| ViewPager2 | `androidx.viewpager2.widget.ViewPager2` | `Swiper` | 轮播容器 | 页面切换器 |
| TabHost | `android.widget.TabHost` | `Tabs` + `TabContent` | 已废弃 | 标签页主机（已废弃） |
| TabWidget | `android.widget.TabWidget` | `Tabs` | 已废弃 | 标签页组件（已废弃） |
| ViewFlipper | `android.widget.ViewFlipper` | `Swiper` | 轮播切换 | 视图翻转器 |
| ViewSwitcher | `android.widget.ViewSwitcher` | `Swiper` | 轮播切换 | 视图切换器 |
| ImageSwitcher | `android.widget.ImageSwitcher` | `Swiper` + `Image` | 配合 Image | 图片切换器 |
| TextSwitcher | `android.widget.TextSwitcher` | `Swiper` + `Text` | 配合 Text | 文本切换器 |
---
## 五、Material Design 组件映射
### 5.1 Material 按钮
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| MaterialButton | `com.google.android.material.button.MaterialButton` | `Button` | 配置样式 | Material 按钮 |
| IconButton | `com.google.android.material.button.MaterialButton` | `Button` + 图标 | 组合实现 | 图标按钮 |
| SplitButton | `com.google.android.material.button.MaterialButtonGroup` | `Row` + 2个 `Button` | 组合实现 | 分割按钮 |
| ToggleButton | `com.google.android.material.button.MaterialButtonToggleGroup` | `RadioContainer` | 配合 Radio | 切换按钮组 |
### 5.2 Material 文本输入
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| TextInputLayout | `com.google.android.material.textfield.TextInputLayout` | `Column` + `TextInput` + 样式 | 组合实现 | 文本输入布局 |
| TextInputEditText | `com.google.android.material.textfield.TextInputEditText` | `TextInput` | 配置样式 | 文本输入框 |
| ExposedDropdownMenu | `com.google.android.material.textfield.MaterialAutoCompleteTextView` | `Select` | 下拉选择 | 暴露下拉菜单 |
### 5.3 Material 卡片
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| CardView | `androidx.cardview.widget.CardView` | `Column` + 样式 | borderRadius + shadow | 卡片视图 |
| MaterialCardView | `com.google.android.material.card.MaterialCardView` | `Column` + 样式 | borderRadius + shadow | Material 卡片 |
### 5.4 Material 底部组件
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| BottomNavigationView | `com.google.android.material.bottomnavigation.BottomNavigationView` | `Tabs` | 配合路由 | 底部导航 |
| BottomSheetDialog | `com.google.android.material.bottomsheet.BottomSheetDialog` | `Sheet` | 底部抽屉 | 底部抽屉对话框 |
| BottomSheetDialogFragment | `com.google.android.material.bottomsheet.BottomSheetDialogFragment` | `Sheet` | 配合路由 | 底部抽屉片段 |
| BottomSheetBehavior | `com.google.android.material.bottomsheet.BottomSheetBehavior` | `Sheet` | 配置行为 | 底部抽屉行为 |
### 5.5 Material 导航组件
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| NavigationView | `com.google.android.material.navigation.NavigationView` | 自定义组合 | Column + 列表 | 导航视图 |
| NavigationRailView | `com.google.android.material.navigationrail.NavigationRailView` | 自定义组合 | Column + 垂直列表 | 导航栏 |
| TabLayout | `com.google.android.material.tabs.TabLayout` | `Tabs` | 直接映射 | 标签页布局 |
| TabItem | `com.google.android.material.tabs.TabItem` | `TabContent` | 配合 Tabs | 标签页项 |
### 5.6 Material 浮动组件
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| FloatingActionButton | `com.google.android.material.floatingactionbutton.FloatingActionButton` | `Button` + 样式 | 圆形 + 阴影 | 浮动操作按钮 |
| ExtendedFloatingActionButton | `com.google.android.material.floatingactionbutton.ExtendedFloatingActionButton` | `Button` + 样式 | 长按钮 | 扩展浮动按钮 |
| SpeedDial | `com.google.android.material.floatingactionbutton.FloatingActionButton` | 自定义组合 | 多个 FAB | 快捷拨号（组合实现） |
### 5.7 Material 对话框
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| AlertDialog | `androidx.appcompat.app.AlertDialog` | `AlertDialog` | 直接映射 | 警告对话框 |
| MaterialAlertDialogBuilder | `com.google.android.material.dialog.MaterialAlertDialogBuilder` | `AlertDialog` | 配置 Material 样式 | Material 对话框构建器 |
| DatePickerDialog | `android.app.DatePickerDialog` | `DatePickerDialog` | 直接映射 | 日期选择对话框 |
| TimePickerDialog | `android.app.TimePickerDialog` | `TimePickerDialog` | 直接映射 | 时间选择对话框 |
| ProgressDialog | `android.app.ProgressDialog` | `LoadingDialog` | 已废弃 | 进度对话框（已废弃） |
### 5.8 Material 提示组件
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| Snackbar | `com.google.android.material.snackbar.Snackbar` | 自定义组合 | Toast + 样式 | 快速提示条 |
| Toast | `android.widget.Toast` | `prompt.showToast()` | API 调用 | 吐司提示 |
| Tooltip | `com.google.android.material.tooltip.TooltipDrawable` | 暂无直接对应 | 自定义 Popup | 工具提示 |
### 5.9 Material 菜单组件
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| PopupMenu | `android.widget.PopupMenu` | `Menu` / `BindMenu` | 直接映射 | 弹出菜单 |
| PopupWindow | `android.widget.PopupWindow` | `Popup` | 直接映射 | 弹出窗口 |
| DropdownMenu | `com.google.android.material.menu.MaterialMenuView` | `Select` | 下拉选择 | 下拉菜单 |
### 5.10 Material 进度指示器
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| CircularProgressIndicator | `com.google.android.material.progressindicator.CircularProgressIndicator` | `Progress` (type: CircularProgressType) | 配置类型 | 圆形进度指示器 |
| LinearProgressIndicator | `com.google.android.material.progressindicator.LinearProgressIndicator` | `Progress` | 配置类型 | 线性进度指示器 |
### 5.11 Material 滑块与范围
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| Slider | `com.google.android.material.slider.Slider` | `Slider` | 直接映射 | 滑块 |
| RangeSlider | `com.google.android.material.slider.RangeSlider` | 暂无直接对应 | 自定义双 Slider | 范围滑块 |
### 5.12 Material Chips
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| Chip | `com.google.android.material.chip.Chip` | 自定义组合 | Row + 样式 | 芯片标签 |
| ChipGroup | `com.google.android.material.chip.ChipGroup` | `CheckboxGroup` / `Flex` | 配合 Chip | 芯片组 |
| ChipDrawable | `com.google.android.material.chip.ChipDrawable` | 自定义样式 | @Styles | 芯片绘制 |
### 5.13 Material 顶部应用栏
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| Toolbar | `androidx.appcompat.widget.Toolbar` | 自定义组合 | Row + 按钮 | 工具栏 |
| MaterialToolbar | `com.google.android.material.appbar.MaterialToolbar` | 自定义组合 | Row + 样式 | Material 工具栏 |
| SearchBar | `com.google.android.material.search.SearchBar` | `Search` | 配置样式 | 搜索栏 |
| SearchView | `com.google.android.material.search.SearchView` | `Search` | 配置样式 | 搜索视图 |
### 5.14 Material 骨架屏
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| ShimmerFrameLayout | `com.facebook.shimmer.ShimmerFrameLayout` | 暂无直接对应 | 自定义动画 | 骨架屏动画（Facebook） |
| SkeletonLayout | 第三方库 | 暂无直接对应 | 自定义加载占位 | 骨架屏布局 |
---
## 六、Jetpack Compose 组件映射
### 6.1 Compose 基础组件
| Android Compose | 函数名 | HarmonyOS 组件 | 替代方案 | 说明 |
|----------------|--------|---------------|---------|------|
| Text | `Text()` | `Text` | 直接映射 | 文本显示 |
| TextField | `TextField()` / `OutlinedTextField()` | `TextInput` | 配置样式 | 文本输入框 |
| BasicTextField | `BasicTextField()` | `TextInput` | 基础配置 | 基础文本输入 |
| Button | `Button()` | `Button` | 直接映射 | 按钮 |
| IconButton | `IconButton()` | `Button` + 图标 | 组合实现 | 图标按钮 |
| Icon | `Icon()` | `SymbolGlyph` / `Image` | 系统图标或图片 | 图标 |
| Image | `Image()` | `Image` | 直接映射 | 图片 |
| Checkbox | `Checkbox()` | `Checkbox` | 直接映射 | 复选框 |
| RadioButton | `RadioButton()` | `Radio` | 配合容器 | 单选按钮 |
| Switch | `Switch()` | `Toggle` (Switch) | 直接映射 | 开关 |
| Slider | `Slider()` | `Slider` | 直接映射 | 滑块 |
| RangeSlider | `RangeSlider()` | 暂无直接对应 | 自定义双 Slider | 范围滑块 |
### 6.2 Compose 布局组件
| Android Compose | 函数名 | HarmonyOS 组件 | 替代方案 | 说明 |
|----------------|--------|---------------|---------|------|
| Column | `Column()` | `Column` | 直接映射 | 垂直线性布局 |
| Row | `Row()` | `Row` | 直接映射 | 水平线性布局 |
| Box | `Box()` | `Stack` | 直接映射 | 堆叠布局 |
| ConstraintLayout | `ConstraintLayout()` | `RelativeContainer` | 部分对应 | 约束布局 |
| FlowRow | `FlowRow()` | `Flex` (direction: Row) | 流式行布局 | 流式行布局 |
| FlowColumn | `FlowColumn()` | `Flex` (direction: Column) | 流式列布局 | 流式列布局 |
| LazyColumn | `LazyColumn()` | `List` (listDirection: Axis.Vertical) | 配合 LazyForEach | 懒加载垂直列表 |
| LazyRow | `LazyRow()` | `List` (listDirection: Axis.Horizontal) | 配合 LazyForEach | 懒加载水平列表 |
| LazyVerticalGrid | `LazyVerticalGrid()` | `Grid` + LazyForEach | 网格懒加载 | 懒加载垂直网格 |
| LazyHorizontalGrid | `LazyHorizontalGrid()` | `Grid` + LazyForEach | 网格懒加载 | 懒加载水平网格 |
| GridLayout | `GridLayout()` | `GridRow` + `GridCol` | 栅格系统 | 网格布局 |
### 6.3 Compose Material 3 组件
| Android Compose | 函数名 | HarmonyOS 组件 | 替代方案 | 说明 |
|----------------|--------|---------------|---------|------|
| Card | `Card()` / `ElevatedCard()` / `OutlinedCard()` | `Column` + 样式 | 卡片 |
| FloatingActionButton | `FloatingActionButton()` / `ExtendedFloatingActionButton()` | `Button` + 样式 | 浮动按钮 |
| Chip | `Chip()` / `InputChip()` / `FilterChip()` / `SuggestionChip()` | 自定义组合 | Row + 样式 | 芯片 |
| NavigationBar | `NavigationBar()` | `Tabs` | 配合路由 | 底部导航栏 |
| NavigationRail | `NavigationRail()` | 自定义组合 | 垂直导航 | 侧边导航栏 |
| NavigationDrawer | `ModalNavigationDrawer()` | `Sheet` / 自定义 | 导航抽屉 | 模态导航抽屉 |
| TabRow | `TabRow()` / `ScrollableTabRow()` | `Tabs` | 直接映射 | 标签页行 |
| BottomSheet | `BottomSheetScaffold()` | `Sheet` | 直接映射 | 底部抽屉 |
| Snackbar | `Snackbar()` / `SnackbarHost()` | 自定义组合 | Toast + 样式 | 快速提示 |
| TopAppBar | `TopAppBar()` / `CenterAlignedTopAppBar()` / `MediumTopAppBar()` / `LargeTopAppBar()` | 自定义组合 | Row + 样式 | 顶部应用栏 |
| AlertDialog | `AlertDialog()` | `AlertDialog` | 直接映射 | 警告对话框 |
| DatePicker | `DatePicker()` | `DatePicker` | 直接映射 | 日期选择器 |
| ProgressIndicator | `CircularProgressIndicator()` / `LinearProgressIndicator()` | `Progress` | 配置类型 | 进度指示器 |
| PullRefresh | `PullRefreshIndicator()` | `Refresh` | 直接映射 | 下拉刷新 |
| SwipeToDismiss | `SwipeToDismiss()` | 暂无直接对应 | 拖拽 API + 状态 | 滑动删除 |
### 6.4 Compose 动画组件
| Android Compose | 函数名 | HarmonyOS 组件 | 替代方案 | 说明 |
|----------------|--------|---------------|---------|------|
| AnimatedVisibility | `AnimatedVisibility()` | `transition` + `animateTo` | 动画可见性 |
| AnimatedContent | `AnimatedContent()` | `transition` + `animateTo` | 动画内容切换 |
| Crossfade | `Crossfade()` | `animateTo` (opacity) | 淡入淡出 |
| animateAsState | `animate*AsState()` | `animateTo` | 状态动画 |
| AnimatedValue | `animateFloatAsState()` 等 | `animateTo` | 值动画 |
---
## 七、特殊视图组件映射
### 7.1 网页视图
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| WebView | `android.webkit.WebView` | `Web` | 直接映射 | 网页视图 |
### 7.2 表面视图
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| SurfaceView | `android.view.SurfaceView` | `XComponent` | OpenGL 渲染 | 表面视图（独立绘图线程） |
| TextureView | `android.view.TextureView` | `XComponent` | 原生渲染 | 纹理视图（支持动画变换） |
| GLSurfaceView | `android.opengl.GLSurfaceView` | `XComponent` | OpenGL 渲染 | OpenGL 表面视图 |
### 7.3 自定义组件
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| View | `android.view.View` | `@Component` | 自定义组件 | 视图基类 |
| ViewGroup | `android.view.ViewGroup` | 容器组件 | Row/Column/Stack 等 | 视图组基类 |
### 7.4 通知组件
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| RemoteViews | `android.widget.RemoteViews` | 暂无直接对应 | 通知 API | 远程视图（用于通知、桌面小部件） |
| AppWidgetHostView | `android.appwidget.AppWidgetHostView` | 暂无直接对应 | 桌面小部件 API | 应用小部件宿主视图 |
---
## 八、辅助组件映射
### 8.1 视图辅助
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| ViewStub | `android.view.ViewStub` | 暂无直接对应 | 条件渲染 + Lazy | 延迟加载视图 |
| Space | `android.widget.Space` | `Row`/`Column` 空子项 | 布局技巧 | 空白占位 |
| ViewOutlineProvider | `android.view.ViewOutlineProvider` | 暂无直接对应 | clipShape API | 视图轮廓提供者 |
### 8.2 手势组件
| Android 组件 | 类名 | HarmonyOS 组件 | 替代方案 | 说明 |
|-------------|------|---------------|---------|------|
| GestureDetector | `android.view.GestureDetector` | 手势 API 组合 | TapGesture/PanGesture 等 | 手势检测器 |
| ScaleGestureDetector | `android.view.ScaleGestureDetector` | `PinchGesture` | 直接映射 | 缩放手势检测器 |
---
## 九、布局属性映射（API 20/21）
### 9.1 尺寸属性
| Android XML | HarmonyOS | 说明 | 代码示例对比 |
|-------------|-----------|------|-------------|
| layout_width | width | 宽度 | Android: `android:layout_width="100dp"`
HarmonyOS: `Component().width(100)` |
| layout_height | height | 高度 | Android: `android:layout_height="match_parent"`
HarmonyOS: `Component().height('100%')` |
| minWidth | constraintSize({ minWidth: value }) | 最小宽度 | Android: `android:minWidth="100dp"`
HarmonyOS: `Component().constraintSize({ minWidth: 100 })` |
| maxWidth | constraintSize({ maxWidth: value }) | 最大宽度 | Android: `android:maxWidth="200dp"`
HarmonyOS: `Component().constraintSize({ maxWidth: 200 })` |
| minHeight | constraintSize({ minHeight: value }) | 最小高度 | Android: `android:minHeight="50dp"`
HarmonyOS: `Component().constraintSize({ minHeight: 50 })` |
| maxHeight | constraintSize({ maxHeight: value }) | 最大高度 | Android: `android:maxHeight="300dp"`
HarmonyOS: `Component().constraintSize({ maxHeight: 300 })` |
| layout_weight | layoutWeight | 布局权重 | Android: `android:layout_weight="1"`
HarmonyOS: `Component().layoutWeight(1)` |
### 9.2 边距与内边距
| Android XML | HarmonyOS | 说明 | 代码示例对比 |
|-------------|-----------|------|-------------|
| layout_margin | margin | 外边距 | Android: `android:layout_margin="10dp"`
HarmonyOS: `Component().margin(10)` |
| layout_marginTop | margin({ top: value }) | 上边距 | Android: `android:layout_marginTop="10dp"`
HarmonyOS: `Component().margin({ top: 10 })` |
| layout_marginBottom | margin({ bottom: value }) | 下边距 | Android: `android:layout_marginBottom="10dp"`
HarmonyOS: `Component().margin({ bottom: 10 })` |
| layout_marginLeft | margin({ left: value }) | 左边距 | Android: `android:layout_marginLeft="10dp"`
HarmonyOS: `Component().margin({ left: 10 })` |
| layout_marginRight | margin({ right: value }) | 右边距 | Android: `android:layout_marginRight="10dp"`
HarmonyOS: `Component().margin({ right: 10 })` |
| layout_marginStart | margin({ start: value }) | 起始边距 | Android: `android:layout_marginStart="10dp"`
HarmonyOS: `Component().margin({ start: 10 })` |
| layout_marginEnd | margin({ end: value }) | 结束边距 | Android: `android:layout_marginEnd="10dp"`
HarmonyOS: `Component().margin({ end: 10 })` |
| padding | padding | 内边距 | Android: `android:padding="10dp"`
HarmonyOS: `Component().padding(10)` |
| paddingTop | padding({ top: value }) | 上内边距 | Android: `android:paddingTop="10dp"`
HarmonyOS: `Component().padding({ top: 10 })` |
| paddingBottom | padding({ bottom: value }) | 下内边距 | Android: `android:paddingBottom="10dp"`
HarmonyOS: `Component().padding({ bottom: 10 })` |
### 9.3 对齐与权重
| Android XML | HarmonyOS | 说明 | 代码示例对比 |
|-------------|-----------|------|-------------|
| layout_gravity | align / alignSelf | 对齐方式 | Android: `android:layout_gravity="center"`
HarmonyOS: `Component().align(Alignment.Center)` |
| gravity | textAlign | 文本对齐 | Android: `android:gravity="center"`
HarmonyOS: `Text().textAlign(TextAlign.Center)` |
| layout_weight | layoutWeight | 权重 | Android: `android:layout_weight="1"`
HarmonyOS: `Component().layoutWeight(1)` |
### 9.4 显示属性
| Android XML | HarmonyOS | 说明 | 代码示例对比 |
|-------------|-----------|------|-------------|
| visibility | visibility | 可见性 | Android: `android:visibility="gone"`
HarmonyOS: `Component().visibility(Visibility.None)` |
| alpha | opacity | 透明度 | Android: `android:alpha="0.5"`
HarmonyOS: `Component().opacity(0.5)` |
| background | backgroundColor | 背景色 | Android: `android:background="#FF0000FF"`
HarmonyOS: `Component().backgroundColor('#FF0000FF')` |
| background | backgroundImage | 背景图 | Android: `android:background="@drawable/bg"`
HarmonyOS: `Component().backgroundImage($r('app.media.bg'))` |
| foreground | 无直接对应 | 前景图 | Android: `android:foreground`
HarmonyOS: 无直接对应，需组合实现 |
### 9.5 边框与圆角
| Android XML | HarmonyOS | 说明 | 代码示例对比 |
|-------------|-----------|------|-------------|
| elevation | shadow | 阴影效果 | Android: `android:elevation="10dp"`
HarmonyOS: `Component().shadow({ radius: 10, color: '#80000000', offsetX: 0, offsetY: 5 })` |
| cardElevation | shadow | 卡片阴影 | Android: Material 卡片属性
HarmonyOS: `Column().shadow({ radius: 8, color: '#30000000' })` |
### 9.6 变换属性
| Android XML | HarmonyOS | 说明 | 代码示例对比 |
|-------------|-----------|------|-------------|
| rotation | rotate | 旋转角度 | Android: `android:rotation="90"`
HarmonyOS: `Component().rotate({ angle: 90 })` |
| scaleX / scaleY | scale({ x, y }) | 缩放 | Android: `android:scaleX="1.5"`
HarmonyOS: `Component().scale({ x: 1.5, y: 1 })` |
| translationX / translationY | translate({ x, y }) | 平移 | Android: `android:translationX="100"`
HarmonyOS: `Component().translate({ x: 100 })` |
| pivotX / pivotY | 无直接对应 | 旋转中心点 | Android: `android:pivotX="0.5"`
HarmonyOS: 无直接对应 |
### 9.7 交互属性
| Android XML | HarmonyOS | 说明 | 代码示例对比 |
|-------------|-----------|------|-------------|
| clickable | enabled / enabled | 是否可点击 | Android: `android:clickable="true"`
HarmonyOS: `Component().enabled(true)` |
| focusable | focusable | 是否可获取焦点 | Android: `android:focusable="true"`
HarmonyOS: `Component().focusable(true)` |
| clickable | enabled / enabled | 是否可交互 | Android: `android:clickable="true"`
HarmonyOS: `Component().enabled(true)` |
### 9.8 单位换算（API 20/21）
| Android | HarmonyOS | 换算关系 | 说明 |
|---------|-----------|---------|------|
| dp | vp | 密度无关像素 | Android: `16dp` ≈ HarmonyOS: `16vp` |
| sp | fp | 字体像素 | Android: `16sp` ≈ HarmonyOS: `16fp` |
| px | px | 像素 | Android: `16px` = HarmonyOS: `16px` |
---
## 十、未找到直接对应方案的 Android 组件
以下 Android 组件在 HarmonyOS ArkUI 中暂无直接对应组件，需要通过组合实现、自定义开发或使用特定 Kit 替代：
| Android 组件 | 类名 | HarmonyOS 替代方案 | 难度等级 | 说明 |
|-------------|------|------------------|---------|------|
| **ConstraintLayout 辅助组件** | | | | |
| Guideline | `androidx.constraintlayout.widget.Guideline` | 借助 Absolute 定位 | 中等 | 需手动计算和约束 |
| Barrier | `androidx.constraintlayout.widget.Barrier` | 手动计算位置 | 中等 | 需监听子组件尺寸变化 |
| Group | `androidx.constraintlayout.widget.Group` | 批量操作逻辑 | 简单 | 需要手动管理引用 |
| Placeholder | `androidx.constraintlayout.widget.Placeholder` | 动态替换 | 中等 | 需要状态管理 |
| **Material 3 特殊组件** | | | | |
| RangeSlider | `com.google.android.material.slider.RangeSlider` | 自定义双 Slider | 中等 | 需同步两个 Slider 状态 |
| ShimmerFrameLayout | `com.facebook.shimmer.ShimmerFrameLayout` | 自定义动画 | 简单 | 使用 animateTo + opacity |
| Tooltip | `com.google.android.material.tooltip.TooltipDrawable` | 自定义 Popup | 中等 | 长按触发 Popup |
| Chip | `com.google.android.material.chip.Chip` | 自定义组合 | 简单 | Row + 样式 + 点击逻辑 |
| **协调布局组件** | | | | |
| CoordinatorLayout | `androidx.coordinatorlayout.widget.CoordinatorLayout` | 自定义组合 | 困难 | 需要复杂的嵌套滚动协调 |
| AppBarLayout | `com.google.android.material.appbar.AppBarLayout` | 自定义组合 | 中等 | 需要滚动联动逻辑 |
| CollapsingToolbarLayout | `com.google.android.material.appbar.CollapsingToolbarLayout` | 自定义组合 | 困难 | 需要滚动高度计算 + 动画 |
| **抽屉布局** | | | | |
| DrawerLayout | `androidx.drawerlayout.widget.DrawerLayout` | Sheet / 自定义 | 中等 | 侧滑手势需要自定义 |
| SlidingPaneLayout | `androidx.slidingpanelayout.widget.SlidingPaneLayout` | 自定义组合 | 中等 | Panel + 动画 + 滑动手势 |
| **通知与小部件** | | | | |
| RemoteViews | `android.widget.RemoteViews` | 通知 Kit | 困难 | 桌面小部件暂不支持 |
| AppWidgetHostView | `android.appwidget.AppWidgetHostView` | 暂不支持 | 不可行 | HarmonyOS 没有桌面小部件系统 |
| **Jetpack Compose 特有** | | | | |
| SwipeToDismiss | `SwipeToDismiss()` | 拖拽 API + 状态 | 中等 | 需要配合 PanGesture + 状态管理 |
| **其他特殊组件** | | | | |
| DialerFilter | `android.widget.DialerFilter` | 自定义业务组件 | 中等 | 需要具体的拨号逻辑 |
| ViewStub | `android.view.ViewStub` | 条件渲染 + Lazy | 简单 | 使用 if/else + LazyForEach |
| ViewOutlineProvider | `android.view.ViewOutlineProvider` | clipShape API | 中等 | 使用通用属性中的裁剪 |
| MotionLayout | `androidx.constraintlayout.motion.widget.MotionLayout` | 动画 API 组合 | 困难 | animateTo + transition + 状态管理 |
---
## 十、映射方案总结
### 10.1 完全直接映射的组件（70+）
可以直接一对一替换的组件：
- 基础组件：Text、Button、Image、Checkbox、Radio、Slider、Rating 等
- 布局组件：Row、Column、Flex、Stack、Grid、List 等
- 选择器：DatePicker、TimePicker、CalendarPicker、Select 等
- 弹窗：AlertDialog、ActionSheet、LoadingDialog 等
- 功能组件：Web、Video、Search、Divider 等
### 10.2 需要组合实现的组件（50+）
需要通过多个 HarmonyOS 组件组合实现的 Android 组件：
- ImageButton → Button + Image
- ImageView 带文本 → Row + Image + Text
- Material 组件 → 容器组件 + 样式配置
- 复杂列表 → List + ListItemGroup + LazyForEach
### 10.3 需要自定义实现的组件（20+）
需要编写自定义逻辑或组件的 Android 组件：
- CoordinatorLayout 及相关 → 复杂滚动协调逻辑
- Material 特效组件 → 动画 API + 状态管理
- 通知/小部件 → 暂不支持，需替代方案
- ConstraintLayout 高级辅助 → 手动计算和约束
### 10.4 完全不支持的组件（5+）
在 HarmonyOS 中无法实现的 Android 组件：
- 桌面小部件系统 → HarmonyOS 架构不同
- 部分通知交互 → 通知 Kit 能力有限
- Material MotionLayout 部分功能 → 需要手动实现
---
## 十一、迁移建议
### 11.1 优先级排序
1. **高优先级**（完全支持）：基础 UI 组件、布局容器、列表组件
2. **中优先级**（部分支持）：Material 组件、复杂动画、自定义布局
3. **低优先级**（暂不支持）：小部件、高级动画、特殊交互
### 11.2 迁移策略
1. **渐进式迁移**：先迁移基础功能，再处理复杂交互
2. **组件降级**：Material 组件可降级为基础组件 + 样式
3. **功能替代**：无直接对应的组件用功能相似的组合替代
4. **自定义开发**：关键但缺失的组件需要自定义实现
### 11.3 注意事项
1. HarmonyOS 声明式 UI 与 Android 命令式 UI 有本质区别
2. 状态管理是 HarmonyOS 的核心，需熟练掌握 @State/@Link 等装饰器
3. 布局参数从 XML 属性改为链式调用，语法差异较大
4. 事件处理从监听器改为回调函数，编程范式不同
5. 部分高级功能（如 MotionLayout、小部件）需要重新设计架构
---
## 参考链接
1. **HarmonyOS 开发者文档**: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/
2. **Android UI 组件总览**: https://developer.android.com/develop/ui
3. **Material Design 3 规范**: https://m3.material.io/components
---
*本文档基于 Android 14 / Material Design 3 和 HarmonyOS NEXT API 20/21 (6.0.0/6.0.1) 整理，具体 API 以官方最新文档为准。*