SuperAPI AI 工具集

new-control-api

编程与开发

查看项目

更新于 10-16 05:06

技能介绍

用途:为既有 WinForms 控件或组件新增公共或受保护成员(属性、方法、事件、委托、枚举、接口)时遵循的规范;创建全新控件请改用 coding-standards 技能。核心原则:每个新公共 API 都必须先跟踪、评审、编写文档并保证可序列化后才能发布。

主要能力与要求:

  1. API 议题跟踪:需在上游仓库查找带 api-suggestion 标签的议题;在 Copilot CLI/Web-UI 中可调用 GitHub API,VS Code/Visual Studio 中应由用户手动管理;禁止在上游仓库新建议题,必要时在 origin fork 中创建或更新。议题需包含背景动机、API 提案(仅完整公共签名,无方法体)、用法示例、替代设计、风险、对 UI 控件(设计器、可访问性、本地化)的影响。
  2. PublicAPI 文件登记:新公共/受保护成员须写入对应项目的 PublicAPI.Unshipped.txt(如 src\System.Windows.Forms\PublicAPI.Unshipped.txt),发布前再移入 Shipped;条目按 Roslyn PublicAPI 格式,访问器各占一行、全限定、字母排序,nullable 用 ? 与 ! 标记,接口成员同样纳入评审。
  3. 属性约定:属性值必须存入 Properties(PropertyStore),每属性一个静态键 PropertyStore.CreateKey();值类型用 GetValueOrDefault 与 AddOrRemoveValue,引用类型同理;须有 CodeDOM 序列化策略([DefaultValue]、[DesignerSerializationVisibility(Hidden)] 或私有 ShouldSerialize/Reset);须提供 protected virtual On[Property]Changed 与 [Property]Changed 事件;使用 SRCategory、SRDescription 等设计时特性,字符串放入 SR.resx。
  4. 事件约定:常规事件用 EventHandler 与 EventArgs.Empty;带数据时自定义 EventArgs 子类与专用委托而非 EventHandler<T>;委托存于 Events 集合配静态键,仅在单一事件组件(如 Timer.Tick)可用字段。
  5. 方法约定:用 ArgumentNullException.ThrowIfNull 等 throw helper 校验参数;需要派生控件重写时用 protected virtual。
  6. XML 文档:所有新公共/受保护成员须有文档,含 summary、param、returns、exception,复杂成员补充 remarks、example;嵌套缩进 1 空格,用 Unicode 字符与 <see cref>。
  7. 版本保护:新 API 须用 #if NET11_0_OR_GREATER 预处理器包裹,测试同样加保护。

提交前检查:议题存在、PublicAPI 已登记、版本保护到位、属性经 PropertyStore 存储、有序列化策略与变更通知、事件委托经 Events 集合存储。

限制:资料未提供具体运行命令、安装方式、收费信息或平台支持范围,暂未提供;本文不涉及创建新控件或通用编码标准。