feat(popup): add useSafeArea for edge placements and optimize comments

tdesign-component/demo_tool/all_build.sh

@@ -129,7 +129,7 @@ dart run tdesign_flutter_tools:main generate --folder "$PARENT_DIR/lib/src/compo
 # popover
 dart run tdesign_flutter_tools:main generate --folder "$PARENT_DIR/lib/src/components/popover" --name TPopover,TPopoverWidget --folder-name popover --output "$PARENT_DIR/example/assets/api/" --only-api --get-comments
 # popup
-dart run tdesign_flutter_tools:main generate --folder "$PARENT_DIR/lib/src/components/popup" --name TPopup,TPopupOptions,TPopupHandle,TPopupPlacement,TPopupTrigger --folder-name popup --output "$PARENT_DIR/example/assets/api/" --only-api --get-comments
+dart run tdesign_flutter_tools:main generate --folder "$PARENT_DIR/lib/src/components/popup" --name TPopup,TPopupOptions,TPopupHandle,TPopupPlacement,TPopupTrigger,TPopupInset,TPopupBottomInset,TPopupTopInset,TPopupLeftInset,TPopupRightInset --folder-name popup --output "$PARENT_DIR/example/assets/api/" --only-api --get-comments
 # refresh
 dart run tdesign_flutter_tools:main generate --file "$PARENT_DIR/lib/src/components/refresh/t_refresh_header.dart" --name TRefreshHeader --folder-name pull-down-refresh --output "$PARENT_DIR/example/assets/api/" --only-api --get-comments
 # swipecell

tdesign-component/example/assets/api/action-sheet_api.md

@@ -9,7 +9,7 @@
 | badge | TBadge? | - | 角标 |
 | description | String? | - | 描述信息 |
 | disabled | bool | false | 是否禁用 |
-| group | String? | - | 分组，用于带描述多行滚动宫格 当[TActionSheet.theme]等于[TActionSheetTheme.group]时有效 有效时，如果该值未配置整个[TActionSheetItem]会被忽略，即不会展示 |
+| group | String? | - | 分组，用于带描述多行滚动宫格 当`TActionSheet.theme`等于`TActionSheetTheme.group`时有效 有效时，如果该值未配置整个`TActionSheetItem`会被忽略，即不会展示 |
 | icon | Widget? | - | 图标 |
 | iconSize | double? | - | 图标大小 |
 | label | String | - | 标题 |
@@ -19,31 +19,6 @@
 ### TActionSheet
 #### 简介
 动作面板
-#### 默认构造方法
-
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| context | BuildContext | - | 上下文 |
-| align | TActionSheetAlign | TActionSheetAlign.center | 对齐方式 |
-| cancelText | String? | - | 取消按钮的文本 |
-| closeOnOverlayClick | bool | true | 点击蒙层时是否关闭 |
-| count | int | 8 | 每页显示的项目数 当[theme]等于[TActionSheetTheme.grid]且[showPagination]为true时有效 |
-| description | String? | - | 描述文本 当[theme]等于[TActionSheetTheme.grid]或[theme]等于[TActionSheetTheme.list]时有效 |
-| itemHeight | double | 96.0 | 项目的行高 当[theme]等于[TActionSheetTheme.grid]或[theme]等于[TActionSheetTheme.group]时有效 |
-| itemMinWidth | double | 80.0 | 项目的最小宽度 当[theme]等于[TActionSheetTheme.grid]且[scrollable]为true时有效 或当[theme]等于[TActionSheetTheme.group]时有效 |
-| items | List<TActionSheetItem> | - | ActionSheet的项目列表 |
-| onCancel | VoidCallback? | - | 取消按钮的回调函数 |
-| onClose | VoidCallback? | - | 关闭时的回调函数 |
-| onSelected | TActionSheetItemCallback? | - | 选择项目时的回调函数 |
-| rows | int | 2 | 显示的行数 当[theme]等于[TActionSheetTheme.grid]时有效 |
-| scrollable | bool | false | 是否可以横向滚动 当[theme]等于[TActionSheetTheme.grid]且[showPagination]为false时有效 |
-| showCancel | bool | true | 是否显示取消按钮 |
-| showOverlay | bool | true | 是否显示遮罩层 |
-| showPagination | bool | false | 是否显示分页 当[theme]等于[TActionSheetTheme.grid]时有效 |
-| theme | TActionSheetTheme | TActionSheetTheme.list | 主题样式 |
-| useSafeArea | bool | true | 使用安全区域 |
-| visible | bool | false | 是否立即显示 |
-
 
 #### 静态方法
 
@@ -63,14 +38,14 @@
 | onSelected | TActionSheetItemCallback? | - | 选择项目时的回调函数 |
 | showOverlay | bool | true | 是否显示遮罩层 |
 | closeOnOverlayClick | bool | true | 点击蒙层时是否关闭 |
-| count | int | 8 | 每页显示的项目数 当[theme]等于[TActionSheetTheme.grid]且[showPagination]为true时有效 |
-| rows | int | 2 | 显示的行数 当[theme]等于[TActionSheetTheme.grid]时有效 |
-| itemHeight | double | 96.0 | 项目的行高 当[theme]等于[TActionSheetTheme.grid]或[theme]等于[TActionSheetTheme.group]时有效 |
-| itemMinWidth | double | 80.0 | 项目的最小宽度 当[theme]等于[TActionSheetTheme.grid]且[scrollable]为true时有效 或当[theme]等于[TActionSheetTheme.group]时有效 |
-| scrollable | bool | false | 是否可以横向滚动 当[theme]等于[TActionSheetTheme.grid]且[showPagination]为false时有效 |
-| showPagination | bool | false | 是否显示分页 当[theme]等于[TActionSheetTheme.grid]时有效 |
+| count | int | 8 | 每页显示的项目数 当`theme`等于`TActionSheetTheme.grid`且`showPagination`为true时有效 |
+| rows | int | 2 | 显示的行数 当`theme`等于`TActionSheetTheme.grid`时有效 |
+| itemHeight | double | 96.0 | 项目的行高 当`theme`等于`TActionSheetTheme.grid`或`theme`等于`TActionSheetTheme.group`时有效 |
+| itemMinWidth | double | 80.0 | 项目的最小宽度 当`theme`等于`TActionSheetTheme.grid`且`scrollable`为true时有效 或当`theme`等于`TActionSheetTheme.group`时有效 |
+| scrollable | bool | false | 是否可以横向滚动 当`theme`等于`TActionSheetTheme.grid`且`showPagination`为false时有效 |
+| showPagination | bool | false | 是否显示分页 当`theme`等于`TActionSheetTheme.grid`时有效 |
 | onCancel | VoidCallback? | - | 取消按钮的回调函数 |
-| description | String? | - | 描述文本 当[theme]等于[TActionSheetTheme.grid]或[theme]等于[TActionSheetTheme.list]时有效 |
+| description | String? | - | 描述文本 当`theme`等于`TActionSheetTheme.grid`或`theme`等于`TActionSheetTheme.list`时有效 |
 | onClose | VoidCallback? | - | 关闭时的回调函数 |
 | useSafeArea | bool | true | 使用安全区域 |
 
@@ -91,8 +66,8 @@
 | onSelected | TActionSheetItemCallback? | - | 选择项目时的回调函数 |
 | showOverlay | bool | true | 是否显示遮罩层 |
 | closeOnOverlayClick | bool | true | 点击蒙层时是否关闭 |
-| itemHeight | double | 96.0 | 项目的行高 当[theme]等于[TActionSheetTheme.grid]或[theme]等于[TActionSheetTheme.group]时有效 |
-| itemMinWidth | double | 80.0 | 项目的最小宽度 当[theme]等于[TActionSheetTheme.grid]且[scrollable]为true时有效 或当[theme]等于[TActionSheetTheme.group]时有效 |
+| itemHeight | double | 96.0 | 项目的行高 当`theme`等于`TActionSheetTheme.grid`或`theme`等于`TActionSheetTheme.group`时有效 |
+| itemMinWidth | double | 80.0 | 项目的最小宽度 当`theme`等于`TActionSheetTheme.grid`且`scrollable`为true时有效 或当`theme`等于`TActionSheetTheme.group`时有效 |
 | onCancel | VoidCallback? | - | 取消按钮的回调函数 |
 | onClose | VoidCallback? | - | 关闭时的回调函数 |
 | useSafeArea | bool | true | 使用安全区域 |
@@ -118,6 +93,31 @@
 | onClose | VoidCallback? | - | 关闭时的回调函数 |
 | useSafeArea | bool | true | 使用安全区域 |
 
+#### 默认构造方法
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| context | BuildContext | - | 上下文 |
+| align | TActionSheetAlign | TActionSheetAlign.center | 对齐方式 |
+| cancelText | String? | - | 取消按钮的文本 |
+| closeOnOverlayClick | bool | true | 点击蒙层时是否关闭 |
+| count | int | 8 | 每页显示的项目数 当`theme`等于`TActionSheetTheme.grid`且`showPagination`为true时有效 |
+| description | String? | - | 描述文本 当`theme`等于`TActionSheetTheme.grid`或`theme`等于`TActionSheetTheme.list`时有效 |
+| itemHeight | double | 96.0 | 项目的行高 当`theme`等于`TActionSheetTheme.grid`或`theme`等于`TActionSheetTheme.group`时有效 |
+| itemMinWidth | double | 80.0 | 项目的最小宽度 当`theme`等于`TActionSheetTheme.grid`且`scrollable`为true时有效 或当`theme`等于`TActionSheetTheme.group`时有效 |
+| items | List<TActionSheetItem> | - | ActionSheet的项目列表 |
+| onCancel | VoidCallback? | - | 取消按钮的回调函数 |
+| onClose | VoidCallback? | - | 关闭时的回调函数 |
+| onSelected | TActionSheetItemCallback? | - | 选择项目时的回调函数 |
+| rows | int | 2 | 显示的行数 当`theme`等于`TActionSheetTheme.grid`时有效 |
+| scrollable | bool | false | 是否可以横向滚动 当`theme`等于`TActionSheetTheme.grid`且`showPagination`为false时有效 |
+| showCancel | bool | true | 是否显示取消按钮 |
+| showOverlay | bool | true | 是否显示遮罩层 |
+| showPagination | bool | false | 是否显示分页 当`theme`等于`TActionSheetTheme.grid`时有效 |
+| theme | TActionSheetTheme | TActionSheetTheme.list | 主题样式 |
+| useSafeArea | bool | true | 使用安全区域 |
+| visible | bool | false | 是否立即显示 |
+
 
 ### TActionSheetTheme
 #### 枚举值

tdesign-component/example/assets/api/avatar_api.md

@@ -1,5 +1,7 @@
 ## API
 ### TAvatar
+#### 简介
+用于头像显示
 #### 默认构造方法
 
 | 参数 | 类型 | 默认值 | 说明 |

tdesign-component/example/assets/api/button_api.md

@@ -1,5 +1,7 @@
 ## API
 ### TButton
+#### 简介
+TD常规按钮
 #### 默认构造方法
 
 | 参数 | 类型 | 默认值 | 说明 |
@@ -32,17 +34,8 @@
 
 
 ### TButtonStyle
-#### 默认构造方法
-
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| backgroundColor | Color? | - | 背景颜色 |
-| frameColor | Color? | - | 边框颜色 |
-| frameWidth | double? | - | 边框宽度 |
-| gradient | Gradient? | - | 渐变背景色 |
-| radius | BorderRadiusGeometry? | - | 自定义圆角 |
-| textColor | Color? | - | 文字颜色 |
-
+#### 简介
+TButton按钮样式
 
 #### 工厂构造方法
 
@@ -89,6 +82,17 @@
 | theme | TButtonTheme? | - | - |
 | status | TButtonStatus | - | - |
 
+#### 默认构造方法
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| backgroundColor | Color? | - | 背景颜色 |
+| frameColor | Color? | - | 边框颜色 |
+| frameWidth | double? | - | 边框宽度 |
+| gradient | Gradient? | - | 渐变背景色 |
+| radius | BorderRadiusGeometry? | - | 自定义圆角 |
+| textColor | Color? | - | 文字颜色 |
+
 
 ### TButtonSize
 #### 枚举值

tdesign-component/example/assets/api/calendar_api.md

@@ -1,5 +1,7 @@
 ## API
 ### TCalendar
+#### 简介
+日历组件
 #### 默认构造方法
 
 | 参数 | 类型 | 默认值 | 说明 |
@@ -40,13 +42,15 @@
 
 
 ### TCalendarPopup
+#### 简介
+单元格组件popup模式
 #### 默认构造方法
 
 | 参数 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
 | context | BuildContext | - | 上下文 |
 | autoClose | bool? | true | 自动关闭；在点击关闭按钮、确认按钮、遮罩层时自动关闭 |
-| builder | CalendarBuilder? | - | 控件构建器，优先级高于[child] |
+| builder | CalendarBuilder? | - | 控件构建器，优先级高于`child` |
 | child | TCalendar? | - | 日历控件 |
 | confirmBtn | Widget? | - | 自定义确认按钮 |
 | onClose | VoidCallback? | - | 关闭时触发 |
@@ -56,30 +60,8 @@
 
 
 ### TCalendarStyle
-#### 默认构造方法
-
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| cellDecoration | BoxDecoration? | - | 日期decoration |
-| cellPrefixStyle | TextStyle? | - | 日期前面的字符串的样式 |
-| cellStyle | TextStyle? | - | 日期样式 |
-| cellSuffixStyle | TextStyle? | - | 日期后面的字符串的样式 |
-| centreColor | Color? | - | 日期范围内背景样式 |
-| decoration | BoxDecoration? | - | - |
-| monthTitleStyle | TextStyle? | - | body区域 年月文字样式 |
-| titleCloseColor | Color? | - | header区域 关闭图标的颜色 |
-| titleMaxLine | int? | - | header区域 [TCalendar.title]的行数 |
-| titleStyle | TextStyle? | - | header区域 [TCalendar.title]的样式 |
-| weekdayStyle | TextStyle? | - | header区域 周 文字样式 |
-
-#### 公开属性
-
-| 属性 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| bodyPadding | double? | - | 月与月之间的垂直间距 |
-| todayStyle | TextStyle? | - | 当天日期样式 |
-| verticalGap | double? | - | 日期垂直间距，水平间距为[verticalGap] / 2 |
-
+#### 简介
+日历组件样式
 
 #### 工厂构造方法
 
@@ -101,29 +83,55 @@
 | --- | --- | --- | --- |
 | context | BuildContext | - | - |
 
+#### 默认构造方法
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| cellDecoration | BoxDecoration? | - | 日期decoration |
+| cellPrefixStyle | TextStyle? | - | 日期前面的字符串的样式 |
+| cellStyle | TextStyle? | - | 日期样式 |
+| cellSuffixStyle | TextStyle? | - | 日期后面的字符串的样式 |
+| centreColor | Color? | - | 日期范围内背景样式 |
+| decoration | BoxDecoration? | - | - |
+| monthTitleStyle | TextStyle? | - | body区域 年月文字样式 |
+| titleCloseColor | Color? | - | header区域 关闭图标的颜色 |
+| titleMaxLine | int? | - | header区域 `TCalendar.title`的行数 |
+| titleStyle | TextStyle? | - | header区域 `TCalendar.title`的样式 |
+| weekdayStyle | TextStyle? | - | header区域 周 文字样式 |
+
+#### 公开属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| bodyPadding | double? | - | 月与月之间的垂直间距 |
+| todayStyle | TextStyle? | - | 当天日期样式 |
+| verticalGap | double? | - | 日期垂直间距，水平间距为`verticalGap` / 2 |
+
 
 ### TCalendarDataSource
 #### 简介
 日历数据源接口
- 
- 开发者需要实现此接口来提供农历转换能力。
- 组件内部不包含农历算法和数据，完全依赖外部实现。
+
+开发者需要实现此接口来提供农历转换能力。
+组件内部不包含农历算法和数据，完全依赖外部实现。
 
 #### 方法
 
 | 名称 | 返回类型 | 参数 | 说明 |
 | --- | --- | --- | --- |
-| getLunarInfo | TLunarInfo? | required DateTime solarDate | 获取指定阳历日期的农历信息 [solarDate] 阳历日期 返回 null 表示不显示农历信息 |
-| formatDate | String | required DateTime date, required TCalendarDateType type, TLunarInfo? lunarInfo | 格式化日期文本 [date] 阳历日期 [type] 日历类型 [lunarInfo] 农历信息（可选） 返回格式化后的日期字符串 |
-| getSolarTerm | String? | required DateTime date | 获取节气信息（可选实现） [date] 阳历日期 返回节气名称，如"春分"、"秋分"等，无节气则返回 null |
-| getFestival | String? | required DateTime date, TLunarInfo? lunarInfo | 获取节日信息（可选实现） [date] 阳历日期 [lunarInfo] 农历信息（可选） 返回节日名称，如"春节"、"中秋节"等，无节日则返回 null |
-| getHolidayInfo | Map<String, String>? | required DateTime date | 获取假期信息（可选实现） [date] 阳历日期 返回假期类型和名称： - 'holiday': 法定节假日/公共假期（如"国庆节"） - 'workday': 调休工作日（如"补班"） - null: 正常日期 示例返回值： - {'type': 'holiday', 'name': '国庆节'} - {'type': 'workday', 'name': '补班'} - null |
-| formatYear | String | required int year, required TCalendarDateType type | 格式化年份文本 [year] 年份 [type] 日历类型 返回格式化后的年份字符串 阳历示例：2025 -> "2025年" 阴历示例：2025 -> "二〇二五年" |
-| formatMonth | String | required int month, required TCalendarDateType type, bool isLeapMonth | 格式化月份文本 [month] 月份（1-12） [type] 日历类型 [isLeapMonth] 是否是闰月（仅农历有效） 返回格式化后的月份字符串 阳历示例：3 -> "3月" 阴历示例：3 -> "三月"，闰3月 -> "闰三月" |
-| formatDay | String | required int day, required TCalendarDateType type | 格式化日期文本 [day] 日期（1-31） [type] 日历类型 返回格式化后的日期字符串 阳历示例：7 -> "7日" 阴历示例：7 -> "初七" |
+| getLunarInfo | TLunarInfo? | required DateTime solarDate | 获取指定阳历日期的农历信息 返回 null 表示不显示农历信息 |
+| formatDate | String | required DateTime date, required TCalendarDateType type, TLunarInfo? lunarInfo | 格式化日期文本 返回格式化后的日期字符串 |
+| getSolarTerm | String? | required DateTime date | 获取节气信息（可选实现） 返回节气名称，如"春分"、"秋分"等，无节气则返回 null |
+| getFestival | String? | required DateTime date, TLunarInfo? lunarInfo | 获取节日信息（可选实现） 返回节日名称，如"春节"、"中秋节"等，无节日则返回 null |
+| getHolidayInfo | Map<String, String>? | required DateTime date | 获取假期信息（可选实现） 返回假期类型和名称： - 'holiday': 法定节假日/公共假期（如"国庆节"） - 'workday': 调休工作日（如"补班"） - null: 正常日期 示例返回值： - {'type': 'holiday', 'name': '国庆节'} - {'type': 'workday', 'name': '补班'} - null |
+| formatYear | String | required int year, required TCalendarDateType type | 格式化年份文本 返回格式化后的年份字符串 阳历示例：2025 -> "2025年" 阴历示例：2025 -> "二〇二五年" |
+| formatMonth | String | required int month, required TCalendarDateType type, bool isLeapMonth | 格式化月份文本 返回格式化后的月份字符串 阳历示例：3 -> "3月" 阴历示例：3 -> "三月"，闰3月 -> "闰三月" |
+| formatDay | String | required int day, required TCalendarDateType type | 格式化日期文本 返回格式化后的日期字符串 阳历示例：7 -> "7日" 阴历示例：7 -> "初七" |
 
 
 ### TLunarInfo
+#### 简介
+农历日期信息模型
 #### 默认构造方法
 
 | 参数 | 类型 | 默认值 | 说明 |
@@ -185,17 +193,17 @@
 | empty | - |
 
 
-### CalendarFormat
+### CalendarBuilder
 #### 类型定义
 
 ```dart
-typedef CalendarFormat = TDate? Function(TDate? day);
+typedef CalendarBuilder = Widget Function(BuildContext context);
 ```
 
 
-### CalendarBuilder
+### CalendarFormat
 #### 类型定义
 
 ```dart
-typedef CalendarBuilder = Widget Function(BuildContext context);
+typedef CalendarFormat = TDate? Function(TDate? day);
 ```

tdesign-component/example/assets/api/cell_api.md

@@ -58,6 +58,17 @@
 ### TCellStyle
 #### 简介
 单元格组件样式
+
+#### 工厂构造方法
+
+##### TCellStyle.cellStyle
+
+生成单元格默认样式
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| context | BuildContext | - | 传递context，会生成默认样式 |
+
 #### 默认构造方法
 
 | 参数 | 类型 | 默认值 | 说明 |
@@ -82,15 +93,14 @@
 | titleStyle | TextStyle? | - | 标题文字样式 |
 
 
-#### 工厂构造方法
-
-##### TCellStyle.cellStyle
+### TCellGroupTheme
+#### 枚举值
 
-生成单元格默认样式
 
-| 参数 | 类型 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| context | BuildContext | - | 传递context，会生成默认样式 |
+| 名称 | 说明 |
+| --- | --- |
+| defaultTheme | - |
+| cardTheme | - |
 
 
 ### TCellAlign
@@ -104,27 +114,17 @@
 | bottom | - |
 
 
-### TCellGroupTheme
-#### 枚举值
-
-
-| 名称 | 说明 |
-| --- | --- |
-| defaultTheme | - |
-| cardTheme | - |
-
-
-### TCellClick
+### CellBuilder
 #### 类型定义
 
 ```dart
-typedef TCellClick = void Function(TCell cell);
+typedef CellBuilder = Widget Function(BuildContext context, TCell cell, int index);
 ```
 
 
-### CellBuilder
+### TCellClick
 #### 类型定义
 
 ```dart
-typedef CellBuilder = Widget Function(BuildContext context, TCell cell, int index);
+typedef TCellClick = void Function(TCell cell);
 ```