Repository navigation
fix(api): 补齐公开成员文档并保留泛型类型 - #28
Merged
Merged
Conversation
|
✅ 编译完成，产物如下：
在 Actions 运行页 Artifacts 区域按平台名称下载。 |
文档变更tdesign-component/example/assets/api/action_sheet_api.md--- /dev/null 2026-10-07 20:31:19.541382546 +0000
+++ ./tdesign-component/example/assets/api/action_sheet_api.md 2026-10-07 20:32:47.650045428 +0000
@@ -0,0 +1,135 @@
+## API
+
+默认值列展示源码声明的默认值；`-` 表示未显式声明。运行时的 Theme / Token 回退见说明，参数是否必填见「必填」列。
+
+### TActionSheet
+
+#### 声明
+
+```dart
+final class TActionSheet
+```
+
+
+#### 静态方法
+
+##### TActionSheet.showGrid
+
+```dart
+static TPopupHandle showGrid<T>(
+ BuildContext context, {
+ required List<TActionSheetItem<T>> items,
+ TActionSheetGridLayout layout = const TActionSheetGridLayout.fixed(),
+ String? cancelText,
+ String? subtitle,
+ bool showCancel = true,
+ bool showOverlay = true,
+ bool closeOnOverlayClick = true,
+ bool useSafeArea = true,
+ double? itemHeight,
+ VoidCallback? onCancel,
+ VoidCallback? onClosed,
+ TActionSheetOnSelected<T>? onSelected,
+})
+```
+
+
+显示宫格动作面板
+
+返回类型：`TPopupHandle`
+
+| 参数 | 类型 | 默认值 | 说明 | 必填 |
+| --- | --- | --- | --- | --- |
+| context | BuildContext | - | 用于查找承载弹层的 Navigator。 | 是 |
+| items | List<TActionSheetItem<T>> | - | 宫格中的动作项目。 | 是 |
+| layout | TActionSheetGridLayout | const TActionSheetGridLayout.fixed() | 普通、分页或横向滚动宫格布局。 | 否 |
+| cancelText | String? | - | 取消按钮文字。 | 否 |
+| subtitle | String? | - | 面板副标题；为 null 或空字符串时不展示。 | 否 |
+| showCancel | bool | true | 是否显示取消按钮。 | 否 |
+| showOverlay | bool | true | 是否显示蒙层。 | 否 |
+| closeOnOverlayClick | bool | true | 点击蒙层是否关闭。 | 否 |
+| useSafeArea | bool | true | 是否避让系统安全区。 | 否 |
+| itemHeight | double? | - | 宫格项目高度。 | 否 |
+| onCancel | VoidCallback? | - | 点击取消时回调。 | 否 |
+| onClosed | VoidCallback? | - | 面板关闭后回调。 | 否 |
+| onSelected | TActionSheetOnSelected<T>? | - | 点击动作时回调。 | 否 |
+
+
+##### TActionSheet.showGridSections
+
+```dart
+static TPopupHandle showGridSections<T>(
+ BuildContext context, {
+ required List<TActionSheetGridSection<T>> sections,
+ String? cancelText,
+ bool showCancel = true,
+ bool showOverlay = true,
+ bool closeOnOverlayClick = true,
+ bool useSafeArea = true,
+ double itemWidth = 80,
+ double? itemHeight,
+ VoidCallback? onCancel,
+ VoidCallback? onClosed,
+ TActionSheetOnSelected<T>? onSelected,
+})
+```
+
+
+显示带标题分组的横向滚动宫格动作面板。
+
+返回类型：`TPopupHandle`
+
+| 参数 | 类型 | 默认值 | 说明 | 必填 |
+| --- | --- | --- | --- | --- |
+| context | BuildContext | - | 用于查找承载弹层的 Navigator。 | 是 |
+| sections | List<TActionSheetGridSection<T>> | - | 带标题的分组列表，每组独立横向滚动。 | 是 |
+| cancelText | String? | - | 取消按钮文字，为 null 时使用本地化文案。 | 否 |
+| showCancel | bool | true | 是否显示取消按钮。 | 否 |
+| showOverlay | bool | true | 是否显示蒙层。 | 否 |
+| closeOnOverlayClick | bool | true | 点击蒙层是否关闭。 | 否 |
+| useSafeArea | bool | true | 是否避让系统安全区。 | 否 |
+| itemWidth | double | 80 | 横向列表单项宽度，默认为 80。 | 否 |
+| itemHeight | double? | - | 单项高度；为 null 时使用组件主题，最终回退为 96。 | 否 |
+| onCancel | VoidCallback? | - | 点击取消时回调。 | 否 |
+| onClosed | VoidCallback? | - | 面板关闭后回调。 | 否 |
+| onSelected | TActionSheetOnSelected<T>? | - | 点击项目时回传原始项目。 | 否 |
+
+
+##### TActionSheet.showList
+
+```dart
+static TPopupHandle showList<T>(
+ BuildContext context, {
+ required List<TActionSheetItem<T>> items,
+ TActionSheetAlign align = TActionSheetAlign.center,
+ String? cancelText,
+ String? subtitle,
+ bool showCancel = true,
+ bool showOverlay = true,
+ bool closeOnOverlayClick = true,
+ bool useSafeArea = true,
+ VoidCallback? onCancel,
+ VoidCallback? onClosed,
+ TActionSheetOnSelected<T>? onSelected,
+})
+```
+
+
+显示列表动作面板
+
+返回类型：`TPopupHandle`
+
+| 参数 | 类型 | 默认值 | 说明 | 必填 |
+| --- | --- | --- | --- | --- |
+| context | BuildContext | - | 用于查找承载弹层的 Navigator。 | 是 |
+| items | List<TActionSheetItem<T>> | - | 列表中的动作项目。 | 是 |
+| align | TActionSheetAlign | TActionSheetAlign.center | 项目文字对齐方式。 | 否 |
+| cancelText | String? | - | 取消按钮文字。 | 否 |
+| subtitle | String? | - | 面板副标题；为 null 或空字符串时不展示。 | 否 |
+| showCancel | bool | true | 是否显示取消按钮。 | 否 |
+| showOverlay | bool | true | 是否显示蒙层。 | 否 |
+| closeOnOverlayClick | bool | true | 点击蒙层是否关闭。 | 否 |
+| useSafeArea | bool | true | 是否避让系统安全区。 | 否 |
+| onCancel | VoidCallback? | - | 点击取消时回调。 | 否 |
+| onClosed | VoidCallback? | - | 面板关闭后回调。 | 否 |
+| onSelected | TActionSheetOnSelected<T>? | - | 点击动作时回调。 | 否 |tdesign-component/example/assets/api/avatar_api.mddiff --git a/tdesign-component/example/assets/api/avatar_api.md b/tdesign-component/example/assets/api/avatar_api.md
index 6ceb808..fb9d20c 100644
--- a/tdesign-component/example/assets/api/avatar_api.md
+++ b/tdesign-component/example/assets/api/avatar_api.md
@@ -1,43 +1,38 @@
## API
+
+默认值列展示源码声明的默认值；`-` 表示未显式声明。运行时的 Theme / Token 回退见说明，参数是否必填见「必填」列。
+
### TAvatar
-#### 默认构造方法
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| child | Widget? | - | 自定义头像内容。 |
-| fit | BoxFit | BoxFit.cover | 图片填充方式。 |
-| image | ImageProvider<Object>? | - | 头像图片。 |
-| key | Key? | - | 组件标识，用于区分或保留组件状态。 |
-| onTap | GestureTapCallback? | - | 点击回调；为空时头像不创建点击行为。 |
-| shape | TAvatarShape? | - | 头像形状；未设置时使用圆形默认值。 |
-| size | TAvatarSize? | - | 头像尺寸；未设置时继承所在头像组的尺寸，独立使用时默认为中号。 |
+#### 声明
+```dart
+class TAvatar extends StatelessWidget
+```
-### TAvatarGroup
#### 默认构造方法
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| cascading | TAvatarGroupCascading | TAvatarGroupCascading.endUp | 头像组成员的层叠方向，使用 start/end 语义并跟随文字方向。 |
-| children | List<Widget> | - | 头像列表。 |
-| key | Key? | - | 组件标识，用于区分或保留组件状态。 |
-| maxCount | int? | - | 最多显示的头像数量。 |
-| overflow | Widget? | - | 发生截断时显示在末尾的内容。 |
-| spacing | double? | - | 相邻头像的重叠宽度；有效范围为 0 到成员外框边长。 |
+```dart
+const TAvatar({
+ this.image,
+ this.child,
+ this.size,
+ this.shape,
+ this.fit = BoxFit.cover,
+ this.onTap,
+ super.key,
+})
+```
-### TAvatarThemeData
-#### 默认构造方法
+##### 参数
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| backgroundColor | Color? | - | 默认背景色；未设置时回退全局 `brandColorLightActive`。 |
-| circleBorderRadius | double? | - | 圆形头像圆角；未设置时回退全局 `radiusCircle`（逻辑像素）。 |
-| dimension | double? | - | 自定义头像边长。 |
-| foregroundColor | Color? | - | 默认图标与继承文字的前景色；未设置时回退全局品牌色。 |
-| groupBorderColor | Color? | - | 头像组成员描边颜色。 |
-| groupBorderWidth | double? | - | 头像组成员描边宽度。 未设置时按成员尺寸使用小/中/大 1/2/3 逻辑像素。 |
-| groupShadow | BoxShadow? | - | 头像组成员阴影；未设置时使用 1px 水平偏移、2px `blurRadius` 和 15% 黑色。 |
-| groupSpacing | double? | - | 头像组重叠宽度。 |
-| iconSize | double? | - | 默认图标大小。 |
-| squareBorderRadius | double? | - | 方形头像圆角；未设置时回退全局 `radiusDefault`（默认 6 逻辑像素）。 |
+| 参数 | 类型 | 默认值 | 说明 | 必填 |
+| --- | --- | --- | --- | --- |
+| child | Widget? | - | 自定义头像内容。 | 否 |
+| fit | BoxFit | BoxFit.cover | 图片填充方式。 | 否 |
+| image | ImageProvider<Object>? | - | 头像图片。 | 否 |
+| key | Key? | - | 组件标识，用于区分或保留组件状态。 | 否 |
+| onTap | GestureTapCallback? | - | 点击回调；为空时头像不创建点击行为。 | 否 |
+| shape | TAvatarShape? | - | 头像形状；未设置时使用圆形默认值。 | 否 |
+| size | TAvatarSize? | - | 头像尺寸；未设置时继承所在头像组的尺寸，独立使用时默认为中号。 | 否 |tdesign-component/example/assets/api/backtop_api.md--- /dev/null 2026-10-07 20:31:19.541382546 +0000
+++ ./tdesign-component/example/assets/api/backtop_api.md 2026-10-07 20:32:47.628348916 +0000
@@ -0,0 +1,4 @@
+## API
+
+默认值列展示源码声明的默认值；`-` 表示未显式声明。运行时的 Theme / Token 回退见说明，参数是否必填见「必填」列。
+tdesign-component/example/assets/api/badge_api.mddiff --git a/tdesign-component/example/assets/api/badge_api.md b/tdesign-component/example/assets/api/badge_api.md
index 72c2419..5ef82d4 100644
--- a/tdesign-component/example/assets/api/badge_api.md
+++ b/tdesign-component/example/assets/api/badge_api.md
@@ -1,111 +1,84 @@
## API
-### TBadge
-#### 简介
-在内容边角或独立位置展示短文本、圆点或角标状态。
-默认使用 `TBadgeVariant.circle` 与 `TBadgeSize.medium`。当 `child` 非空时，
-徽标叠加在 `child` 上；当 `child` 为空时，只渲染徽标本体。
-TabBar、SideBar、ActionSheet 等内部拥有锚点的组合组件使用
-`TBadgeConfig`，调用方不应向这些组件传入一个待拆解的 `TBadge`。
-
-#### 工厂构造方法
-
-##### TBadge.custom
-
-创建完全自定义外观的徽标；`badge` 是徽标本体，`child` 是可选锚点，未提供锚点时直接展示徽标本体。
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| key | Key? | - | 组件标识，用于区分或保留组件状态。 |
-| badge | Widget? | - | `TBadge.custom` 提供的完整徽标外观。 普通构造下为 null。该 Widget 仅表示徽标本体，不包含 `child`。 |
-| alignment | AlignmentGeometry? | - | 徽标相对 `child` 的对齐方式。 为空时使用组合组件提供的对齐位置，最终回退为逻辑 右上角 `AlignmentDirectional.topEnd`，在 RTL 下对应物理左上角。 ribbon、triangle 的方位已编码在 `variant` 中，不读取该字段。 当 `child` 为空时不参与布局。 |
-| offset | Offset? | - | 相对默认锚点的逐实例位置偏移；未设置时使用组合组件提供的 默认偏移，最终回退为 `Offset.zero`。 显式值使用物理坐标：正 x 始终向右，RTL 下不会自动镜像。 默认徽标以中心点对齐内容的逻辑右上角，在 RTL 下对应物理左上角。 当 `child` 为空时不参与布局。 |
-| child | Widget? | - | 被徽标标记的内容；为空时徽标可独立展示。 |
-| onTap | GestureTapCallback? | - | 点击徽标及其 `child` 时触发；为空时不创建点击语义。 |
+默认值列展示源码声明的默认值；`-` 表示未显式声明。运行时的 Theme / Token 回退见说明，参数是否必填见「必填」列。
-#### 默认构造方法
+### TBadge
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| alignment | AlignmentGeometry? | - | 徽标相对 `child` 的对齐方式。 为空时使用组合组件提供的对齐位置，最终回退为逻辑 右上角 `AlignmentDirectional.topEnd`，在 RTL 下对应物理左上角。 ribbon、triangle 的方位已编码在 `variant` 中，不读取该字段。 当 `child` 为空时不参与布局。 |
-| border | bool | false | 是否为徽标增加对比色描边，默认为 false，适用于全部形态。 |
-| child | Widget? | - | 被徽标标记的内容；为空时徽标可独立展示。 |
-| key | Key? | - | 组件标识，用于区分或保留组件状态。 |
-| label | String? | '0' | 徽标实际展示的短文本，例如 `8`、`99+` 或 `NEW`。 文本形态下为 null 时隐藏徽标；`TBadgeVariant.dot` 不读取该字段。 |
-| offset | Offset? | - | 相对默认锚点的逐实例位置偏移；未设置时使用组合组件提供的 默认偏移，最终回退为 `Offset.zero`。 显式值使用物理坐标：正 x 始终向右，RTL 下不会自动镜像。 默认徽标以中心点对齐内容的逻辑右上角，在 RTL 下对应物理左上角。 当 `child` 为空时不参与布局。 |
-| onTap | GestureTapCallback? | - | 点击徽标及其 `child` 时触发；为空时不创建点击语义。 |
-| showZero | bool | true | `label` 恰好为字符串 `0` 时是否显示徽标，默认为 true。 `TBadgeVariant.dot` 始终显示，不受该字段影响。 |
-| size | TBadgeSize | TBadgeSize.medium | 徽标的预设尺寸，默认为 `TBadgeSize.medium`。 `TBadgeVariant.dot` 与 `TBadge.custom` 不读取该字段。 |
-| variant | TBadgeVariant | TBadgeVariant.circle | 徽标的结构形态，默认为 `TBadgeVariant.circle`。 `TBadge.custom` 不读取该字段。 |
-
-#### 公开属性
+#### 声明
-| 属性 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| badge | Widget? | - | `TBadge.custom` 提供的完整徽标外观。 普通构造下为 null。该 Widget 仅表示徽标本体，不包含 `child`。 |
+```dart
+class TBadge extends StatelessWidget
+```
-### TBadgeConfig
-#### 简介
-由组合组件消费的徽标配置。
-该对象不参与 Widget 树，也不拥有被标记的内容。仅当 TabBar、SideBar、
-ActionSheet 等组件在内部创建徽标锚点时使用；组件会把配置和自己的锚点交给
-与 `TBadge` 相同的渲染实现。
-调用方已经拥有锚点 Widget 时，应直接使用 `TBadge`：
+#### 命名构造方法
-完全自定义徽标外观时使用 `TBadgeConfig.custom`。传入的 `badge` 是徽标本体，
-不应包含锚点或自行使用 `Positioned` 定位。
+##### TBadge.custom
-#### 工厂构造方法
+```dart
+const TBadge.custom({
+ super.key,
+ required this.badge,
+ this.alignment,
+ this.offset,
+ this.child,
+ this.onTap,
+})
+```
-##### TBadgeConfig.custom
-创建完全自定义外观的徽标配置。
+创建完全自定义外观的徽标；`badge` 是徽标本体，`child` 是可选锚点，未提供锚点时直接展示徽标本体。
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| badge | Widget? | - | 仅定义徽标本体；最终锚点和默认位置由消费该配置的组合组件决定。 |
-| alignment | AlignmentGeometry? | - | 徽标相对锚点的对齐方式。 为空时使用消费组件的默认值。 ribbon、triangle 的方位已编码在 `variant` 中，不读取该字段。 |
-| offset | Offset? | - | 在最终对齐位置上追加的偏移。 为空时使用消费组件的默认值。 显式值使用物理坐标：正 x 始终向右，RTL 下不会自动镜像；消费组件仅会 根据最终生效的 `alignment` 转换自己提供的默认偏移。 ribbon、triangle 始终贴住锚点的物理左上角或右上角，但仍读取该偏移。 |
+| 参数 | 类型 | 默认值 | 说明 | 必填 |
+| --- | --- | --- | --- | --- |
+| key | Key? | - | 组件标识，用于区分或保留组件状态。 | 否 |
+| badge | Widget? | - | `TBadge.custom` 提供的完整徽标外观。 普通构造下为 null。该 Widget 仅表示徽标本体，不包含 `child`。 | 是 |
+| alignment | AlignmentGeometry? | - | 徽标相对 `child` 的对齐方式。 为空时使用组合组件提供的对齐位置，最终回退为逻辑 右上角 `AlignmentDirectional.topEnd`，在 RTL 下对应物理左上角。 ribbon、triangle 的方位已编码在 `variant` 中，不读取该字段。 当 `child` 为空时不参与布局。 | 否 |
+| offset | Offset? | - | 相对默认锚点的逐实例位置偏移；未设置时使用组合组件提供的 默认偏移，最终回退为 `Offset.zero`。 显式值使用物理坐标：正 x 始终向右，RTL 下不会自动镜像。 默认徽标以中心点对齐内容的逻辑右上角，在 RTL 下对应物理左上角。 当 `child` 为空时不参与布局。 | 否 |
+| child | Widget? | - | 被徽标标记的内容；为空时徽标可独立展示。 | 否 |
+| onTap | GestureTapCallback? | - | 点击徽标及其 `child` 时触发；为空时不创建点击语义。 | 否 |
#### 默认构造方法
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| alignment | AlignmentGeometry? | - | 徽标相对锚点的对齐方式。 为空时使用消费组件的默认值。 ribbon、triangle 的方位已编码在 `variant` 中，不读取该字段。 |
-| border | bool | false | 是否为预设徽标增加对比色描边，默认为 false。 `TBadgeConfig.custom` 不读取该字段。 |
-| label | String? | '0' | 预设徽标展示的短文本，例如 `8`、`99+` 或 `NEW`。 文本形态下为 null 时隐藏徽标；`TBadgeVariant.dot` 不读取该字段。 `TBadgeConfig.custom` 下固定为 null。 |
-| offset | Offset? | - | 在最终对齐位置上追加的偏移。 为空时使用消费组件的默认值。 显式值使用物理坐标：正 x 始终向右，RTL 下不会自动镜像；消费组件仅会 根据最终生效的 `alignment` 转换自己提供的默认偏移。 ribbon、triangle 始终贴住锚点的物理左上角或右上角，但仍读取该偏移。 |
-| showZero | bool | true | `label` 恰好为字符串 `0` 时是否显示，默认为 true。 `TBadgeVariant.dot` 与 `TBadgeConfig.custom` 不读取该字段。 |
-| size | TBadgeSize | TBadgeSize.medium | 预设徽标尺寸，默认为 `TBadgeSize.medium`。 `TBadgeVariant.dot` 与 `TBadgeConfig.custom` 不读取该字段。 |
-| variant | TBadgeVariant | TBadgeVariant.circle | 预设徽标的结构形态，默认为 `TBadgeVariant.circle`。 `TBadgeConfig.custom` 不读取该字段。 |
-#### 公开属性
+```dart
+const TBadge({
+ super.key,
+ this.label = '0',
+ this.variant = TBadgeVariant.circle,
+ this.size = TBadgeSize.medium,
+ this.border = false,
+ this.showZero = true,
+ this.alignment,
+ this.offset,
+ this.child,
+ this.onTap,
+})
+```
+
+##### 参数
+
+| 参数 | 类型 | 默认值 | 说明 | 必填 |
+| --- | --- | --- | --- | --- |
+| alignment | AlignmentGeometry? | - | 徽标相对 `child` 的对齐方式。 为空时使用组合组件提供的对齐位置，最终回退为逻辑 右上角 `AlignmentDirectional.topEnd`，在 RTL 下对应物理左上角。 ribbon、triangle 的方位已编码在 `variant` 中，不读取该字段。 当 `child` 为空时不参与布局。 | 否 |
+| border | bool | false | 是否为徽标增加对比色描边，默认为 false，适用于全部形态。 | 否 |
+| child | Widget? | - | 被徽标标记的内容；为空时徽标可独立展示。 | 否 |
+| key | Key? | - | 组件标识，用于区分或保留组件状态。 | 否 |
+| label | String? | '0' | 徽标实际展示的短文本，例如 `8`、`99+` 或 `NEW`。 文本形态下为 null 时隐藏徽标；`TBadgeVariant.dot` 不读取该字段。 | 否 |
+| offset | Offset? | - | 相对默认锚点的逐实例位置偏移；未设置时使用组合组件提供的 默认偏移，最终回退为 `Offset.zero`。 显式值使用物理坐标：正 x 始终向右，RTL 下不会自动镜像。 默认徽标以中心点对齐内容的逻辑右上角，在 RTL 下对应物理左上角。 当 `child` 为空时不参与布局。 | 否 |
+| onTap | GestureTapCallback? | - | 点击徽标及其 `child` 时触发；为空时不创建点击语义。 | 否 |
+| showZero | bool | true | `label` 恰好为字符串 `0` 时是否显示徽标，默认为 true。 `TBadgeVariant.dot` 始终显示，不受该字段影响。 | 否 |
+| size | TBadgeSize | TBadgeSize.medium | 徽标的预设尺寸，默认为 `TBadgeSize.medium`。 `TBadgeVariant.dot` 与 `TBadge.custom` 不读取该字段。 | 否 |
+| variant | TBadgeVariant | TBadgeVariant.circle | 徽标的结构形态，默认为 `TBadgeVariant.circle`。 `TBadge.custom` 不读取该字段。 | 否 |
+
+#### 公开属性（字段与访问器）
| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
-| badge | Widget? | - | `TBadgeConfig.custom` 提供的完整徽标外观。 普通构造下为 null。该 Widget 不包含锚点，定位由消费组件负责。 |
-
...（共 184 行）tdesign-component/example/assets/api/button_api.mddiff --git a/tdesign-component/example/assets/api/button_api.md b/tdesign-component/example/assets/api/button_api.md
index 603bd42..0d7badb 100644
--- a/tdesign-component/example/assets/api/button_api.md
+++ b/tdesign-component/example/assets/api/button_api.md
@@ -1,29 +1,46 @@
## API
+
+默认值列展示源码声明的默认值；`-` 表示未显式声明。运行时的 Theme / Token 回退见说明，参数是否必填见「必填」列。
+
### TButton
+
+#### 声明
+
+```dart
+class TButton extends StatefulWidget
+```
+
#### 默认构造方法
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| child | Widget? | - | 内容（纯文案用 `Text('...')`） |
-| colorPreset | TButtonColorPreset? | - | 内置配色预设；未传时使用 `TButtonColorPreset.defaultTheme`。 不改变 `variant` 的绘制方式，也不覆写显式 Material 按钮主题； 当前按钮的具体颜色、边框和文字样式通过 `style` 配置。 |
-| icon | Widget? | - | 图标（Widget 类型，IconData 需包裹为 `Icon(...)`） |
-| iconPosition | TButtonIconPosition | TButtonIconPosition.left | 图标位置 |
-| key | Key? | - | 组件标识，用于区分或保留组件状态。 |
-| onLongPress | VoidCallback? | - | 长按回调。 仅在 `onPressed` 非空时生效；当 `onPressed` 为空时按钮保持禁用态， 不会触发点击或长按回调。 |
-| onPressed | VoidCallback? | - | 点击回调，`null` 表示禁用 |
-| shape | TButtonShape | TButtonShape.rectangle | 按钮结构形状；纯图标的 square/circle 同时决定等宽高布局。 具体边框及圆角仍可通过 `style` 配置。 |
-| size | TButtonSize? | - | 尺寸，未传时使用 `TButtonSize.medium`。 默认按 48、40、32、28dp 的 TDesign 视觉高度参与布局。 |
-| style | ButtonStyle? | - | 当前按钮的完整 `ButtonStyle` 视觉配置入口，不影响其他按钮。 组件默认使用 `MaterialTapTargetSize.shrinkWrap` 保持 TDesign 精确尺寸； 需要至少 48dp 点击区时可将 `ButtonStyle.tapTargetSize` 设为 `MaterialTapTargetSize.padded`。 |
-| variant | TButtonVariant? | - | 变体（fill / outline / text / ghost），未传时使用 `TButtonVariant.fill`。 |
-
-
-### TButtonColorPreset
-#### 枚举值
-
-
-| 名称 | 说明 |
-| --- | --- |
-| defaultTheme | 默认配色 |
-| primary | 品牌主色 |
-| danger | 危险操作配色 |
-| light | 浅色品牌配色；不改变填充/描边等 `TButtonVariant` 绘制方式。 |
+
+```dart
+const TButton({
+ Key? key,
+ this.child,
+ this.size,
+ this.variant,
+ this.shape = TButtonShape.rectangle,
+ this.colorPreset,
+ this.icon,
+ this.iconPosition = TButtonIconPosition.left,
+ this.onPressed,
+ this.onLongPress,
+ this.style,
+})
+```
+
+##### 参数
+
+| 参数 | 类型 | 默认值 | 说明 | 必填 |
+| --- | --- | --- | --- | --- |
+| child | Widget? | - | 内容（纯文案用 `Text('...')`） | 否 |
+| colorPreset | TButtonColorPreset? | - | 内置配色预设；未传时使用 `TButtonColorPreset.defaultTheme`。 不改变 `variant` 的绘制方式，也不覆写显式 Material 按钮主题； 当前按钮的具体颜色、边框和文字样式通过 `style` 配置。 | 否 |
+| icon | Widget? | - | 图标（Widget 类型，IconData 需包裹为 `Icon(...)`） | 否 |
+| iconPosition | TButtonIconPosition | TButtonIconPosition.left | 图标位置 | 否 |
+| key | Key? | - | 组件标识，用于区分或保留组件状态。 | 否 |
+| onLongPress | VoidCallback? | - | 长按回调。 仅在 `onPressed` 非空时生效；当 `onPressed` 为空时按钮保持禁用态， 不会触发点击或长按回调。 | 否 |
+| onPressed | VoidCallback? | - | 点击回调，`null` 表示禁用 | 否 |
+| shape | TButtonShape | TButtonShape.rectangle | 按钮结构形状；纯图标的 square/circle 同时决定等宽高布局。 具体边框及圆角仍可通过 `style` 配置。 | 否 |
+| size | TButtonSize? | - | 尺寸，未传时使用 `TButtonSize.medium`。 默认按 48、40、32、28dp 的 TDesign 视觉高度参与布局。 | 否 |
+| style | ButtonStyle? | - | 当前按钮的完整 `ButtonStyle` 视觉配置入口，不影响其他按钮。 组件默认使用 `MaterialTapTargetSize.shrinkWrap` 保持 TDesign 精确尺寸； 需要至少 48dp 点击区时可将 `ButtonStyle.tapTargetSize` 设为 `MaterialTapTargetSize.padded`。 | 否 |
+| variant | TButtonVariant? | - | 变体（fill / outline / text / ghost），未传时使用 `TButtonVariant.fill`。 | 否 |tdesign-component/example/assets/api/calendar_api.mddiff --git a/tdesign-component/example/assets/api/calendar_api.md b/tdesign-component/example/assets/api/calendar_api.md
index 7202a7c..963c87b 100644
--- a/tdesign-component/example/assets/api/calendar_api.md
+++ b/tdesign-component/example/assets/api/calendar_api.md
@@ -1,96 +1,52 @@
## API
-### TCalendar
-#### 默认构造方法
-
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| anchorDate | DateTime? | - | 滚动锚点日期。 |
-| animateTo | bool | false | 锚点滚动是否使用动画。 |
-| cellBuilder | TCalendarCellBuilder? | - | 日期格构建器。 |
-| firstDayOfWeek | TCalendarFirstDayOfWeek | TCalendarFirstDayOfWeek.sunday | 每周从星期几开始，默认从星期日开始。 |
-| key | Key? | - | 组件标识，用于区分或保留组件状态。 |
-| maxDate | DateTime? | - | 最大可选日期。 |
-| minDate | DateTime? | - | 最小可选日期。 |
-| monthTitleBuilder | TCalendarMonthTitleBuilder? | - | 月标题构建器。 |
-| onChanged | ValueChanged<List<DateTime>>? | - | 选中日期变化回调；为 null 时禁用。 |
-| onMonthChanged | ValueChanged<DateTime>? | - | 可见月份变化回调。 |
-| subtitleBuilder | TCalendarSubtitleBuilder? | - | 日期副标题构建器。 |
-| value | List<DateTime> | - | 受控选中日期列表。 列表长度与 `variant` 对应： - `TCalendarVariant.single`：1 个元素（选中日期） - `TCalendarVariant.multiple`：N 个元素（所有选中日期） - `TCalendarVariant.range`：2 个元素（起始、结束日期） |
-| variant | TCalendarVariant | TCalendarVariant.single | 选择模式。 |
-| weekdayNames | List<String>? | - | 星期标题。未设置时使用当前资源代理中的文案。 |
-
-
-### TCalendarStyle
-
-#### 静态方法
-
-##### TCalendarStyle.generateStyle
-
-生成默认样式
-
-返回类型：`TCalendarStyle`
-
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| context | BuildContext? | - | - |
-
-#### 默认构造方法
-
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| bodyPadding | double? | - | 内边距 |
-| cellDecoration | BoxDecoration? | - | 日期单元格装饰（选中状态） |
-| cellHeight | double | 60 | 日期单元格高度，默认 60 |
-| centreColor | Color? | - | 区间中间格背景与格间衔接条颜色。 |
-| dayStyle | TextStyle? | - | 日期数字样式 |
-| decoration | BoxDecoration? | - | 组件容器装饰 |
-| monthTitleHeight | double | 22 | 月份标题高度，默认 22 |
-| monthTitleStyle | TextStyle? | - | 月份标题文字样式 |
-| subtitleStyle | TextStyle? | - | 副标题样式 |
-| todayDayStyle | TextStyle? | - | 今天日期数字样式 |
-| verticalGap | double? | - | 日期格垂直间距，水平间距为 `verticalGap` / 2 |
-| weekdayGap | double? | - | 星期之间的水平间距 |
-| weekdayStyle | TextStyle? | - | 星期文字样式 |
+默认值列展示源码声明的默认值；`-` 表示未显式声明。运行时的 Theme / Token 回退见说明，参数是否必填见「必填」列。
-### TCalendarCellModel
-#### 默认构造方法
-
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| date | DateTime | - | 当前日期。 |
-| isLastDayOfMonth | bool | - | 是否为当月最后一天。 |
-| selectType | DateSelectType | - | 当前格的选中、区间或禁用展示状态。 |
-
-
-### TCalendarSubtitleContext
-#### 默认构造方法
-
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| date | DateTime | - | 当前格子的阳历日期（仅年月日，无时分秒）。 |
-| selectType | DateSelectType | - | 当前格的选中/区间/禁用等展示状态，便于按态设置副标题样式。 |
-
+### TCalendar
-### TCalendarSubtitleBuilder
-#### 类型定义
+#### 声明
```dart
-typedef TCalendarSubtitleBuilder = Widget? Function(BuildContext context, TCalendarSubtitleContext subtitleContext);
+class TCalendar extends StatefulWidget+#### 默认构造方法 -### TCalendarCellBuilder -typedef TCalendarCellBuilder = Widget? Function(BuildContext context, TCalendarCellModel cell);
+TCalendar({
+ super.key,
+ required this.value,
+ this.firstDayOfWeek = TCalendarFirstDayOfWeek.sunday,
+ DateTime? minDate,
+ DateTime? maxDate,
+ this.variant = TCalendarVariant.single,
+ this.onChanged,
+ this.onMonthChanged,
+ TCalendarMonthTitleBuilder? monthTitleBuilder,
+ this.weekdayNames,
+ this.cellBuilder,
+ this.subtitleBuilder,
+ this.animateTo = false,
+ this.anchorDate,
+})-### TCalendarMonthTitleBuilder
|
RSS1102
marked this pull request as ready for review
October 7, 2026 17:12
9 of 16 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
组件源码中已有 dartdoc 的控制器、句柄实例方法和 getter 会被生成器遗漏；嵌套目录、命名扩展、无参构造和泛型也不能完整展示。本修复从 AST 收录这些公开能力，并增加可选 --strict-names 供消费仓库按导出清单控制归属。
公开声明及每个构造/方法展示源码签名，包含泛型约束、位置/命名参数、const/factory 标记与默认值；参数表独立完整展示类型、说明和必填状态。泛型在 Markdown 表格中转义，避免网页吞掉类型。自定义 copyWith/lerp/Token 查询运算符不会因缺少注释被静默排除；标准框架钩子、私有及内部/测试成员不收录。
修复参数说明误复用：普通方法不再套用同名字段说明，Widget key 的兜底只适用于 Key/Key?，Token 的 String/Object 键必须由源码说明。保留有 AST 证据的构造透传。读取带默认值参数前的行内 dartdoc，保留字段初始值及默认声明值。
验证：Flutter 3.32.0 与官方 stable 3.47.6 下均 60 项完整工具测试通过，dart analyze --fatal-infos 零问题。最新提交 dc679da 的 双版本完整回归 CI 也实际通过，各 60 项测试且零分析问题。CLI 冷启动回归单独设置两分钟上限，保留生成成功、默认 manifest 验收成功和删参数失败的全部断言。回归包括泛型约束、目标索引与当前 getter 同名、Token 键与 Widget key 区分、const 重定向工厂、普通句柄、getter/setter、各种构造、行内参数说明、Markdown 泛型渲染、递归目录和严格清单筛选。
在配套消费仓库候选源码上，57 个组件 / 369 个声明 / 435 个构造和方法 / 2,510 个参数与 AST 逐项比对，无缺口、错类型、错默认值或错必填状态；新增 18 项审计器 CLI 正反例测试，双 Flutter 版本通过。官网全部 57 个 API 页已实际打开核对声明与签名。消费仓库继续声明正式 main；该 PR 合入后重新解析依赖、生成并验证正式链，不提交临时 override 或 PR 分支依赖。
配套消费仓库：Tencent/tdesign-flutter#1149，包含逐组件验收清单及真实 Demo 文档入口回归。
修复生成→validate 对默认构造参数标题的误截断、external 签名格式化、字符串字面量空白损坏、旧式函数类型参数及业务 build/custom override 静默遗漏。解析、框架成员筛选、签名格式化和纯 Markdown 渲染分别维护，渲染不修改解析模型；无法确定的类型不伪造 dynamic。validate 默认读取消费仓库 tool/components.json，保留旧 YAML/JSON 抽测兼容。新增 Flutter 3.32.0 / latest 完整工具回归 CI，包含实际 CLI 正例和删参数反例。
合并验收：最终候选 dc679da 的 8 项远端检查全部通过，包含双版本完整回归、四个二进制构建、预览站及产物评论。57 份候选组件文档在两个 SDK 的生成结果和重复生成字节一致；默认 manifest 全量 validate 均 ERROR=0、WARN=0。