From 7afcbe5eefd3618408bf63e65782e5dc7bc78ad4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9D=8E=E8=8B=A5=E8=BE=B0?= Date: Wed, 18 Jun 2025 11:50:49 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20HowToUseXericLibrary?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- HowToUseXericLibrary.md | 119 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 117 insertions(+), 2 deletions(-) diff --git a/HowToUseXericLibrary.md b/HowToUseXericLibrary.md index b6cf574..3408ce4 100644 --- a/HowToUseXericLibrary.md +++ b/HowToUseXericLibrary.md @@ -66,7 +66,67 @@ Xeric中使用宏 (Macro) 作为隔离用法的的单元，所有的操作都可 ---- #### [排序宏] ---- -#### [文本宏] +#### [文本宏 MacroMath](../wiki/MacroMath) + +提供： +* StringBuilderPool: 文本构建池 +* join: 文本序列拼接。 + ``` + List objects = new List(); + objects.Join(obj => obj.ToString(), ) + + ``` +* 文本判断：空判断，空格判断，相等判断，字符集判断 +* 格式包裹：支持TMP的26个富文本标签，或者自行扩展更多包裹器。 + 包裹器可以依靠多态模型来构建文本，而不依赖字面量构建。下面是一个示例： + ``` + _blockBuilder = new TextBlockBuilder( + new ColorBlock(Color.white, "重量"), + new DelegateBlock(() => value.ToString()), + new SizeBlock(20, "kg"))); + ``` + TextBlockBuilder 是所有blocker的基类，使用它包裹所有文本将起到单纯拼接文本的作用；TextBlockBuilder 里的三个block的作用是使用相应的富文本标签包裹，根据标签的类型，包裹器会自动决定标签格式。 + `DelegateBlock`的作用是通过委托来实时获取一个变量，示例中直接获取value的文本值，拼接到结果中。 + TextBlockBuilder 可以不依靠如`DelegateBlock这样的包裹器，可以直接将返回字符串类型的方法委托传入，blocker 会自动识别；前提是开启对应 blocker 里的compatibility兼容性检查，但这会带来额外的性能开销，如果没有特别的需求，建议还是使用DelegateBlock`进行多态封装，这样也会更安全。 + + 在新的更新中，包裹器支持域写法，同时可以省略部分参数： + ``` + _blockBuilder = new TextBlockBuilder() + { + new ColorBlock() // 默认值就是白色 + { + "重量" + }, + new DelegateBlock(() => value.ToString()), + new SizeBlock(20) // 默认单位为像素 + { + "kg" + } + }; + ``` + 这里的作用与上面的示例完全一致，更新的包裹器中支持自动填入更多的默认值了，比如颜色默认为白色。 + 虽然看起来更长了，但是对于较复杂的格式来说可以有更强的可读性，建议这样写。 + + 同时，委托包裹器并不是唯一设置动态参数的方式: + * `SetParamters`:在根包裹器上使用赋值方法，可以将一系列值一一对应地填入到后续一系列包裹器中。 + * `RefernceBlock`:反射包裹器允许传入一个对象，以及成员名称来访问属性（字段，访问器，方法均可）。 + * `ValueBlock:值包裹器，搭配SetParamters`来设置值，目标需要实现Tostring方法。 + * `NumberValueBlock数值类型包裹器，搭配SetParamters`来设置值，设置值会自动限制在最大最小范围内，如果给定的参数是字符串类型，将尝试通过默认的格式化方法转为数值。 + + 在实际使用时，只有`ValueBlock默认会从SetParamters`参数列表中获取值, + 其他包裹器需要手动通过`SetParameterization`参数化包裹器，否则不会响应参数列表。 + + 值得时刻注意的是，`SetParamters`传递的值需要按深度优先的顺序逐一匹对，基本上可以认为是blockBuilder定义时的block先后顺序。 + 如果`SetParamters`中参数数量少于需求，在匹配时将会提前退出，导致后续值保持不变； + 如果遇到强制类型检查的block且值无法匹配，block不会处理这个值，而是丢给下一个，只有遇到这种情况时，索引才有可能不是一一对应的形式。(默认认为是这么处理的，具体行为可以由block自己定义) + + 关于性能：这种做法绝对不是省油的灯，绝对不要在运行时重复创建，而是声名在当前作用域的全局用作静态，或保持实例唯一。 + +* 文本转换：自动值转换为文本。 +* NumberToChinese：将数值转为中文大写。 +* 沃格纳费舍尔拼写检查器：检查一对或多对文本是否相似，返回最相似的文本序列，及相似度。 +* ListToString：打印数组 + ---- #### [时间宏] ---- @@ -88,10 +148,65 @@ Xeric中使用宏 (Macro) 作为隔离用法的的单元，所有的操作都可 # 组件 #### [Splie曲线组件] + +提供`XericSplinePath，XericRectSplinePath`组件。 +他们的区别是，一个用于三维世界，另一个用于UI界面。 +UI界面上的Spline组件会通过RectTransform控制，有区别与三维世界。 + +`XericSplinePath`可以直接在unity中进行挂载，并通过界面编辑点，在列表中可以增加和减少点，或改变点的顺序。 + +在脚本中使用`XericSplinePath`定义字段，可以让脚本在inspecter上呈现一个引用端口，引用组件以获取曲线实例。 + +曲线通常用于静态计算，在设计上并未考虑动态刷新，动态构建曲线的方法，如果希望动态地构建曲线，可以自行根据其中的结构提供点位数据。 + +在`XericSplinePath曲线上初始时使用BakePoint()来烘焙一次数据，这个方法会在线组件上生成BakeData，有这个数据可以获得速度正确的的曲线映射，如果担心多个烘焙进行时的性能问题，可以使用协程方法BakePointCoroutine()`推迟烘焙到来。 +烘焙的速度与精度有关，`BakePoint()`包含一个形参用于输入烘焙精度，默认100，表示进行100次采样，理论上采样越多，精度越高，但实际上并非越高越好，采样数量保持在数倍于实际点数量即可。 +烘焙后的曲线才可以使用重映射`RemappingTimeValue()，同时也可以使用SplineLength`获取曲线的长度。 + +在曲线实例上可以访问`Evaluate...()`方法来计算坐标，旋转，数值，颜色过度。 +方法要求给定一个驱动值t，取值范围在0-1之间。 +默认情况下，驱动值是几乎等分地控制着每条线路的，无论两个点之间的距离长短，都近似为“时间”相等的多段线，这意味着无法通过这样的一个线驱动一个物体平滑地从起点运动到终点。 +而开头我们使用`BakePoint()烘焙的数据就起作用了，通过调用线实例上的RemappingTimeValue()`将时间驱动值转换为速度驱动值，这会带来非常平滑的效果。 + +2D的线路组件`XericRectSplinePath`工作在Rect上，如果屏幕的工作分辨率实际上是可变的，可能会导致实际线路有时会错位，这是因为线路工作的参考坐标系是静态的。 +如果当前项目的窗口缩放易变，建议每帧调用`UpdateRectDepend()`（一般都很难遇到分辨率亘古不变的情况），这个方法可以刷新曲线构建所依赖的矩形空间坐标。 + +为了适配速度矫正后的线路，建议使用线路的长度作为循环的时间最大值，而不是强制所有线路从0-1取值，线路总长度可以使用`SplineLength`属性获取。 +这里是一个示例：（这个示例中使用的是二维曲线，但设置ui的方法是世界空间的，并非屏幕空间，这是因为我驱动的目标对象还是世界空间的Sprite，同时较小的ui坐标便于计算尾迹的长度，避免结果速度太快） +``` +public void UpdateBySpline(XericRectSplinePath spline) +{ + totalTime = (float)spline.SplineLength; + var remappingTime = time / totalTime; // 这是没有速度矫正的值 + remappingTime = spline.RemappingTimeValue(remappingTime); // 经过速度矫正 + // 设置坐标 + var pos = spline.EvaluatePosition(remappingTime); // 获得坐标 + transform.position = pos; + // 设置旋转朝向运动方向 + var lastOffset = (lastPosition - pos).normalized; + var ang = Mathf.Atan2(lastOffset.y, lastOffset.x) * Mathf.Rad2Deg; + transform.localRotation = Quaternion.Euler(0, 0, ang); + lastPosition = pos; + // 设置缩放，来自曲线上定义的浮点值 + var size = spline.EvaluateValue(remappingTime); + transform.localScale = size; +} +``` + +三维曲线与二维曲线类似，也可以通过烘焙操作来获得一些特殊方法的调用许可。 + ---- #### [文件阅读器] + +提供`WWWDataDriver和WebFileLoader`网络文件读取功能。 + +MacroFile库中对web平台的文件操作通过`WebFileLoader`实现，其中包含一个简单的协程文本加载。 + +`WWWDataDriver`则可以自行配置post或get请求，并允许将对象属性填入表单来进行请求。 +同时，允许下载文本，图片等内容。 + ---- -#### [简易批处理器] +#### [简易批处理器] 在代码中引用 XericLibrary.Runtime.Type.BatchProcess ， 并将需要进行批处理的对象实现 ICanBatchProcess 接口，