跳到主要内容

类型系统概览

谁该读本文

已在 JS/TS 中访问 C#、需要理解 CSharp / csharp: 与静/实例隔离的开发者。 入门语法见 JS 调用 C#；权威契约见 02-TYPE-SYSTEM。

设计目标​

目标说明
统一入口普通类型经 CSharp 懒加载；脚本推荐 import { T } from "csharp:…"，与 CSharp 同一类型对象
语义贴近 C#Type.Static()、obj.Method()、new Type(...)
静实例隔离静态与实例成员使用 独立 三表
仅 publicJS 仅可访问 public 成员
Bind 期扁平继承继承成员在 EnsureBinding 写入当前类型三表；无运行时沿链查找
strict miss未注册成员 throw Error('zts: member not found: …')

两条等价入口​

flowchart TB
    R[CSharp 根对象] --> A[assembly 对象]
    A --> T[类型对象 Demo]
    IM["import from csharp:asm/ns"] --> T
    T --> SMT[静态三表\nmethod / getter / setter]
    T --> IEO[实例分派原型 IEO]
    T --> Ctor["new Type(...)"]
    Ctor --> INST[实例 exotic object]
    INST --> IEO
入口写法用途
csharp:（推荐）import { Demo } from "csharp:Assembly-CSharp"业务脚本、TS 声明友好
CSharp（权威低层）CSharp['Assembly-CSharp'].Demo调试、嵌套类型、adaptor

csharp: 在宿主 moduleLoader 之前拦截；禁止把 csharp: 交给业务 loader。

程序集别名（惯例）​

CSharp.AC = CSharp["Assembly-CSharp"];
const demo = new CSharp.AC.Demo();

命名空间与嵌套类型​

场景写法
无命名空间 + 合法标识符CSharp.AC.Demo
有命名空间CSharp.AC['MyGame.UI.Panel']（必须整段键）
嵌套类型CSharp.AC['Outer+Inner']（+ 分隔，禁止用 .）
csharp: 带命名空间import { Panel } from "csharp:Assembly-CSharp/MyGame.UI"

禁止 CSharp.AC.MyGame.UI.Panel——. 属于 CLR 全名字符串，不是 JS 路径。

静实例隔离​

静态成员与实例成员 不得混用：

操作正确错误
静态方法Demo.Add(1, 2)demo.Add(1, 2)（若 Add 仅为静态）
实例方法demo.GetX()Demo.GetX()（无静态同名时 miss）
静态字段Demo.s_x = 1demo.s_x = 1
方法 this

obj.Method(args) 作为 方法调用 时自动传入 CLR this。把方法提取为独立函数再调用时 不 自动绑定（与常见 JS 行为一致）。

flowchart LR
    subgraph Static["类型对象 / STO（静态域）"]
        SM[methodTable]
        SG[fieldGetter]
        SS[fieldSetter]
    end

    subgraph Instance["实例 exotic / IEO（实例域）"]
        IM[methodTable]
        IG[fieldGetter]
        IS[fieldSetter]
    end

    JS["JS 脚本"] -->|Type.Static| Static
    JS -->|obj.Method| Instance

构造​

类型构造方式
class / structnew Type(...args)
struct 默认实例类型上的 _default（若提供）
enum无 new；用静态字面量 / 数值规则
Nullable经类型 [[Construct]] 构造 element

禁止依赖脚本侧 _ctor 字段——规范不在类型对象上暴露与构造等价的 _ctor 属性。

懒加载与 EnsureBinding​

首次取得某类型对象时，运行时扫描 public 成员并填充静/实例三表：

sequenceDiagram
    participant J as JS
    participant T as 类型对象
    participant N as EnsureBinding

    J->>T: import / CSharp.AC.Demo
    alt 未绑定
        T->>N: 触发绑定
        N->>T: 注册 method/field/event 表
    end
    J->>T: demo.Run(10)
运行时绑定实现
MonoExpression Emit + 懒绑定
Il2CppGenerate stub + 懒绑定

泛型与数组（摘要）​

场景入口
开放泛型定义CSharp.mscorlib['System.Collections.Generic.List1']`
闭合泛型zts.make_generic_type(...) 等（见 05-LIB）
数组类型类型系统 §7 / 数组指南

详见 泛型指南。

undefined / null 与 miss​

场景行为
读 C# 绑定不存在的成员throw Error（不是 undefined）
读普通 JS 对象缺失属性ECMAScript 默认 undefined
CLR 引用 nullJS null
必选引用形参传 undefinedthrow Error（须显式 null）

完整规则见 Marshal 概览。

何时读规范​

问题文档
成员如何分派？Exotic 对象模型
重载与别名？方法重载规范 · TsAlias
数组 / 继承？类型系统规范
扩展方法？扩展方法

相关文档​