文档站副本
本页为语义契约的发布副本；请在上游 ZTSTest/Docs/spec 修改后执行 npm run sync-spec。（源：marshal\08-ENUM.md）
枚举 Marshal
规范性： C#
enum在 JavaScript 与 C# 之间的默认 Marshal 规则。 相关： 类型表常量 → ../02-TYPE-SYSTEM.md §3.5；zts.box→ ../05-LIB.md；refenum → 03-BYREF.md；[TsMarshalAs]→ 02-MARSHAL-AS.md。
平台原则： 枚举默认 不 推送 exotic，而按 number（整数） Marshal。v1 禁止 bigint 通道（../00-OVERVIEW.md §1.3）。
1. 设计要点
| 场景 | 形态 |
|---|---|
| 默认传参 | number（Number.isInteger） |
| boxed 实例 | ByObj exotic；仅 zts.box |
| 类型表常量 | number 属性（非 exotic） |
枚举类型对象 无 [[Construct]]；不可 new EnumType(...) 构造 ByVal。
2. 默认规则（C# ↔ JavaScript）
| 方向 | 默认形态 | 说明 |
|---|---|---|
| C# → JS | number（整数） | 底层整数值；不 Push exotic |
| JS → C# | number（整数） | Enum.ToObject / 等价 |
| JS → C#（备选） | ByObj exotic（boxed） | 解包 underlying |
不接受（除非另行标注）：枚举 名字 string、boolean、plain object。
undefined：必选 enum 形参 → throw；Nullable<enum> 无值 → null/undefined（01-OVERVIEW.md §2）。
3. 底层类型与范围
读取 enum underlying type（Int32、Byte 等）：
| 底层类型 | Push | Pop |
|---|---|---|
sbyte … ulong | number 整数 | number 整数 + 范围校验 |
Pop 越界 → throw Error('zts: …')。
禁止 bigint Pop → throw Error('zts: bigint is not supported for enum marshal')（或等价文案）。
4. 类型表常量字段
const Color = CSharp.AC['MyGame.Color'];
console.assert(Color.Red === 0); // number，非 exotic
foo(Color.Red);
foo(1); // 裸整型，须可转换为该 enum
5. Boxed 形态（zts.box）
const boxed = zts.box(Color, Color.Green);
const boxed2 = zts.box(Color, 2);
| 项 | 说明 |
|---|---|
| 返回值 | ByObj exotic（boxed） |
| 拆箱 | zts.unbox(boxed) → underlying number |
ref Color | boxed 走临时槽路径（03-BYREF.md） |
6. ref / out / in enum
| JS 实参 | 行为 |
|---|---|
| OpaqueValue | handle 地址 |
integer number | 临时槽 |
zts.box 产物 | 临时槽 |
C#→JS：ref enum 默认 OpaqueValue。
7. [TsMarshalAs] 扩展
| 标注 | by-val enum |
|---|---|
Default | §2 |
Object | 非法（by-val）；回退 Default |
OpaqueValue | C#→JS 合法 |
Table / UnpackedValues | 非法 |
8. 与 struct / class 差异（摘要）
| 项 | enum | struct | class |
|---|---|---|---|
| 默认跨边界 | number | ByVal exotic | ByObj exotic |
[[Construct]] | 无 | 有 | 有 |
| boxed | zts.box | box / ByVal | 构造 |
9. Mono / Il2Cpp 一致性
默认 Push/Pop、常量、zts.box、范围校验、bigint 拒绝 — 须一致。
10. 相关文档
| 文档 | 内容 |
|---|---|
| 01-OVERVIEW.md | number、禁止 bigint |
| 03-BYREF.md | byref |
| 05-STRUCT.md | box 对比 |
| ../02-TYPE-SYSTEM.md | 枚举类型表 |