RGF 仓颉版 TextFormat 文本格式类完全指南：字体属性、段落排版与行裁剪配置

图形学桌面应用【免费下载链接】RGF_CJRGF是仓颉Windows系统下的通用渲染框架兼应用开发框架。RGF仓颉版后续简称RGF基于RGF(C/C版)封装优化而来。RGF为开发者提供轻量化、安全、高性能以及高度一致性的2D渲染能力以及常用的桌面应用开发工具并且提供对接Direct3D的相关接口以满足开发者对3D画面渲染的需求。在Windows开发方面RGF在子包内也提供开箱即用的Windows API确保熟悉Win32的开发者快速上手。此外RGF还提供一些常用功能的封装如XAudio2、MF以辅助开发者实现音频、摄像头等扩展功能的管理。项目地址https://gitcode.com/Cangjie-SIG/RGF_CJ点击查看免费下载TextFormat是 RGF仓颉 Windows 通用渲染框架文本渲染管线中负责文本外观与排版策略的设备相关资源它把字体族、字号、字重、文字流方向、段落对齐、换行与裁剪等十余项属性收敛为一个可复用的格式对象供TextLayout布局与Surface.drawTexts绘制使用。本文以 RGF_CJ 仓库中的 TextFormat API 文档 为骨架结合 rgf_text.cj 源码、底层 foreign 函数声明与 渲染文本教程 的实战流程系统讲解该类的每个 Get/Set 接口、相关枚举取值、底层实现原理与完整使用示例读完即可在 RGF 应用中精确控制文本渲染效果。一、TextFormat 在 RGF 文本渲染体系中的定位在 RGF 中渲染一段文本需要三类资源协同工作资源职责对应类渲染核心执行字形光栅化与绘制TextCore文本格式描述字体、排版与裁剪策略TextFormat本文主题文本布局按格式与约束宽度执行排版、提供测量/命中测试TextLayout从源码声明看rgf_text.cj 第 64 行 定义public open class TextFormat : SfcSubObjBaseTextFormat继承自SfcSubObjBasergf_base.cj 第 515 行属于典型的设备相关资源它内部持有一个指向底层渲染对象的指针objPtr与对象类型SfcSubObjType.TextFormatrgf_base.cj 第 327 行。所有 Get/Set 方法执行前都会先调用isValid()检查底层对象是否存在即objPtr.isNotNull()见 rgf_base.cj 第 424 行若对象未创建则抛出rgfErrorCpluapluaObjNotExist异常——这正是文档中每个方法都标注若请求时底层对象未创建则抛出异常的原因。因此TextFormat()空构造只能得到一个空壳实例rgf_text.cj 第 71 行必须通过渲染表面的工厂方法才能真正绑定底层对象这一点与TextCore、TextLayout一致。二、创建 TextFormat四种工厂方法签名TextFormat实例由Surface渲染表面创建在 rgf_draw_creater.cj 第 495-508 行 中声明了四组接口// 创建并返回新实例 func createTextFormat( size: Float32, familyName!: String, locale!: String, weight!: FontWeight, style!: FontStyle, stretch!: FontStretch ): TextFormat // 复用已有引用对象先释放旧对象再创建 func createTextFormat( ref: TextFormat, size: Float32, familyName!: String, locale!: String, weight!: FontWeight, style!: FontStyle, stretch!: FontStretch ): ICreater其中familyName、locale、weight、style、stretch均为命名参数全部带默认值见 rgf_renderer.cj 第 1988 行 的完整实现public func createTextFormat( size: Float32, familyName!: String , locale!: String , weight!: FontWeight FontWeight.Normal, style!: FontStyle FontStyle.Normal, stretch!: FontStretch FontStretch.Normal ): TextFormat参数说明参数类型默认值含义sizeFloat32必填字体尺寸DPI 单位即设备独立像素familyNameString字体族名如Microsoft YaHei、Segoe UI为空表示使用系统默认字体localeString区域设置名locale影响字形选择与字符形状如zh-cnweightFontWeightFontWeight.Normal字体权重粗细styleFontStyleFontStyle.Normal字体风格正常/斜体等stretchFontStretchFontStretch.Normal字体延展宽窄底层实现上createTextFormat会将familyName与locale字符串经ruStrToWStr转为宽字符串指针枚举通过e2Num转为数值最终调用 foreign 函数rApiDctClassCreateTextFormat声明于 rgf_api.cj 第 319 行创建底层格式对象并包装为TextFormat返回。2.1 测试工程中的创建示例test/HLT/base/src/test_win.cj 第 15 行 先声明成员变量然后在createDeviceResources中创建private var textformat: TextFormat TextFormat() // createDeviceResources 中 textformat surface.createTextFormat(28.0)这里只传入必填参数size 28.028 DIP其余全部使用默认值。注意在destroyDeviceResources中对应的释放调用为textformat.release()test_win.cj 第 225 行。三、核心属性字体相关Font 系列3.1 字体族名 getFontFamilyNamepublic func getFontFamilyName(): String获取当前格式绑定的字体族名。其实现rgf_text.cj 第 103 行先通过rApiTxtFormatGetFontFamilyNameLength取得宽字符长度再调用rApiTxtFormatGetFontFamilyName填充缓冲区并转换为仓颉String返回长度为 0 时返回空字符串。该长度/取值两段式模式同样用于getLocaleName。3.2 字体尺寸 getFontSizepublic func getFontSize(): Float32获取字体尺寸单位为 DPI 单位DIP设备独立像素。它直接透传底层rApiTxtFormatGetFontSize的返回值rgf_text.cj 第 122 行。该值即创建时传入的size参数。3.3 字体权重 getFontWeight / 底层数值映射public func getFontWeight(): FontWeight返回FontWeight枚举。该枚举在 rgf_text_dw.cj 第 87 行 定义底层以 OpenType 标准的 100~950 数值表示映射关系如下枚举值数值Thin100ExtraLight200Light300SemiLight350Normal400Medium500DemiBold600Bold700ExtraBold800Black900ExtraBlack950getFontWeight内部通过FontWeight.num2e(...)将UInt16数值还原为枚举rgf_text.cj 第 149 行。3.4 字体风格 getFontStylepublic func getFontStyle(): FontStyleFontStyle定义于 rgf_text_dw.cj 第 133 行三个取值及其底层数值枚举值数值说明Normal0常规字体Oblique1倾斜无真实斜体字形时由系统合成Italic2斜体优先使用字体自带斜体字形3.5 字体延展 getFontStretchpublic func getFontStretch(): FontStretchFontStretch定义于 rgf_text_dw.cj 第 155 行共 10 个取值按宽度从小到大依次为Undefined(0)、UltraCondensed(1)、ExtraCondensed(2)、Condensed(3)、SemiCondensed(4)、Normal(5)、SemiExpanded(6)、Expanded(7)、ExtraExpanded(8)、UltraExpanded(9)。Condensed系列表示压缩窄体Expanded系列表示扩展宽体Undefined表示未定义/不指定。四、核心属性段落与阅读方向Direction/Alignment 系列4.1 文字流方向 getFlowDirection / setFlowDirectionpublic func getFlowDirection(): FlowDirection public func setFlowDirection(flowDirection: FlowDirection): Bool控制文档内容的排布流向。FlowDirection枚举取值文档见 FlowDirection.md取值含义LeftToRight从左到右西文/中文默认RightToLeft从右到左如阿拉伯文排版TopToBottom从上到下BottomToTop从下到上setFlowDirection通过FlowDirection.e2Num转数值后调用rApiTxtFormatSetFlowDirection返回Bool表示设置是否成功rgf_text.cj 第 94 行。4.2 阅读方向 getReadingDirection / setReadingDirectionpublic func getReadingDirection(): ReadingDirection public func setReadingDirection(readingDirection: ReadingDirection): BoolReadingDirection与FlowDirection取值相同LeftToRight/RightToLeft/TopToBottom/BottomToTop定义见 rgf_text_dw.cj 第 242 行但语义不同FlowDirection决定段落内容的主流方向ReadingDirection决定单个文本行内字符的阅读顺序。两者叠加使用可处理诸如竖排但行内从左到右的混合排版需求。4.3 文本对齐 getTextAlignment / setTextAlignmentpublic func getTextAlignment(): TextAlignment public func setTextAlignment(textAlignment: TextAlignment): Bool控制水平方向上每行文本的对齐方式。TextAlignment定义于 rgf_text_dw.cj 第 267 行取值数值含义Leading0行首对齐跟随阅读方向默认Trailing1行尾对齐Center2居中对齐Justified3两端对齐自动调整词间距4.4 段落对齐 getParagraphAlignment / setParagraphAlignmentpublic func getParagraphAlignment(): ParagraphAlignment public func setParagraphAlignment(paragraphAlignment: ParagraphAlignment): Bool控制垂直方向上段落整体所有行的位置。ParagraphAlignment定义于 rgf_text_dw.cj 第 220 行取值数值含义Near0靠近起始端顶部默认Far1远离起始端底部Center2垂直居中当文本总高度小于布局区域高度时此属性决定文字落在区域的上方、中间还是下方。五、核心属性行距、制表位与区域设置5.1 行间距 getLineSpacing / setLineSpacing两个重载public func getLineSpacing(): OptionLineSpacing public func setLineSpacing(lineSpacingMethod: LineSpacingMethod, lineSpacing: Float32, baseline: Float32): Bool public func setLineSpacing(lineSpacin: LineSpacing): BoolgetLineSpacing返回OptionLineSpacing底层通过三个输出指针lineSpacingMethod/lineSpacing/baseline读取行距数据读取成功时包装为LineSpacing返回Some否则返回Nonergf_text.cj 第 176 行。LineSpacing是携带行距三要素的简单数据类LineSpacing.mdpublic class LineSpacing { public var lineSpacingMethod: LineSpacingMethod // 行距确定模型 public var lineSpacing: Float32 // 基线间距 public var baseline: Float32 // 行顶到基线的距离 public init( lineSpacingMethod!: LineSpacingMethod LineSpacingMethod.Default, lineSpacing!: Float32 0.0, baseline!: Float32 0.0 ) }LineSpacingMethod枚举定义于 rgf_text_dw.cj 第 198 行表示行高由哪种模型确定取值数值含义Default0由字体排版默认决定Uniform1统一行距lineSpacing为总行高baseline指定基线位置Proportional2比例行距lineSpacing为基线间距行高按字体度量自动缩放两个setLineSpacing重载最终都调用同一个 foreign 函数rApiTxtFormatSetLineSpacingrgf_text.cj 第 210-223 行区别只是参数组织方式一个直接传三个原始参数一个传LineSpacing对象并解包其字段。5.2 增量制表位 getIncrementalTabStop / setIncrementalTabStoppublic func getIncrementalTabStop(): Float32 public func setIncrementalTabStop(incrementalTabStop: Float32): Bool设置/获取制表位的增量间距即每按一次 Tab 前进的宽度DIP 单位。实现为对rApiTxtFormatGet/SetIncrementalTabStop的直接透传rgf_text.cj 第 158-169 行。5.3 区域设置名 getLocaleNamepublic func getLocaleName(): String获取格式绑定的区域设置名locale。实现与getFontFamilyName相同的两段式读取先rApiTxtFormatGetLocaleNameLength取长度再rApiTxtFormatGetLocaleName读内容rgf_text.cj 第 229 行。区域设置会影响数字、标点、连字等按语言习惯的字符呈现。六、核心属性换行与行裁剪Trimming/Wrapping6.1 换行选项 getWordWrapping / setWordWrappingpublic func getWordWrapping(): WordWrapping public func setWordWrapping(wordWrapping: WordWrapping): Bool控制文本超出布局宽度时的自动换行策略。WordWrapping定义于 rgf_text_dw.cj 第 292 行取值数值含义Wrap0按单词边界换行默认NoWrap1不换行溢出部分被裁剪或超出布局框EmergencyBreak2紧急断行单词过长时在字符处强制断行WholeWord3整词换行优先保持单词完整Character4按字符换行适合中文等无空格语言6.2 行裁剪 getTrimming / setTrimming两个重载public func getTrimming(): OptionTrimmingPck public func setTrimming(trimmingOptions: Trimming, trimmingSign: OptionTextInlineObj): Bool public func setTrimming(trimming: TrimmingPck): Bool为溢出布局宽度的文本设置剪裁选项。Trimming是裁剪策略描述类Trimming.mdpublic class Trimming { public let granularity: TrimmingGranularity // 裁剪粒度 public let delimiter: Rune // 分隔符默认 r\0 public let delimiterCount: UInt32 // 分隔符重复次数默认 0 public init( granularity!: TrimmingGranularity TrimmingGranularity.None, delimiter!: Rune r\0, delimiterCount!: UInt32 0 ) }TrimmingGranularity溢出裁剪模式定义于 rgf_text_dw.cj 第 320 行取值数值含义None0不裁剪Character1按字符粒度裁剪Word2按单词粒度裁剪TrimmingPck是把裁剪策略与裁剪标记省略号等内联对象打包的组合类TrimmingPck.mdpublic class TrimmingPck { public let trimmingOptions: Trimming public let trimmingSign: OptionTextInlineObj public init( trimmingOptions!: Trimming Trimming(), trimmingSign!: OptionTextInlineObj OptionTextInlineObj.None ) }TextInlineObj是文本内联对象如自定义的…图形、图片用于充当裁剪指示符TextInlineObj.md。setTrimming实现中rgf_text.cj 第 322 行先将Trimming通过toStruct()写入底层结构体Trimming_再调用rApiTxtFormatSetTrimmingtrimmingSign为Some时传入其底层objPtr为None时传入空内联对象并把inlineObj缓存到实例字段。getTrimming则反向执行从rApiTxtFormatGetTrimming读回后组装成TrimmingPck返回rgf_text.cj 第 367 行。七、资源生命周期空构造、释放与自释放变体TextFormat是设备相关资源需要遵循表面创建 → 使用 → 释放的生命周期声明空实例private var textformat: TextFormat TextFormat()此时底层对象为空调用任何 Get/Set 都会抛异常绑定底层对象在createDeviceResources中用surface.createTextFormat(size, ...)创建释放在destroyDeviceResources中调用textformat.release()该方法会调用rApiSfcSubObjRelease释放底层对象并清空指针rgf_base.cj 第 431 行。如需自释放语义析构时自动释放无需手动release()可使用子类STextFormatrgf_auto_class.cj 第 170 行它覆写了~init()在对象被回收时自动释放底层资源public class STextFormat : TextFormat { ~init() { if(objPtr.isNotNull()){ unsafe { rApiSfcSubObjRelease(objPtr, SfcSubObjType.e2Num(objType)) } objPtr CPointerUnit() } } }八、完整实战从创建到绘制文本结合 013_渲染文本教程 与 test_win.cj 测试工程一个完整流程如下第一步声明成员LifeCycle class WinSelf : WinCore{ let txtCore: TextCore // 文本渲染核心 let txtfmt: TextFormat // 文本格式 let txtlyt: TextLayout // 文本布局 }第二步创建资源并精细配置格式public override func createDeviceResources(): Bool{ // 创建渲染核心 surface.createTextCore(txtCore) // 创建格式字号 24 DIP指定字体族与区域加粗 surface.createTextFormat( txtfmt, 24.0, // 字体大小DPI 单位 familyName: Microsoft YaHei, locale: zh-cn, weight: FontWeight.Bold, style: FontStyle.Normal, stretch: FontStretch.Normal ) // 创建后仍可通过 Set 方法微调排版策略 txtfmt.setTextAlignment(TextAlignment.Leading) txtfmt.setParagraphAlignment(ParagraphAlignment.Near) txtfmt.setWordWrapping(WordWrapping.Wrap) txtfmt.setIncrementalTabStop(36.0) // 创建布局 surface.createTextLayout( txtlyt, 绘制的文本, txtfmt, Size(Int32.Max, 60) // 文本布局区宽高 ) return true }第三步在渲染事件中绘制public override func onPaint(wRect: Rect): Unit{ surface.clear(1.0, 1.0, 1.0, 1.0) // 绘制文本可带绘制位置偏移 surface.drawTexts(txtCore, brush, txtlyt, originX: 20.0, originY: 20.0) }第四步释放资源public override func destroyDeviceResources(): Bool{ txtlyt.release() txtfmt.release() txtCore.release() return true }测试工程 test_win.cj 第 173 行 展示了更复杂的使用形态——创建布局后传入textformat并配合setInlineObject插入内联对象textLayout surface.createTextLayout( fps: fpsStr \n让我们说中文*\nඅපි චීනි කතා කරමු., textformat, Float32(wRect.right - wRect.left), Float32(wRect.bottom - wRect.top) ) textLayout.setInlineObject(textInline, 10, 1) surface.drawTexts(textCore, brush, textLayout, originX: 10.0, originY: 200.0)九、接口速查表方法说明返回/参数要点getFlowDirection/setFlowDirection文字流方向FlowDirectionLTR/RTL/TTB/BTTgetFontFamilyName字体族名String空串表示默认字体getFontSize字体尺寸Float32DPI 单位getFontStretch字体延展FontStretch10 档宽窄getFontStyle字体风格FontStyleNormal/Oblique/ItalicgetFontWeight字体权重FontWeight100~950getIncrementalTabStop/setIncrementalTabStop增量制表位Float32DIP 单位getLineSpacing/setLineSpacing行间距OptionLineSpacing三参数重载或对象重载getLocaleName区域设置名StringgetParagraphAlignment/setParagraphAlignment段落垂直对齐ParagraphAlignmentNear/Far/CentergetReadingDirection/setReadingDirection行内阅读方向ReadingDirectionLTR/RTL/TTB/BTTgetTextAlignment/setTextAlignment文本水平对齐TextAlignmentLeading/Trailing/Center/JustifiedgetTrimming/setTrimming行裁剪OptionTrimmingPck策略标记对象两个重载getWordWrapping/setWordWrapping换行选项WordWrappingWrap/NoWrap/EmergencyBreak/WholeWord/Characterinit()创建空实例需配合surface.createTextFormat(...)绑定底层对象十、关键结论与注意事项设备相关资源TextFormat的所有方法均要求底层对象已创建否则抛出对象不存在异常空构造得到的实例必须先经createTextFormat绑定后才能使用。枚举数值由底层传递所有 Set 方法通过e2Num将枚举转为底层数值如FontWeight.Bold → 700、TextAlignment.Justified → 3Get 方法通过num2e还原底层 foreign 函数集中在 rgf_text_dw.cj 第 1048-1094 行。可复用性TextFormat是格式策略的载体同一实例可被多个TextLayout复用修改格式属性会影响所有引用它的布局需要局部差异化时应创建独立格式实例。自释放变体偏好 RAII 风格时选用STextFormat其析构函数自动释放底层资源免去手动release()。配合接口TextFormat的消费方是TextLayout布局与Surface.drawTexts绘制创建入口统一由Surface.createTextFormat提供相关接口签名可查阅 rgf_draw_creater.cj。赞分享图形学桌面应用【免费下载链接】RGF_CJRGF是仓颉Windows系统下的通用渲染框架兼应用开发框架。RGF仓颉版后续简称RGF基于RGF(C/C版)封装优化而来。RGF为开发者提供轻量化、安全、高性能以及高度一致性的2D渲染能力以及常用的桌面应用开发工具并且提供对接Direct3D的相关接口以满足开发者对3D画面渲染的需求。在Windows开发方面RGF在子包内也提供开箱即用的Windows API确保熟悉Win32的开发者快速上手。此外RGF还提供一些常用功能的封装如XAudio2、MF以辅助开发者实现音频、摄像头等扩展功能的管理。项目地址https://gitcode.com/Cangjie-SIG/RGF_CJ点击查看免费下载相关推荐RGF 仓颉版文本排版深度解析LineSpacing 行距类与 TextFormat 行间距控制RGF 仓颉版文本排版深度解析LineSpacing 行距类与 TextFormat 行间距控制 在 Windows 桌面应用中多行文本的排版质量直接取决于图形学桌面应用RGF 仓颉版文本渲染TextAlignment 枚举与 TextFormat 文本对齐详解RGF 仓颉版文本渲染TextAlignment 枚举与 TextFormat 文本对齐详解 TextAlignment 是 RGF 仓颉版RGF_CJ中图形学桌面应用RGF仓颉版文本渲染详解WordWrapping 自动换行模式枚举与 TextFormat 换行选项实战RGF仓颉版文本渲染详解WordWrapping 自动换行模式枚举与 TextFormat 换行选项实战 本文聚焦 RGF 仓颉 Windows 渲染框架图形学桌面应用上一篇Wagtail 2.11 (LTS) 版本深度解析多语言内容、页面别名与集合层级下一篇langchain/weaviate 演进全解析从 LangChain v1.0 兼容到 jsonSchema 原生支持创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考