From d9be4b0acf0bff0dc42b2c5b534a945d6f77aceb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9D=8E=E8=8B=A5=E8=BE=B0?= Date: Fri, 10 Oct 2025 17:08:33 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20TextBlockBuilder?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- TextBlockBuilder.md | 92 +++++++++++++++++++++++++++++++++------------ 1 file changed, 67 insertions(+), 25 deletions(-) diff --git a/TextBlockBuilder.md b/TextBlockBuilder.md index fbd5a34..09c1d35 100644 --- a/TextBlockBuilder.md +++ b/TextBlockBuilder.md @@ -1,22 +1,44 @@ [返回](../wiki/HowToUseXericLibrary) -# 格式包裹: +# 格式包裹器: -支持TMP的26个富文本标签,或者自行扩展更多包裹器。 -包裹器可以依靠多态模型来构建文本,而不依赖字面量构建。下面是一个示例: +支持TMP的26个富文本标签,以及更多动态包裹器,更可自行扩展更多包裹器类型。 +使用包裹器进行文本拼接的优点: +1. 通过编辑器实现语法检查,如果直接编写长串的复杂富文本,可能会由于不起眼的语法问题导致引擎不识别,而转写为包裹器格式,则可以降低低级错误的出现。 +2. 快速复用富文本,如果使用字面量的富文本字符串,则需要自行实现大篇文本拼接,或单独编写一个方法来实现这个固定格式的输出; + * 包裹器支持参数填充,也支持使用反射,委托等方式自动获取上下文参数。 + * 包裹器的返回值类型一致,可以存放在同一个数据结构中。 + * 包裹器拥有完整的数据结构语法,可以动态添加和移除标签结构。 +3. 包裹器多种语法,满足绝大部分使用情况。(如果不喜欢下面的new语法,可以先翻到后面查阅#工具语法) -``` +## 基本语法 + +包裹器最简单的用法是直接通过嵌套构造函数进行创建,下面是一个简单的示例: + +``` scharp _blockBuilder = new TextBlockBuilder( new ColorBlock(Color.white, "重量"), new NumberValueBlock(1.23), new SizeBlock(20, "kg"))); + // 结果:重量1.23kg ``` -TextBlockBuilder 是所有blocker的基类,使用它包裹所有文本将起到单纯拼接文本的作用,TextBlockBuilder里的三个block的作用是使用相应的富文本标签包裹,根据标签的类型,包裹器会自动决定标签格式。 -这里由于最外层没有要展现的标签,所以直接使用TextBlockBuilder作为最外层的拼接器,如果有最外层的标签,则可以直接使用这个标签的包裹器作为文本拼接器。 +格式包裹器`TextBlockBuilder`是所有`blocker`的基类,这个结构内部是一个字符串拼接池,包括它自身在内,所有的`blocker`都相当于一个文本拼接器,只是它自带一定的格式。 +在`TextBlockBuilder`里的三个不同的`blocker`的作用是使用相应的富文本标签包裹,比如`ColorBlock`是将括号内的成员使用``标签包裹,离开这个`blocker`语法范围后将自动添加标签结束标记``。 -``` +> 这里使用`TextBlockBuilder`作为最外层的包裹器,并不是因为必须使用它,而是最外层没有可以贯通首尾的标签,也就是不需要任何标签进行拼接。 + +> 注意,包裹器是基于多态模型实现全部功能的结构,你可以在参数中填入任何对象,通过重写ToString方法来使其可以被序列化。 + +> 注意,这个实例中虽然没有明确写明,但强烈建议将`blocker`对象提升到静态作用域,并复用它,而不是反复动态创建它。 +> 后续也会介绍更合理的池语法来优化这一点。 + +## 作用域语法 + +包裹器支持使用大括号表示一系列对象成员,这样可以利用具有默认值的无参构造函数进行创建,下面是一个简单的示例: + +``` csharp _blockBuilder = new TextBlockBuilder() { new ColorBlock() // 默认值就是白色 @@ -32,8 +54,11 @@ _blockBuilder = new TextBlockBuilder() // 结果: 重量1.23kg ``` -这里使用作用域的写法相比入参写法看起来更长了,但是对于较复杂的格式来说可以有更强的可读性,所以建议这样写。 -同时,还有更多的值包裹器用法: +在面对复杂的富文本时,这样写可读性更强; + +## 动态参数语法 + +除了26个常规富文本标签,还支持更多值包裹器用法,比如: * `SetParamters`: 在根包裹器上使用赋值方法,可以将一系列值一一对应地填入到后续一系列包裹器中。 * `DelegateBlock`: 委托包裹器允许声名一个返回值为字符串的委托来获取值。 @@ -44,28 +69,29 @@ _blockBuilder = new TextBlockBuilder() > 注意,所有BlockBuilder都支持直接使用反射获取对象,可以直接将返回字符串类型的方法名称传入,BlockBuilder 会自动识别; > 前提是开启对应 blocker 的`compatibility`兼容性检查,但这带来额外的性能开销,如果没有特别的需求,建议还是使用`DelegateBlock`进行多态封装,这样也会更快更安全。 -### 参数列表 +## 值插入语法 -在任意`BlockBuilder`上使用`SetParamters()`方法可以传递一个参数列表,并以深度优先的方式传播(或者说以符合默认阅读习惯的方式传播),当遇到可以传入参数的`BlockBuilder`时,将会填入目前的参数并在内部的下标计数器上自增,以此类推。 +在任意`BlockBuilder`上使用`SetParamters()`方法可以传递一个参数列表,并以深度优先的方式传播(或者说以符合默认阅读习惯的方式传播,从左往右逐一设置)。 -在实际使用时,默认只有`ValueBlock`会自动从参数列表中获取值,其他包裹器需要手动使用`.SetParameterization()`参数化包裹器,否则不会响应参数列表(这个方法是支持链式调用的,可以在声名时写在语法结构中)。 +> 默认只有`ValueBlock`这类值包裹器会自动从参数列表中获取值,其他标签包裹器需要手动使用`.SetParameterization()`参数化包裹器. +> 说人话:在设置参数时,值包裹器是默认用于设置值的,但如果想设置普通的标签包裹器,比如`ColorBlock`上的颜色值,则需要在对应的标签上调用`SetParameterization`方法。 +> 设置后,这个标签会占用一个或多个参数名额,比如`ColorBlock`有一个颜色参数,它就会占用一个名额,如果传递的所有参数列表的名额用完了,后续的`blocker`就得不到参数,进而不会被修改并提前退出。 -> `.SetParameterization()`参数化包裹器时,可以手动指定期望参数化的成员,通常这仅包含包裹器上的一些数值设定,不会响应枚举设定; -> 这时需要设定`.SetParameterization(2)`这样的方式,来强制占用其他的参数来识别。 - -如果参数列表的数量少于需求,在匹配时将会提前退出,导致后续值保持不变; -而如果参数列表数量多于需求,在匹配时将不会关注这部分内容。 - -> 如果遇到需要强制类型检查的block且值无法匹配,block不会处理这个值,而是丢给下一个。 -> 只有遇到这种情况时,引用才有可能不是一一对应的形式,具体原因后面会讲。 +在使用`.SetParameterization()`参数化一个包裹器时,可以手动指定期望参数化的成员,使用小于等于0的值表示使用默认值; +你可以使用比如`.SetParameterization(2)`的方式来让这个包裹器强制占用2个参数。 +* 如果参数列表的数量少于需求,在匹配时将会提前退出,导致后续值保持不变; +* 如果参数列表数量多于需求,在匹配时将不会关注这部分内容。 +* 如果参数与包裹器期望的值类型不一致,那么会忽略,注意包裹器不会尝试去寻找其他位置上的值是否能够填入,它是严格按照索引一一对应的。 +另外,你会注意到: * 关于体积:可以看到相比直接写富文本格式,这样写的体积更大。但对于开始不了解富文本格式的情况下,这个功能可以当作一种拼写检查。 -* 关于安全:包裹器允许链式语法赋值,隐式地反向赋值,但部分模块也会使用反射功能,这可能会在部分平台上被认为是不安全的,并且可能不利于协作。 -* 关于性能:这种做法可能比较浪费内存,使用时注意要声名在当前作用域的全局用作静态,或持实例唯一。 不过文本拼接不太需要担心,里面所有地方要拼接文本的地方都用了stringbuilder,比直接使用字符串内插可能还要高效。 +* 关于安全:包裹器允许链式语法赋值,隐式反向赋值,部分模块也会使用反射,生成树等功能,这可能会在部分平台上被认为是不安全的;同时过度使用隐式语法也可能导致维护,调试困难。 +* 关于性能:这种做法可能比较浪费内存,所以使用时注意要声名在当前作用域的全局用作静态,或持实例唯一。同时在使用过程中可能存在部分可能会频繁装拆箱的操作,不过这些基本上对性能影响微乎其微。 +* 关于文本拼接:所有要拼接文本的地方都用了stringbuilder。 -### 自定义Block示例 +## 自定义Block示例 -``` +``` csharp public class MyBlock : TextBlockBuilder // 继承自TextBlockBuilder { // 声名一个构造函数并调用到基类,它可以传入一个参数列表,可以是任何对象,或是反射方法的名称。 @@ -109,10 +135,26 @@ public class MyBlock : TextBlockBuilder // 继承自TextBlockBuilder // 这个方法将会逐层循环执行,每个block将处理自己的最外层的内容 // 如果成功,返回ture,否则false } + + // 如果使用using块语法,或池化语法,需要设定如何释放这个包裹器 + protected override void DisposeAsRequired() + { + TextBlockPool.Release(this); + } } ``` -### 注意事项 +## 工具集语法 + +在使用包裹器创建格式时,大量的new语句可能会劝退一些比较保守的程序员。 +所以这里也提供了可以隐藏这些new语句的方法,当然考虑到各位可能会对性能存疑,所以我特意基于对象池来实现各种获取操作,不管这对性能是否有所提升,都可以暂时堵住其他随意质疑你这么写的人的嘴巴。 +> 起因是我向其他人推荐这个写法,就有人会有这个疑问,说在java中如果这么new对象,怕是要被老板约谈。 +> 嘛,说的也没错,其实我也不喜欢这样去写,但设计之初没有太多选择,需要先建立一个基本的框架,否则这些进阶语法都免谈。 +> 我早之前也写了语法逆向,尝试将一个富文本转为blocker,不过这样性能消耗有点大。 + + + +## 注意事项 注意传入参数尽量不要为null,这样分辨不出来类型,在大多数包裹器上会产生报错。