定义CustomSpan相关的结构体和接口,用于实现自定义绘制Span的精确尺寸测量、布局排版和绘制效果。支持开发者在富文本编辑器、聊天应用、文档应用等场景中实现图文混排、表情内嵌、自定义标记等功能,提供灵活的自定义绘制Span能力,帮助开发者提升开发效率,实现更丰富的文本排版效果。
引用文件: <arkui/node_attributes/custom_span.h>
库: libace_ndk.z.so
系统能力: SystemCapability.ArkUI.ArkUI.Full
起始版本: 12
相关模块: ArkUI_NativeModule
相关示例: native_type_sample
| 名称 | typedef关键字 | 描述 |
|---|---|---|
| ArkUI_CustomSpanMeasureInfo | ArkUI_CustomSpanMeasureInfo | 自定义绘制Span的测量信息。该结构体用于在自定义绘制Span的测量回调中提供组件的测量数据,帮助开发者实现自定义文本组件的精确尺寸测量与布局排版。 |
| ArkUI_CustomSpanMetrics | ArkUI_CustomSpanMetrics | 自定义绘制Span的度量指标,用于设置组件的宽高等布局信息。适用于富文本编辑器、聊天应用等场景的图文混排。 |
| ArkUI_CustomSpanDrawInfo | ArkUI_CustomSpanDrawInfo | 自定义绘制Span的绘制信息,用于在该组件的绘制回调中向开发者传递绘制信息,开发者可在自定义绘制流程中获取并使用该信息,实现定制化的段落组件绘制效果。 |
ArkUI_CustomSpanMeasureInfo* OH_ArkUI_CustomSpanMeasureInfo_Create(void)
描述
创建自定义绘制Span测量信息。
必须与OH_ArkUI_CustomSpanMeasureInfo_Dispose()配对使用。
调用流程:OH_ArkUI_CustomSpanMeasureInfo_Create()→使用info对象→OH_ArkUI_CustomSpanMeasureInfo_Dispose()释放资源。
使用完毕后必须调用OH_ArkUI_CustomSpanMeasureInfo_Dispose()释放内存,否则会导致资源泄漏。
起始版本: 12
返回:
| 类型 | 说明 |
|---|---|
| ArkUI_CustomSpanMeasureInfo* | ArkUI_CustomSpanMeasureInfo实例,用于在自定义绘制Span的测量回调中提供组件的测量数据。 如果返回空指针,可能是因为内存不足。 |
void OH_ArkUI_CustomSpanMeasureInfo_Dispose(ArkUI_CustomSpanMeasureInfo* info)
描述
销毁自定义绘制Span测量信息。
必须与OH_ArkUI_CustomSpanMeasureInfo_Create()配对使用。
仅用于销毁由OH_ArkUI_CustomSpanMeasureInfo_Create()方法创建的测量信息对象。
调用前确保已不再需要该对象,调用后该对象不可再使用。
起始版本: 12
参数:
| 参数项 | 描述 |
|---|---|
| ArkUI_CustomSpanMeasureInfo* info | 自定义绘制Span测量信息指针,用于传入需要销毁的测量信息对象。参数不能为空,否则会导致参数验证失败。必须是由OH_ArkUI_CustomSpanMeasureInfo_Create()创建的对象。 |
float OH_ArkUI_CustomSpanMeasureInfo_GetFontSize(ArkUI_CustomSpanMeasureInfo* info)
描述
获取自定义绘制Span的父节点Text的字体大小。在自定义绘制Span的测量回调中,可根据父节点Text的字体大小计算自定义组件的布局尺寸,用于实现图文混排、表情内嵌等场景的精确排版。
必须先调用OH_ArkUI_CustomSpanMeasureInfo_Create()创建测量信息对象。
参数info必须是通过OH_ArkUI_CustomSpanMeasureInfo_Create()方法返回的有效对象指针。
起始版本: 12
参数:
| 参数项 | 描述 |
|---|---|
| ArkUI_CustomSpanMeasureInfo* info | 自定义绘制Span测量信息指针。参数不能为空,否则会导致参数验证失败。 |
返回:
| 类型 | 说明 |
|---|---|
| float | 父节点Text的字体大小,单位为fp。若参数验证失败,返回0.0f。 异常返回原因:参数验证失败,参数不能为空。 |
ArkUI_CustomSpanMetrics* OH_ArkUI_CustomSpanMetrics_Create(void)
描述
创建自定义绘制Span度量信息。
必须与OH_ArkUI_CustomSpanMetrics_Dispose()配对使用。
调用流程:OH_ArkUI_CustomSpanMetrics_Create()→设置宽高(可选)→使用metrics对象→OH_ArkUI_CustomSpanMetrics_Dispose()释放资源。
使用完毕后必须调用OH_ArkUI_CustomSpanMetrics_Dispose()释放内存,否则会导致资源泄漏。
起始版本: 12
返回:
| 类型 | 说明 |
|---|---|
| ArkUI_CustomSpanMetrics* | ArkUI_CustomSpanMetrics实例,用于描述自定义绘制Span的宽高等布局信息。 如果返回空指针,可能是因为内存不足。 |
void OH_ArkUI_CustomSpanMetrics_Dispose(ArkUI_CustomSpanMetrics* metrics)
描述
销毁自定义绘制Span度量信息。
必须与OH_ArkUI_CustomSpanMetrics_Create()配对使用。
仅用于销毁由OH_ArkUI_CustomSpanMetrics_Create()方法创建的度量信息对象。
调用前确保已不再需要该对象,调用后该对象不可再使用。
起始版本: 12
参数:
| 参数项 | 描述 |
|---|---|
| ArkUI_CustomSpanMetrics* metrics | 自定义绘制Span度量信息实例指针,用于传入需要销毁的度量信息对象。参数不能为空,否则会导致参数验证失败。必须是由OH_ArkUI_CustomSpanMetrics_Create()创建的对象。 |
int32_t OH_ArkUI_CustomSpanMetrics_SetWidth(ArkUI_CustomSpanMetrics* metrics, float width)
描述
设置自定义绘制Span的宽度。在图文混排场景中,需要为嵌入的图片或表情设置合适的宽度以匹配文本行高;在文档应用中,可能需要为自定义标记元素设置固定宽度。
必须先调用OH_ArkUI_CustomSpanMetrics_Create()创建度量信息对象。
参数metrics必须是通过OH_ArkUI_CustomSpanMetrics_Create()方法返回的有效对象指针。
起始版本: 12
参数:
| 参数项 | 描述 |
|---|---|
| ArkUI_CustomSpanMetrics* metrics | 自定义绘制Span度量信息实例指针,用于传入需要设置宽度的度量信息对象。参数不能为空,否则会导致参数验证失败。 |
| float width | 宽度大小,单位为vp。取值范围[0, +∞),默认值为0.0f,负值与默认值效果一致。 |
返回:
| 类型 | 说明 |
|---|---|
| int32_t | 错误码。 ARKUI_ERROR_CODE_PARAM_INVALID 参数验证失败。 可能原因:参数不能为空。 处理步骤:请确保传入的metrics参数不为空指针。 |
int32_t OH_ArkUI_CustomSpanMetrics_SetHeight(ArkUI_CustomSpanMetrics* metrics, float height)
描述
设置自定义绘制Span的高度。在表情内嵌场景中,需要根据表情大小设置合适的高度以保持与文本对齐;在图文混排场景中,需要为嵌入元素设置与文本行高匹配的高度。
必须先调用OH_ArkUI_CustomSpanMetrics_Create()创建度量信息对象。
参数metrics必须是通过OH_ArkUI_CustomSpanMetrics_Create()方法返回的有效对象指针。
起始版本: 12
参数:
| 参数项 | 描述 |
|---|---|
| ArkUI_CustomSpanMetrics* metrics | 自定义绘制Span度量信息实例指针,用于传入需要设置高度的度量信息对象。参数不能为空,否则会导致参数验证失败。必须是通过OH_ArkUI_CustomSpanMetrics_Create()创建的有效对象。 |
| float height | 高度大小,单位为vp。取值范围[0, +∞),默认值为0.0f,负值与默认值效果一致。 |
返回:
| 类型 | 说明 |
|---|---|
| int32_t | 错误码。 ARKUI_ERROR_CODE_PARAM_INVALID 参数验证失败。 可能原因:参数不能为空。 处理步骤:请确保传入的metrics参数不为空指针。 |
ArkUI_CustomSpanDrawInfo* OH_ArkUI_CustomSpanDrawInfo_Create(void)
描述
创建自定义绘制Span绘制信息。
必须与OH_ArkUI_CustomSpanDrawInfo_Dispose()配对使用。
调用流程:OH_ArkUI_CustomSpanDrawInfo_Create()→使用info对象→OH_ArkUI_CustomSpanDrawInfo_Dispose()释放资源。
使用完毕后必须调用OH_ArkUI_CustomSpanDrawInfo_Dispose()释放内存,否则会导致资源泄漏。
起始版本: 12
返回:
| 类型 | 说明 |
|---|---|
| ArkUI_CustomSpanDrawInfo* | ArkUI_CustomSpanDrawInfo实例,表示自定义绘制Span的绘制信息。 如果返回空指针,可能是因为内存不足。 |
void OH_ArkUI_CustomSpanDrawInfo_Dispose(ArkUI_CustomSpanDrawInfo* info)
描述
销毁自定义绘制Span绘制信息。
必须与OH_ArkUI_CustomSpanDrawInfo_Create()配对使用。
仅用于销毁由OH_ArkUI_CustomSpanDrawInfo_Create()方法创建的绘制信息对象。
调用前确保已不再需要该对象,调用后该对象不可再使用。
起始版本: 12
参数:
| 参数项 | 描述 |
|---|---|
| ArkUI_CustomSpanDrawInfo* info | 自定义绘制Span绘制信息指针,用于传入需要销毁的绘制信息对象。参数不能为空,否则会导致参数验证失败。必须是由OH_ArkUI_CustomSpanDrawInfo_Create()创建的对象。 |
float OH_ArkUI_CustomSpanDrawInfo_GetXOffset(ArkUI_CustomSpanDrawInfo* info)
描述
获取自定义绘制Span相对于挂载组件的x轴偏移值。在自定义绘制回调中,需要根据偏移值确定绘制起始位置,用于实现表情内嵌、图文混排等场景的精确绘制。
必须先调用OH_ArkUI_CustomSpanDrawInfo_Create()创建绘制信息对象。
参数info必须是通过OH_ArkUI_CustomSpanDrawInfo_Create()方法返回的有效对象指针。
起始版本: 12
参数:
| 参数项 | 描述 |
|---|---|
| ArkUI_CustomSpanDrawInfo* info | 自定义绘制Span绘制信息指针,用于传入需要获取x轴偏移值的绘制信息对象。参数不能为空,否则会导致参数验证失败。必须是通过OH_ArkUI_CustomSpanDrawInfo_Create()创建的有效对象。 |
返回:
| 类型 | 说明 |
|---|---|
| float | x轴偏移值,单位为px。若参数验证失败,返回0.0f。 异常返回原因:参数验证失败,参数不能为空。 |
float OH_ArkUI_CustomSpanDrawInfo_GetLineTop(ArkUI_CustomSpanDrawInfo* info)
描述
获取自定义绘制Span相对于挂载组件的上边距。在自定义绘制时,需要根据上边距确定绘制区域的垂直起始位置,用于富文本编辑器、文档应用等场景的精确排版。
必须先调用OH_ArkUI_CustomSpanDrawInfo_Create()创建绘制信息对象。
参数info必须是通过OH_ArkUI_CustomSpanDrawInfo_Create()方法返回的有效对象指针。
起始版本: 12
参数:
| 参数项 | 描述 |
|---|---|
| ArkUI_CustomSpanDrawInfo* info | 自定义绘制Span绘制信息指针,用于传入需要获取上边距的绘制信息对象。参数不能为空,否则会导致参数验证失败。必须是通过OH_ArkUI_CustomSpanDrawInfo_Create()创建的有效对象。 |
返回:
| 类型 | 说明 |
|---|---|
| float | 上边距值,单位为px。若参数验证失败,返回0.0f。 异常返回原因:参数验证失败,参数不能为空。 |
float OH_ArkUI_CustomSpanDrawInfo_GetLineBottom(ArkUI_CustomSpanDrawInfo* info)
描述
获取自定义绘制Span相对于挂载组件的下边距。在自定义绘制时,需要结合上边距和下边距计算绘制区域的高度范围,用于图文混排、表情内嵌等场景的精确布局。
必须先调用OH_ArkUI_CustomSpanDrawInfo_Create()创建绘制信息对象。
参数info必须是通过OH_ArkUI_CustomSpanDrawInfo_Create()方法返回的有效对象指针。
起始版本: 12
参数:
| 参数项 | 描述 |
|---|---|
| ArkUI_CustomSpanDrawInfo* info | 自定义绘制Span绘制信息指针,用于传入需要获取下边距的绘制信息对象。参数不能为空,否则会导致参数验证失败。必须是通过OH_ArkUI_CustomSpanDrawInfo_Create()创建的有效对象。 |
返回:
| 类型 | 说明 |
|---|---|
| float | 下边距值,单位为px。若参数验证失败,返回0.0f。 异常返回原因:参数验证失败,参数不能为空。 |
float OH_ArkUI_CustomSpanDrawInfo_GetBaseline(ArkUI_CustomSpanDrawInfo* info)
描述
获取自定义绘制Span相对于挂载组件的基线偏移量。在自定义绘制Span的绘制回调中,通过本接口获取基线偏移量用于文本对齐排版,实现富文本编辑器、图文混排等场景的精准绘制效果。
必须先调用OH_ArkUI_CustomSpanDrawInfo_Create()创建绘制信息对象。
参数info必须是通过OH_ArkUI_CustomSpanDrawInfo_Create()方法返回的有效对象指针。
起始版本: 12
参数:
| 参数项 | 描述 |
|---|---|
| ArkUI_CustomSpanDrawInfo* info | 自定义绘制Span绘制信息指针,用于传入需要获取基线偏移量的绘制信息对象。参数不能为空,否则会导致参数验证失败。 |
返回:
| 类型 | 说明 |
|---|---|
| float | 基线偏移量值,单位为px。若参数验证失败,返回0.0f。 异常返回原因:参数验证失败,参数不能为空。 |