1. 项目概述从“Hello World”到第一个控件的跨越很多开发者朋友在接触一个新的开发框架时都会经历一个经典的“Hello World”阶段。在 eTsExtended TypeScript的语境下这通常意味着你已经在开发环境中成功运行了一个基础的页面看到了屏幕上的默认文本。这固然令人兴奋但距离真正“上手”还差关键一步——亲手编写并控制一个界面元素。今天我们就来聊聊如何迈出这坚实的一步编写你的第一个 eTs 控件。所谓“控件”你可以把它理解为构成用户界面的一个个积木块。按钮、文本框、图片、列表这些都是控件。在 eTs 中控件不仅仅是静态的显示元素更是承载了丰富属性、样式和交互逻辑的“活”的组件。编写第一个控件意味着你将从被动的“看”代码转变为主动的“写”代码去定义这个积木块长什么样、能做什么。这个过程是理解 eTs 声明式 UI 编程范式和组件化思想的最佳切入点。无论你是前端开发者想探索新的技术栈还是移动应用开发者对跨端开发感兴趣掌握控件的编写都是构建任何复杂应用的基础。2. 环境准备与项目结构再审视在动手编写控件之前确保你的开发环境已经就绪并且对项目结构有一个清晰的认识这能避免很多后续的路径和依赖问题。2.1 开发环境确认首先你需要一个支持 eTs 的开发环境。目前主流的集成开发环境IDE是 DevEco Studio。请确保你已经安装了最新稳定版本并且正确配置了相关的 SDK 和工具链。打开你的第一个 eTs 项目通常是创建项目时默认生成的“Hello World”示例在项目根目录下你应该能看到类似这样的结构MyFirstEtApp/ ├── entry/ │ ├── src/ │ │ ├── main/ │ │ │ ├── ets/ │ │ │ │ ├── pages/ │ │ │ │ │ └── Index.ets // 这是我们主要编辑的文件 │ │ │ │ └── ... │ │ │ ├── resources/ // 存放图片、字符串等资源 │ │ │ └── module.json5 // 应用配置文件 │ │ └── ... └── ...我们绝大部分的编码工作将在entry/src/main/ets/pages/Index.ets这个文件中进行。这个文件定义了一个页面也是我们放置控件的地方。2.2 理解基础页面模板打开Index.ets你最初看到的代码可能类似这样Entry Component struct Index { State message: string Hello World build() { Row() { Column() { Text(this.message) .fontSize(50) .fontWeight(FontWeight.Bold) } .width(100%) } .height(100%) } }我们来快速拆解一下这个结构Entry: 装饰器表示这个组件是应用的入口页面。Component: 装饰器表示这是一个自定义组件控件。struct Index: 定义了一个名为Index的结构体这就是我们的页面组件。State message: string Hello World: 定义了一个状态变量message其初始值为 ‘Hello World’。State装饰器意味着这个变量是响应式的当它的值改变时所有依赖它的 UI 部分会自动更新。build()方法: 这是组件的核心它描述了 UI 的结构。它必须返回一个 UI 组件。Row()和Column(): 是布局容器控件。Row水平排列子组件Column垂直排列。这里用了一个Row包含一个Column目的是让Column在屏幕上水平和垂直都居中通过后续的.width(100%)和.height(100%)实现。Text(this.message): 这就是一个文本控件。它显示message状态变量的值。后面的.fontSize(50)和.fontWeight(FontWeight.Bold)是它的属性方法用于设置样式。所以其实你已经见过一个控件了——Text。但它是现成的我们接下来要做的是更主动地去创建一个控件并赋予它更复杂的行为。3. 第一个自定义控件一个可交互的按钮我们不再满足于仅仅显示文本而是要创建一个可以点击、并有视觉反馈的按钮。这个按钮点击后会改变上面显示的文本内容。3.1 规划控件功能与状态在动手写代码前先明确我们要做什么UI 元素一个背景色为蓝色的圆角矩形按钮内部有白色的文字例如“点击我”。交互逻辑当手指按下按钮时按钮的背景色略微变深模拟按压效果。当手指松开时恢复原色并触发一个“点击”事件。数据联动按钮的点击事件能修改页面上另一个文本控件显示的内容。为了实现这些我们需要管理几个状态按钮当前的按压状态是否被按下。页面上需要被改变的文本内容。3.2 逐步实现自定义按钮组件我们不直接在Index页面的build方法里堆砌所有代码而是采用组件化的思想先创建一个独立的按钮组件。在pages目录下或者为了更好地管理在ets目录下创建一个components文件夹然后新建MyButton.ets文件。第一步定义组件结构和基础属性// MyButton.ets Component export struct MyButton { // 按钮上显示的文字由外部传入 private label: string 按钮 // 按钮的背景色默认蓝色 private backgroundColor: Color Color.Blue // 按钮被按下时的背景色 private activeColor: Color Color.Grey // 按钮的点击事件回调函数由外部传入 private onClick: () void () {} // 内部状态记录按钮是否被按下 State private isPressed: boolean false build() { // 构建函数返回按钮的UI } }这里我们定义了几个属性label,backgroundColor,activeColor,onClick这些是组件的参数使用private修饰意味着它们需要在创建组件时从外部提供。我们暂时给了默认值。isPressed这是一个内部状态用State装饰用于控制按钮的按压视觉反馈。第二步构建UI与添加手势现在我们在build()方法中描述这个按钮长什么样以及如何交互。build() { // 使用Text组件显示按钮文字并用Column和Padding来增加可点击区域和美观度 Column() { Text(this.label) .fontSize(18) .fontColor(Color.White) .fontWeight(FontWeight.Medium) } .padding({ top: 12, bottom: 12, left: 24, right: 24 }) // 内边距让文字不紧贴边缘 .backgroundColor(this.isPressed ? this.activeColor : this.backgroundColor) // 根据按压状态切换颜色 .borderRadius(24) // 圆角值越大越圆 .opacity(this.isPressed ? 0.9 : 1.0) // 按压时稍微降低透明度 .gesture( // 添加手势识别 TapGesture({ count: 1 }) // 监听单次点击 .onActionStart(() { // 手势动作开始手指按下 this.isPressed true }) .onActionEnd(() { // 手势动作结束手指抬起 this.isPressed false }) .onAction(() { // 点击动作完成时触发 console.info(MyButton被点击了) this.onClick() // 执行外部传入的回调函数 }) .onActionCancel(() { // 手势被取消如滑动出了控件区域 this.isPressed false }) ) }这段代码是核心视觉部分用一个Column包裹Text并设置内边距、背景色、圆角。背景色和透明度通过三元运算符? :根据isPressed状态动态切换。交互部分.gesture()方法为组件添加了手势识别器。我们使用了TapGesture点击手势。onActionStart手指按下瞬间触发我们在这里将isPressed设为true触发UI更新变颜色。onActionEnd手指抬起触发将isPressed复位。onAction完整的点击动作按下并抬起完成后触发这里我们打印日志并调用外部传入的onClick回调函数。onActionCancel非常重要当手势被意外取消时比如按下后滑出按钮区域必须在这里复位状态否则按钮会保持“按下”样式。注意手势事件的这几个生命周期回调必须正确实现否则会导致交互状态“卡住”这是新手常踩的坑。务必在onActionEnd或onActionCancel中清理按压状态。第三步优化组件接口使用Prop和Link上面的组件能用但它的参数label,onClick等是固定的无法从外部设置。为了让组件更通用我们需要使用专门的装饰器来定义它的公共接口。修改MyButton.etsComponent export struct MyButton { // Prop 装饰的变量允许从父组件传入且在子组件内部变化不会同步回父组件单向同步 Prop label: string 按钮 Prop backgroundColor: Color Color.Blue Prop activeColor: Color Color.Grey // 事件回调使用常规函数属性即可 private onClick?: () void State private isPressed: boolean false build() { // ... build 方法内部代码不变但引用的是 this.label, this.backgroundColor 等 Column() { Text(this.label) // 使用 Prop 传入的 label .fontSize(18) .fontColor(Color.White) .fontWeight(FontWeight.Medium) } .padding({ top: 12, bottom: 12, left: 24, right: 24 }) .backgroundColor(this.isPressed ? this.activeColor : this.backgroundColor) // 使用 Prop 传入的颜色 .borderRadius(24) .opacity(this.isPressed ? 0.9 : 1.0) .gesture( TapGesture({ count: 1 }) .onActionStart(() { this.isPressed true }) .onActionEnd(() { this.isPressed false }) .onAction(() { console.info(按钮“${this.label}”被点击) // 安全地调用回调函数 this.onClick?.() }) .onActionCancel(() { this.isPressed false }) ) } }现在父组件如Index就可以在创建MyButton时传入自定义的文字、颜色和点击事件了。4. 在主页中集成并使用自定义控件现在让我们回到Index.ets使用我们刚刚创建的这个炫酷按钮。4.1 修改主页逻辑首先我们需要在Index页面中引入MyButton组件并定义页面所需的状态。// Index.ets import { MyButton } from ../components/MyButton // 根据实际路径调整 Entry Component struct Index { // 页面状态文本消息 State message: string 等待按钮点击... // 页面状态记录点击次数 State clickCount: number 0 build() { Row() { Column() { // 原有的Text控件显示动态消息 Text(this.message) .fontSize(30) .fontWeight(FontWeight.Bold) .margin({ bottom: 40 }) // 显示点击次数 Text(点击次数${this.clickCount}) .fontSize(20) .fontColor(Color.Gray) .margin({ bottom: 60 }) // 使用我们的自定义按钮 MyButton({ label: 点我改变文字, // 传入按钮文字 backgroundColor: Color.RoyalBlue, // 传入自定义背景色 activeColor: Color.DarkBlue, // 传入按压颜色 onClick: () { // 定义点击回调函数 this.clickCount 1 this.message 你好eTs(第${this.clickCount}次点击) } }) // 再添加一个按钮演示不同的回调 MyButton({ label: 重置, backgroundColor: Color.Orange, activeColor: Color.DarkOrange, onClick: () { this.clickCount 0 this.message 状态已重置 } }) .margin({ top: 20 }) // 给第二个按钮加上上边距 } .width(100%) } .height(100%) .padding(20) // 给页面整体加个内边距避免内容紧贴屏幕边缘 } }4.2 效果解析与交互流程现在运行你的应用。你会看到页面上方显示着“等待按钮点击...”和“点击次数0”。下方有一个蓝色按钮写着“点我改变文字”。当你用手指按下它时它会变成深蓝色并略微透明松开后恢复同时上方的文本会变为“你好eTs(第1次点击)”点击次数变为1。橙色按钮“重置”同理点击后会将计数归零文本重置。整个交互的数据流是清晰的Index页面维护着message和clickCount状态。将onClick回调函数传递给MyButton组件。这个回调函数内部会修改Index页面的状态。当MyButton被点击触发其内部的onAction手势回调执行了从父页面传来的onClick函数。Index页面中的message和clickCount状态发生变化。由于Text(this.message)和Text(点击次数${this.clickCount})绑定了这些状态它们会自动重新渲染更新显示内容。这就是 eTs 声明式 UI 和响应式数据绑定的核心魅力你只需要描述状态和UI之间的关系状态变化UI自动更新。5. 控件样式深度定制与布局探索我们的MyButton目前样式还比较简单。eTs 提供了强大的链式调用API来设置样式让我们来丰富一下。5.1 扩展样式属性我们可以给MyButton增加更多可配置的样式属性比如字体大小、字体颜色、圆角大小、边框等。// 在 MyButton 结构体内增加 Prop 属性 Component export struct MyButton { Prop label: string 按钮 Prop backgroundColor: Color Color.Blue Prop activeColor: Color Color.Grey Prop fontColor: Color Color.White // 新增文字颜色 Prop fontSize: number 18 // 新增文字大小 Prop borderRadius: number 24 // 新增圆角半径 Prop borderWidth?: number // 新增边框宽度可选 Prop borderColor?: Color // 新增边框颜色可选 private onClick?: () void State private isPressed: boolean false build() { Column() { Text(this.label) .fontSize(this.fontSize) .fontColor(this.fontColor) // 使用传入的文字颜色 .fontWeight(FontWeight.Medium) } .padding({ top: 12, bottom: 12, left: 24, right: 24 }) .backgroundColor(this.isPressed ? this.activeColor : this.backgroundColor) .borderRadius(this.borderRadius) // 使用传入的圆角半径 .opacity(this.isPressed ? 0.9 : 1.0) // 条件性地添加边框样式 .border({ width: this.borderWidth ? this.borderWidth : 0, color: this.borderColor ? this.borderColor : Color.Black }) .gesture( // ... 手势代码不变 ) } }在Index页面中你就可以这样使用MyButton({ label: 有边框的按钮, backgroundColor: Color.Transparent, // 透明背景 fontColor: Color.Blue, fontSize: 16, borderRadius: 8, borderWidth: 2, borderColor: Color.Blue, onClick: () { /* ... */ } })5.2 理解布局容器Row, Column, Flex, Stack控件本身需要被放置在合适的容器中才能构成完整的页面布局。eTs 提供了几种基础布局容器Column垂直方向排列子组件。子组件默认从上到下排列。Row水平方向排列子组件。子组件默认从左到右排列。Flex弹性布局功能强大可以通过justifyContent和alignItems在主轴上和交叉轴上灵活对齐子组件。Stack堆叠布局子组件会重叠在一起适用于实现浮层、叠加效果。例如如果你想将两个按钮水平并排居中可以这样做Column() { Text(按钮组) Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { MyButton({ label: 按钮A, onClick: () {} }) MyButton({ label: 按钮B, onClick: () {} }).margin({ left: 10 }) } .width(100%) .margin({ top: 20 }) }Flex容器使得内部的按钮可以在水平和垂直方向上都居中margin({ left: 10 })则为第二个按钮添加了左间距。6. 常见问题与调试技巧实录编写和调试控件时你肯定会遇到一些问题。这里记录一些典型场景和解决思路。6.1 控件不显示或显示异常问题自定义控件在预览或运行时完全看不到或者样式错乱。排查检查导入路径在Index.ets中import的路径是否正确。../components/MyButton表示上一级目录的components文件夹。如果文件移动了路径也要相应修改。检查build()方法确保build()方法返回了一个有效的组件。有时忘记写return或者最后一行不是组件会导致渲染空白。在 eTs 中build()方法直接返回最后一个表达式的值通常我们直接写组件树。检查样式冲突如果控件显示但样式不对检查链式调用中是否有属性被覆盖。例如先写了.width(100)后面又写了.width(100%)最终生效的是最后一个。使用预览器刷新DevEco Studio 的预览器有时会有缓存。尝试点击预览器上的刷新按钮或者保存文件后等待自动刷新。6.2 手势交互无响应或状态“卡住”问题点击按钮没有反应或者按下后按钮一直保持按压状态。排查确认手势事件绑定检查是否在控件上正确添加了.gesture(TapGesture(...))。检查手势回调这是最常见的原因。务必完整实现onActionStart,onActionEnd,onActionCancel。特别是在onActionCancel中一定要将按压状态isPressed重置为false。如果只写了onActionStart设为true而没在onActionEnd或onActionCancel中设为false状态就会一直为真。检查控件尺寸有时控件看起来很大但实际可点击区域很小比如只有文字部分。确保包裹控件的容器如Column有足够的尺寸或者通过.width()、.height()或.padding()来扩大热区。查看日志在onAction回调中添加console.info打印日志可以在 DevEco Studio 的Log窗口查看确认点击事件是否真的触发了。6.3 样式设置不生效问题设置了.fontSize()、.backgroundColor()等属性但界面上没变化。排查优先级问题后设置的属性会覆盖先设置的。检查代码顺序。属性值类型确认传入的值类型正确。例如.fontSize(‘20’)传入的是字符串而它需要数字20。.backgroundColor(‘blue’)是错误的需要Color.Blue。父容器约束有时子控件的尺寸受父容器约束。例如父Column设置了固定高度子Text设置fontSize很大可能显示不全。可以尝试给子控件设置.layoutWeight(1)或检查父容件的尺寸属性。6.4 性能与最佳实践小贴士避免在build()中执行复杂逻辑build()方法在状态更新时可能会被频繁调用。将数据准备、计算等逻辑放在生命周期函数如aboutToAppear或单独的方法中。合理使用State,Prop,LinkState用于组件内部管理私有状态变化会触发自身UI更新。Prop用于从父组件向子组件单向传递数据。子组件可以修改本地值但不会同步回父组件。适用于展示型组件。Link用于在父子组件间建立双向数据绑定。任何一方的修改都会同步到另一方。适用于需要联动修改的场景使用时需谨慎避免循环更新。组件拆分当一个页面的build()方法变得非常庞大时考虑将其中可复用的部分拆分成更小的子组件。这有助于代码维护、复用和性能优化因为只有状态变化的组件会重新渲染。编写第一个控件的过程是一个从理解到创造的过程。你不再只是框架功能的使用者而是开始成为界面和交互的定义者。通过这个简单的按钮你已经触及了 eTs 开发的核心组件化设计、声明式 UI 描述、响应式状态管理以及手势交互处理。以此为起点你可以尝试去封装更复杂的控件如图片按钮、开关、滑块等逐步构建起属于自己的组件库这是迈向熟练 eTs 开发者的重要一步。