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	无直接对应	需自定义实现	使用渲染模式

组合示例：

// Android
<ImageButton
    android:layout_width="48dp"
    android:layout_height="48dp"
    android:src="@drawable/ic_back"
    android:background="?attr/selectableItemBackgroundBorderless"
    android:contentDescription="Back" />

// 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 变量管理选中项

组合示例：

// Android
<RadioGroup
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:orientation="vertical">
    <RadioButton
        android:id="@+id/radio1"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Option 1" />
    <RadioButton
        android:id="@+id/radio2"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:text="Option 2" />
</RadioGroup>

// 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 切换全屏

组合示例：

// Android
<VideoView
    android:id="@+id/videoView"
    android:layout_width="match_parent"
    android:layout_height="200dp" />
<MediaController
    android:id="@+id/mediaController"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:layout_alignParentBottom="true"
    app:mediaController="@id/videoView" />

// 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: 需自定义实现
appflow_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"<br/>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"``<br/>HarmonyOS: .alignItems(VerticalAlign.Bottom)<br/>Android: android:layout_gravity="center_horizontal"<br/>HarmonyOS: .alignItems(HorizontalAlign.Center)<br/>Android: android:layout_gravity="start"<br/>HarmonyOS: .alignItems(HorizontalAlign.Start)<br/>Android: android:layout_gravity="end"<br/>HarmonyOS: .alignItems(HorizontalAlign.End)<br/>Android: android:layout_gravity="center_vertical"<br/>HarmonyOS: .justifyContent(FlexAlign.Center)<br/>Android: android:layout_gravity="left"<br/>HarmonyOS: .alignItems(VerticalAlign.Top)<br/>Android: android:layout_gravity="right"<br/>HarmonyOS: .alignItems(VerticalAlign.Bottom)<br/>Android: android:layout_gravity="center_horizontal"<br/>HarmonyOS: .alignItems(HorizontalAlign.Center)<br/>Android: android:layout_gravity="start"<br/>HarmonyOS: .alignItems(HorizontalAlign.Start)<br/>Android: android:layout_gravity="end"<br/>HarmonyOS: .alignItems(VerticalAlign.Bottom)<br/>Android: android:layout_gravity="center_vertical"<br/>HarmonyOS: .align(Alignment.Center)<br/>Android: android:layout_gravity="left"<br/>HarmonyOS: .alignItems(VerticalAlign.Top)<br/>Android: android:layout_gravity="right"<br/>HarmonyOS: .alignItems(VerticalAlign.End)<br/>Android: android:layout_gravity="start"<br/>HarmonyOS: .alignItems(VerticalAlign.Start)<br/>Android: android:layout_gravity="end"<br/>HarmonyOS: .alignItems(VerticalAlign.End)<br/>Android: android:layout_gravity="center_vertical"<br/>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. Android UI 组件全量清单: /docs/android-ui-components-full-list.md
2. HarmonyOS ArkUI 组件全量清单: /docs/harmonyos-arkui-components-full-list.md
3. HarmonyOS 开发者文档: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/
4. Android UI 组件总览: https://developer.android.com/develop/ui
5. 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 以官方最新文档为准。