怎么读组件文档

组件库（顶部「组件」入口，或直达 /components）收录了一百多个框架组件。它们看起来量大，但每一页都由同一套模板自动生成，结构、字段、阅读方式完全一致。所以这一页不教你某个具体组件，而是教你"打开任意组件页时，从上到下该看什么、怎么查"。掌握了它，后面翻任何组件都是五秒钟的事。

一个组件页的固定骨架

从上到下，每个组件页都是这几段：

1. 标题行：组件类名（如 Button）+ 中文名（如「按钮」）+ 一句话简介（excerpt）。类名就是你在 Razor 里写的标签名，也是这页的 URL 段——Button 对应 /components/Button。
2. 在线示例区：一块能真正点、能改参数看效果的交互示例。它是一段按需加载的 WebAssembly 孤岛，所以刚进页面时可能短暂显示"正在加载在线示例…"，等一两秒即可。这一区是组件文档的灵魂——不用读代码，先把控件点一遍，行为就懂了大半。
3. 说明：这个组件的设计意图与关键取舍（比如 Button 会说"Kind 决定语义配色、Size 决定尺寸、Loading 会自动禁用并显示加载指示"）。
4. 常见能力：几条要点，列出它支持的能力维度（语义风格、尺寸、块级、仅图标等），适合快速扫一眼"它能不能干我要的活"。
5. 用法：一段可直接照抄的 Razor 代码样例。
6. API 参数表：一页里最硬的资产，下一节专门讲。

读懂 API 参数表

参数表是四列：参数 / 类型 / 默认值 / 说明。它是 DocGen 反射组件真实类型自动生成的，永远和代码同步，所以类型和默认值这一栏可信度最高——遇到说明文字没写清的，直接看类型和默认值推断。

几个固定的读法：

• 名字带 Changed、或类型是 EventCallback<...> 的行，会在说明列标一个 事件 —— 那是回调出口，配合前面的 Value 就能写双向绑定（@bind-Value）。例如 Visible 旁边跟着 VisibleChanged、Button 的 OnClick。
• 类型写成 RenderFragment 的行（如 ChildContent）表示"这个组件可以夹子内容"，用它写标签之间的内容。
• 字符串枚举型的参数（如 Kind、Size、IconPosition），说明列会把可选值一一列出（primary / outline / soft / text …），照着挑即可。
• 表格末尾的 Visible、Class、Disabled、Style 四行是空的说明，别以为是遗漏——它们来自所有组件共同继承的 BaseComponent，全站通用，因此这里刻意不重复解释。想搞懂这四个（以及 UserAttributes）怎么用，看组件通用约定，那一页讲一次、这里全部适用。表下方那句"所有组件均继承 BaseComponent…"就是这个指引。

分组与顺序：怎么在左侧目录里定位

组件不是一股脑平铺，而是按用途分成若干分组（基础、表单、数据展示、反馈、布局、媒体、设备、AI……），每个组件归属一个 group。左侧目录就是按分组折叠展开的；同组内按 order 排序（Button 是 base 组的 101）。你也可以直接在浏览器里用 /components/{类名} 命中某页——知道类名就无需翻目录。

这些页为什么不能手改，以及去哪看更全的信息

每个组件 .md 文件顶部都有一行注释："本文件由 Tools/DocGen 从 Known.Docs 组件目录自动生成，请勿手改"。它的真相源有两处——一是 Known.Docs 里的组件目录（Catalog.*.cs 的 DocInfo：简介、说明、能力要点、代码样例），二是组件类型本身（参数、类型、默认值、参数上的 XML 摘要）。所以：

• 说明列某行是空的 → 大概率是该参数的 XML 摘要没写或写得简略，属于文档源信息缺失，而非组件缺功能。
• 想要最权威、最新的参数（包括文档还没补全说明的） → 直接跳到开源仓库里看组件源码，或用在线示例把参数试出来。
• 如果你在给框架新增/改组件 → 要同步改的是 Catalog.*.cs 的 DocInfo 和组件上的 [Parameter] XML 摘要，重新构建后这些页会自动重生成，不要去手改 .md。

快速上手建议

第一次来，先看组件通用约定把 BaseComponent、@bind-Value、UIService 三件事建立起来；然后回到组件库，随便挑一个你正要用的组件，先点在线示例、再扫一眼 API 表的类型列——绝大多数需求这两步就够了，读说明只是补充。