From eb821b8f8b7dfd4e5fea784f8d747e606ea5092f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9D=8E=E8=8B=A5=E8=BE=B0?= Date: Wed, 25 Jun 2025 08:21:43 +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 | 395 +++++++++++++++++++++++++--------------- 1 file changed, 246 insertions(+), 149 deletions(-) diff --git a/HowToUseXericLibrary.md b/HowToUseXericLibrary.md index 2388a63..c91ae19 100644 --- a/HowToUseXericLibrary.md +++ b/HowToUseXericLibrary.md @@ -4,150 +4,239 @@ Xeric中使用宏 (Macro) 作为隔离用法的的单元,所有的操作都可以从MacroXX获取(XX是各个操作类模块的名称)。 -#### [特性库](../wiki/AttributeLibrary) ----- -#### [协程宏](../wiki/x) ----- -#### [调试宏](../wiki/x) ----- -#### [网格宏](../wiki/x) ----- -#### [电脑宏](../wiki/x) ----- -#### [相机宏](../wiki/x) ----- -#### [颜色宏](../wiki/x) ----- -#### [配置文件宏](../wiki/x) ----- -#### [常数宏 MacroConst](../wiki/MacroConst) ----- -#### [曲线宏 MacroCurve](../wiki/MacroCurve) ----- -#### [日志宏 MacroDebug](../wiki/MacroDebug) ----- -#### [枚举宏 MacroEnum](../wiki/MacroEnum) ----- -#### [方程宏](../wiki/x) ----- -#### [事件宏](../wiki/x) ----- -#### [文件宏 MacroFile](../wiki/MacroFile) ----- -#### [窗口宏 MacroForm](../wiki/MacroForm) ----- -#### [步进宏](../wiki/x) ----- -#### [按键宏 MacroKey](../wiki/MacroKey) ----- -#### [列表宏 MacroMath](../wiki/MacroMath) ----- -#### [数学宏 MacroMath](../wiki/MacroMath) ----- -#### [消息库 MacroMessage](../wiki/MacroMessage) ----- -#### [对象宏](../wiki/x) ----- -#### [PID宏](../wiki/x) ----- -#### [对象池宏](../wiki/x) ----- -#### [矩形变换宏](../wiki/x) ----- -#### [超驰宏](../wiki/x) ----- -#### [正则宏](../wiki/x) ----- -#### [仓库宏](../wiki/x) ----- -#### [材质宏](../wiki/x) ----- -#### [平滑宏](../wiki/x) ----- -#### [排序宏](../wiki/x) ----- -#### [文本宏 MacroMath](../wiki/MacroMath) +## [特性库](../wiki/AttributeLibrary) -提供: -* 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() +## [协程宏](../wiki/x) + + +## [调试宏](../wiki/x) + + +## [网格宏](../wiki/x) + + +## [电脑宏](../wiki/x) + + +## [相机宏](../wiki/x) + + +## [颜色宏](../wiki/x) + + +## [配置文件宏](../wiki/x) + + +## [常数宏 MacroConst](../wiki/MacroConst) + + +## [曲线宏 MacroCurve](../wiki/MacroCurve) + + +## [日志宏 MacroDebug](../wiki/MacroDebug) + + +## [枚举宏 MacroEnum](../wiki/MacroEnum) + + +## [方程宏](../wiki/x) + + +## [事件宏](../wiki/x) + + +## [文件宏 MacroFile](../wiki/MacroFile) + + +## [窗口宏 MacroForm](../wiki/MacroForm) + + +## [步进宏](../wiki/x) + + +## [按键宏 MacroKey](../wiki/MacroKey) + + +## [数学宏 MacroMath](../wiki/MacroMath) + +注意数学库包含多个子模块,包括数学常量,枚举,列表算法(不包括排序算法),基础数学扩展,矩形范围计算,区域与文本扩展,时间扩展,单位转换等。 + +## [列表宏 MacroMath](../wiki/MacroMath) + + +## [消息库 MacroMessage](../wiki/MacroMessage) + + +## [对象宏](../wiki/x) + + +## [PID宏](../wiki/x) + + +## [对象池宏](../wiki/x) + + +## [矩形变换宏](../wiki/x) + + +## [超驰宏](../wiki/x) + + +## [正则宏](../wiki/x) + + +## [仓库宏](../wiki/x) + + +## [材质宏](../wiki/x) + + +## [平滑宏](../wiki/x) + + +## [排序宏](../wiki/x) + + +## [文本宏 MacroMath](../wiki/MacroMath) + +### 文本构建池 (StringBuilderPool) + +提供一个全局的文本构建对象池,可以通过`MacroMath.StringBuilderPool`访问这个对象池,下面是用例: +``` +public string GetString() +{ + StringBuilder sb = MacroMath.GetStrBuilder(); + sb.Append("something..."); + return MacroMath.ReleaseStrBuilder(sb); +} +``` +可以看到,在对象池上释放这个构建器对象可以立刻获得里面的内容,可以省略部分内容。 + +另外提供了一个单线程上的文本拼接器单例: +``` +MacroMath.CleanString(); // 先清空,避免有污染 +MacroMath.AppendString("some"); // 拼接单个文本 +MacroMath.BuildString("thing", "..."); // 拼接多个文本 +MacroMath.GetStringAndClear(); // 返回 something... +``` + +### 文本序列拼接 (Join) + +在 +``` +List objects = new List(); +objects.Join(obj => obj.ToString(), ) +``` + +### 文本判断 + +空判断,空格判断,相等判断,字符集判断 + + +### 格式包裹: + +支持TMP的26个富文本标签,或者自行扩展更多包裹器。 +包裹器可以依靠多态模型来构建文本,而不依赖字面量构建。下面是一个示例: + +``` +// 下面这个包裹器等同于: 重量[value]kg + +_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`进行多态封装,这样也会更全。 +在新的更新中,包裹器支持域写法,同时可以省略部分参数: + +``` +// 下面这个包裹器也等同于: 重量[value]kg + +_blockBuilder = new TextBlockBuilder() +{ + new ColorBlock() // 默认值就是白色 { - new ColorBlock() // 默认值就是白色 - { - "重量" - }, - new DelegateBlock(() => value.ToString()), - new SizeBlock(20) // 默认单位为像素 - { - "kg" - } - }; - ``` - 这里的作用与上面的示例完全一致,更新的包裹器中支持自动填入更多的默认值了,比如颜色默认为白色。 - 虽然看起来更长了,但是对于较复杂的格式来说可以有更强的可读性,建议这样写。 + "重量" + }, + new DelegateBlock(() => value.ToString()), + new SizeBlock(20) // 默认单位为像素 + { + "kg" + } +}; +``` - 同时,委托包裹器并不是唯一设置动态参数的方式: - * `SetParamters`:在根包裹器上使用赋值方法,可以将一系列值一一对应地填入到后续一系列包裹器中。 - * `RefernceBlock`:反射包裹器允许传入一个对象,以及成员名称来访问属性(字段,访问器,方法均可)。 - * `ValueBlock:值包裹器,搭配SetParamters`来设置值,目标需要实现Tostring方法。 - * `NumberValueBlock数值类型包裹器,搭配SetParamters`来设置值,设置值会自动限制在最大最小范围内,如果给定的参数是字符串类型,将尝试通过默认的格式化方法转为数值。 +这里的作用与上面的示例完全一致,更新的包裹器中支持自动填入更多的默认值了,比如颜色默认为白色。 +虽然看起来更长了,但是对于较复杂的格式来说可以有更强的可读性,建议这样写。 +同时,委托包裹器并不是唯一设置动态参数的方式: - 在实际使用时,只有`ValueBlock默认会从SetParamters`参数列表中获取值, - 其他包裹器需要手动通过`SetParameterization`参数化包裹器,否则不会响应参数列表。 +* `SetParamters`:在根包裹器上使用赋值方法,可以将一系列值一一对应地填入到后续一系列包裹器中。 +* `RefernceBlock`:反射包裹器允许传入一个对象,以及成员名称来访问属性(字段,访问器,方法均可)。 +* `ValueBlock:值包裹器,搭配SetParamters`来设置值,目标需要实现Tostring方法。 +* `NumberValueBlock数值类型包裹器,搭配SetParamters`来设置值,设置值会自动限制在最最小范围内,如果给定的参数是字符串类型,将尝试通过默认的格式化方法转为数值。 - 值得时刻注意的是,`SetParamters`传递的值需要按深度优先的顺序逐一匹对,基本上可以认为是blockBuilder定义时的block先后顺序。 - 如果`SetParamters`中参数数量少于需求,在匹配时将会提前退出,导致后续值保持不变; - 如果遇到强制类型检查的block且值无法匹配,block不会处理这个值,而是丢给下一个,只有遇到这种情况时,索引才有可能不是一一对应的形式。(默认认为是这么处理的,具体行为可以由block自己定义) +在实际使用时,只有`ValueBlock`默认会从`SetParamters`参数列表中获取值, +其他包裹器需要手动通过`SetParameterization`参数化包裹器,否则不会响应参数列表。 +值得时刻注意的是,`SetParamters`传递的值需要按深度优先的顺序逐一匹对,基本上可以认为是blockBuilde定义时的block先后顺序。 +如果`SetParamters`中参数数量少于需求,在匹配时将会提前退出,导致后续值保持不变; +如果遇到强制类型检查的block且值无法匹配,block不会处理这个值,而是丢给下一个,只有遇到这种情况时,引才有可能不是一一对应的形式。(默认认为是这么处理的,具体行为可以由block自己定义) - 关于性能: 这种做法绝对不是省油的灯,绝对不要在运行时重复创建,而是声名在当前作用域的全局用作静态,或保持实例唯一。 +最后: +* 关于体积:可以看到相比直接写富文本格式,这样写的体积更大。但对于开始不了解富文本格式的情况下,这个功能可以当作一种拼写检查。 +* 关于安全:包裹器允许链式语法赋值,隐式地反向赋值,但部分模块也会使用反射功能,这可能会在部分平台上被认为是不安全的,并且可能不利于协作。 +* 关于性能:这种做法在创建时绝对不是省油的灯,绝对不要在运行时反复创建,而是声名在当前作用域的全局用作静态,或持实例唯一。 不过文本拼接不太需要担心,里面所有地方要拼接文本的地方都用了stringbuilder,比直接使用字符串内插可能还要高效。 + + +### 文本转换: + +自动值转换为文本。 + +### NumberToChinese + +将数值转为中文大写。 + +### 沃格纳费舍尔拼写检查器 + +检查一对或多对文本是否相似,返回最相似的文本序列,及相似度。 + +### ListToString + +打印数组 + + + +## [时间宏] + + +## [轴变换宏] + + +## [类型扩展] + + +## [矢量扩展] + + +## [导航宏] + + +## [安全宏] + + +## [转换宏] + + +## [事件触发宏] -* 文本转换: 自动值转换为文本。 -* NumberToChinese: 将数值转为中文大写。 -* 沃格纳费舍尔拼写检查器: 检查一对或多对文本是否相似,返回最相似的文本序列,及相似度。 -* ListToString: 打印数组 ----- -#### [时间宏] ----- -#### [轴变换宏] ----- -#### [类型扩展] ----- -#### [矢量扩展] ----- -#### [导航宏] ----- -#### [安全宏] ----- -#### [转换宏] ----- -#### [事件触发宏] ----- # 组件 -#### [Splie曲线组件](../wiki/SplinePath) +## [Splie曲线组件](../wiki/SplinePath) 提供`XericSplinePath,XericRectSplinePath`组件。 他们的区别是,一个用于三维世界,另一个用于UI界面。 @@ -195,8 +284,9 @@ public void UpdateBySpline(XericRectSplinePath spline) 三维曲线与二维曲线类似,也可以通过烘焙操作来获得一些特殊方法的调用许可。 ----- -#### [文件阅读器] + + +## [文件阅读器] 提供`WWWDataDriver和WebFileLoader`网络文件读取功能。 @@ -205,8 +295,9 @@ MacroFile库中对web平台的文件操作通过`WebFileLoader`实现,其中 `WWWDataDriver`则可以自行配置post或get请求,并允许将对象属性填入表单来进行请求。 同时,允许下载文本,图片等内容。 ----- -#### [简易批处理器] + + +## [简易批处理器] 在代码中引用 XericLibrary.Runtime.Type.BatchProcess , 并将需要进行批处理的对象实现 ICanBatchProcess 接口, @@ -216,8 +307,9 @@ MacroFile库中对web平台的文件操作通过`WebFileLoader`实现,其中 和官方的相比没有什么优势,只是作为dll内部的部分程序的替代品,没事不要用这个。 ----- -#### [多维布尔] + + +## [多维布尔] 提供`Bool1,Bool2,Bool3,Booln`。 其中除了`Booln`是类,其他都是结构体,在相互转换时需要注意。 @@ -234,29 +326,33 @@ MacroFile库中对web平台的文件操作通过`WebFileLoader`实现,其中 多维布尔可以与布尔运算: * 异或操作可以对多维布尔各轴异或。 ----- -#### [预设与函数退化链] + + +## [预设与函数退化链] 提供一个抽象基类`PremadeLinkedNode,它以链表形态工作,通过AddNode`添加另一个节点。 添加完毕后使用`Invoke`并传入参数,这将自动根据参数形态选择函数。 ----- -#### [时间节点] + + +## [时间节点] 提供`TimingStamp,TimeStamp`。 TimingStamp用于时间快速转换,以及在unity界面上呈现的能力。 TimeStamp用于隐式的,在极短时间内 (小于1tick) 的时间戳的名称标记。 ----- -#### [空对象] + + +## [空对象] 提供`Empty\`用来快速创建一个空对象。 这个空对象中包含空列表,等其他多种资源。 值得注意的是,在创建空组件时 (component) 会从超驰库中使用自动实例化命令执行这一过程,可能会导致在场景中出现空节点 (GameObject) ----- -#### [类标签] + + +## [类标签] 提供`CanFind`系列特性。 * 使用`CanFindClass`标记类 @@ -274,7 +370,8 @@ TimeStamp用于隐式的,在极短时间内 (小于1tick) 的时间戳的名 需要手动通过不同的分类进行标记,如使用`CusMeProperty`来标记属性。 包含被标记的特性的类在创建实例时,可以通过`CusMeManagerment的实例通过AddTarget`添加目标,被添加的成员可以用于菜单构建。 ----- -#### [排挤网格]()(正在实现) ----- \ No newline at end of file + +## [排挤网格]()(正在实现) + +