Linpingzhi - HarmonyOS NEXT开发专家
专注于HarmonyOS NEXT（API 12+）原生应用开发，使用ArkTS语言和ArkUI声明式框架。
核心技术栈
- 语言: ArkTS（TypeScript超集，严格类型）
- 框架: ArkUI声明式UI
- 模型: Stage应用模型
- 工具: DevEco Studio
ArkTS语法要点
严格约束
// ✅ 正确
let name: string = '张三'
const age: number = 25
// ❌ 禁止
var x = 1 // 禁用var
let any_val: any // 禁用any
obj["key"] // 禁止动态属性状态管理装饰器
| 装饰器 | 作用域 | 同步方式 | 使用场景 |
|---|---|---|---|
| @State | 组件内 | - | 组件私有状态 |
| @Prop | 父→子 | 单向(深拷贝) | 父传子，子不影响父 |
| @Link | 父↔子 | 双向(引用) | 父子数据同步 |
| @Provide/@Consume | 跨层级 | 双向 | 爷孙组件通信 |
| @ObjectLink | 嵌套对象 | 引用 | 配合@Observed监听嵌套属性 |
| @StorageLink | 全局 | 双向 | 应用级持久化状态 |
传参语法：@Prop直接传值，@Link用$符号传引用
// 父组件
@State count: number = 0
Child({ propVal: this.count, linkVal: $count })
// 子组件
@Prop propVal: number // 单向
@Link linkVal: number // 双向组件开发模板
基础页面结构
@Entry
@Component
struct PageName {
@State message: string = 'Hello'
build() {
Column() {
Text(this.message)
.fontSize(24)
.fontWeight(FontWeight.Bold)
Button('点击')
.onClick(() => this.message = '已点击')
}
.width('100%')
.height('100%')
.justifyContent(FlexAlign.Center)
}
}自定义组件
@Component
struct CustomCard {
@Prop title: string = ''
@BuilderParam content: () => void = this.defaultContent
@Builder defaultContent() { Text('默认内容') }
build() {
Column() {
Text(this.title).fontSize(18).fontWeight(FontWeight.Bold)
this.content()
}
.padding(16)
.backgroundColor('#fff')
.borderRadius(8)
}
}复用装饰器
// @Builder - 轻量UI片段
@Builder function CardItem(title: string) {
Text(title).fontSize(16).padding(12)
}
// @Styles - 通用样式复用（不支持参数）
@Styles function cardStyle() {
.backgroundColor('#fff')
.borderRadius(8)
.padding(16)
}
// @Extend - 扩展特定组件（支持参数）
@Extend(Text) function titleText(size: number) {
.fontSize(size)
.fontWeight(FontWeight.Bold)
}列表性能优化
LazyForEach + @Reusable
// 数据源实现
class MyDataSource implements IDataSource {
private data: MyItem[] = []
totalCount(): number { return this.data.length }
getData(index: number): MyItem { return this.data[index] }
registerDataChangeListener(listener: DataChangeListener) {}
unregisterDataChangeListener(listener: DataChangeListener) {}
}
// 可复用组件
@Reusable
@Component
struct ReusableItem {
@State item: MyItem = new MyItem()
aboutToReuse(params: Record<string, Object>) {
this.item = params.item as MyItem
}
build() {
Row() {
Text(this.item.name)
}.padding(12)
}
}
// 列表使用
List() {
LazyForEach(this.dataSource, (item: MyItem) => {
ListItem() {
ReusableItem({ item: item })
}
}, (item: MyItem) => item.id.toString())
}
.cachedCount(5)动画实现
显式动画
animateTo({
duration: 500,
curve: Curve.EaseInOut,
onFinish: () => console.log('完成')
}, () => {
this.opacity = this.opacity === 1 ? 0 : 1
this.scale = this.scale === 1 ? 1.2 : 1
})转场动画
if (this.isShow) {
Column()
.transition(
TransitionEffect.OPACITY
.combine(TransitionEffect.translate({ y: 100 }))
.animation({ duration: 400, curve: Curve.EaseOut })
)
}一镜到底
Image($r('app.media.photo'))
.geometryTransition('shared_id') // 相同id实现共享元素转场路由导航
Navigation（推荐）
@Entry
@Component
struct MainPage {
pageStack: NavPathStack = new NavPathStack()
build() {
Navigation(this.pageStack) {
Button('跳转详情')
.onClick(() => this.pageStack.pushPath({ name: 'DetailPage', param: { id: 1 } }))
}
.navDestination(this.PageBuilder)
}
@Builder PageBuilder(name: string, param: Object) {
if (name === 'DetailPage') {
DetailPage({ param: param })
}
}
}路由配置 (module.json5)
{
"routerMap": "$profile:route_map"
}网络请求
import { http } from '@kit.NetworkKit'
async function fetchData<T>(url: string): Promise<T> {
const httpRequest = http.createHttp()
const response = await httpRequest.request(url, {
method: http.RequestMethod.GET,
header: { 'Content-Type': 'application/json' }
})
httpRequest.destroy()
return JSON.parse(response.result as string) as T
}数据持久化
Preferences（键值对）
import { preferences } from '@kit.ArkData'
const store = await preferences.getPreferences(context, 'settings')
await store.put('theme', 'dark')
await store.flush()
const theme = await store.get('theme', 'light')生命周期
@Entry
@Component
struct LifecyclePage {
aboutToAppear() { /* 组件创建，初始化数据 */ }
aboutToDisappear() { /* 组件销毁，清理资源 */ }
onPageShow() { /* 页面显示 */ }
onPageHide() { /* 页面隐藏 */ }
onBackPress(): boolean { return false /* 返回true拦截返回 */ }
}多设备适配
GridRow({ columns: { sm: 4, md: 8, lg: 12 } }) {
GridCol({ span: { sm: 4, md: 4, lg: 3 } }) {
CardItem()
}
}
.onBreakpointChange((bp) => this.breakpoint = bp)代码规范
- 类型安全: 始终声明类型，禁用any
- 状态管理: 根据数据流向选择正确的装饰器
- 性能优化: 长列表用LazyForEach，复杂组件用@Reusable
- 布局优先: Row/Column > Flex，减少嵌套层级
- 资源引用: 使用$r('app.xxx')引用资源
- 异步处理: 耗时操作使用TaskPool/Worker
详细参考
- 状态管理详解: references/state-management.md
- 动画完全指南: references/animation-guide.md
- 性能优化手册: references/performance.md