更新 HowToUseXericLibrary

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