Harmony OS Next《ArkUI全组件终极指南 | 从布局到交互一站式精通》

Harmony OS Next《ArkUI全组件终极指南 | 从布局到交互一站式精通》

本文全面解析ArkUI五大核心组件的花式玩法，助你轻松打造高颜值、强交互的HarmonyOS应用！

Harmony OS Next ##Ark Ts ##教育

本文适用于教育科普行业进行学习，有错误之处请指出我会修改。

涵盖组件全家桶：
✅ ​​布局容器​​（Flex/Stack/Grid）
✅ ​​图片处理​​（Image/PixelMap/SVG）
✅ ​​文本魔法​​（Text/Span）
✅ ​​输入交互​​（TextInput/TextArea）
✅ ​​按钮艺术​​（Capsule/Circle/Normal）

教程亮点：
🎯 ​​零基础友好​​：分步图解+口语化讲解
🎨 ​​样式自由定制​​：边框/阴影/滤镜/动效全解锁
💡 ​​实战场景覆盖​​：登录页/相册/商品列表/悬浮按钮
🚀 ​​性能优化秘籍​​：图片缓存/键盘避让/防重复点击

🌼ArkUI布局超全指南 | 看完秒变排版大师！

---

🌟布局到底是什么？

就像搭积木一样🗿，组件按照特定规则排列组合就形成了页面！在ArkUI中，所有页面都是通过自定义组件+布局魔法搭建的~

开发四步曲🎻：
1️⃣ ​​画框架​​：先想好页面长啥样（比如顶部导航+中间内容+底部Tab）
2️⃣ ​​拆零件​​：分析要放哪些元素（按钮？图片？列表？）
3️⃣ ​​选容器​​：用Column纵向堆叠，Row横向排列，Stack叠叠乐...
4️⃣ ​​调细节​​：控制每个元素的位置和大小

---

🎨布局元素解剖课

%E9%93%BE%E6%8E%A5%E5%8D%A0%E4%BD%8D%E7%AC%A6
🔵 ​​蓝区​​：组件的"地盘" → 用width/height设定
🟡 ​​黄区​​：实际可用空间 = 蓝区 - border值
🟢 ​​绿区​​：内容真实大小（比如文字自动撑开）
⚫ ​​虚线区​​：组件+margin的势力范围

对齐小技巧✨：
当内容比黄区小时 → 用align玩对齐魔术（居中/靠左/靠右）

---

🚀10大布局神器速查表

布局方式	使用场景	举个栗子🌰
Row/Column	需要直线排列时（超过1个元素）	商品横向排列栏
Stack	要做叠加效果（比如悬浮按钮）	图片上叠加收藏图标⭐
Flex	元素需要自动伸缩比例	三栏等分导航
RelativeContainer	复杂二维布局（拒绝套娃！）	头像+昵称+简介自由组合
Grid系列	需要响应式布局（不同设备自动适配）	手机/平板不同列数展示
List	超长滚动列表（聊天记录/商品列表）	朋友圈动态瀑布流
Swiper	轮播图/广告横幅	电商首页顶部Banner
Tabs	标签页切换（保持导航可见）	设置页的多个分类

---

🎯定位黑科技

// 绝对定位：爸爸的左上角是原点
Component1().position({x: 20, y: 30})

// 相对定位：从自己原来的位置漂移
Component2().offset({x: 5, y: -10})

🚨避坑指南：
绝对定位在适配不同屏幕时容易翻车，建议多用相对布局！

---

🧩子元素控制三大绝招

效果	属性	使用场景	代码示例
拉伸	flexGrow/flexShrink	空间重新分配	Text('拉伸').flexGrow(1
缩放	aspectRatio	保持宽高比	Image().aspectRatio(1.5
隐藏	displayPriority	空间不足时智能隐藏	Button().displayPriority(2

---

💡超实用小贴士

1. 百分比布局：width('50%')超方便，但要注意父容器有没有设置尺寸！
2. 布局权重：用layoutWeight让元素自动吃满剩余空间
3. 媒体查询：不同设备用不同布局，代码示例：

// 手机竖屏显示Column，横屏变Row
if (mediaQuery.matchDevice({orientation: 'portrait'})) {
  buildColumnLayout()
} else {
  buildRowLayout()
}

🎉记住啦！ 好的布局 = 选对容器 + 灵活运用定位属性 ~ 现在就去ArkUI里大显身手吧！

🚀ArkUI图片全攻略 | 一文学会花式玩图技巧

---

🌈Image组件初体验

想让你的APP颜值飙升？Image组件就是你的美图秀秀！支持PNG/JPG/SVG等格式，轻松实现：
✅ 本地图片 ✅ 网络图片 ✅ 矢量图标 ✅ 动态GIF

// 基础用法三连击！
Image($r('app.media.logo')) // 资源图片
Image('images/avatar.jpg')   // 本地图片
Image('https://example.com/banner.png') // 网络图片

---

📥六种图片加载姿势

类型	使用场景	代码示例
本地图片	固定展示的图标/背景	Image('images/icon.png')
网络图片	动态更新的Banner/头像	Image('https://xxx.jpg')
资源引用	跨模块复用图片	Image($r('app.media.logo'))
媒体库	用户相册图片选择	Image('file://media/Photos/5')
Base64	小图内嵌（网页常用）	Image('data:image/png;base64,...')
PixelMap	处理解码后的像素数据	Image(pixelMap对象)

🛑网络图片必看：

1. 需要申请网络权限 ohos.permission.INTERNET
2. 首次加载会请求网络，后续自动读缓存
3. 复杂场景推荐使用ImageKnife库

---

🎯媒体库图片实战

三步get用户相册美图：

// 1. 引入媒体库模块
import { photoAccessHelper } from '@kit.MediaLibraryKit';

// 2. 创建图片选择器
let picker = new photoAccessHelper.PhotoViewPicker();
picker.select({
  MIMEType: 'IMAGE_TYPE', 
  maxSelectNumber: 5 
}).then(result => {
  // 3. 获取选中图片URI
  this.imgUrls = result.photoUris; 
})

// 在Grid中展示
Grid() {
  ForEach(this.imgUrls, (uri) => {
    GridItem() {
      Image(uri).width(200).height(200)
    }
  })
}

---

🔮矢量图魔法时间

SVG图标随心变色！

Image($r('app.media.cloud'))
  .width(50)
  .fillColor(Color.Blue) // 一键换色！

%E9%93%BE%E6%8E%A5%E5%8D%A0%E4%BD%8D%E7%AC%A6

💡嵌套位图技巧：

// 工程目录结构
ets/
  images/
    icon.svg
    sky.png 

// SVG文件内引用
<svg>
  <image xlink:href="sky.png"></image>
</svg>

---

⚙️图片属性调教指南

📐缩放模式大比拼

// 六种objectFit效果演示
Image($r('app.media.pic'))
  .objectFit(ImageFit.Contain)  // 等比例完整显示
  .objectFit(ImageFit.Cover)    // 填满容器并裁剪
  .objectFit(ImageFit.Fill)     // 拉伸变形填满

%E9%93%BE%E6%8E%A5%E5%8D%A0%E4%BD%8D%E7%AC%A6

🖼️重复平铺特效

// 四种重复模式
Image($r('app.media.pattern'))
  .objectRepeat(ImageRepeat.XY)  // 双向平铺
  .objectRepeat(ImageRepeat.X)   // 横向平铺

🎨滤镜调色板

// 添加复古滤镜
Image($r('app.media.photo'))
  .colorFilter([
    0.393, 0.769, 0.189, 0, 0,
    0.349, 0.686, 0.168, 0, 0,
    0.272, 0.534, 0.131, 0, 0,
    0,     0,     0,     1, 0
  ])

---

⚡性能优化秘籍

1. 解码尺寸控制 - 降低分辨率

Image($r('app.media.high_res'))
  .sourceSize({ width: 100, height: 100 }) // 强制解码为100x100

1. 插值抗锯齿 - 放大不模糊

Image($r('app.media.low_res'))
  .interpolation(ImageInterpolation.High) // 高质量插值

1. 同步加载 - 防闪烁（慎用！）

Image($r('app.media.banner'))
  .syncLoad(true)  // 可能阻塞UI！

---

🔔事件监听小助手

Image($r('app.media.dynamic'))
  .onComplete((msg) => { // 加载成功回调
    console.log(`图片尺寸：${msg.width}x${msg.height}`)
  })
  .onError(() => { // 加载失败处理
    console.log('图片加载失败啦！')
  })

---

🎉终极Tips：

• 网络图片记得处理加载状态（占位图+错误提示）
• SVG图标优先选择，适配不同分辨率屏幕
• 大图建议使用缩略图+点击查看原图方案
• 定期清理图片缓存防止OOM

现在就去用Image组件打造你的视觉盛宴吧！🚀

📚ArkUI文本全解 | Text和Span的魔法手册

---

🎨文本创建三连击

方式一：直接字符串

Text('我是人见人爱的文本宝宝~') 

方式二：资源引用

// 在string.json定义资源
Text($r('app.string.welcome')) 
  .fontSize(30)
  .border({ width: 1 })

彩蛋玩法：
✅ 支持多语言资源
✅ 自动适配系统字体大小
✅ 跨模块复用文本资源

---

👯Text和Span的共舞

组件	特性	使用场景
Text	独立显示文本	普通段落、标题
Span	必须嵌套在Text中使用	行内多样式文本组合

CP组合技演示：

Text('主文本') {
  Span('红色删除线').decoration({ 
    type: TextDecorationType.LineThrough, 
    color: Color.Red 
  })
  Span('蓝色下划线').decoration({
    type: TextDecorationType.Underline,
    color: Color.Blue
  })
}
.borderWidth(1)

%E9%93%BE%E6%8E%A5%E5%8D%A0%E4%BD%8D%E7%AC%A6

---

✨文本样式美容院

📐对齐与溢出

// 三种对齐方式
Text('左对齐').textAlign(TextAlign.Start)  
Text('居中').textAlign(TextAlign.Center)
Text('右对齐').textAlign(TextAlign.End)

// 超长文本处理
Text('很长很长的内容...')
  .maxLines(1)
  .textOverflow({overflow: TextOverflow.Ellipsis}) // 显示...

🎭文字变形术

Text('Hello World')
  .textCase(TextCase.UpperCase) // 全大写
  .letterSpacing(5)            // 字间距
  .baselineOffset(10)          // 基线偏移

🌈动态字号

// 自适应字号（根据容器大小）
Text('智能缩放文字')
  .maxFontSize(30)
  .minFontSize(12)
  .height(50)
  .width(200)

---

⚡交互与事件

🖱️点击响应

Text('点我有惊喜！')
  .onClick(() => {
    console.log('文本被点击啦！')
  })

Text() {
  Span('可点击Span')
    .onClick(() => {
      console.log('Span被戳中~')
    })
}

⚠️注意：

• Span仅支持点击事件
• Text支持所有通用事件（onTouch/onLongPress等）

---

🎩高级特效秀

📜滚动字幕

Text('紧急通知：ArkUI 3.0发布啦！')
  .textOverflow({overflow: TextOverflow.Marquee})
  .maxLines(1)

📋复制粘贴

Text("长按复制我")
  .copyOption(CopyOptions.InApp) // 允许应用内复制

🖌️文字阴影

Text('立体文字')
  .textShadow({
    radius: 5,
    color: Color.Grey,
    offsetX: 2,
    offsetY: 2
  })

---

💡最佳实践Tips

1. 性能优化：

• 避免在滚动视图中使用复杂Span嵌套
• 长文本优先使用Ellipsis代替Marquee

1. 国际化：

// 使用资源引用适配多语言
Text($r('app.string.greeting'))

1. 无障碍：

Text('重要提示')
  .accessibilityDescription('这是关于系统更新的重要通知')

1. 样式复用：

// 使用@Styles定义通用样式
@Styles function boldRed() {
  .fontColor(Color.Red)
  .fontWeight(FontWeight.Bold)
}

Text('重点内容').boldRed()

🎉现在就去用Text和Span打造你的文字艺术馆吧！

🚀ArkUI输入框终极指南 | TextInput & TextArea全掌握

---

📱输入框双雄登场

TextInput - 单行输入小王子
​​TextArea​​ - 多行文本大管家

// 基础创建姿势
TextInput()  // 单行输入
TextArea()   // 多行输入（自动换行）

// 带预设文本
TextArea({ text: "我是超长文本..." }).width(300) 

---

🔧九大输入类型任你选

类型	场景	代码示例
Normal	普通文本输入	.type(InputType.Normal)
Password	密码输入（圆点隐藏）	.type(InputType.Password)
Email	邮箱格式校验	.type(InputType.Email)
Number	纯数字键盘	.type(InputType.Number)
PhoneNumber	电话号码输入	.type(InputType.PhoneNumber)
URL	网址输入（自动补全）	.type(InputType.URL)
NUMBER_DECIMAL	带小数点的数字	.type(InputType.NUMBER_DECIMAL)

---

🎨个性化装扮指南

📝基础装扮三件套

TextInput({ 
  placeholder: '请输入用户名',  // 提示文字
  text: '默认内容'             // 预设文本
})
.backgroundColor(Color.Pink)  // 粉嫩背景
.fontColor(Color.Black)        // 文字颜色

🖌️高级样式魔法

✅ 边框定制
✅ 圆角效果
✅ 字体大小调整
✅ 输入框尺寸控制

TextInput()
  .width('90%')
  .height(50)
  .border({ 
    width: 2, 
    color: Color.Blue,
    radius: 10 
  })

---

⚡事件监听大师课

TextInput()
  // 内容变化实时监听
  .onChange((value: string) => {
    console.log(`输入内容：${value}`);
  })
  // 聚焦/失焦监听
  .onFocus(() => console.log('获得焦点'))
  .onBlur(() => console.log('失去焦点'))
  // 回车键响应
  .onSubmit((keyType) => {
    console.log(`回车类型：${keyType}`);
  })

---

📱登录页面实战

@Entry
@Component
struct LoginPage {
  build() {
    Column() {
      TextInput({ placeholder: '账号' })
        .margin(20)
        .type(InputType.USER_NAME)

      TextInput({ placeholder: '密码' })
        .margin(20)
        .type(InputType.PASSWORD)

      Button('登录', { type: ButtonType.Capsule })
        .width(200)
        .margin(20)
    }
    .padding(20)
  }
}

---

🛡️键盘避让黑科技

为什么需要？
手机键盘弹出时可能遮挡输入框！

解决方案：
用Scroll/List/Grid包裹输入容器

@Entry
@Component
struct ChatPage {
  build() {
    Scroll() {  // 关键包裹层！
      Column() {
        ForEach(消息列表, (消息) => {
          TextArea({ text: 消息内容 })
            .margin(10)
        })
      }
    }
    .height('100%')
  }
}

---

💡超实用技巧合集

1. 智能字号调整

TextInput()
  .maxFontSize(20)
  .minFontSize(12)  // 根据容器自动缩放

1. 禁止复制粘贴

TextInput()
  .copyOption(CopyOptions.None)

1. 输入长度限制

TextInput()
  .maxLength(10)  // 最多输入10字符

1. 光标控制

const controller = new TextInputController()
TextInput({ controller })
  .onClick(() => {
    controller.caretPosition(5)  // 光标定位到第5位
  })

---

🚨避坑指南

⚠️ 多行输入避免使用height固定高度 → 用maxLines控制
⚠️ 密码输入记得搭配.type(InputType.Password)
⚠️ 表单提交前务必做输入校验

---

🎉现在就去打造你的智能输入界面吧！ 记得多用Scroll解决键盘遮挡问题哦~ 🚀

🚀ArkUI按钮全攻略 | 玩转交互设计就靠它！

---

🛠️按钮创建双模式

模式一：文字按钮

// 基础文字按钮
Button('确认', { 
  type: ButtonType.Normal, 
  stateEffect: true  // 开启点击动效
})
.borderRadius(8)
.backgroundColor(0x317aff)
.width(90)
.height(40)

模式二：图文混合按钮

// 图标+文字组合按钮
Button({ type: ButtonType.Capsule }) {
  Row() {
    Image($r('app.media.ic_star'))
      .width(20).height(20).margin({ left: 10 })
    Text('收藏').fontSize(12).margin({ left: 5, right: 10 })
  }.alignItems(VerticalAlign.Center)
}
.backgroundColor(Color.Blue)
.width(120)

---

🎨按钮类型三剑客

类型	特性	代码示例
胶囊按钮	圆角=高度/2（不可修改）	ButtonType.Capsule
圆形按钮	正圆形状（不可修改圆角）	ButtonType.Circle
普通按钮	自定义圆角（默认直角）	ButtonType.Normal

示例对比：

// 胶囊按钮（自动圆角）
Button('删除', { type: ButtonType.Capsule })
  .width(100).height(40)

// 圆形按钮（固定圆形）
Button('+', { type: ButtonType.Circle })
  .width(60).height(60)

// 普通按钮（自定义圆角）
Button('分享', { type: ButtonType.Normal })
  .borderRadius(20)

---

✨样式美容院

🎩百变造型

// 渐变背景按钮
Button('VIP专属')
  .linearGradient({
    angle: 90,
    colors: [[0xffd700, 0], [0xff4500, 1]]
  })

// 边框发光按钮  
Button('新消息')
  .border({ 
    width: 2,
    color: Color.White,
    style: BorderStyle.Dotted
  })
  .shadow({ radius: 10, color: Color.Blue })

🖼️图标功能按钮

// 删除按钮
Button({ type: ButtonType.Circle }) {
  Image($r('app.media.ic_delete'))
    .width(30).height(30)
}
.width(50).height(50)
.backgroundColor(Color.Red)

---

⚡点击魔法

基础点击事件

Button('立即购买')
  .onClick(() => {
    console.log('商品加入购物车')
    // 这里调用支付接口
  })

防重复点击

let isProcessing = false

Button('提交订单')
  .onClick(() => {
    if (isProcessing) return
    isProcessing = true
    // 执行提交逻辑
    setTimeout(() => { isProcessing = false }, 1000)
  })

---

🚀实战演练室

📱页面导航按钮

// 跳转到设置页
Button('设置')
  .onClick(() => {
    router.pushUrl({ url: 'pages/Settings' })
  })

🔐登录注册按钮

Column() {
  TextInput({ placeholder: '手机号' })
  TextInput({ placeholder: '密码' }).type(InputType.Password)
  Button('注册', { type: ButtonType.Capsule })
    .width('80%')
    .onClick(() => {
      // 调用注册API
    })
}

🎯悬浮动作按钮

Stack() {
  List() { /* 长列表内容 */ }
  
  Button({ type: ButtonType.Circle }) {
    Image($r('app.media.ic_add'))
      .width(40).height(40)
  }
  .width(60).height(60)
  .position({ x: '85%', y: '80%' })
  .shadow({ radius: 10 })
  .onClick(() => {
    // 弹出新建内容浮层
  })
}

---

💡超实用技巧

1. 禁用状态

Button('已售罄')
  .enabled(false)  // 禁用点击
  .opacity(0.6)    // 透明度变化

1. 加载中状态

Button({ type: ButtonType.Normal }) {
  LoadingProgress().width(20).height(20)
  Text('加载中...').margin({ left: 8 })
}

1. 长按菜单

Button('长按复制')
  .onLongPress(() => {
    clipboard.copy('复制的内容')
  })

1. 按键反馈

Button('震动反馈')
  .onTouch((event) => {
    if (event.type === TouchType.Down) {
      vibrator.vibrate(50)  // 按下时震动50ms
    }
  })

---

🚨避坑指南

⚠️ 胶囊按钮不要设置borderRadius（无效）
⚠️ 图文按钮确保子组件不超过一个
⚠️ 悬浮按钮需用Stack布局防止滚动遮挡
⚠️ 提交按钮务必做防重复点击处理

---

🎉现在就去用Button点亮你的交互设计吧！ 记得多用不同样式区分主要/次要操作哦~ 🚀