ui_edit_text

ui_edit_text 模块提供文本输入框组件，支持文本编辑、光标管理与内容变化事件监听。

Class Summary

OHOS::UIEditText

文本输入编辑视图，支持文本/密码输入模式、占位符显示及光标动画

• 构造：无

• 成员函数：

  接口名称	功能简述
  GetViewType	获取视图类型
  OnPressEvent	处理按压事件
  SetStyle	设置视图样式
  OnPreDraw	判断绘制前是否需要遮盖
  OnDraw	绘制视图
  Focus	获取焦点
  Blur	失去焦点
  SetText	设置文本内容
  GetText	获取输入文本
  SetPlaceholder	设置占位符内容
  GetPlaceholder	获取占位符内容
  SetMaxLength	设置最大输入长度
  GetMaxLength	获取最大输入长度
  SetInputType	设置输入类型
  GetInputType	获取输入类型
  SetTextColor	设置文本颜色
  GetTextColor	获取文本颜色
  SetPlaceholderColor	设置占位符颜色
  GetPlaceholderColor	获取占位符颜色
  SetCursorColor	设置光标颜色
  GetCursorColor	获取光标颜色
  SetFontId	设置字体ID
  GetFontId	获取字体ID
  SetFont	设置字体名称和大小
  GetTextWidth	获取文本宽度
  GetTextHeight	获取文本高度
  ReMeasure	重新测量文本尺寸
  InsertText	插入输入法传入的文本
  DeleteBackward	向前删除指定长度字符
  SetOnChangeListener	设置值变化监听器
  GetOnChangeListener	获取值变化监听器

• 使用包含头文件：#include "components/ui_edit_text.h"

• 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/ui_edit_text.h
• 公有运算符：无
• 继承关系：UIView
• 嵌套类型：OnChangeListener
• 模板形参：无

OHOS::UIEditText::OnChangeListener

值变化事件监听器，注册后可在编辑文本值变化时触发回调

• 构造：无

• 成员函数：

  接口名称	功能简述
  OnChange	值变化时的回调函数

• 使用包含头文件：#include "components/ui_edit_text.h"

• 声明头文件：middleware/services/gui/uikit/ui/interfaces/kits/components/ui_edit_text.h
• 公有运算符：无
• 继承关系：HeapBase
• 嵌套类型：无
• 模板形参：无

Functions

OHOS::UIEditText

GetViewType

virtual UIViewType GetViewType() const override

功能说明

• 核心用途：获取当前视图的类型标识
• 返回类型为 UI_EDIT_TEXT，用于在视图系统中区分编辑文本视图
• 使用场景：视图类型判断、事件路由分发

返回值

• 返回类型：UIViewType

返回视图类型标识

返回值	触发场景
UI_EDIT_TEXT	当前视图为编辑文本视图

OnPressEvent

bool OnPressEvent(const PressEvent& event) override

功能说明

• 核心用途：处理按压事件，请求焦点并激活输入法
• 设计目的：响应触摸/按键操作，使编辑框获得焦点
• 使用场景：用户触摸编辑框时触发

入参

名称	参数类型	详细说明	约束取值范围
event	const PressEvent&	入参只读引用，按压事件信息，包含按压位置	有效PressEvent对象

返回值

• 返回类型：bool

返回事件是否被消费

返回值	触发场景
true	事件被消费
false	事件未被消费

SetStyle

void SetStyle(Style& style) override

功能说明

• 核心用途：设置视图的完整样式
• 设置样式后会刷新文本显示
• 使用场景：需要整体更新编辑框外观时调用

入参

名称	参数类型	详细说明	约束取值范围
style	Style&	入参引用，视图样式对象	有效Style对象

SetStyle

void SetStyle(uint8_t key, int64_t value) override

功能说明

• 核心用途：按键值对设置单个样式属性
• 设置样式后会刷新文本显示
• 使用场景：仅修改某一样式属性时调用

入参

名称	参数类型	详细说明	约束取值范围
key	uint8_t	样式键值	有效样式键
value	int64_t	样式值	对应键的有效取值

OnPreDraw

bool OnPreDraw(Rect& invalidatedArea) const override

功能说明

• 核心用途：判断绘制前视图是否需要被遮盖
• 固定返回 false，表示不需要遮盖
• 使用场景：绘制流程中的预处理判断

入参

名称	参数类型	详细说明	约束取值范围
invalidatedArea	Rect&	入参引用，待绘制区域	有效Rect对象

返回值

• 返回类型：bool

返回是否需要遮盖

返回值	触发场景
false	编辑文本视图无需遮盖

OnDraw

void OnDraw(BufferInfo& gfxDstBuffer, const Rect& invalidatedArea) override

功能说明

• 核心用途：绘制编辑文本视图内容
• 有文本时绘制文本，无文本时绘制占位符；焦点状态下绘制光标
• 使用场景：UI 渲染流程中调用

入参

名称	参数类型	详细说明	约束取值范围
gfxDstBuffer	BufferInfo&	入参引用，图形目标缓冲区	有效BufferInfo对象
invalidatedArea	const Rect&	入参只读引用，无效区域	有效Rect对象

Focus

void Focus() override

功能说明

• 核心用途：使编辑框获得焦点并启动光标动画
• 获取焦点后光标开始闪烁
• 使用场景：用户点击编辑框或通过导航切换焦点时

Blur

void Blur() override

功能说明

• 核心用途：使编辑框失去焦点并停止光标动画
• 失去焦点后光标停止闪烁并隐藏
• 使用场景：用户点击其他区域或通过导航切换焦点时

SetText

void SetText(const char* text)

功能说明

• 核心用途：设置编辑框的文本内容
• 传入 nullptr 时不执行任何操作；超长文本会被截断至最大长度
• 使用场景：程序化设置编辑框初始文本或更新内容

入参

名称	参数类型	详细说明	约束取值范围
text	const char*	入参指针，指向文本内容，不可为 nullptr	有效的C字符串指针

GetText

const char* GetText()

功能说明

• 核心用途：获取编辑框当前输入文本
• 返回内部字符串的C风格指针
• 使用场景：读取用户输入内容

返回值

• 返回类型：const char*

返回文本内容的C字符串指针

返回值	触发场景
非空指针	正常返回文本内容
空字符串	编辑框无内容

SetPlaceholder

void SetPlaceholder(const char* placeholder)

功能说明

• 核心用途：设置编辑框的占位符文本
• 占位符在编辑框无输入内容时显示
• 使用场景：提示用户应输入的内容

入参

名称	参数类型	详细说明	约束取值范围
placeholder	const char*	入参指针，指向占位符文本内容	有效的C字符串指针

GetPlaceholder

const char* GetPlaceholder()

功能说明

• 核心用途：获取编辑框的占位符文本
• 未设置占位符时返回空字符串
• 使用场景：读取当前占位符内容

返回值

• 返回类型：const char*

返回占位符文本的C字符串指针

返回值	触发场景
非空指针	正常返回占位符内容
空字符串	未设置占位符

SetMaxLength

void SetMaxLength(uint16_t maxLength)

功能说明

• 核心用途：设置编辑框最大可输入字符长度
• 超过 MAX_TEXT_LENGTH 的值会被截断为 MAX_TEXT_LENGTH；设置后若当前文本超出新长度则自动截断
• 使用场景：限制用户输入字数

入参

名称	参数类型	详细说明	约束取值范围
maxLength	uint16_t	最大输入字符长度	0 ~ MAX_TEXT_LENGTH

GetMaxLength

uint16_t GetMaxLength()

功能说明

• 核心用途：获取编辑框最大可输入字符长度
• 默认值为 MAX_TEXT_LENGTH
• 使用场景：查询当前输入长度限制

返回值

• 返回类型：uint16_t

返回最大输入长度

返回值	触发场景
maxLength	当前设置的最大输入长度

SetInputType

void SetInputType(InputType type)

功能说明

• 核心用途：设置输入类型（文本或密码）
• 密码模式下输入字符显示为圆点
• 使用场景：切换文本/密码输入模式

入参

名称	参数类型	详细说明	约束取值范围
type	InputType	输入类型	InputType枚举值

GetInputType

InputType GetInputType()

功能说明

• 核心用途：获取当前输入类型
• 默认为 TEXT_TYPE
• 使用场景：查询当前输入模式

返回值

• 返回类型：InputType

返回输入类型

返回值	触发场景
TEXT_TYPE	文本输入模式
PASSWORD_TYPE	密码输入模式

SetTextColor

void SetTextColor(ColorType color)

功能说明

• 核心用途：设置编辑框文本颜色
• 设置后覆盖主题默认文本颜色
• 使用场景：自定义编辑框文本显示颜色

入参

名称	参数类型	详细说明	约束取值范围
color	ColorType	入参只读，文本颜色值	有效ColorType值

GetTextColor

ColorType GetTextColor() const

功能说明

• 核心用途：获取编辑框文本颜色
• 未单独设置时返回主题样式中定义的文本颜色
• 使用场景：查询当前文本颜色

返回值

• 返回类型：ColorType

返回文本颜色值

返回值	触发场景
ColorType	已设置自定义颜色时返回该颜色；未设置时返回主题默认颜色

SetPlaceholderColor

void SetPlaceholderColor(ColorType color)

功能说明

• 核心用途：设置编辑框占位符文本颜色
• 使用场景：自定义占位符显示颜色

入参

名称	参数类型	详细说明	约束取值范围
color	ColorType	入参只读，占位符颜色值	有效ColorType值

GetPlaceholderColor

ColorType GetPlaceholderColor() const

功能说明

• 核心用途：获取编辑框占位符文本颜色
• 使用场景：查询当前占位符颜色

返回值

• 返回类型：ColorType

返回占位符颜色值

返回值	触发场景
ColorType	当前占位符颜色

SetCursorColor

void SetCursorColor(ColorType color)

功能说明

• 核心用途：设置编辑框光标颜色
• 使用场景：自定义光标显示颜色

入参

名称	参数类型	详细说明	约束取值范围
color	ColorType	入参只读，光标颜色值	有效ColorType值

GetCursorColor

ColorType GetCursorColor() const

功能说明

• 核心用途：获取编辑框光标颜色
• 使用场景：查询当前光标颜色

返回值

• 返回类型：ColorType

返回光标颜色值

返回值	触发场景
ColorType	当前光标颜色

SetFontId

void SetFontId(uint16_t fontId)

功能说明

• 核心用途：设置编辑框文本和占位符的字体ID
• 字体ID由字体名称和大小组成
• 使用场景：通过ID快速切换字体

入参

名称	参数类型	详细说明	约束取值范围
fontId	uint16_t	字体ID，由字体名称和大小组成	有效字体ID

GetFontId

uint8_t GetFontId()

功能说明

• 核心用途：获取编辑框当前字体ID
• 使用场景：查询当前字体配置

返回值

• 返回类型：uint8_t

返回字体ID

返回值	触发场景
fontId	当前字体ID

SetFont

void SetFont(const char* name, uint8_t size)

功能说明

• 核心用途：通过字体名称和大小设置编辑框字体
• 同时应用于文本和占位符
• 使用场景：通过名称和大小指定字体

入参

名称	参数类型	详细说明	约束取值范围
name	const char*	入参指针，字体名称	有效的C字符串指针
size	uint8_t	字体大小	有效字号

GetTextWidth

uint16_t GetTextWidth()

功能说明

• 核心用途：获取编辑框文本的绘制宽度
• 若文本需要刷新会先触发重新测量
• 使用场景：布局计算中获取文本宽度

返回值

• 返回类型：uint16_t

返回文本宽度（像素）

返回值	触发场景
width	文本绘制宽度

GetTextHeight

uint16_t GetTextHeight()

功能说明

• 核心用途：获取编辑框文本的绘制高度
• 若文本需要刷新会先触发重新测量
• 使用场景：布局计算中获取文本高度

返回值

• 返回类型：uint16_t

返回文本高度（像素）

返回值	触发场景
height	文本绘制高度

ReMeasure

void ReMeasure() override

功能说明

• 核心用途：重新测量编辑框文本尺寸
• 根据当前样式和内容重新计算文本和占位符的尺寸及省略位置
• 使用场景：样式或内容变化后需要更新测量结果

InsertText

virtual void InsertText(std::string text)

功能说明

• 核心用途：在当前文本末尾插入输入法传入的文本
• 插入后会重启光标动画
• 使用场景：输入法回调中向编辑框插入文字

入参

名称	参数类型	详细说明	约束取值范围
text	std::string	入参只读，要插入的文本	有效字符串

DeleteBackward

virtual void DeleteBackward(uint32_t length)

功能说明

• 核心用途：从当前文本末尾向前删除指定长度的字符
• 按 UTF-8 字符边界删除；删除长度超过现有文本长度时清空全部文本
• 使用场景：输入法回调中执行退格删除

入参

名称	参数类型	详细说明	约束取值范围
length	uint32_t	要删除的字符数	0 ~ 当前文本字符数

SetOnChangeListener

void SetOnChangeListener(OnChangeListener* onChangeListener)

功能说明

• 核心用途：设置值变化事件监听器
• 文本内容发生变化时触发监听器回调
• 使用场景：监听编辑框内容变化

入参

名称	参数类型	详细说明	约束取值范围
onChangeListener	OnChangeListener*	入参指针，值变化监听器对象	有效指针或nullptr

GetOnChangeListener

OnChangeListener*& GetOnChangeListener()

功能说明

• 核心用途：获取当前值变化事件监听器的引用
• 返回引用可用于直接修改监听器指针
• 使用场景：查询或替换当前监听器

返回值

• 返回类型：OnChangeListener*

返回监听器指针的引用

返回值	触发场景
非空指针引用	已设置监听器
nullptr引用	未设置监听器

OHOS::UIEditText::OnChangeListener

OnChange

virtual void OnChange(UIView& view, const char* value)

功能说明

• 核心用途：编辑文本值变化时的回调函数
• 默认实现为空，子类需重写以实现自定义逻辑
• 使用场景：继承 OnChangeListener 并重写此方法以响应文本变化

入参

名称	参数类型	详细说明	约束取值范围
view	UIView&	入参引用，触发值变化的编辑视图	有效UIView引用
value	const char*	入参指针，变化后的新值	有效的C字符串指针

Enumerations

InputType

enum class InputType {
    TEXT_TYPE,
    PASSWORD_TYPE
};

枚举成员	取值	描述
TEXT_TYPE	0	文本输入模式，输入内容明文显示
PASSWORD_TYPE	1	密码输入模式，输入内容以圆点显示