diff --git a/tdesign-component/demo_tool/all_build.sh b/tdesign-component/demo_tool/all_build.sh index 1a8f8977d..8f03ce077 100644 --- a/tdesign-component/demo_tool/all_build.sh +++ b/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 diff --git a/tdesign-component/example/assets/api/action-sheet_api.md b/tdesign-component/example/assets/api/action-sheet_api.md index 64bc4b9dd..26b527133 100644 --- a/tdesign-component/example/assets/api/action-sheet_api.md +++ b/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 | - | 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 | - | 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 #### 枚举值 diff --git a/tdesign-component/example/assets/api/avatar_api.md b/tdesign-component/example/assets/api/avatar_api.md index ddc9cf598..2f15e3acf 100644 --- a/tdesign-component/example/assets/api/avatar_api.md +++ b/tdesign-component/example/assets/api/avatar_api.md @@ -1,5 +1,7 @@ ## API ### TAvatar +#### 简介 +用于头像显示 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-component/example/assets/api/button_api.md b/tdesign-component/example/assets/api/button_api.md index c036c83cb..bbdd0ce71 100644 --- a/tdesign-component/example/assets/api/button_api.md +++ b/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 #### 枚举值 diff --git a/tdesign-component/example/assets/api/calendar_api.md b/tdesign-component/example/assets/api/calendar_api.md index 76638af64..cb35cb855 100644 --- a/tdesign-component/example/assets/api/calendar_api.md +++ b/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? | 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? | 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); ``` diff --git a/tdesign-component/example/assets/api/cell_api.md b/tdesign-component/example/assets/api/cell_api.md index c7563c928..7a9a87386 100644 --- a/tdesign-component/example/assets/api/cell_api.md +++ b/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); ``` diff --git a/tdesign-component/example/assets/api/checkbox_api.md b/tdesign-component/example/assets/api/checkbox_api.md index 40e8991af..7a1bb4638 100644 --- a/tdesign-component/example/assets/api/checkbox_api.md +++ b/tdesign-component/example/assets/api/checkbox_api.md @@ -1,5 +1,9 @@ ## API ### TCheckbox +#### 简介 +复选框组件。 +FuiCheckbox支持3种内置样式的的复选框，还支持各种自定义样式，除了提供勾选之外还提供了内 +容选项，内容包含一个主标题和副标题，并且支持完全自定义内容，支持指定内容的方向等等 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -34,6 +38,25 @@ ### TCheckboxGroup +#### 简介 +CheckBox组，可以通过控制器控制组内的多个CheckBox的选择状态 +child的属性可以是任意包含TCheckBox的容器组件，例如： +```dart +TCheckboxGroup( + child: Row( + children: [ + TCheckBox(), + Column( + children: [ + TCheckBox() + ... + ] + ) + ... + ] + ) +) +``` #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-component/example/assets/api/collapse_api.md b/tdesign-component/example/assets/api/collapse_api.md index bc0ef877e..63d2c767c 100644 --- a/tdesign-component/example/assets/api/collapse_api.md +++ b/tdesign-component/example/assets/api/collapse_api.md @@ -1,7 +1,22 @@ ## API ### TCollapse #### 简介 -折叠面板列表组件，需配合 [TCollapsePanel] 使用 +折叠面板列表组件，需配合 `TCollapsePanel` 使用 + +#### 工厂构造方法 + +##### TCollapse.accordion + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| children | List | - | 折叠面板列表的子组件 | +| style | TCollapseStyle | TCollapseStyle.block | 折叠面板列表的样式 - `TCollapseStyle.block` 通栏风格 - `TCollapseStyle.card` 卡片风格 | +| expansionCallback | ExpansionPanelCallback? | - | 折叠面板列表的回调函数； 回调时，入参为当前点击的折叠面板的索引 index 和是否展开的状态 isExpanded | +| animationDuration | Duration | kThemeAnimationDuration | 折叠面板列表的动画时长 | +| elevation | double | 0 | 折叠面板列表的阴影 | +| initialOpenPanelValue | Object? | - | 折叠面板列表的默认展开面板的值； 当使用 `TCollapse.accordion` 时，此值生效 | +| key | Key? | - | 组件标识，用于区分或保留组件状态。 | + #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -11,28 +26,13 @@ | elevation | double | 0 | 折叠面板列表的阴影 | | expansionCallback | ExpansionPanelCallback? | - | 折叠面板列表的回调函数； 回调时，入参为当前点击的折叠面板的索引 index 和是否展开的状态 isExpanded | | key | Key? | - | 组件标识，用于区分或保留组件状态。 | -| style | TCollapseStyle | TCollapseStyle.block | 折叠面板列表的样式 - [TCollapseStyle.block] 通栏风格 - [TCollapseStyle.card] 卡片风格 | +| style | TCollapseStyle | TCollapseStyle.block | 折叠面板列表的样式 - `TCollapseStyle.block` 通栏风格 - `TCollapseStyle.card` 卡片风格 | #### 公开属性 | 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| initialOpenPanelValue | Object? | - | 折叠面板列表的默认展开面板的值； 当使用 [TCollapse.accordion] 时，此值生效 | - - -#### 工厂构造方法 - -##### TCollapse.accordion - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| children | List | - | 折叠面板列表的子组件 | -| style | TCollapseStyle | TCollapseStyle.block | 折叠面板列表的样式 - [TCollapseStyle.block] 通栏风格 - [TCollapseStyle.card] 卡片风格 | -| expansionCallback | ExpansionPanelCallback? | - | 折叠面板列表的回调函数； 回调时，入参为当前点击的折叠面板的索引 index 和是否展开的状态 isExpanded | -| animationDuration | Duration | kThemeAnimationDuration | 折叠面板列表的动画时长 | -| elevation | double | 0 | 折叠面板列表的阴影 | -| initialOpenPanelValue | Object? | - | 折叠面板列表的默认展开面板的值； 当使用 [TCollapse.accordion] 时，此值生效 | -| key | Key? | - | 组件标识，用于区分或保留组件状态。 | +| initialOpenPanelValue | Object? | - | 折叠面板列表的默认展开面板的值； 当使用 `TCollapse.accordion` 时，此值生效 | ### TCollapseStyle diff --git a/tdesign-component/example/assets/api/dialog_api.md b/tdesign-component/example/assets/api/dialog_api.md index 0679ea786..d1f6ec0b6 100644 --- a/tdesign-component/example/assets/api/dialog_api.md +++ b/tdesign-component/example/assets/api/dialog_api.md @@ -1,36 +1,16 @@ ## API ### TAlertDialog -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| backgroundColor | Color? | - | 背景颜色 | -| buttonStyle | TDialogButtonStyle | TDialogButtonStyle.normal | - | -| buttonWidget | Widget? | - | 自定义按钮 | -| content | String? | - | 内容 | -| contentColor | Color? | - | 内容颜色 | -| contentMaxHeight | double | 0 | 内容的最大高度，默认为0，也就是不限制高度 | -| contentWidget | Widget? | - | 内容Widget | -| key | Key? | - | 组件标识，用于区分或保留组件状态。 | -| leftBtn | TDialogButtonOptions? | - | 左侧按钮配置 | -| leftBtnAction | Function()? | - | 左侧按钮默认点击 | -| padding | EdgeInsets? | const EdgeInsets.fromLTRB(24, 32, 24, 0) | 内容内边距 | -| radius | double | 12.0 | 圆角 | -| rightBtn | TDialogButtonOptions? | - | 右侧按钮配置 | -| rightBtnAction | Function()? | - | 右侧按钮默认点击 | -| showCloseButton | bool? | - | 显示右上角关闭按钮 | -| title | String? | - | 标题 | -| titleAlignment | AlignmentGeometry? | - | 标题对齐模式 | -| titleColor | Color? | - | 标题颜色 | - +#### 简介 +弹窗控件 +支持横向或竖向摆放按钮 +横向最多摆放两个按钮 #### 工厂构造方法 ##### TAlertDialog.vertical 纵向按钮排列的对话框 - - [buttons]参数是必须的，纵向按钮默认样式都是[TButtonTheme.primary] +`buttons`参数是必须的，纵向按钮默认样式都是`TButtonTheme.primary` | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | @@ -49,8 +29,34 @@ | padding | EdgeInsets? | const EdgeInsets.fromLTRB(24, 32, 24, 0) | 内容内边距 | | buttonWidget | Widget? | - | 自定义按钮 | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| backgroundColor | Color? | - | 背景颜色 | +| buttonStyle | TDialogButtonStyle | TDialogButtonStyle.normal | - | +| buttonWidget | Widget? | - | 自定义按钮 | +| content | String? | - | 内容 | +| contentColor | Color? | - | 内容颜色 | +| contentMaxHeight | double | 0 | 内容的最大高度，默认为0，也就是不限制高度 | +| contentWidget | Widget? | - | 内容Widget | +| key | Key? | - | 组件标识，用于区分或保留组件状态。 | +| leftBtn | TDialogButtonOptions? | - | 左侧按钮配置 | +| leftBtnAction | Function()? | - | 左侧按钮默认点击 | +| padding | EdgeInsets? | const EdgeInsets.fromLTRB(24, 32, 24, 0) | 内容内边距 | +| radius | double | 12.0 | 圆角 | +| rightBtn | TDialogButtonOptions? | - | 右侧按钮配置 | +| rightBtnAction | Function()? | - | 右侧按钮默认点击 | +| showCloseButton | bool? | - | 显示右上角关闭按钮 | +| title | String? | - | 标题 | +| titleAlignment | AlignmentGeometry? | - | 标题对齐模式 | +| titleColor | Color? | - | 标题颜色 | + ### TConfirmDialog +#### 简介 +只有一个按钮的弹窗控件 +按钮样式支持普通和文字 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -77,6 +83,8 @@ ### TDialogButtonOptions +#### 简介 +弹窗按钮配置 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -93,6 +101,8 @@ ### TDialogScaffold +#### 简介 +TDialog手脚架 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -106,6 +116,8 @@ ### TDialogTitle +#### 简介 +弹窗标题 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -116,6 +128,8 @@ ### TDialogContent +#### 简介 +弹窗内容 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -126,6 +140,8 @@ ### TDialogInfoWidget +#### 简介 +弹窗信息 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -142,6 +158,8 @@ ### HorizontalNormalButtons +#### 简介 +横向排列的两个按钮 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -152,6 +170,8 @@ ### HorizontalTextButtons +#### 简介 +左右横向文字按钮，顶部和中间有分割线 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -162,6 +182,8 @@ ### TDialogButton +#### 简介 +弹窗标题 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -181,6 +203,8 @@ ### TImageDialog +#### 简介 +带有图片的弹窗控件 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -204,6 +228,8 @@ ### TInputDialog +#### 简介 +带有输入框的弹窗 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -230,9 +256,8 @@ ### TDialogButtonStyle #### 简介 Dialog按钮样式 - - 用于在Dialog层面配置按钮样式 - Dialog内支持配置每个按钮的样式 +用于在Dialog层面配置按钮样式 +Dialog内支持配置每个按钮的样式 #### 枚举值 diff --git a/tdesign-component/example/assets/api/divider_api.md b/tdesign-component/example/assets/api/divider_api.md index 72e5ed264..d8e0f8ee2 100644 --- a/tdesign-component/example/assets/api/divider_api.md +++ b/tdesign-component/example/assets/api/divider_api.md @@ -1,5 +1,9 @@ ## API ### TDivider +#### 简介 +分割线 +对于非flutter原有的控件，则只需满足TDesign规范即可； +如果有业务在实际使用，还需兼容实际业务场景。 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-component/example/assets/api/drawer_api.md b/tdesign-component/example/assets/api/drawer_api.md index 9ca2934fa..dc726340f 100644 --- a/tdesign-component/example/assets/api/drawer_api.md +++ b/tdesign-component/example/assets/api/drawer_api.md @@ -10,7 +10,7 @@ | backgroundColor | Color? | - | 组件背景颜色 | | bordered | bool? | true | 是否显示边框 | | closeOnOverlayClick | bool? | true | 点击蒙层时是否关闭抽屉 | -| contentWidget | Widget? | - | 自定义内容，优先级高于[items]/[footer]/[title] | +| contentWidget | Widget? | - | 自定义内容，优先级高于`items`/`footer`/`title` | | drawerTop | double? | - | 距离顶部的距离 | | footer | Widget? | - | 抽屉的底部 | | hover | bool? | true | 是否开启点击反馈 | @@ -30,14 +30,14 @@ ### TDrawerWidget #### 简介 抽屉内容组件 - 可用于 Scaffold 中的 drawer 属性 +可用于 Scaffold 中的 drawer 属性 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | backgroundColor | Color? | - | 组件背景颜色 | | bordered | bool? | true | 是否显示边框 | -| contentWidget | Widget? | - | 自定义内容，优先级高于[items]/[footer]/[title] | +| contentWidget | Widget? | - | 自定义内容，优先级高于`items`/`footer`/`title` | | footer | Widget? | - | 抽屉的底部 | | hover | bool? | true | 是否开启点击反馈 | | isShowLastBordered | bool? | true | 是否显示最后一行分割线 | diff --git a/tdesign-component/example/assets/api/dropdown-menu_api.md b/tdesign-component/example/assets/api/dropdown-menu_api.md index 940cadce5..b384934b1 100644 --- a/tdesign-component/example/assets/api/dropdown-menu_api.md +++ b/tdesign-component/example/assets/api/dropdown-menu_api.md @@ -8,7 +8,7 @@ | --- | --- | --- | --- | | arrowColor | Color? | - | 自定义箭头颜色 | | arrowIcon | IconData? | - | 自定义箭头图标 | -| builder | TDropdownItemBuilder? | - | 下拉菜单构建器，优先级高于[items] | +| builder | TDropdownItemBuilder? | - | 下拉菜单构建器，优先级高于`items` | | closeOnClickOverlay | bool? | true | 是否在点击遮罩层后关闭菜单 | | decoration | Decoration? | - | 下拉菜单的装饰器 | | direction | TDropdownMenuDirection? | TDropdownMenuDirection.auto | 菜单展开方向（down、up、auto） | @@ -21,7 +21,7 @@ | onMenuClosed | ValueChanged? | - | 关闭菜单事件 | | onMenuOpened | ValueChanged? | - | 展开菜单事件 | | showOverlay | bool? | true | 是否显示遮罩层 | -| tabBarAlign | MainAxisAlignment? | MainAxisAlignment.center | [TDropdownItem.label]和[arrowIcon]/[TDropdownItem.arrowIcon]的对齐方式 | +| tabBarAlign | MainAxisAlignment? | MainAxisAlignment.center | `TDropdownItem.label`和`arrowIcon`/`TDropdownItem.arrowIcon`的对齐方式 | | width | double? | - | menu的宽度 | @@ -47,9 +47,9 @@ | onReset | VoidCallback? | - | 点击重置时触发 | | options | List? | const [] | 选项数据 | | optionsColumns | int? | 1 | 选项分栏（1-3） | -| tabBarAlign | MainAxisAlignment? | - | [label]和[arrowIcon]/[TDropdownMenu.arrowIcon]的对齐方式 | -| tabBarFlex | int? | 1 | 该item在menu上的宽度占比，仅在[TDropdownMenu.isScrollable]为false时有效 | -| tabBarWidth | double? | - | 该item在menu上的宽度，仅在[TDropdownMenu.isScrollable]为true时有效 | +| tabBarAlign | MainAxisAlignment? | - | `label`和`arrowIcon`/`TDropdownMenu.arrowIcon`的对齐方式 | +| tabBarFlex | int? | 1 | 该item在menu上的宽度占比，仅在`TDropdownMenu.isScrollable`为false时有效 | +| tabBarWidth | double? | - | 该item在menu上的宽度，仅在`TDropdownMenu.isScrollable`为true时有效 | #### 静态成员 @@ -91,37 +91,37 @@ | auto | 根据内容高度动态展示方向 | -### TDropdownItemContentBuilder +### TDropdownItemBuilder +#### 简介 +下拉菜单构建器 #### 类型定义 ```dart -typedef TDropdownItemContentBuilder = Widget Function(BuildContext context, _TDropdownItemState itemState, TDropdownPopup? popupState); +typedef TDropdownItemBuilder = List Function(BuildContext context); ``` -### TDropdownItemOptionsCallback +### LabelBuilder +#### 简介 +自定义标签内容 #### 类型定义 ```dart -typedef TDropdownItemOptionsCallback = void Function(List? options); +typedef LabelBuilder = Widget Function(BuildContext context, String label, bool isOpened, int index); ``` -### TDropdownItemBuilder -#### 简介 -下拉菜单构建器 +### TDropdownItemContentBuilder #### 类型定义 ```dart -typedef TDropdownItemBuilder = List Function(BuildContext context); +typedef TDropdownItemContentBuilder = Widget Function(BuildContext context, _TDropdownItemState itemState, TDropdownPopup? popupState); ``` -### LabelBuilder -#### 简介 -自定义标签内容 +### TDropdownItemOptionsCallback #### 类型定义 ```dart -typedef LabelBuilder = Widget Function(BuildContext context, String label, bool isOpened, int index); +typedef TDropdownItemOptionsCallback = void Function(List? options); ``` diff --git a/tdesign-component/example/assets/api/form_api.md b/tdesign-component/example/assets/api/form_api.md index 948830f5e..e80089fbc 100644 --- a/tdesign-component/example/assets/api/form_api.md +++ b/tdesign-component/example/assets/api/form_api.md @@ -57,6 +57,9 @@ ### TFormValidation +#### 简介 +实现普通表单项的校验 +校验规则 和 错误提醒 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-component/example/assets/api/icon_api.md b/tdesign-component/example/assets/api/icon_api.md index 73c5f852d..8d7536763 100644 --- a/tdesign-component/example/assets/api/icon_api.md +++ b/tdesign-component/example/assets/api/icon_api.md @@ -2119,10 +2119,3 @@ | zoom_in_filled | - | - | - | | zoom_out | - | - | - | | zoom_out_filled | - | - | - | - - -#### 工厂构造方法 - -##### TIcons._ - -私有构造方法，不支持外部创建，仅提供静态常量给外部使用 \ No newline at end of file diff --git a/tdesign-component/example/assets/api/image-viewer_api.md b/tdesign-component/example/assets/api/image-viewer_api.md index 1cc94ffd9..e703e78c8 100644 --- a/tdesign-component/example/assets/api/image-viewer_api.md +++ b/tdesign-component/example/assets/api/image-viewer_api.md @@ -1,5 +1,7 @@ ## API ### TImageViewer +#### 简介 +图片预览工具 #### 静态方法 diff --git a/tdesign-component/example/assets/api/image_api.md b/tdesign-component/example/assets/api/image_api.md index f49591872..4c2eba839 100644 --- a/tdesign-component/example/assets/api/image_api.md +++ b/tdesign-component/example/assets/api/image_api.md @@ -16,7 +16,7 @@ | excludeFromSemantics | bool | false | - | | filterQuality | FilterQuality | FilterQuality.low | - | | fit | BoxFit? | - | 适配样式 | -| frameBuilder | ImageFrameBuilder? | - | 以下系统Image属性，释义请参考系统[Image]中注释 | +| frameBuilder | ImageFrameBuilder? | - | 以下系统Image属性，释义请参考系统`Image`中注释 | | gaplessPlayback | bool | false | - | | height | double? | - | 自定义高 | | imageFile | File? | - | 图片文件路径 | diff --git a/tdesign-component/example/assets/api/message_api.md b/tdesign-component/example/assets/api/message_api.md index c1cfed62a..09573b3fb 100644 --- a/tdesign-component/example/assets/api/message_api.md +++ b/tdesign-component/example/assets/api/message_api.md @@ -1,23 +1,7 @@ ## API ### TMessage -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| closeBtn | dynamic | - | 关闭按钮 | -| content | String? | - | 通知内容 | -| duration | int? | 3000 | 消息内置计时器 | -| icon | dynamic | true | 自定义消息前面的图标 | -| key | Key? | - | 组件标识，用于区分或保留组件状态。 | -| link | dynamic | - | 链接名称 | -| marquee | MessageMarquee? | - | 跑马灯效果 | -| offset | List? | - | 相对于 placement 的偏移量 | -| onCloseBtnClick | VoidCallback? | - | 点击关闭按钮触发 | -| onDurationEnd | VoidCallback? | - | 计时结束后触发 | -| onLinkClick | VoidCallback? | - | 点击链接文本时触发 | -| theme | MessageTheme? | MessageTheme.info | 消息组件风格 info/success/warning/error | -| visible | bool? | true | 是否显示 | - +#### 简介 +TMessage 组件 #### 静态方法 @@ -41,8 +25,28 @@ | onDurationEnd | VoidCallback? | - | 计时结束后触发 | | onLinkClick | VoidCallback? | - | 点击链接文本时触发 | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| closeBtn | dynamic | - | 关闭按钮 | +| content | String? | - | 通知内容 | +| duration | int? | 3000 | 消息内置计时器 | +| icon | dynamic | true | 自定义消息前面的图标 | +| key | Key? | - | 组件标识，用于区分或保留组件状态。 | +| link | dynamic | - | 链接名称 | +| marquee | MessageMarquee? | - | 跑马灯效果 | +| offset | List? | - | 相对于 placement 的偏移量 | +| onCloseBtnClick | VoidCallback? | - | 点击关闭按钮触发 | +| onDurationEnd | VoidCallback? | - | 计时结束后触发 | +| onLinkClick | VoidCallback? | - | 点击链接文本时触发 | +| theme | MessageTheme? | MessageTheme.info | 消息组件风格 info/success/warning/error | +| visible | bool? | true | 是否显示 | + ### MessageMarquee +#### 简介 +跑马灯配置 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -53,6 +57,8 @@ ### MessageLink +#### 简介 +链接设置 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-component/example/assets/api/notice-bar_api.md b/tdesign-component/example/assets/api/notice-bar_api.md index 5f72f1e01..403e49b6e 100644 --- a/tdesign-component/example/assets/api/notice-bar_api.md +++ b/tdesign-component/example/assets/api/notice-bar_api.md @@ -17,7 +17,7 @@ | prefixIcon | IconData? | - | 左侧图标 | | right | Widget? | - | 右侧内容（自定义右侧内容，优先级高于suffixIcon） | | speed | double? | 50 | 滚动速度 | -| style | TNoticeBarStyle? | - | 公告栏样式 [TNoticeBarStyle] | +| style | TNoticeBarStyle? | - | 公告栏样式 `TNoticeBarStyle` | | suffixIcon | IconData? | - | 右侧图标 | | theme | TNoticeBarTheme? | TNoticeBarTheme.info | 主题 | @@ -25,17 +25,6 @@ ### TNoticeBarStyle #### 简介 公告栏样式 -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| backgroundColor | Color? | - | 公告栏背景色 | -| context | BuildContext? | - | 上下文 | -| leftIconColor | Color? | - | 公告栏左侧图标颜色 | -| padding | EdgeInsetsGeometry? | - | 公告栏内边距 | -| rightIconColor | Color? | - | 公告栏右侧图标颜色 | -| textStyle | TextStyle? | - | 公告栏内容样式 | - #### 工厂构造方法 @@ -48,6 +37,17 @@ | context | BuildContext | - | 上下文 | | theme | TNoticeBarTheme? | TNoticeBarTheme.info | - | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| backgroundColor | Color? | - | 公告栏背景色 | +| context | BuildContext? | - | 上下文 | +| leftIconColor | Color? | - | 公告栏左侧图标颜色 | +| padding | EdgeInsetsGeometry? | - | 公告栏内边距 | +| rightIconColor | Color? | - | 公告栏右侧图标颜色 | +| textStyle | TextStyle? | - | 公告栏内容样式 | + ### TNoticeBarType #### 简介 diff --git a/tdesign-component/example/assets/api/picker_api.md b/tdesign-component/example/assets/api/picker_api.md index 57fbf9802..861cf2b7a 100644 --- a/tdesign-component/example/assets/api/picker_api.md +++ b/tdesign-component/example/assets/api/picker_api.md @@ -1,28 +1,51 @@ ## API ### TPicker +#### 简介 +纯滚轮选择器组件 +数据决定形态（编译期类型安全）： +- `TPickerColumns` → 多列独立选择 +- `TPickerLinked` → 联动选择 +```dart +// 多列独立 +TPicker( + items: TPickerColumns.fromRaw([['北京', '上海', '广州']]), +) +// 联动 +TPicker( + items: TPickerLinked.fromRaw({'广东': {'深圳': ['南山', '福田']}}), +) +``` #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| cancel | Widget? | - | 工具栏左侧自定义插槽，默认使用 [TResourceDelegate.cancel] 可用于渲染图标、图标+文字组合等。点击事件依然由外层 [GestureDetector] 处理，触发 [onCancel] 回调——所以插槽内的 Widget 不需要自己处理点击。 ```dart // 简单改文字 TPicker( cancel: const Text('关闭'), onCancel: () => Navigator.of(context).pop(), ) // 带图标 TPicker( cancel: const Icon(Icons.close, size: 22), onCancel: () => Navigator.of(context).pop(), ) ``` | -| confirm | Widget? | - | 工具栏右侧自定义插槽，默认使用 [TResourceDelegate.confirm] 可用于渲染图标、图标+文字组合等。点击事件依然由外层 [GestureDetector] 处理，触发 [onConfirm] 回调——所以插槽内的 Widget 不需要自己处理点击。 ```dart // 简单改文字 TPicker( confirm: const Text('确定'), onConfirm: (v) => Navigator.of(context).pop(v), ) // 带图标 TPicker( confirm: const Icon(Icons.check, size: 22), onConfirm: (v) => Navigator.of(context).pop(v), ) ``` | +| cancel | Widget? | - | 工具栏左侧自定义插槽，默认使用 `TResourceDelegate.cancel` 可用于渲染图标、图标+文字组合等。点击事件依然由外层 `GestureDetector` 处理，触发 `onCancel` 回调——所以插槽内的 Widget 不需要自己处理点击。 ```dart // 简单改文字 TPicker( cancel: const Text('关闭'), onCancel: () => Navigator.of(context).pop(), ) // 带图标 TPicker( cancel: const Icon(Icons.close, size: 22), onCancel: () => Navigator.of(context).pop(), ) ``` | +| confirm | Widget? | - | 工具栏右侧自定义插槽，默认使用 `TResourceDelegate.confirm` 可用于渲染图标、图标+文字组合等。点击事件依然由外层 `GestureDetector` 处理，触发 `onConfirm` 回调——所以插槽内的 Widget 不需要自己处理点击。 ```dart // 简单改文字 TPicker( confirm: const Text('确定'), onConfirm: (v) => Navigator.of(context).pop(v), ) // 带图标 TPicker( confirm: const Icon(Icons.check, size: 22), onConfirm: (v) => Navigator.of(context).pop(v), ) ``` | | disabled | bool | false | 是否禁用整个选择器（禁止滚动和操作），默认 false | | height | double | 200 | 视窗高度，默认 200 | | initialValue | List? | - | 初始选中值列表（按 value 匹配） | | itemBuilder | ItemBuilderType? | - | 自定义子项构建器（disabled 项仍由内部统一渲染，不会走此 builder） | | itemCount | int | 5 | 每屏显示 item 数，默认 5 | | itemDistanceCalculator | ItemDistanceCalculator? | - | 自定义距离计算器（控制颜色/字重/字号随"离中心距离"的变化） | -| items | TPickerItems | - | 数据源（必填） 使用密封类 [TPickerItems] 编译期强制二选一： - [TPickerColumns] → 多列独立选择 - [TPickerLinked] → 联动选择 自由结构数据通过 `.fromRaw()` 工厂构造归一化。 | +| items | TPickerItems | - | 数据源（必填） 使用密封类 `TPickerItems` 编译期强制二选一： - `TPickerColumns` → 多列独立选择 - `TPickerLinked` → 联动选择 自由结构数据通过 `.fromRaw()` 工厂构造归一化。 | | key | Key? | - | 组件标识，用于区分或保留组件状态。 | | onCancel | VoidCallback? | - | 点击「取消」按钮回调 仅作为点击事件通知，不携带任何参数。组件本身不会做任何 popup 操作，业务层可在此自行决定是否关闭弹窗、重置状态等。 | -| onChange | void Function(TPickerValue)? | - | 值改变回调（滚动时实时触发） 触发时机： - 用户滚动经过某个 enabled 项并稳定时 - disabled 修正动画完成后，回调最终落点 **注意**：此回调代表"滚动时实时变化"，不代表"用户已确认选择"。 如需"已确认"语义，请使用 [onConfirm]。 如需做网络请求/埋点等去抖处理，请在业务层自行 debounce。 | -| onConfirm | void Function(TPickerValue)? | - | 点击「确认」按钮回调 携带当前选中的完整 [TPickerValue]，包含： - `selectedOptions`: 当前选中的所有 [TPickerOption] - `values`: 各列选中项的 value 列表 - `labels`: 各列选中项的 label 列表 - `indexes`: 各列选中项的索引 与 [onChange] 不同——只有用户点击「确认」时才触发，代表"已确认选择"。 组件本身不会做任何 popup 操作，业务层可在此自行决定是否关闭弹窗、 提交表单等。 | -| onLoad | void Function(TPickerLoadEvent)? | - | 列选中项变化的事件回调 **触发时机**：每次用户滚动到一个 enabled 项后都会触发（联动模式下还会 在新展开的列就位后触发）。组件本身不做"距底部多少项"的阈值判断——把 决策权交给业务层。 **事件参数**包含： - [TPickerLoadEvent.column]：触发列索引 - [TPickerLoadEvent.remaining]：当前列距底部剩余项数 - [TPickerLoadEvent.displayedCount]：当前列总项数 - [TPickerLoadEvent.parentValue]：联动模式下父级选中值（首列为 null） **典型用法**：业务层根据 [TPickerLoadEvent.remaining] 自行判断是否加载更多。 ```dart onLoad: (e) async { if (e.remaining > 5 \|\| _isLoading) return; // 距底部还远 / 已在加载，跳过 _isLoading = true; final more = await fetchMore(parent: e.parentValue); setState(() { _data.addAll(more); _isLoading = false; }); } ``` | -| title | String? | - | 工具栏中部标题（可选，不传时中部留白） 顶部工具栏永远显示，包含「取消」「标题」「确认」三块。 用户点击「取消」触发 [onCancel]，点击「确认」触发 [onConfirm]。 选择器与弹窗（popup）完全解耦——关闭/打开弹窗的逻辑由业务层在 这两个回调中自行控制。 典型用法（与 popup 弹窗组合）： ```dart TPicker( items: items, title: '请选择地区', onCancel: () => setState(() => visible = false), onConfirm: (value) { setState(() { selected = value; visible = false; }); }, ) ``` | -| titleWidget | Widget? | - | 工具栏中部自定义标题插槽 传入后会**完全替换**默认的 [title] 文字，可用于渲染更复杂的标题（副标题、图标+文字等）。 标题区域不响应点击。 | +| onChange | void Function(TPickerValue)? | - | 值改变回调（滚动时实时触发） 触发时机： - 用户滚动经过某个 enabled 项并稳定时 - disabled 修正动画完成后，回调最终落点 **注意**：此回调代表"滚动时实时变化"，不代表"用户已确认选择"。 如需"已确认"语义，请使用 `onConfirm`。 如需做网络请求/埋点等去抖处理，请在业务层自行 debounce。 | +| onConfirm | void Function(TPickerValue)? | - | 点击「确认」按钮回调 携带当前选中的完整 `TPickerValue`，包含： - `selectedOptions`: 当前选中的所有 `TPickerOption` - `values`: 各列选中项的 value 列表 - `labels`: 各列选中项的 label 列表 - `indexes`: 各列选中项的索引 与 `onChange` 不同——只有用户点击「确认」时才触发，代表"已确认选择"。 组件本身不会做任何 popup 操作，业务层可在此自行决定是否关闭弹窗、 提交表单等。 | +| onLoad | void Function(TPickerLoadEvent)? | - | 列选中项变化的事件回调 **触发时机**：每次用户滚动到一个 enabled 项后都会触发（联动模式下还会 在新展开的列就位后触发）。组件本身不做"距底部多少项"的阈值判断——把 决策权交给业务层。 **事件参数**包含： - `TPickerLoadEvent.column`：触发列索引 - `TPickerLoadEvent.remaining`：当前列距底部剩余项数 - `TPickerLoadEvent.displayedCount`：当前列总项数 - `TPickerLoadEvent.parentValue`：联动模式下父级选中值（首列为 null） **典型用法**：业务层根据 `TPickerLoadEvent.remaining` 自行判断是否加载更多。 ```dart onLoad: (e) async { if (e.remaining > 5 \|\| _isLoading) return; // 距底部还远 / 已在加载，跳过 _isLoading = true; final more = await fetchMore(parent: e.parentValue); setState(() { _data.addAll(more); _isLoading = false; }); } ``` | +| title | String? | - | 工具栏中部标题（可选，不传时中部留白） 顶部工具栏永远显示，包含「取消」「标题」「确认」三块。 用户点击「取消」触发 `onCancel`，点击「确认」触发 `onConfirm`。 选择器与弹窗（popup）完全解耦——关闭/打开弹窗的逻辑由业务层在 这两个回调中自行控制。 典型用法（与 popup 弹窗组合）： ```dart TPicker( items: items, title: '请选择地区', onCancel: () => setState(() => visible = false), onConfirm: (value) { setState(() { selected = value; visible = false; }); }, ) ``` | +| titleWidget | Widget? | - | 工具栏中部自定义标题插槽 传入后会**完全替换**默认的 `title` 文字，可用于渲染更复杂的标题（副标题、图标+文字等）。 标题区域不响应点击。 | ### TPickerOption +#### 简介 +选择器选项 +label 用于显示，value 用于 onChange 返回，两者分离以便自定义展示 +（emoji、单位、国际化）同时保持纯净的业务值。 +```dart +TPickerOption(label: '👨 男性', value: 'M') +TPickerOption(label: '广东省', value: 'GD', disabled: true) +``` #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -33,6 +56,12 @@ ### TPickerValue +#### 简介 +onChange 回调返回的选中信息 +```dart +onChange: (v) => setState(() => _lastValue = v); +Text(_lastValue?.labels.join(' / ') ?? ''); +``` #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -49,6 +78,12 @@ ### TPickerLoadEvent +#### 简介 +列选中变化的事件参数 +每当用户在某一列滚动到一个 enabled 项后，`TPicker.onLoad` 会收到一个该事件实例。 +事件里携带了"列索引、当前列总数、距底部剩余项数、联动模式下父级选中值"等 +上下文信息，业务层据此自行决定是否加载更多数据（例如： +`if (e.remaining > 5) return;`）。 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -60,68 +95,95 @@ ### TPickerColumns -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| columns | List> | - | 每列的选项列表 | - +#### 简介 +多列独立选择的数据源 +```dart +TPicker( + items: TPickerColumns([ + [TPickerOption(label: '北京', value: 'BJ'), ...], + [TPickerOption(label: '朝阳区', value: 'CY'), ...], + ]), +) +``` #### 工厂构造方法 ##### TPickerColumns.fromRaw 从自由结构的 raw 数据创建，自动归一化 - - ```dart - TPickerColumns.fromRaw( - [['北京', '上海', '广州']], - keys: const TPickerKeys(label: 'name', value: 'code'), - ) - ``` +```dart +TPickerColumns.fromRaw( + [['北京', '上海', '广州']], + keys: const TPickerKeys(label: 'name', value: 'code'), +) +``` | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | rawColumns | List | - | - | | keys | TPickerKeys | TPickerKeys.defaults | - | - -### TPickerLinked #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| tree | Map | - | 联动树结构：`Map` value 可以是： - `Map` → 下一级联动 - `List` → 叶子级选项 | +| columns | List> | - | 每列的选项列表 | +### TPickerLinked +#### 简介 +联动选择的数据源 +```dart +TPicker( + items: TPickerLinked({ + TPickerOption(label: '广东', value: 'GD'): { + TPickerOption(label: '深圳', value: 'SZ'): [ + TPickerOption(label: '南山', value: 'NS'), + ], + }, + }), +) +``` + #### 工厂构造方法 ##### TPickerLinked.fromRaw 从自由结构的 raw Map 数据创建，自动归一化 - - ```dart - TPickerLinked.fromRaw({ - '广东': {'深圳': ['南山', '福田'], '广州': ['天河']}, - '浙江': {'杭州': ['西湖']}, - }) - ``` +```dart +TPickerLinked.fromRaw({ + '广东': {'深圳': ['南山', '福田'], '广州': ['天河']}, + '浙江': {'杭州': ['西湖']}, +}) +``` | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | rawTree | Map | - | - | | keys | TPickerKeys | TPickerKeys.defaults | - | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| tree | Map | - | 联动树结构：`Map` value 可以是： - `Map` → 下一级联动 - `List` → 叶子级选项 | + ### TPickerItems #### 简介 选择器数据源密封类 - - 编译期强制二选一，消除运行时类型错误： - - [TPickerColumns] → 多列独立选择 - - [TPickerLinked] → 联动选择 +编译期强制二选一，消除运行时类型错误： +- `TPickerColumns` → 多列独立选择 +- `TPickerLinked` → 联动选择 ### TPickerKeys +#### 简介 +字段映射配置 +当 picker 数据源不是 `TPickerOption` 时，用于声明原始结构中的字段名。 +```dart +// 数据：[{ id: '1', name: '选项A', readonly: false }] +const keys = TPickerKeys(label: 'name', value: 'id', disabled: 'readonly'); +``` #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-component/example/assets/api/popup_api.md b/tdesign-component/example/assets/api/popup_api.md index 9ff884bdf..5c9e7e072 100644 --- a/tdesign-component/example/assets/api/popup_api.md +++ b/tdesign-component/example/assets/api/popup_api.md @@ -2,342 +2,281 @@ ### TPopup #### 简介 弹出层入口：五向滑入 / 居中弹出，支持蒙层、bottom 操作区、center 面板外下方关闭区。 +通过 `show` 命令式打开；返回 `TPopupHandle` 用于关闭与再次打开。 +多次调用 `show` 会继续压入新的浮层路由，可用于叠加展示。 - 通过 [show] 命令式打开；返回 [TPopupHandle] 用于关闭与再次打开。 - 多次调用 [show] 会继续压入新的浮层路由，可用于叠加展示。 - - **示例** - - ```dart - final handle = TPopup.show( - context, - options: TPopupOptions.bottom( - titleWidget: const Text('标题'), - child: MyPanel(), - ), - ); - handle.close(); - handle.open(); - ``` - - 配置项见 [TPopupOptions]；方向见 [TPopupPlacement]。 - -#### 工厂构造方法 - -##### TPopup._ +配置项见 `TPopupOptions`；方向见 `TPopupPlacement`。 #### 静态方法 ##### TPopup.show -打开浮层并压入独立 [PopupRoute]。 - - [context] 用于查找 [Navigator] 并展示浮层。 - - [options] 浮层配置；方向固定时推荐 [TPopupOptions.bottom] 等命名工厂。 - - 返回 [TPopupHandle]，可用 [TPopupHandle.close]、[TPopupHandle.open]、 - [TPopupHandle.isShowing] 控制与查询。 - 重复调用会继续 push 新的浮层；若需互斥请在业务层管理。 - - [navigatorContext] 可选，指定承载浮层的 [Navigator] 的 context，默认 [context]。 - - [useRootNavigator] 为 true 时使用根 [Navigator]（嵌套导航场景）。 +打开浮层并压入 `PopupRoute`，返回 `TPopupHandle` 用于关闭/再次打开。 +连续调用会重复 push 新路由；互斥展示请在业务层自行管理。 返回类型：`TPopupHandle` | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| context | BuildContext | - | - | -| options | TPopupOptions | - | 创建时传入的配置；每次 [open] 会按 [TPopupOptions.placement] 裁剪无效字段后使用。 | -| navigatorContext | BuildContext? | - | 与 [TPopup.show] 的 [navigatorContext] 相同。 | -| useRootNavigator | bool | false | 与 [TPopup.show] 的 [useRootNavigator] 相同。 | +| context | BuildContext | - | 用于查找并展示 `Navigator`。 | +| options | TPopupOptions | - | 浮层配置；方向固定时建议 `TPopupOptions.bottom` 等命名工厂。 | +| navigatorContext | BuildContext? | - | 可选，指定承载浮层的 `Navigator` context，默认 `context`。 | +| useRootNavigator | bool | false | 为 true 时使用根 `Navigator`（嵌套导航场景）。 | ### TPopupOptions #### 简介 -[TPopup.show] 的配置对象。 - - ## 如何创建 - - | 场景 | 推荐用法 | - |------|----------| - | 弹出方向已知 | [TPopupOptions.bottom]、[TPopupOptions.center]、[TPopupOptions.top]、[TPopupOptions.left]、[TPopupOptions.right] | - | 方向由变量决定 | 默认构造并设置 [placement]；传错字段会在 [TPopup.show] / [TPopupHandle.open] 时抛 [FlutterError] | - - 命名工厂只暴露当前方向生效的字段（例如 [TPopupOptions.bottom] 无 [width] 参数）。 - - ## 字段与 [TPopupPlacement] +`TPopup.show` 的配置对象。 +## 如何创建 +| 场景 | 推荐用法 | +|------|----------| +| 弹出方向已知 | `TPopupOptions.bottom`、`TPopupOptions.center`、`TPopupOptions.top`、`TPopupOptions.left`、`TPopupOptions.right` | +| 方向由变量决定 | 默认构造并设置 `placement`；传错字段会在 `TPopup.show` / `TPopupHandle.open` 时抛 `FlutterError` | +命名工厂只暴露当前方向生效的字段（例如 `TPopupOptions.bottom` 无 `width` 参数）。 +## 字段与 `TPopupPlacement` +| `TPopupPlacement` | 头部 / 关闭区 | 尺寸 | +|-------------------|-------------|------| +| `TPopupPlacement.bottom` | `headerBuilder`、`titleWidget`、`cancelBuilder`、`confirmBuilder` | `height`、`inset` | +| `TPopupPlacement.center` | `closeBuilder` | `width`、`height` | +| `TPopupPlacement.top` | — | `height`、`inset` | +| `TPopupPlacement.left`、`TPopupPlacement.right` | — | `width`、`inset` | +`inset` 须为与 `placement` 匹配的类型（如 bottom 用 `TPopupBottomInset`），否则校验失败。 +## Builder 三态（`headerBuilder`、`cancelBuilder`、`confirmBuilder`、`closeBuilder`） +| 传参方式 | 效果 | +|----------|------| +| 省略（使用默认值） | 渲染内置 UI | +| 显式 `null` | 隐藏该区域 | +| 自定义 `TPopupHeaderBuilder` / `TPopupSlotBuilder` | 完全替换；需自行提供交互与语义，可调用 `close` 关闭浮层 | +`titleWidget` 默认为 `null`，表示无标题内容。 +生命周期回调见 `onOpen`、`onOpened`、`onClose`、`onClosed`、`onVisibleChange`、`onOverlayClick`。 +## modal 与 showOverlay 组合 +| modal | showOverlay | 表现 | +|-------|-------------|------| +| true | true | 标准模态弹层（半透明蒙层 + 阻断背景） | +| true | false | 透明模态弹层（无可见蒙层，仍阻断背景） | +| false | false | 非模态浮层（不阻断背景） | +## closeOnOverlayClick +构造参数类型为 `bool?`。省略（`null`）时按 `showOverlay` 推导：有蒙层为 true，无蒙层为 false。 +通过 `closeOnOverlayClick` getter 读取解析后的 `bool` 值。 - | [TPopupPlacement] | 头部 / 关闭区 | 尺寸 | - |-------------------|-------------|------| - | [TPopupPlacement.bottom] | [headerBuilder]、[titleWidget]、[cancelBuilder]、[confirmBuilder] | [height]、[inset] | - | [TPopupPlacement.center] | [closeBuilder] | [width]、[height] | - | [TPopupPlacement.top] | — | [height]、[inset] | - | [TPopupPlacement.left]、[TPopupPlacement.right] | — | [width]、[inset] | - - ## Builder 三态（[headerBuilder]、[cancelBuilder]、[confirmBuilder]、[closeBuilder]） +#### 工厂构造方法 - | 传参方式 | 效果 | - |----------|------| - | 省略（使用默认值） | 渲染内置 UI | - | 显式 `null` | 隐藏该区域 | - | 自定义 [TPopupHeaderBuilder] / [TPopupSlotBuilder] | 完全替换；需自行提供交互与语义，可调用 `close` 关闭浮层 | +##### 通用参数 - [titleWidget] 默认为 `null`，表示无标题内容。 - - 生命周期回调见 [onOpen]、[onOpened]、[onClose]、[onClosed]、[onVisibleChange]、[onOverlayClick]。 -#### 默认构造方法 +以下参数由各命名工厂统一透传，含义一致： | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| animationDuration | Duration | const Duration(milliseconds: 240) | 打开/关闭动画时长。 | +| animationDuration | Duration | const Duration(milliseconds: 240) | 打开/关闭动画时长，默认 240ms。 | | backgroundColor | Color? | - | 内容区背景色，默认主题容器色。 | -| cancelBuilder | TPopupSlotBuilder? | _kPopupDefaultCancel | bottom 左侧操作槽；仅 [headerBuilder] 为内置默认时生效。 内置默认为「取消」，点击触发 [TPopupTrigger.cancel]。 | | child | Widget | - | 浮层主体内容（必填）。 | -| closeBuilder | TPopupSlotBuilder? | _kPopupDefaultClose | center 面板外下方关闭区；仅 [TPopupPlacement.center] 生效。三态见类文档「Builder 三态」。 内置默认点击触发 [TPopupTrigger.close]。 | | closeOnOverlayClick | bool? | - | - | -| confirmBuilder | TPopupSlotBuilder? | _kPopupDefaultConfirm | bottom 右侧操作槽；仅 [headerBuilder] 为内置默认时生效。 内置默认为「确定」，点击触发 [TPopupTrigger.confirm]。 | -| destroyOnClose | bool | false | 为 true 时路由 `maintainState` 为 false，关闭后不保留路由内 State。 | -| headerBuilder | TPopupHeaderBuilder? | _kPopupDefaultHeader | bottom 头部；仅 [TPopupPlacement.bottom] 生效。三态见类文档「Builder 三态」。 自定义时忽略 [titleWidget]、[cancelBuilder]、[confirmBuilder]。 | -| height | double? | - | 高度；[TPopupPlacement.top]、[TPopupPlacement.bottom] 生效；[TPopupPlacement.center] 约束面板尺寸。 | -| inset | TPopupInset? | - | 交叉轴边缘留白；具体类型由 [placement] 决定。 * [TPopupPlacement.bottom] 使用 [TPopupBottomInset] * [TPopupPlacement.top] 使用 [TPopupTopInset] * [TPopupPlacement.left] 使用 [TPopupLeftInset] * [TPopupPlacement.right] 使用 [TPopupRightInset] * [TPopupPlacement.center] 不支持 | -| modal | bool | true | 是否以模态方式展示；为 true 时阻断背景交互与底层语义/焦点。 结合 [showOverlay] 可表达三种模式： * `modal=true, showOverlay=true`：标准模态弹层 * `modal=true, showOverlay=false`：透明模态弹层 * `modal=false, showOverlay=false`：非模态浮层 | -| onClose | VoidCallback? | - | 开始关闭（与 [onVisibleChange] 的 `visible: false` 同期）。 | -| onClosed | VoidCallback? | - | 当前展示周期真正结束。 大多数场景下会在关闭动画结束后触发；非栈顶路由被直接移除时不保证存在关闭动画。 | -| onOpen | VoidCallback? | - | 路由 push 时（打开动画开始前）。 | -| onOpened | VoidCallback? | - | 打开动画结束。 | -| onOverlayClick | VoidCallback? | - | 蒙层点击；是否关闭取决于 [closeOnOverlayClick]。 | -| onVisibleChange | TPopupVisibleChangeCallback? | - | 显隐变化；第二个参数为 [TPopupTrigger]。 | +| destroyOnClose | bool | false | 关闭后销毁路由 State（`maintainState=false`），默认 false。 | +| modal | bool | true | 是否模态展示；为 true 时阻断背景交互与语义/焦点（与 `showOverlay` 组合见类文档）。 | +| onClose | VoidCallback? | - | 开始关闭时触发（与 [onVisibleChange](false, …) 同期）。 | +| onClosed | VoidCallback? | - | 展示周期结束触发；通常于关闭动画结束后，被直接移除时可能无动画。 | +| onOpen | VoidCallback? | - | 路由 push 时触发（打开动画开始前）。 | +| onOpened | VoidCallback? | - | 打开动画结束后触发。 | +| onOverlayClick | VoidCallback? | - | 蒙层点击回调；是否关闭由 `closeOnOverlayClick` 决定。 | +| onVisibleChange | TPopupVisibleChangeCallback? | - | 显隐变化回调；第二参数为 `TPopupTrigger`。 | | overlayColor | Color? | - | 蒙层颜色，默认 black54。 | -| overlayOpacity | double? | - | 蒙层透明度系数（0–1），与 [overlayColor] 的 alpha 相乘后用于绘制。 | -| placement | TPopupPlacement | TPopupPlacement.bottom | 出现位置，默认 [TPopupPlacement.bottom]。 | +| overlayOpacity | double? | - | 蒙层透明度系数（0–1），与 `overlayColor` 的 alpha 相乘后用于绘制。 | | radius | double? | - | 内容区圆角，默认主题大圆角。 | -| showOverlay | bool | true | 是否绘制半透明蒙层。 当 [modal] 为 true 且此值为 false 时，为“透明模态弹层”。 | -| titleWidget | Widget? | - | bottom 标题插槽；仅 [headerBuilder] 为内置默认时生效。`null` 表示无标题。 | -| width | double? | - | 宽度；[TPopupPlacement.left]、[TPopupPlacement.right]、[TPopupPlacement.center] 生效。 | +| showOverlay | bool | true | 是否绘制蒙层；`modal`=true 且此值为 false 时为透明模态（见类文档「modal 与 showOverlay 组合」）。 | +| useSafeArea | bool | true | 是否避让系统安全区，默认 true；仅贴边方向生效，`TPopupPlacement.center` 忽略，与 `inset` 叠加。 | -#### 工厂构造方法 - ##### TPopupOptions.bottom -创建 [TPopupPlacement.bottom] 配置。 +创建 bottom 配置：固定 `placement`，默认内置头部，其余字段见成员文档。 - 固定 [placement] 为 [TPopupPlacement.bottom]；默认带内置头部。 - 蒙层、动画、生命周期等字段语义见同名成员文档。 +其余参数见「通用参数」。 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| child | Widget | - | 浮层主体内容（必填）。 | -| height | double? | - | 高度；[TPopupPlacement.top]、[TPopupPlacement.bottom] 生效；[TPopupPlacement.center] 约束面板尺寸。 | -| inset | TPopupBottomInset? | - | 交叉轴边缘留白；具体类型由 [placement] 决定。 * [TPopupPlacement.bottom] 使用 [TPopupBottomInset] * [TPopupPlacement.top] 使用 [TPopupTopInset] * [TPopupPlacement.left] 使用 [TPopupLeftInset] * [TPopupPlacement.right] 使用 [TPopupRightInset] * [TPopupPlacement.center] 不支持 | -| headerBuilder | TPopupHeaderBuilder? | _kPopupDefaultHeader | bottom 头部；仅 [TPopupPlacement.bottom] 生效。三态见类文档「Builder 三态」。 自定义时忽略 [titleWidget]、[cancelBuilder]、[confirmBuilder]。 | -| titleWidget | Widget? | - | bottom 标题插槽；仅 [headerBuilder] 为内置默认时生效。`null` 表示无标题。 | -| cancelBuilder | TPopupSlotBuilder? | _kPopupDefaultCancel | bottom 左侧操作槽；仅 [headerBuilder] 为内置默认时生效。 内置默认为「取消」，点击触发 [TPopupTrigger.cancel]。 | -| confirmBuilder | TPopupSlotBuilder? | _kPopupDefaultConfirm | bottom 右侧操作槽；仅 [headerBuilder] 为内置默认时生效。 内置默认为「确定」，点击触发 [TPopupTrigger.confirm]。 | -| radius | double? | - | 内容区圆角，默认主题大圆角。 | -| backgroundColor | Color? | - | 内容区背景色，默认主题容器色。 | -| showOverlay | bool | true | 是否绘制半透明蒙层。 当 [modal] 为 true 且此值为 false 时，为“透明模态弹层”。 | -| closeOnOverlayClick | bool? | - | - | -| overlayColor | Color? | - | 蒙层颜色，默认 black54。 | -| overlayOpacity | double? | - | 蒙层透明度系数（0–1），与 [overlayColor] 的 alpha 相乘后用于绘制。 | -| modal | bool | true | 是否以模态方式展示；为 true 时阻断背景交互与底层语义/焦点。 结合 [showOverlay] 可表达三种模式： * `modal=true, showOverlay=true`：标准模态弹层 * `modal=true, showOverlay=false`：透明模态弹层 * `modal=false, showOverlay=false`：非模态浮层 | -| destroyOnClose | bool | false | 为 true 时路由 `maintainState` 为 false，关闭后不保留路由内 State。 | -| animationDuration | Duration | const Duration(milliseconds: 240) | 打开/关闭动画时长。 | -| onOpen | VoidCallback? | - | 路由 push 时（打开动画开始前）。 | -| onOpened | VoidCallback? | - | 打开动画结束。 | -| onClose | VoidCallback? | - | 开始关闭（与 [onVisibleChange] 的 `visible: false` 同期）。 | -| onClosed | VoidCallback? | - | 当前展示周期真正结束。 大多数场景下会在关闭动画结束后触发；非栈顶路由被直接移除时不保证存在关闭动画。 | -| onVisibleChange | TPopupVisibleChangeCallback? | - | 显隐变化；第二个参数为 [TPopupTrigger]。 | -| onOverlayClick | VoidCallback? | - | 蒙层点击；是否关闭取决于 [closeOnOverlayClick]。 | +| height | double? | - | 内容高度；top/bottom 传值时固定高度，bottom 省略时由内容撑开；center 用于约束面板尺寸。 | +| inset | TPopupBottomInset? | - | 交叉轴边缘留白，类型须与 `placement` 匹配（见各类 *Inset）；`TPopupPlacement.center` 不支持。 | +| headerBuilder | TPopupHeaderBuilder? | _kPopupDefaultHeader | bottom 头部构建器（仅 bottom）；省略=内置，null=隐藏，自定义见类文档「Builder 三态」。 | +| titleWidget | Widget? | - | bottom 标题（仅内置头部时）；`null` 表示不展示标题。 | +| cancelBuilder | TPopupSlotBuilder? | _kPopupDefaultCancel | bottom 左侧槽（仅内置头部时）；默认「取消」，触发 `TPopupTrigger.cancel`。 | +| confirmBuilder | TPopupSlotBuilder? | _kPopupDefaultConfirm | bottom 右侧槽（仅内置头部时）；默认「确定」，触发 `TPopupTrigger.confirm`。 | ##### TPopupOptions.center -创建 [TPopupPlacement.center] 配置。 +创建 center 配置：固定 `placement`，默认面板外下方圆形关闭按钮。 - 固定 [placement] 为 [TPopupPlacement.center]；默认展示面板外下方圆形关闭按钮。 +其余参数见「通用参数」。 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| child | Widget | - | 浮层主体内容（必填）。 | -| width | double? | - | 宽度；[TPopupPlacement.left]、[TPopupPlacement.right]、[TPopupPlacement.center] 生效。 | -| height | double? | - | 高度；[TPopupPlacement.top]、[TPopupPlacement.bottom] 生效；[TPopupPlacement.center] 约束面板尺寸。 | -| closeBuilder | TPopupSlotBuilder? | _kPopupDefaultClose | center 面板外下方关闭区；仅 [TPopupPlacement.center] 生效。三态见类文档「Builder 三态」。 内置默认点击触发 [TPopupTrigger.close]。 | -| radius | double? | - | 内容区圆角，默认主题大圆角。 | -| backgroundColor | Color? | - | 内容区背景色，默认主题容器色。 | -| showOverlay | bool | true | 是否绘制半透明蒙层。 当 [modal] 为 true 且此值为 false 时，为“透明模态弹层”。 | -| closeOnOverlayClick | bool? | - | - | -| overlayColor | Color? | - | 蒙层颜色，默认 black54。 | -| overlayOpacity | double? | - | 蒙层透明度系数（0–1），与 [overlayColor] 的 alpha 相乘后用于绘制。 | -| modal | bool | true | 是否以模态方式展示；为 true 时阻断背景交互与底层语义/焦点。 结合 [showOverlay] 可表达三种模式： * `modal=true, showOverlay=true`：标准模态弹层 * `modal=true, showOverlay=false`：透明模态弹层 * `modal=false, showOverlay=false`：非模态浮层 | -| destroyOnClose | bool | false | 为 true 时路由 `maintainState` 为 false，关闭后不保留路由内 State。 | -| animationDuration | Duration | const Duration(milliseconds: 240) | 打开/关闭动画时长。 | -| onOpen | VoidCallback? | - | 路由 push 时（打开动画开始前）。 | -| onOpened | VoidCallback? | - | 打开动画结束。 | -| onClose | VoidCallback? | - | 开始关闭（与 [onVisibleChange] 的 `visible: false` 同期）。 | -| onClosed | VoidCallback? | - | 当前展示周期真正结束。 大多数场景下会在关闭动画结束后触发；非栈顶路由被直接移除时不保证存在关闭动画。 | -| onVisibleChange | TPopupVisibleChangeCallback? | - | 显隐变化；第二个参数为 [TPopupTrigger]。 | -| onOverlayClick | VoidCallback? | - | 蒙层点击；是否关闭取决于 [closeOnOverlayClick]。 | +| width | double? | - | 内容宽度；仅 `TPopupPlacement.left`、`TPopupPlacement.right`、`TPopupPlacement.center` 生效。 | +| height | double? | - | 内容高度；top/bottom 传值时固定高度，bottom 省略时由内容撑开；center 用于约束面板尺寸。 | +| closeBuilder | TPopupSlotBuilder? | _kPopupDefaultClose | center 面板外下方关闭区（仅 center）；默认圆形关闭，触发 `TPopupTrigger.close`。 | ##### TPopupOptions.left -创建 [TPopupPlacement.left] 配置。 +创建 left 配置：固定 `placement`，未传 `width` 时默认 280。 - 固定 [placement] 为 [TPopupPlacement.left]；未传 [width] 时布局默认宽度 280。 +其余参数见「通用参数」。 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| child | Widget | - | 浮层主体内容（必填）。 | -| width | double? | - | 宽度；[TPopupPlacement.left]、[TPopupPlacement.right]、[TPopupPlacement.center] 生效。 | -| inset | TPopupLeftInset? | - | 交叉轴边缘留白；具体类型由 [placement] 决定。 * [TPopupPlacement.bottom] 使用 [TPopupBottomInset] * [TPopupPlacement.top] 使用 [TPopupTopInset] * [TPopupPlacement.left] 使用 [TPopupLeftInset] * [TPopupPlacement.right] 使用 [TPopupRightInset] * [TPopupPlacement.center] 不支持 | -| radius | double? | - | 内容区圆角，默认主题大圆角。 | -| backgroundColor | Color? | - | 内容区背景色，默认主题容器色。 | -| showOverlay | bool | true | 是否绘制半透明蒙层。 当 [modal] 为 true 且此值为 false 时，为“透明模态弹层”。 | -| closeOnOverlayClick | bool? | - | - | -| overlayColor | Color? | - | 蒙层颜色，默认 black54。 | -| overlayOpacity | double? | - | 蒙层透明度系数（0–1），与 [overlayColor] 的 alpha 相乘后用于绘制。 | -| modal | bool | true | 是否以模态方式展示；为 true 时阻断背景交互与底层语义/焦点。 结合 [showOverlay] 可表达三种模式： * `modal=true, showOverlay=true`：标准模态弹层 * `modal=true, showOverlay=false`：透明模态弹层 * `modal=false, showOverlay=false`：非模态浮层 | -| destroyOnClose | bool | false | 为 true 时路由 `maintainState` 为 false，关闭后不保留路由内 State。 | -| animationDuration | Duration | const Duration(milliseconds: 240) | 打开/关闭动画时长。 | -| onOpen | VoidCallback? | - | 路由 push 时（打开动画开始前）。 | -| onOpened | VoidCallback? | - | 打开动画结束。 | -| onClose | VoidCallback? | - | 开始关闭（与 [onVisibleChange] 的 `visible: false` 同期）。 | -| onClosed | VoidCallback? | - | 当前展示周期真正结束。 大多数场景下会在关闭动画结束后触发；非栈顶路由被直接移除时不保证存在关闭动画。 | -| onVisibleChange | TPopupVisibleChangeCallback? | - | 显隐变化；第二个参数为 [TPopupTrigger]。 | -| onOverlayClick | VoidCallback? | - | 蒙层点击；是否关闭取决于 [closeOnOverlayClick]。 | +| width | double? | - | 内容宽度；仅 `TPopupPlacement.left`、`TPopupPlacement.right`、`TPopupPlacement.center` 生效。 | +| inset | TPopupLeftInset? | - | 交叉轴边缘留白，类型须与 `placement` 匹配（见各类 *Inset）；`TPopupPlacement.center` 不支持。 | ##### TPopupOptions.right -创建 [TPopupPlacement.right] 配置。 +创建 right 配置：固定 `placement`，未传 `width` 时默认 280。 - 固定 [placement] 为 [TPopupPlacement.right]；未传 [width] 时布局默认宽度 280。 +其余参数见「通用参数」。 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| child | Widget | - | 浮层主体内容（必填）。 | -| width | double? | - | 宽度；[TPopupPlacement.left]、[TPopupPlacement.right]、[TPopupPlacement.center] 生效。 | -| inset | TPopupRightInset? | - | 交叉轴边缘留白；具体类型由 [placement] 决定。 * [TPopupPlacement.bottom] 使用 [TPopupBottomInset] * [TPopupPlacement.top] 使用 [TPopupTopInset] * [TPopupPlacement.left] 使用 [TPopupLeftInset] * [TPopupPlacement.right] 使用 [TPopupRightInset] * [TPopupPlacement.center] 不支持 | -| radius | double? | - | 内容区圆角，默认主题大圆角。 | -| backgroundColor | Color? | - | 内容区背景色，默认主题容器色。 | -| showOverlay | bool | true | 是否绘制半透明蒙层。 当 [modal] 为 true 且此值为 false 时，为“透明模态弹层”。 | -| closeOnOverlayClick | bool? | - | - | -| overlayColor | Color? | - | 蒙层颜色，默认 black54。 | -| overlayOpacity | double? | - | 蒙层透明度系数（0–1），与 [overlayColor] 的 alpha 相乘后用于绘制。 | -| modal | bool | true | 是否以模态方式展示；为 true 时阻断背景交互与底层语义/焦点。 结合 [showOverlay] 可表达三种模式： * `modal=true, showOverlay=true`：标准模态弹层 * `modal=true, showOverlay=false`：透明模态弹层 * `modal=false, showOverlay=false`：非模态浮层 | -| destroyOnClose | bool | false | 为 true 时路由 `maintainState` 为 false，关闭后不保留路由内 State。 | -| animationDuration | Duration | const Duration(milliseconds: 240) | 打开/关闭动画时长。 | -| onOpen | VoidCallback? | - | 路由 push 时（打开动画开始前）。 | -| onOpened | VoidCallback? | - | 打开动画结束。 | -| onClose | VoidCallback? | - | 开始关闭（与 [onVisibleChange] 的 `visible: false` 同期）。 | -| onClosed | VoidCallback? | - | 当前展示周期真正结束。 大多数场景下会在关闭动画结束后触发；非栈顶路由被直接移除时不保证存在关闭动画。 | -| onVisibleChange | TPopupVisibleChangeCallback? | - | 显隐变化；第二个参数为 [TPopupTrigger]。 | -| onOverlayClick | VoidCallback? | - | 蒙层点击；是否关闭取决于 [closeOnOverlayClick]。 | +| width | double? | - | 内容宽度；仅 `TPopupPlacement.left`、`TPopupPlacement.right`、`TPopupPlacement.center` 生效。 | +| inset | TPopupRightInset? | - | 交叉轴边缘留白，类型须与 `placement` 匹配（见各类 *Inset）；`TPopupPlacement.center` 不支持。 | ##### TPopupOptions.top -创建 [TPopupPlacement.top] 配置。 +创建 top 配置：固定 `placement`，无内置头部。 - 固定 [placement] 为 [TPopupPlacement.top]；无内置头部。 +其余参数见「通用参数」。 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| child | Widget | - | 浮层主体内容（必填）。 | -| height | double? | - | 高度；[TPopupPlacement.top]、[TPopupPlacement.bottom] 生效；[TPopupPlacement.center] 约束面板尺寸。 | -| inset | TPopupTopInset? | - | 交叉轴边缘留白；具体类型由 [placement] 决定。 * [TPopupPlacement.bottom] 使用 [TPopupBottomInset] * [TPopupPlacement.top] 使用 [TPopupTopInset] * [TPopupPlacement.left] 使用 [TPopupLeftInset] * [TPopupPlacement.right] 使用 [TPopupRightInset] * [TPopupPlacement.center] 不支持 | -| radius | double? | - | 内容区圆角，默认主题大圆角。 | +| height | double? | - | 内容高度；top/bottom 传值时固定高度，bottom 省略时由内容撑开；center 用于约束面板尺寸。 | +| inset | TPopupTopInset? | - | 交叉轴边缘留白，类型须与 `placement` 匹配（见各类 *Inset）；`TPopupPlacement.center` 不支持。 | + +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| animationDuration | Duration | const Duration(milliseconds: 240) | 打开/关闭动画时长，默认 240ms。 | | backgroundColor | Color? | - | 内容区背景色，默认主题容器色。 | -| showOverlay | bool | true | 是否绘制半透明蒙层。 当 [modal] 为 true 且此值为 false 时，为“透明模态弹层”。 | +| cancelBuilder | TPopupSlotBuilder? | _kPopupDefaultCancel | bottom 左侧槽（仅内置头部时）；默认「取消」，触发 `TPopupTrigger.cancel`。 | +| child | Widget | - | 浮层主体内容（必填）。 | +| closeBuilder | TPopupSlotBuilder? | _kPopupDefaultClose | center 面板外下方关闭区（仅 center）；默认圆形关闭，触发 `TPopupTrigger.close`。 | | closeOnOverlayClick | bool? | - | - | +| confirmBuilder | TPopupSlotBuilder? | _kPopupDefaultConfirm | bottom 右侧槽（仅内置头部时）；默认「确定」，触发 `TPopupTrigger.confirm`。 | +| destroyOnClose | bool | false | 关闭后销毁路由 State（`maintainState=false`），默认 false。 | +| headerBuilder | TPopupHeaderBuilder? | _kPopupDefaultHeader | bottom 头部构建器（仅 bottom）；省略=内置，null=隐藏，自定义见类文档「Builder 三态」。 | +| height | double? | - | 内容高度；top/bottom 传值时固定高度，bottom 省略时由内容撑开；center 用于约束面板尺寸。 | +| inset | TPopupInset? | - | 交叉轴边缘留白，类型须与 `placement` 匹配（见各类 *Inset）；`TPopupPlacement.center` 不支持。 | +| modal | bool | true | 是否模态展示；为 true 时阻断背景交互与语义/焦点（与 `showOverlay` 组合见类文档）。 | +| onClose | VoidCallback? | - | 开始关闭时触发（与 [onVisibleChange](false, …) 同期）。 | +| onClosed | VoidCallback? | - | 展示周期结束触发；通常于关闭动画结束后，被直接移除时可能无动画。 | +| onOpen | VoidCallback? | - | 路由 push 时触发（打开动画开始前）。 | +| onOpened | VoidCallback? | - | 打开动画结束后触发。 | +| onOverlayClick | VoidCallback? | - | 蒙层点击回调；是否关闭由 `closeOnOverlayClick` 决定。 | +| onVisibleChange | TPopupVisibleChangeCallback? | - | 显隐变化回调；第二参数为 `TPopupTrigger`。 | | overlayColor | Color? | - | 蒙层颜色，默认 black54。 | -| overlayOpacity | double? | - | 蒙层透明度系数（0–1），与 [overlayColor] 的 alpha 相乘后用于绘制。 | -| modal | bool | true | 是否以模态方式展示；为 true 时阻断背景交互与底层语义/焦点。 结合 [showOverlay] 可表达三种模式： * `modal=true, showOverlay=true`：标准模态弹层 * `modal=true, showOverlay=false`：透明模态弹层 * `modal=false, showOverlay=false`：非模态浮层 | -| destroyOnClose | bool | false | 为 true 时路由 `maintainState` 为 false，关闭后不保留路由内 State。 | -| animationDuration | Duration | const Duration(milliseconds: 240) | 打开/关闭动画时长。 | -| onOpen | VoidCallback? | - | 路由 push 时（打开动画开始前）。 | -| onOpened | VoidCallback? | - | 打开动画结束。 | -| onClose | VoidCallback? | - | 开始关闭（与 [onVisibleChange] 的 `visible: false` 同期）。 | -| onClosed | VoidCallback? | - | 当前展示周期真正结束。 大多数场景下会在关闭动画结束后触发；非栈顶路由被直接移除时不保证存在关闭动画。 | -| onVisibleChange | TPopupVisibleChangeCallback? | - | 显隐变化；第二个参数为 [TPopupTrigger]。 | -| onOverlayClick | VoidCallback? | - | 蒙层点击；是否关闭取决于 [closeOnOverlayClick]。 | +| overlayOpacity | double? | - | 蒙层透明度系数（0–1），与 `overlayColor` 的 alpha 相乘后用于绘制。 | +| placement | TPopupPlacement | TPopupPlacement.bottom | 弹出位置，默认 `TPopupPlacement.bottom`。 | +| radius | double? | - | 内容区圆角，默认主题大圆角。 | +| showOverlay | bool | true | 是否绘制蒙层；`modal`=true 且此值为 false 时为透明模态（见类文档「modal 与 showOverlay 组合」）。 | +| titleWidget | Widget? | - | bottom 标题（仅内置头部时）；`null` 表示不展示标题。 | +| useSafeArea | bool | true | 是否避让系统安全区，默认 true；仅贴边方向生效，`TPopupPlacement.center` 忽略，与 `inset` 叠加。 | +| width | double? | - | 内容宽度；仅 `TPopupPlacement.left`、`TPopupPlacement.right`、`TPopupPlacement.center` 生效。 | ### TPopupHandle #### 简介 -[TPopup.show] 的返回值，用于控制同一份 [TPopupOptions] 的多次打开与关闭。 - - **示例** - - ```dart - final handle = TPopup.show( - context, - options: TPopupOptions.bottom(child: panel), - ); - handle.close(); - handle.open(); // 可省略 context，复用已缓存的 Navigator - ``` +`TPopup.show` 的返回值，用于控制同一份 `TPopupOptions` 的多次打开与关闭。 #### 公开属性 | 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| navigatorContext | BuildContext? | - | 与 [TPopup.show] 的 [navigatorContext] 相同。 | -| options | TPopupOptions | - | 创建时传入的配置；每次 [open] 会按 [TPopupOptions.placement] 裁剪无效字段后使用。 | -| useRootNavigator | bool | - | 与 [TPopup.show] 的 [useRootNavigator] 相同。 | +| navigatorContext | BuildContext? | - | 与 `TPopup.show` 的 `navigatorContext` 相同。 | +| options | TPopupOptions | - | 创建时传入的配置；每次 `open` 会按 `TPopupOptions.placement` 裁剪无效字段后使用。 | +| useRootNavigator | bool | - | 与 `TPopup.show` 的 `useRootNavigator` 相同。 | -#### 工厂构造方法 +### TPopupInset +#### 简介 +Popup 在交叉轴方向的边缘留白基类。 -##### TPopupHandle._ +### TPopupBottomInset +#### 简介 +`TPopupPlacement.bottom` 的 `TPopupOptions.inset`：内容区相对屏幕左右的留白。 +#### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| options | TPopupOptions | - | 创建时传入的配置；每次 [open] 会按 [TPopupOptions.placement] 裁剪无效字段后使用。 | -| navigatorContext | BuildContext? | - | 与 [TPopup.show] 的 [navigatorContext] 相同。 | -| useRootNavigator | bool | false | 与 [TPopup.show] 的 [useRootNavigator] 相同。 | +| left | double | 0 | - | +| right | double | 0 | - | -### TPopupPlacement +### TPopupTopInset #### 简介 -浮层出现方向；决定 [TPopupOptions] 中哪些字段生效。 +`TPopupPlacement.top` 的 `TPopupOptions.inset`：内容区相对屏幕左右的留白。 +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| left | double | 0 | - | +| right | double | 0 | - | - 与 [TPopupOptions] 类文档中的「字段与 placement」表对应。 - 方向固定时请用 [TPopupOptions.bottom]、[TPopupOptions.center] 等命名工厂。 + +### TPopupLeftInset +#### 简介 +`TPopupPlacement.left` 的 `TPopupOptions.inset`：内容区相对屏幕上下的留白。 +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| bottom | double | 0 | - | +| top | double | 0 | - | + + +### TPopupRightInset +#### 简介 +`TPopupPlacement.right` 的 `TPopupOptions.inset`：内容区相对屏幕上下的留白。 +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| bottom | double | 0 | - | +| top | double | 0 | - | + + +### TPopupPlacement +#### 简介 +浮层出现方向；决定 `TPopupOptions` 中哪些字段生效。 +与 `TPopupOptions` 类文档中的「字段与 placement」表对应。 +方向固定时请用 `TPopupOptions.bottom`、`TPopupOptions.center` 等命名工厂。 #### 枚举值 | 名称 | 说明 | | --- | --- | -| top | 自顶部滑入；使用 [TPopupOptions.height]、[TPopupOptions.inset]（[TPopupTopInset]）。 | -| left | 自左侧滑入；使用 [TPopupOptions.width]、[TPopupOptions.inset]（[TPopupLeftInset]）。 | -| right | 自右侧滑入；使用 [TPopupOptions.width]、[TPopupOptions.inset]（[TPopupRightInset]）。 | -| bottom | 自底部滑入；默认内置头部；使用 [TPopupOptions.height]、[TPopupOptions.inset]（[TPopupBottomInset]）。 | -| center | 屏幕居中；使用 [TPopupOptions.closeBuilder] 控制面板外下方关闭区。 | +| top | 自顶部滑入；无内置头部；使用 `TPopupOptions.height`、`TPopupOptions.inset`（`TPopupTopInset`）。 | +| left | 自左侧滑入；无内置头部；使用 `TPopupOptions.width`、`TPopupOptions.inset`（`TPopupLeftInset`）；未传 `width` 默认 280。 | +| right | 自右侧滑入；无内置头部；使用 `TPopupOptions.width`、`TPopupOptions.inset`（`TPopupRightInset`）；未传 `width` 默认 280。 | +| bottom | 自底部滑入；默认内置头部；使用 `TPopupOptions.height`、`TPopupOptions.inset`（`TPopupBottomInset`）。 | +| center | 屏幕居中弹出；默认面板外下方关闭按钮；使用 `TPopupOptions.width`、`TPopupOptions.height`、`TPopupOptions.closeBuilder`；不支持 `TPopupOptions.inset`。 | ### TPopupTrigger #### 简介 浮层关闭或显隐变化时的触发来源。 - - 作为 [TPopupVisibleChangeCallback] 的第二个参数，以及关闭流程中的语义标记。 - - 内置控件会映射为 [TPopupTrigger.overlay]、[TPopupTrigger.cancel]、 - [TPopupTrigger.confirm]、[TPopupTrigger.close]； - [TPopupHandle.close] 为 [TPopupTrigger.api]；系统返回为 - [TPopupTrigger.systemBack]；[headerBuilder] 内调用 `close` 等为 - [TPopupTrigger.custom]。 +作为 `TPopupVisibleChangeCallback` 的第二个参数，以及关闭流程中的语义标记。 +内置控件会映射为 `TPopupTrigger.overlay`、`TPopupTrigger.cancel`、 +`TPopupTrigger.confirm`、`TPopupTrigger.close`； +`TPopupHandle.close` 为 `TPopupTrigger.api`；系统返回为 +`TPopupTrigger.systemBack`；`headerBuilder` 内调用 `close` 等为 +`TPopupTrigger.custom`。 #### 枚举值 | 名称 | 说明 | | --- | --- | -| overlay | 点击蒙层，且 [TPopupOptions.closeOnOverlayClick] 为 true。 | -| cancel | 点击 bottom 取消语义槽位（含默认与自定义 [TPopupOptions.cancelBuilder]）。 | -| confirm | 点击 bottom 确认语义槽位（含默认与自定义 [TPopupOptions.confirmBuilder]）。 | -| close | 点击 center 关闭语义槽位（含默认与自定义 [TPopupOptions.closeBuilder]）。 | -| api | 外部 API 主动触发的显隐变化，如 [TPopupHandle.close] 或打开事件。 | +| overlay | 点击蒙层，且 `TPopupOptions.closeOnOverlayClick` 为 true。 | +| cancel | 点击 bottom 取消语义槽位（含默认与自定义 `TPopupOptions.cancelBuilder`）。 | +| confirm | 点击 bottom 确认语义槽位（含默认与自定义 `TPopupOptions.confirmBuilder`）。 | +| close | 点击 center 关闭语义槽位（含默认与自定义 `TPopupOptions.closeBuilder`）。 | +| api | 外部 API 主动触发的显隐变化，如 `TPopupHandle.close` 或打开事件。 | | systemBack | 系统返回键或系统路由返回触发的关闭。 | -| custom | 无框架预设动作语义的自定义关闭，如 [headerBuilder] 内调用 `close`。 | +| custom | 无框架预设动作语义的自定义关闭，如 `headerBuilder` 内调用 `close`。 | diff --git a/tdesign-component/example/assets/api/pull-down-refresh_api.md b/tdesign-component/example/assets/api/pull-down-refresh_api.md index c819e7919..2e51da9be 100644 --- a/tdesign-component/example/assets/api/pull-down-refresh_api.md +++ b/tdesign-component/example/assets/api/pull-down-refresh_api.md @@ -2,7 +2,7 @@ ### TRefreshHeader #### 简介 TDesign刷新头部 - 结合EasyRefresh类实现下拉刷新,继承自Header类，字段含义与父类一致 +结合EasyRefresh类实现下拉刷新,继承自Header类，字段含义与父类一致 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -27,7 +27,7 @@ TDesign刷新头部 | loadingIcon | TLoadingIcon | TLoadingIcon.circle | loading样式 | | maxOverOffset | - | - | - | | notifyWhenInvisible | - | - | - | -| overScroll | bool | true | 越界滚动([enableInfiniteRefresh]为true或[infiniteOffset]有值时生效) | +| overScroll | bool | true | 越界滚动(`enableInfiniteRefresh`为true或`infiniteOffset`有值时生效) | | position | - | - | - | | processedDuration | Duration? | - | - | | readySpringBuilder | - | - | - | @@ -38,7 +38,7 @@ TDesign刷新头部 | secondaryVelocity | - | - | - | | spring | - | - | - | | springRebound | - | - | - | -| triggerDistance | double | 48.0 | 触发刷新任务的偏移量，同[triggerOffset] | +| triggerDistance | double | 48.0 | 触发刷新任务的偏移量，同`triggerOffset` | | triggerOffset | double? | - | - | | triggerWhenReach | - | - | - | | triggerWhenRelease | - | - | - | diff --git a/tdesign-component/example/assets/api/radio_api.md b/tdesign-component/example/assets/api/radio_api.md index 3ae5d569b..87d587be8 100644 --- a/tdesign-component/example/assets/api/radio_api.md +++ b/tdesign-component/example/assets/api/radio_api.md @@ -36,10 +36,9 @@ ### TRadioGroup #### 简介 RadioGroup分组对象，继承自TCheckboxGroup，字段含义与父类一致 - RadioGroup应该嵌套在RadioGroup内，所有在RadioGroup的RadioButton只能有一个被选中 - - cardMode: 使用卡片样式，需要配合direction 和 directionalTdRadios 使用， - 组合为横向、纵向卡片，同时需要在每个TRadio上设置cardMode参数。 +RadioGroup应该嵌套在RadioGroup内，所有在RadioGroup的RadioButton只能有一个被选中 +cardMode: 使用卡片样式，需要配合direction 和 directionalTdRadios 使用， +组合为横向、纵向卡片，同时需要在每个TRadio上设置cardMode参数。 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-component/example/assets/api/rate_api.md b/tdesign-component/example/assets/api/rate_api.md index 6fd415996..e1024dad7 100644 --- a/tdesign-component/example/assets/api/rate_api.md +++ b/tdesign-component/example/assets/api/rate_api.md @@ -1,27 +1,29 @@ ## API ### TRate +#### 简介 +评分组件 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | allowHalf | bool? | false | 是否允许半选 | -| builderText | Widget Function(BuildContext context, double value)? | - | 评分等级对应的辅助文字自定义构建，优先级高于[texts] 配置后，会忽略[texts],[textWidth],[iconTextGap] | -| color | List? | - | 评分图标的颜色，示例：[选中颜色] / [选中颜色，未选中颜色]，默认：[TTheme.of(context).warningColor5, TTheme.of(context).grayColor4] | +| builderText | Widget Function(BuildContext context, double value)? | - | 评分等级对应的辅助文字自定义构建，优先级高于`texts` 配置后，会忽略`texts`,`textWidth`,`iconTextGap` | +| color | List? | - | 评分图标的颜色，示例：`选中颜色` / `选中颜色，未选中颜色`，默认：`TTheme.of(context).warningColor5, TTheme.of(context).grayColor4` | | count | int? | 5 | 评分的数量 | | crossAxisAlignment | CrossAxisAlignment? | CrossAxisAlignment.center | 评分图标与辅助文字的交叉轴对齐方式 | | direction | Axis? | Axis.horizontal | 评分图标与辅助文字的布局方向 | | disabled | bool? | false | 是否禁用评分 | | gap | double? | - | 评分图标的间距，默认：TTheme.of(context).spacer8 | -| icon | List? | - | 自定义评分图标，[选中和未选中图标] / [选中图标，未选中图标]，默认：[TIcons.star_filled] | -| iconTextGap | double? | - | 评分图标与辅助文字的间距，默认：[TTheme.of(context).spacer16] | +| icon | List? | - | 自定义评分图标，`选中和未选中图标` / `选中图标，未选中图标`，默认：`TIcons.star_filled` | +| iconTextGap | double? | - | 评分图标与辅助文字的间距，默认：`TTheme.of(context).spacer16` | | key | Key? | - | 组件标识，用于区分或保留组件状态。 | | mainAxisAlignment | MainAxisAlignment? | MainAxisAlignment.start | 评分图标与辅助文字的主轴对齐方式 | | mainAxisSize | MainAxisSize? | MainAxisSize.min | 评分图标与辅助文字主轴方向上如何占用空间 | | onChange | void Function(double value)? | - | 评分数改变时触发 | -| placement | PlacementEnum? | PlacementEnum.top | 选择评分弹框的位置，值为[PlacementEnum.none]表示不显示评分弹框。 | +| placement | PlacementEnum? | PlacementEnum.top | 选择评分弹框的位置，值为`PlacementEnum.none`表示不显示评分弹框。 | | showText | bool? | false | 是否显示对应的辅助文字 | | size | double? | 24.0 | 评分图标的大小 | -| texts | List? | const ['极差', '失望', '一般', '满意', '惊喜'] | 评分等级对应的辅助文字， 当[allowHalf]为false时长度应与[count]一致， 当[allowHalf]为true时长度应为[count]的两倍， 自定义值示例：['1分', '2分', '3分', '4分', '5分']。 | +| texts | List? | const ['极差', '失望', '一般', '满意', '惊喜'] | 评分等级对应的辅助文字， 当`allowHalf`为false时长度应与`count`一致， 当`allowHalf`为true时长度应为`count`的两倍， 自定义值示例：`'1分', '2分', '3分', '4分', '5分'`。 | | textWidth | double? | 48.0 | 评分等级对应的辅助文字宽度 | | value | double? | 0 | 选择评分的值 | diff --git a/tdesign-component/example/assets/api/skeleton_api.md b/tdesign-component/example/assets/api/skeleton_api.md index 5b13db47b..88190e5ab 100644 --- a/tdesign-component/example/assets/api/skeleton_api.md +++ b/tdesign-component/example/assets/api/skeleton_api.md @@ -1,5 +1,19 @@ ## API ### TSkeleton + +#### 工厂构造方法 + +##### TSkeleton.fromRowCol + +从行列框架创建骨架屏 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| key | Key? | - | 组件标识，用于区分或保留组件状态。 | +| animation | TSkeletonAnimation? | - | 动画效果 | +| delay | int | 0 | 延迟显示加载时间 | +| rowCol | TSkeletonRowCol | - | 自定义行列数量、宽度高度、间距等 | + #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -16,21 +30,9 @@ | rowCol | TSkeletonRowCol | - | 自定义行列数量、宽度高度、间距等 | -#### 工厂构造方法 - -##### TSkeleton.fromRowCol - -从行列框架创建骨架屏 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| key | Key? | - | 组件标识，用于区分或保留组件状态。 | -| animation | TSkeletonAnimation? | - | 动画效果 | -| delay | int | 0 | 延迟显示加载时间 | -| rowCol | TSkeletonRowCol | - | 自定义行列数量、宽度高度、间距等 | - - ### TSkeletonRowColStyle +#### 简介 +骨架屏样式 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -39,6 +41,8 @@ ### TSkeletonRowCol +#### 简介 +骨架屏行列框架 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -48,13 +52,8 @@ ### TSkeletonRowColObjStyle -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| background | Color Function(BuildContext) | _defaultBackground | 背景颜色 | -| borderRadius | double Function(BuildContext) | _textBorderRadius | 圆角 | - +#### 简介 +骨架屏元素样式 #### 工厂构造方法 @@ -88,19 +87,18 @@ | --- | --- | --- | --- | | background | Color Function(BuildContext) | _defaultBackground | 背景颜色 | - -### TSkeletonRowColObj #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| flex | int? | 1 | 弹性因子 | -| height | double? | 16 | 高度 | -| margin | EdgeInsets | EdgeInsets.zero | 间距 | -| style | TSkeletonRowColObjStyle | const TSkeletonRowColObjStyle() | 样式 | -| width | double? | - | 宽度 | +| background | Color Function(BuildContext) | _defaultBackground | 背景颜色 | +| borderRadius | double Function(BuildContext) | _textBorderRadius | 圆角 | +### TSkeletonRowColObj +#### 简介 +骨架屏元素 + #### 工厂构造方法 ##### TSkeletonRowColObj.circle @@ -153,6 +151,16 @@ | margin | EdgeInsets | EdgeInsets.zero | 间距 | | style | TSkeletonRowColObjStyle | const TSkeletonRowColObjStyle.text() | 样式 | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| flex | int? | 1 | 弹性因子 | +| height | double? | 16 | 高度 | +| margin | EdgeInsets | EdgeInsets.zero | 间距 | +| style | TSkeletonRowColObjStyle | const TSkeletonRowColObjStyle() | 样式 | +| width | double? | - | 宽度 | + ### TSkeletonAnimation #### 简介 diff --git a/tdesign-component/example/assets/api/slider_api.md b/tdesign-component/example/assets/api/slider_api.md index e7ee4332e..e72b68a49 100644 --- a/tdesign-component/example/assets/api/slider_api.md +++ b/tdesign-component/example/assets/api/slider_api.md @@ -1,5 +1,7 @@ ## API ### TSlider +#### 简介 +单滑动选择器 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -18,6 +20,8 @@ ### TRangeSlider +#### 简介 +范围滑动选择器 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-component/example/assets/api/stepper_api.md b/tdesign-component/example/assets/api/stepper_api.md index 95debede2..4a82f9e7c 100644 --- a/tdesign-component/example/assets/api/stepper_api.md +++ b/tdesign-component/example/assets/api/stepper_api.md @@ -1,5 +1,7 @@ ## API ### TStepper +#### 简介 +步进器 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-component/example/assets/api/steps_api.md b/tdesign-component/example/assets/api/steps_api.md index 6cd49f650..ffca913fd 100644 --- a/tdesign-component/example/assets/api/steps_api.md +++ b/tdesign-component/example/assets/api/steps_api.md @@ -1,5 +1,7 @@ ## API ### TSteps +#### 简介 +Steps步骤条 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -15,6 +17,8 @@ ### TStepsItemData +#### 简介 +Steps步骤条数据类型 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-component/example/assets/api/swipe-cell_api.md b/tdesign-component/example/assets/api/swipe-cell_api.md index 5f6f0c9ca..b7c0d1d0b 100644 --- a/tdesign-component/example/assets/api/swipe-cell_api.md +++ b/tdesign-component/example/assets/api/swipe-cell_api.md @@ -2,34 +2,13 @@ ### TSwipeCell #### 简介 滑动单元格组件 -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| cell | Widget | - | 单元格 [TCell] | -| closeWhenOpened | bool? | true | 当同一组（[groupTag]）中的一个[TSwipeCell]打开时，是否关闭组中的所有其他[TSwipeCell] | -| closeWhenTapped | bool? | true | 当同一组（[groupTag]）中的一个[TSwipeCell]被点击时，是否应该关闭组中的所有[TSwipeCell] [cell]组件被点击时必须传递点击事件，执行`TSwipeCellInherited.of(context)?.cellClick()` | -| controller | SlidableController? | - | 自定义控制滑动窗口 | -| direction | Axis? | Axis.horizontal | 可拖动的方向 | -| disabled | bool? | false | 是否禁用滑动 | -| dragStartBehavior | DragStartBehavior? | DragStartBehavior.start | 处理拖动开始行为的方式[GestureDetector.dragStartBehavior] | -| duration | Duration? | const Duration(milliseconds: 200) | 打开关闭动画时长 | -| groupTag | Object? | - | 组，配置后，[closeWhenOpened]、[closeWhenTapped]才起作用 | -| key | Key? | - | 组件标识，用于区分或保留组件状态。 | -| left | TSwipeCellPanel? | - | 左侧滑动操作项面板 | -| onChange | Function(TSwipeDirection direction, bool open)? | - | 滑动展开事件 | -| opened | List? | const [false, false] | 默认打开，[left, right] | -| right | TSwipeCellPanel? | - | 右侧滑动操作项面板 | -| slidableKey | Key? | - | 滑动组件的 Key | - #### 静态方法 ##### TSwipeCell.close -根据[groupTag]关闭[TSwipeCell] - - current：保留当前不关闭 +根据`groupTag`关闭`TSwipeCell` +current：保留当前不关闭 返回类型：`void` @@ -41,7 +20,7 @@ ##### TSwipeCell.of -获取上下文最近的[controller] +获取上下文最近的`controller` 返回类型：`SlidableController?` @@ -49,6 +28,26 @@ | --- | --- | --- | --- | | context | BuildContext | - | - | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| cell | Widget | - | 单元格 `TCell` | +| closeWhenOpened | bool? | true | 当同一组（`groupTag`）中的一个`TSwipeCell`打开时，是否关闭组中的所有其他`TSwipeCell` | +| closeWhenTapped | bool? | true | 当同一组（`groupTag`）中的一个`TSwipeCell`被点击时，是否应该关闭组中的所有`TSwipeCell` `cell`组件被点击时必须传递点击事件，执行`TSwipeCellInherited.of(context)?.cellClick()` | +| controller | SlidableController? | - | 自定义控制滑动窗口 | +| direction | Axis? | Axis.horizontal | 可拖动的方向 | +| disabled | bool? | false | 是否禁用滑动 | +| dragStartBehavior | DragStartBehavior? | DragStartBehavior.start | 处理拖动开始行为的方式`GestureDetector.dragStartBehavior` | +| duration | Duration? | const Duration(milliseconds: 200) | 打开关闭动画时长 | +| groupTag | Object? | - | 组，配置后，`closeWhenOpened`、`closeWhenTapped`才起作用 | +| key | Key? | - | 组件标识，用于区分或保留组件状态。 | +| left | TSwipeCellPanel? | - | 左侧滑动操作项面板 | +| onChange | Function(TSwipeDirection direction, bool open)? | - | 滑动展开事件 | +| opened | List? | const [false, false] | 默认打开，`left, right` | +| right | TSwipeCellPanel? | - | 右侧滑动操作项面板 | +| slidableKey | Key? | - | 滑动组件的 Key | + ### TSwipeDirection #### 枚举值 diff --git a/tdesign-component/example/assets/api/swiper_api.md b/tdesign-component/example/assets/api/swiper_api.md index a6b8650eb..57680e43f 100644 --- a/tdesign-component/example/assets/api/swiper_api.md +++ b/tdesign-component/example/assets/api/swiper_api.md @@ -24,14 +24,6 @@ TDesign风格的Swiper指示器样式，与flutter_swiper的Swiper结合使用 ### TPageTransformer #### 简介 TD默认PageTransformer -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| fade | double? | - | 淡化比例 | -| margin | double? | - | 左右间隔 | -| scale | double? | - | 缩放比例 | - #### 工厂构造方法 @@ -52,3 +44,11 @@ TD默认PageTransformer | --- | --- | --- | --- | | fade | double? | 1 | 淡化比例 | | scale | double? | 0.8 | 缩放比例 | + +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| fade | double? | - | 淡化比例 | +| margin | double? | - | 左右间隔 | +| scale | double? | - | 缩放比例 | diff --git a/tdesign-component/example/assets/api/tab-bar_api.md b/tdesign-component/example/assets/api/tab-bar_api.md index 84af968b6..89d7fffdb 100644 --- a/tdesign-component/example/assets/api/tab-bar_api.md +++ b/tdesign-component/example/assets/api/tab-bar_api.md @@ -30,6 +30,8 @@ ### BadgeConfig +#### 简介 +飘新配置 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -41,6 +43,8 @@ ### TBottomTabBarTabConfig +#### 简介 +单个 tab 配置 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -58,6 +62,8 @@ ### TBottomTabBarPopUpBtnConfig +#### 简介 +展开项配置 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -68,6 +74,8 @@ ### TBottomTabBarPopUpShapeConfig +#### 简介 +弹窗UI配置 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -81,6 +89,8 @@ ### PopUpMenuItem +#### 简介 +弹窗菜单item #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-component/example/assets/api/table_api.md b/tdesign-component/example/assets/api/table_api.md index b5b15b344..2fc78caca 100644 --- a/tdesign-component/example/assets/api/table_api.md +++ b/tdesign-component/example/assets/api/table_api.md @@ -26,6 +26,8 @@ ### TTableCol +#### 简介 +表格列配置 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -45,6 +47,8 @@ ### TTableEmpty +#### 简介 +空数据状态 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -75,49 +79,49 @@ | right | - | -### SelectableFunc +### OnCellTap #### 类型定义 ```dart -typedef SelectableFunc = bool Function(int index, dynamic row); +typedef OnCellTap = void Function(int rowIndex, dynamic row, TTableCol col); ``` -### RowCheckFunc +### OnScroll #### 类型定义 ```dart -typedef RowCheckFunc = bool Function(int index, dynamic row); +typedef OnScroll = void Function(ScrollController controller); ``` -### OnCellTap +### OnSelect #### 类型定义 ```dart -typedef OnCellTap = void Function(int rowIndex, dynamic row, TTableCol col); +typedef OnSelect = void Function(List? data); ``` -### OnScroll +### OnRowSelect #### 类型定义 ```dart -typedef OnScroll = void Function(ScrollController controller); +typedef OnRowSelect = void Function(int index, bool checked); ``` -### OnSelect +### SelectableFunc #### 类型定义 ```dart -typedef OnSelect = void Function(List? data); +typedef SelectableFunc = bool Function(int index, dynamic row); ``` -### OnRowSelect +### RowCheckFunc #### 类型定义 ```dart -typedef OnRowSelect = void Function(int index, bool checked); +typedef RowCheckFunc = bool Function(int index, dynamic row); ``` diff --git a/tdesign-component/example/assets/api/tabs_api.md b/tdesign-component/example/assets/api/tabs_api.md index 2bddc3c38..e08a02ced 100644 --- a/tdesign-component/example/assets/api/tabs_api.md +++ b/tdesign-component/example/assets/api/tabs_api.md @@ -63,28 +63,28 @@ | key | Key? | - | 组件标识，用于区分或保留组件状态。 | -### TTabSize +### TTabBarOutlineType #### 枚举值 | 名称 | 说明 | | --- | --- | -| large | - | -| small | - | +| filled | 填充样式 | +| capsule | 胶囊样式 | +| card | 卡片 | -### TTabOutlineType +### TTabSize #### 枚举值 | 名称 | 说明 | | --- | --- | -| filled | 填充样式 | -| capsule | 胶囊样式 | -| card | 卡片 | +| large | - | +| small | - | -### TTabBarOutlineType +### TTabOutlineType #### 枚举值 diff --git a/tdesign-component/example/assets/api/tag_api.md b/tdesign-component/example/assets/api/tag_api.md index 35b04aeab..d147830e3 100644 --- a/tdesign-component/example/assets/api/tag_api.md +++ b/tdesign-component/example/assets/api/tag_api.md @@ -1,5 +1,8 @@ ## API ### TTag +#### 简介 +展示型标签组件，仅展示，内部不可更改自身状态 +支持样式：方形/圆角/半圆/带关闭图标 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -28,6 +31,9 @@ ### TSelectTag +#### 简介 +点击型标签组件，点击时内部更改自身状态 +支持样式：方形/圆角/半圆/带关闭图标 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -55,25 +61,8 @@ ### TTagStyle -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| backgroundColor | Color? | - | 背景颜色 | -| border | double | 0 | 线框粗细 | -| borderColor | Color? | - | 边框颜色 | -| borderRadius | BorderRadiusGeometry? | - | 圆角 | -| context | BuildContext? | - | 上下文，方便获取主题内容 | -| font | Font? | - | 字体尺寸 | -| fontWeight | FontWeight? | - | 字体粗细 | -| textColor | Color? | - | 文字颜色 | - -#### 公开属性 - -| 属性 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| closeIconColor | Color? | - | 关闭图标颜色 | - +#### 简介 +标签样式 #### 工厂构造方法 @@ -112,6 +101,25 @@ | light | bool | - | - | | shape | TTagShape | - | - | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| backgroundColor | Color? | - | 背景颜色 | +| border | double | 0 | 线框粗细 | +| borderColor | Color? | - | 边框颜色 | +| borderRadius | BorderRadiusGeometry? | - | 圆角 | +| context | BuildContext? | - | 上下文，方便获取主题内容 | +| font | Font? | - | 字体尺寸 | +| fontWeight | FontWeight? | - | 字体粗细 | +| textColor | Color? | - | 文字颜色 | + +#### 公开属性 + +| 属性 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| closeIconColor | Color? | - | 关闭图标颜色 | + ### TTagTheme #### 简介 diff --git a/tdesign-component/example/assets/api/text_api.md b/tdesign-component/example/assets/api/text_api.md index 07aaf746c..aa2b9463c 100644 --- a/tdesign-component/example/assets/api/text_api.md +++ b/tdesign-component/example/assets/api/text_api.md @@ -1,41 +1,26 @@ ## API ### TText -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| data | - | - | 以下系统 text 属性，释义请参考系统 [Text] 中注释 | -| backgroundColor | Color? | - | 背景颜色 | -| font | Font? | - | 字体尺寸，包含 大小size 和 行高height | -| fontFamily | FontFamily? | - | 字体ttf | -| fontFamilyUrl | String? | - | 是否禁用懒加载 FontFamily 的能力 | -| fontWeight | FontWeight? | - | 字体粗细 | -| forceVerticalCenter | bool | false | 是否强制居中 | -| isInFontLoader | bool | false | 是否在 FontLoader 中使用 | -| isTextThrough | bool? | false | 是否是横线穿过样式（删除线） | -| key | Key? | - | 组件标识，用于区分或保留组件状态。 | -| lineThroughColor | Color? | - | 删除线颜色，对应 TestStyle 的 decorationColor | -| locale | Locale? | - | - | -| maxLines | int? | - | - | -| overflow | TextOverflow? | - | - | -| package | String? | - | 字体包名 | -| semanticsLabel | String? | - | - | -| softWrap | bool? | - | - | -| strutStyle | StrutStyle? | - | - | -| style | TextStyle? | - | 自定义的 TextStyle，其中指定的属性，将覆盖扩展的外层属性 | -| textAlign | TextAlign? | - | - | -| textColor | Color? | - | 文本颜色 | -| textDirection | TextDirection? | - | - | -| textHeightBehavior | ui.TextHeightBehavior? | - | - | -| textScaleFactor | double? | - | - | -| textWidthBasis | TextWidthBasis? | - | - | - -#### 公开属性 - -| 属性 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| textSpan | InlineSpan? | - | - | - +#### 简介 +文本控件 +设计原则： +1. 为了使用更方便，所以对系统组件进行的扩展，需兼容系统控件所有功能，不能让用户使用 TDesign 时，因不能满足系统功能而弃用。 +2. 非系统已有属性，尽量添加注释 +需求：把一部分在 TextStyle 中的属性扁平化，放到外层。 +1. 暴露系统的所有属性，支持系统所有操作 +2. 约束使用主题配置的几种字体 +3. 提供转换为系统 Text 的方法，以使某些系统组件指定接收系统 Text 时可使用。（Image 组件同理） +4. 支持自定义 TextStyle +5. 兼容 TextSpan 形式 +技巧： +命名参数替换属性的正则： +第一步，把 Text 中的可选参数拷贝过来，变成如下格式： +Text(data, +this.style, +this.strutStyle, +……) +第二步，正则替换如下： +匹配(前半有默认值，后半无默认值)：this\.(`a-z|A-Z`+)[]*`\=`+[]*`a-z|A-Z`+\,|this\.(`a-z|A-Z`+)\, +替换：$1$2: this.$1$2, #### 工厂构造方法 @@ -71,8 +56,46 @@ | isInFontLoader | bool | false | 是否在 FontLoader 中使用 | | fontFamilyUrl | String? | - | 是否禁用懒加载 FontFamily 的能力 | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| data | - | - | 以下系统 text 属性，释义请参考系统 `Text` 中注释 | +| backgroundColor | Color? | - | 背景颜色 | +| font | Font? | - | 字体尺寸，包含 大小size 和 行高height | +| fontFamily | FontFamily? | - | 字体ttf | +| fontFamilyUrl | String? | - | 是否禁用懒加载 FontFamily 的能力 | +| fontWeight | FontWeight? | - | 字体粗细 | +| forceVerticalCenter | bool | false | 是否强制居中 | +| isInFontLoader | bool | false | 是否在 FontLoader 中使用 | +| isTextThrough | bool? | false | 是否是横线穿过样式（删除线） | +| key | Key? | - | 组件标识，用于区分或保留组件状态。 | +| lineThroughColor | Color? | - | 删除线颜色，对应 TestStyle 的 decorationColor | +| locale | Locale? | - | - | +| maxLines | int? | - | - | +| overflow | TextOverflow? | - | - | +| package | String? | - | 字体包名 | +| semanticsLabel | String? | - | - | +| softWrap | bool? | - | - | +| strutStyle | StrutStyle? | - | - | +| style | TextStyle? | - | 自定义的 TextStyle，其中指定的属性，将覆盖扩展的外层属性 | +| textAlign | TextAlign? | - | - | +| textColor | Color? | - | 文本颜色 | +| textDirection | TextDirection? | - | - | +| textHeightBehavior | ui.TextHeightBehavior? | - | - | +| textScaleFactor | double? | - | - | +| textWidthBasis | TextWidthBasis? | - | - | + +#### 公开属性 + +| 属性 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| textSpan | InlineSpan? | - | - | + ### TTextSpan +#### 简介 +TextSpan 的 TDesign 扩展，将部分 TextStyle 中的参数扁平化。 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -96,6 +119,8 @@ ### TTextConfiguration +#### 简介 +存储可以自定义 TText 居中算法数据的内部控件 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-component/example/assets/api/textarea_api.md b/tdesign-component/example/assets/api/textarea_api.md index 0414512df..f4bc3d97d 100644 --- a/tdesign-component/example/assets/api/textarea_api.md +++ b/tdesign-component/example/assets/api/textarea_api.md @@ -8,9 +8,9 @@ | --- | --- | --- | --- | | additionInfo | String? | '' | 错误提示信息 | | additionInfoColor | Color? | - | 错误提示颜色 | -| allowInputOverMax | bool? | false | 超出[maxLength]之后是否还允许输入 | +| allowInputOverMax | bool? | false | 超出`maxLength`之后是否还允许输入 | | autofocus | bool? | false | 是否自动获取焦点 | -| autosize | bool? | - | 是否自动增高，值为 true 时，[maxLines]不生效 | +| autosize | bool? | - | 是否自动增高，值为 true 时，`maxLines`不生效 | | backgroundColor | Color? | - | 输入框背景色 | | bordered | bool? | - | 是否显示外边框 | | controller | TextEditingController? | - | controller 用户获取或者赋值输入内容 | diff --git a/tdesign-component/example/assets/api/theme_api.md b/tdesign-component/example/assets/api/theme_api.md index 922b3d8be..472df87e9 100644 --- a/tdesign-component/example/assets/api/theme_api.md +++ b/tdesign-component/example/assets/api/theme_api.md @@ -1,14 +1,7 @@ ## API ### TTheme -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| child | Widget | - | 子控件 | -| data | TThemeData | - | 主题数据 | -| key | Key? | - | 组件标识，用于区分或保留组件状态。 | -| systemData | ThemeData? | - | Flutter系统主题数据 | - +#### 简介 +主题控件 #### 静态方法 @@ -32,7 +25,7 @@ ##### TTheme.of 获取主题数据，如果未传context则获取全局唯一的默认数据, - 传了context，则获取最近的主题，取不到则会获取全局唯一默认数据 +传了context，则获取最近的主题，取不到则会获取全局唯一默认数据 返回类型：`TThemeData` @@ -44,7 +37,7 @@ ##### TTheme.ofNullable 获取主题数据，取不到则可空 - 传了context，则获取最近的主题，取不到或未传context则返回null, +传了context，则获取最近的主题，取不到或未传context则返回null, 返回类型：`TThemeData?` @@ -56,8 +49,8 @@ ##### TTheme.setResourceBuilder 设置资源代理, - needAlwaysBuild=true:每次都会走build方法;如果全局有多个Delegate,需要区分情况去获取,则可以设置needAlwaysBuild为true,业务自己判断返回哪个delegate - needAlwaysBuild=false:返回delegate为null,则每次都会走build方法,返回了 +needAlwaysBuild=true:每次都会走build方法;如果全局有多个Delegate,需要区分情况去获取,则可以设置needAlwaysBuild为true,业务自己判断返回哪个delegate +needAlwaysBuild=false:返回delegate为null,则每次都会走build方法,返回了 返回类型：`void` @@ -66,29 +59,19 @@ | delegate | TResourceBuilder | - | - | | needAlwaysBuild | bool | false | - | - -### TThemeData #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| colorMap | TMap | - | 颜色 | -| extraThemeData | TExtraThemeData? | - | 额外定义的结构 | -| fontFamilyMap | TMap | - | 字体样式 | -| fontMap | TMap | - | 字体尺寸 | -| name | String | - | 名称 | -| radiusMap | TMap | - | 圆角 | -| refMap | TMap | - | 映射关系 | -| shadowMap | TMap> | - | 阴影 | -| spacerMap | TMap | - | 间隔 | - -#### 公开属性 +| child | Widget | - | 子控件 | +| data | TThemeData | - | 主题数据 | +| key | Key? | - | 组件标识，用于区分或保留组件状态。 | +| systemData | ThemeData? | - | Flutter系统主题数据 | -| 属性 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| dark | TThemeData? | - | 暗色主题 | -| light | TThemeData | - | 亮色主题 | +### TThemeData +#### 简介 +主题数据 #### 静态方法 @@ -107,23 +90,15 @@ 解析配置的json文件为主题数据 - [name] 主题名称，目前只支持一级键 - - [themeJson] 主题json字符串，要求json配置必须正确 - - [recoverDefault] 是否恢复为默认主题数据 - - [extraThemeData] 额外扩展的主题数据 - 返回类型：`TThemeData?` | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| name | String | - | 名称 | -| themeJson | String | - | - | +| name | String | - | 主题名称，目前只支持一级键 | +| themeJson | String | - | 主题json字符串，要求json配置必须正确 | | darkName | String? | - | - | -| recoverDefault | - | false | - | -| extraThemeData | TExtraThemeData? | - | 额外定义的结构 | +| recoverDefault | - | false | 是否恢复为默认主题数据 | +| extraThemeData | TExtraThemeData? | - | 额外扩展的主题数据 | ##### TThemeData.parseThemeData @@ -136,6 +111,27 @@ | themeConfig | - | - | - | | extraThemeData | TExtraThemeData? | - | 额外定义的结构 | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| colorMap | TMap | - | 颜色 | +| extraThemeData | TExtraThemeData? | - | 额外定义的结构 | +| fontFamilyMap | TMap | - | 字体样式 | +| fontMap | TMap | - | 字体尺寸 | +| name | String | - | 名称 | +| radiusMap | TMap | - | 圆角 | +| refMap | TMap | - | 映射关系 | +| shadowMap | TMap> | - | 阴影 | +| spacerMap | TMap | - | 间隔 | + +#### 公开属性 + +| 属性 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| dark | TThemeData? | - | 暗色主题 | +| light | TThemeData | - | 亮色主题 | + ### DefaultMapFactory #### 类型定义 diff --git a/tdesign-component/example/assets/api/time-counter_api.md b/tdesign-component/example/assets/api/time-counter_api.md index 5c81242ea..600cc64db 100644 --- a/tdesign-component/example/assets/api/time-counter_api.md +++ b/tdesign-component/example/assets/api/time-counter_api.md @@ -29,6 +29,20 @@ ### TTimeCounterStyle #### 简介 计时组件样式 + +#### 工厂构造方法 + +##### TTimeCounterStyle.generateStyle + +生成默认样式 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| context | BuildContext | - | - | +| size | TTimeCounterSize? | - | - | +| theme | TTimeCounterTheme? | - | - | +| splitWithUnit | bool? | - | - | + #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -50,35 +64,6 @@ | timeWidth | double? | - | 时间容器宽度 | -#### 工厂构造方法 - -##### TTimeCounterStyle.generateStyle - -生成默认样式 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| context | BuildContext | - | - | -| size | TTimeCounterSize? | - | - | -| theme | TTimeCounterTheme? | - | - | -| splitWithUnit | bool? | - | - | - - -### TTimeCounterStatus -#### 简介 -计时组件控制器转态 -#### 枚举值 - - -| 名称 | 说明 | -| --- | --- | -| start | 开始 | -| pause | 暂停 | -| resume | 继续 | -| reset | 重置 | -| idle | 空，默认值 | - - ### TTimeCounterDirection #### 简介 计时组件计时方向 @@ -115,3 +100,18 @@ | defaultTheme | 默认 | | round | 圆形 | | square | 方形 | + + +### TTimeCounterStatus +#### 简介 +计时组件控制器转态 +#### 枚举值 + + +| 名称 | 说明 | +| --- | --- | +| start | 开始 | +| pause | 暂停 | +| resume | 继续 | +| reset | 重置 | +| idle | 空，默认值 | diff --git a/tdesign-component/example/assets/api/toast_api.md b/tdesign-component/example/assets/api/toast_api.md index f0699ef24..00197d341 100644 --- a/tdesign-component/example/assets/api/toast_api.md +++ b/tdesign-component/example/assets/api/toast_api.md @@ -1,5 +1,7 @@ ## API ### TToast +#### 简介 +改进的Toast组件，支持多个实例和独立样式 #### 静态方法 diff --git a/tdesign-component/lib/src/components/popup/_popup_layout.dart b/tdesign-component/lib/src/components/popup/_popup_layout.dart index d55207c02..6ac769eac 100644 --- a/tdesign-component/lib/src/components/popup/_popup_layout.dart +++ b/tdesign-component/lib/src/components/popup/_popup_layout.dart @@ -16,15 +16,18 @@ class PopupLayout { static const double defaultDrawerWidth = 280; - Widget wrapPositioned({required Widget child}) { + Widget wrapPositioned({ + required Widget child, + EdgeInsets safePadding = EdgeInsets.zero, + }) { switch (placement) { case TPopupPlacement.top: final inset = this.inset is TPopupTopInset ? this.inset as TPopupTopInset : null; return Positioned( - top: 0, - left: inset?.left ?? 0, - right: inset?.right ?? 0, + top: safePadding.top, + left: (inset?.left ?? 0) + safePadding.left, + right: (inset?.right ?? 0) + safePadding.right, height: height, child: child, ); @@ -35,17 +38,17 @@ class PopupLayout { final bottomHeight = _bottomHeight(); if (bottomHeight != null) { return Positioned( - left: inset?.left ?? 0, - right: inset?.right ?? 0, - bottom: 0, + left: (inset?.left ?? 0) + safePadding.left, + right: (inset?.right ?? 0) + safePadding.right, + bottom: safePadding.bottom, height: bottomHeight, child: child, ); } return Positioned( - left: inset?.left ?? 0, - right: inset?.right ?? 0, - bottom: 0, + left: (inset?.left ?? 0) + safePadding.left, + right: (inset?.right ?? 0) + safePadding.right, + bottom: safePadding.bottom, child: child, ); case TPopupPlacement.left: @@ -53,9 +56,9 @@ class PopupLayout { ? this.inset as TPopupLeftInset : null; return Positioned( - top: inset?.top ?? 0, - bottom: inset?.bottom ?? 0, - left: 0, + top: (inset?.top ?? 0) + safePadding.top, + bottom: (inset?.bottom ?? 0) + safePadding.bottom, + left: safePadding.left, width: width ?? defaultDrawerWidth, child: child, ); @@ -64,9 +67,9 @@ class PopupLayout { ? this.inset as TPopupRightInset : null; return Positioned( - top: inset?.top ?? 0, - bottom: inset?.bottom ?? 0, - right: 0, + top: (inset?.top ?? 0) + safePadding.top, + bottom: (inset?.bottom ?? 0) + safePadding.bottom, + right: safePadding.right, width: width ?? defaultDrawerWidth, child: child, ); @@ -77,6 +80,38 @@ class PopupLayout { } } + /// 按 [placement] 从 [MediaQuery.padding] 提取需避让的安全区内边距。 + static EdgeInsets safePaddingFor( + TPopupPlacement placement, + EdgeInsets mediaPadding, + bool useSafeArea, + ) { + if (!useSafeArea) { + return EdgeInsets.zero; + } + switch (placement) { + case TPopupPlacement.top: + return EdgeInsets.only(top: mediaPadding.top); + case TPopupPlacement.bottom: + return EdgeInsets.only(bottom: mediaPadding.bottom); + case TPopupPlacement.left: + return EdgeInsets.only( + left: mediaPadding.left, + top: mediaPadding.top, + bottom: mediaPadding.bottom, + ); + case TPopupPlacement.right: + return EdgeInsets.only( + right: mediaPadding.right, + top: mediaPadding.top, + bottom: mediaPadding.bottom, + ); + case TPopupPlacement.center: + // center 不参与贴边避让，由面板尺寸自然落在可视区中部。 + return EdgeInsets.zero; + } + } + double? _bottomHeight() { if (height != null) { return height; diff --git a/tdesign-component/lib/src/components/popup/_popup_route.dart b/tdesign-component/lib/src/components/popup/_popup_route.dart index 1efb0b507..b194c8c65 100644 --- a/tdesign-component/lib/src/components/popup/_popup_route.dart +++ b/tdesign-component/lib/src/components/popup/_popup_route.dart @@ -128,7 +128,7 @@ class _PopupNavigatorRoute extends PopupRoute { ); final t = curved.value; - final shell = PopupShell( + final panel = PopupShell( options: options, onCloseWithTrigger: onCloseWithTrigger, ); @@ -138,16 +138,24 @@ class _PopupNavigatorRoute extends PopupRoute { popupContent = Transform.scale( scale: t, alignment: Alignment.center, - child: shell, + child: panel, ); } else { popupContent = FractionalTranslation( translation: _layout.slideOffset(t), - child: shell, + child: panel, ); } - final positioned = _layout.wrapPositioned(child: popupContent); + final safePadding = PopupLayout.safePaddingFor( + options.placement, + MediaQuery.paddingOf(context), + options.useSafeArea, + ); + final positioned = _layout.wrapPositioned( + child: popupContent, + safePadding: safePadding, + ); final barrier = _buildBarrier(context, t); diff --git a/tdesign-component/lib/src/components/popup/t_popup.dart b/tdesign-component/lib/src/components/popup/t_popup.dart index 4d175352d..b0b088384 100644 --- a/tdesign-component/lib/src/components/popup/t_popup.dart +++ b/tdesign-component/lib/src/components/popup/t_popup.dart @@ -54,19 +54,14 @@ part 't_popup_types.dart'; final class TPopup { const TPopup._(); - /// 打开浮层并压入独立 [PopupRoute]。 - /// - /// [context] 用于查找 [Navigator] 并展示浮层。 - /// - /// [options] 浮层配置；方向固定时推荐 [TPopupOptions.bottom] 等命名工厂。 - /// - /// 返回 [TPopupHandle]，可用 [TPopupHandle.close]、[TPopupHandle.open]、 - /// [TPopupHandle.isShowing] 控制与查询。 - /// 重复调用会继续 push 新的浮层；若需互斥请在业务层管理。 - /// - /// [navigatorContext] 可选，指定承载浮层的 [Navigator] 的 context，默认 [context]。 + /// 打开浮层并压入 [PopupRoute]，返回 [TPopupHandle] 用于关闭/再次打开。 /// + /// [context] 用于查找并展示 [Navigator]。 + /// [options] 浮层配置；方向固定时建议 [TPopupOptions.bottom] 等命名工厂。 + /// [navigatorContext] 可选，指定承载浮层的 [Navigator] context，默认 [context]。 /// [useRootNavigator] 为 true 时使用根 [Navigator]（嵌套导航场景）。 + /// + /// 连续调用会重复 push 新路由；互斥展示请在业务层自行管理。 static TPopupHandle show( BuildContext context, { required TPopupOptions options, diff --git a/tdesign-component/lib/src/components/popup/t_popup_handle.dart b/tdesign-component/lib/src/components/popup/t_popup_handle.dart index f64a9bace..743b28623 100644 --- a/tdesign-component/lib/src/components/popup/t_popup_handle.dart +++ b/tdesign-component/lib/src/components/popup/t_popup_handle.dart @@ -36,15 +36,10 @@ class TPopupHandle { /// 浮层是否仍在展示（路由在栈中且未进入关闭流程）。 bool get isShowing => _route != null && !_isClosed; - /// 打开或重新打开浮层。 + /// 打开或重新打开浮层；已展示时无副作用。 /// - /// [context] 可选。首次调用须能解析 [Navigator]（传入 [context] 或依赖 - /// [navigatorContext]）；后续可省略，优先复用缓存的 [NavigatorState]。 - /// - /// 已展示时调用无副作用。Navigator 已销毁且未提供新 [context] 时，debug 下 assert， - /// release 下静默返回。 - /// - /// 配置非法时会直接抛出 [FlutterError]，debug / release 行为一致。 + /// [context] 可选：首次须能解析 [Navigator]，后续可省略并复用缓存。 + /// 配置非法时抛出 [FlutterError]。 void open([BuildContext? context]) { if (isShowing) { return; @@ -108,11 +103,7 @@ class TPopupHandle { }); } - /// 关闭当前展示的浮层；[TPopupOptions.onVisibleChange] 的 [TPopupTrigger] 为 - /// [TPopupTrigger.api]。 - /// - /// 已关闭或未展示时调用无副作用。 - /// 嵌套浮层场景下会关闭当前 handle 对应的那一层，而不会误关栈顶其它浮层。 + /// 关闭当前 handle 对应浮层，触发源为 [TPopupTrigger.api]；未展示时无副作用。 void close() { final route = _route; final navigator = route?.navigator ?? _lastNavigator; diff --git a/tdesign-component/lib/src/components/popup/t_popup_inset.dart b/tdesign-component/lib/src/components/popup/t_popup_inset.dart index 388564acd..28641436f 100644 --- a/tdesign-component/lib/src/components/popup/t_popup_inset.dart +++ b/tdesign-component/lib/src/components/popup/t_popup_inset.dart @@ -5,7 +5,7 @@ abstract class TPopupInset { const TPopupInset(); } -/// bottom 方向的左右留白。 +/// [TPopupPlacement.bottom] 的 [TPopupOptions.inset]：内容区相对屏幕左右的留白。 class TPopupBottomInset extends TPopupInset { const TPopupBottomInset({ this.left = 0, @@ -16,7 +16,7 @@ class TPopupBottomInset extends TPopupInset { final double right; } -/// top 方向的左右留白。 +/// [TPopupPlacement.top] 的 [TPopupOptions.inset]：内容区相对屏幕左右的留白。 class TPopupTopInset extends TPopupInset { const TPopupTopInset({ this.left = 0, @@ -27,7 +27,7 @@ class TPopupTopInset extends TPopupInset { final double right; } -/// left 方向的上下留白。 +/// [TPopupPlacement.left] 的 [TPopupOptions.inset]：内容区相对屏幕上下的留白。 class TPopupLeftInset extends TPopupInset { const TPopupLeftInset({ this.top = 0, @@ -38,7 +38,7 @@ class TPopupLeftInset extends TPopupInset { final double bottom; } -/// right 方向的上下留白。 +/// [TPopupPlacement.right] 的 [TPopupOptions.inset]：内容区相对屏幕上下的留白。 class TPopupRightInset extends TPopupInset { const TPopupRightInset({ this.top = 0, diff --git a/tdesign-component/lib/src/components/popup/t_popup_options.dart b/tdesign-component/lib/src/components/popup/t_popup_options.dart index c64623ef0..f99f6239e 100644 --- a/tdesign-component/lib/src/components/popup/t_popup_options.dart +++ b/tdesign-component/lib/src/components/popup/t_popup_options.dart @@ -27,6 +27,8 @@ Never _throwPopupOptionsValidationError(String error) { /// | [TPopupPlacement.top] | — | [height]、[inset] | /// | [TPopupPlacement.left]、[TPopupPlacement.right] | — | [width]、[inset] | /// +/// [inset] 须为与 [placement] 匹配的类型（如 bottom 用 [TPopupBottomInset]），否则校验失败。 +/// /// ## Builder 三态（[headerBuilder]、[cancelBuilder]、[confirmBuilder]、[closeBuilder]） /// /// | 传参方式 | 效果 | @@ -38,6 +40,19 @@ Never _throwPopupOptionsValidationError(String error) { /// [titleWidget] 默认为 `null`，表示无标题内容。 /// /// 生命周期回调见 [onOpen]、[onOpened]、[onClose]、[onClosed]、[onVisibleChange]、[onOverlayClick]。 +/// +/// ## modal 与 showOverlay 组合 +/// +/// | modal | showOverlay | 表现 | +/// |-------|-------------|------| +/// | true | true | 标准模态弹层（半透明蒙层 + 阻断背景） | +/// | true | false | 透明模态弹层（无可见蒙层，仍阻断背景） | +/// | false | false | 非模态浮层（不阻断背景） | +/// +/// ## closeOnOverlayClick +/// +/// 构造参数类型为 `bool?`。省略（`null`）时按 [showOverlay] 推导：有蒙层为 true，无蒙层为 false。 +/// 通过 [closeOnOverlayClick] getter 读取解析后的 `bool` 值。 class TPopupOptions { /// 通用构造；[placement] 在运行时才能确定时使用。 /// @@ -68,12 +83,10 @@ class TPopupOptions { this.onClosed, this.onVisibleChange, this.onOverlayClick, + this.useSafeArea = true, }) : _closeOnOverlayClick = closeOnOverlayClick; - /// 创建 [TPopupPlacement.bottom] 配置。 - /// - /// 固定 [placement] 为 [TPopupPlacement.bottom]；默认带内置头部。 - /// 蒙层、动画、生命周期等字段语义见同名成员文档。 + /// 创建 bottom 配置：固定 [placement]，默认内置头部，其余字段见成员文档。 factory TPopupOptions.bottom({ required Widget child, double? height, @@ -97,6 +110,7 @@ class TPopupOptions { VoidCallback? onClosed, TPopupVisibleChangeCallback? onVisibleChange, VoidCallback? onOverlayClick, + bool useSafeArea = true, }) => TPopupOptions( child: child, @@ -122,11 +136,10 @@ class TPopupOptions { onClosed: onClosed, onVisibleChange: onVisibleChange, onOverlayClick: onOverlayClick, + useSafeArea: useSafeArea, ); - /// 创建 [TPopupPlacement.center] 配置。 - /// - /// 固定 [placement] 为 [TPopupPlacement.center]；默认展示面板外下方圆形关闭按钮。 + /// 创建 center 配置：固定 [placement]，默认面板外下方圆形关闭按钮。 factory TPopupOptions.center({ required Widget child, double? width, @@ -147,6 +160,7 @@ class TPopupOptions { VoidCallback? onClosed, TPopupVisibleChangeCallback? onVisibleChange, VoidCallback? onOverlayClick, + bool useSafeArea = true, }) => TPopupOptions( child: child, @@ -169,11 +183,10 @@ class TPopupOptions { onClosed: onClosed, onVisibleChange: onVisibleChange, onOverlayClick: onOverlayClick, + useSafeArea: useSafeArea, ); - /// 创建 [TPopupPlacement.top] 配置。 - /// - /// 固定 [placement] 为 [TPopupPlacement.top]；无内置头部。 + /// 创建 top 配置：固定 [placement]，无内置头部。 factory TPopupOptions.top({ required Widget child, double? height, @@ -193,6 +206,7 @@ class TPopupOptions { VoidCallback? onClosed, TPopupVisibleChangeCallback? onVisibleChange, VoidCallback? onOverlayClick, + bool useSafeArea = true, }) => TPopupOptions( child: child, @@ -214,11 +228,10 @@ class TPopupOptions { onClosed: onClosed, onVisibleChange: onVisibleChange, onOverlayClick: onOverlayClick, + useSafeArea: useSafeArea, ); - /// 创建 [TPopupPlacement.left] 配置。 - /// - /// 固定 [placement] 为 [TPopupPlacement.left]；未传 [width] 时布局默认宽度 280。 + /// 创建 left 配置：固定 [placement]，未传 [width] 时默认 280。 factory TPopupOptions.left({ required Widget child, double? width, @@ -238,6 +251,7 @@ class TPopupOptions { VoidCallback? onClosed, TPopupVisibleChangeCallback? onVisibleChange, VoidCallback? onOverlayClick, + bool useSafeArea = true, }) => TPopupOptions( child: child, @@ -259,11 +273,10 @@ class TPopupOptions { onClosed: onClosed, onVisibleChange: onVisibleChange, onOverlayClick: onOverlayClick, + useSafeArea: useSafeArea, ); - /// 创建 [TPopupPlacement.right] 配置。 - /// - /// 固定 [placement] 为 [TPopupPlacement.right]；未传 [width] 时布局默认宽度 280。 + /// 创建 right 配置：固定 [placement]，未传 [width] 时默认 280。 factory TPopupOptions.right({ required Widget child, double? width, @@ -283,6 +296,7 @@ class TPopupOptions { VoidCallback? onClosed, TPopupVisibleChangeCallback? onVisibleChange, VoidCallback? onOverlayClick, + bool useSafeArea = true, }) => TPopupOptions( child: child, @@ -304,27 +318,22 @@ class TPopupOptions { onClosed: onClosed, onVisibleChange: onVisibleChange, onOverlayClick: onOverlayClick, + useSafeArea: useSafeArea, ); /// 浮层主体内容（必填）。 final Widget child; - /// 出现位置，默认 [TPopupPlacement.bottom]。 + /// 弹出位置，默认 [TPopupPlacement.bottom]。 final TPopupPlacement placement; - /// 宽度；[TPopupPlacement.left]、[TPopupPlacement.right]、[TPopupPlacement.center] 生效。 + /// 内容宽度；仅 [TPopupPlacement.left]、[TPopupPlacement.right]、[TPopupPlacement.center] 生效。 final double? width; - /// 高度；[TPopupPlacement.top]、[TPopupPlacement.bottom] 生效；[TPopupPlacement.center] 约束面板尺寸。 + /// 内容高度；top/bottom 传值时固定高度，bottom 省略时由内容撑开；center 用于约束面板尺寸。 final double? height; - /// 交叉轴边缘留白；具体类型由 [placement] 决定。 - /// - /// * [TPopupPlacement.bottom] 使用 [TPopupBottomInset] - /// * [TPopupPlacement.top] 使用 [TPopupTopInset] - /// * [TPopupPlacement.left] 使用 [TPopupLeftInset] - /// * [TPopupPlacement.right] 使用 [TPopupRightInset] - /// * [TPopupPlacement.center] 不支持 + /// 交叉轴边缘留白，类型须与 [placement] 匹配（见各类 *Inset）；[TPopupPlacement.center] 不支持。 final TPopupInset? inset; /// 内容区圆角，默认主题大圆角。 @@ -333,16 +342,14 @@ class TPopupOptions { /// 内容区背景色，默认主题容器色。 final Color? backgroundColor; - /// 是否绘制半透明蒙层。 - /// - /// 当 [modal] 为 true 且此值为 false 时，为“透明模态弹层”。 + /// 是否绘制蒙层；[modal]=true 且此值为 false 时为透明模态（见类文档「modal 与 showOverlay 组合」）。 final bool showOverlay; final bool? _closeOnOverlayClick; - /// 点击可见蒙层是否关闭。 + /// 点击可见蒙层是否关闭（已解析默认值）。 /// - /// 省略时默认跟随 [showOverlay]：显示蒙层时为 true，否则为 false。 + /// 构造时传 `null` 则按 [showOverlay] 推导；传 `true`/`false` 覆盖推导结果。 bool get closeOnOverlayClick => _closeOnOverlayClick ?? showOverlay; /// 蒙层颜色，默认 black54。 @@ -351,63 +358,51 @@ class TPopupOptions { /// 蒙层透明度系数（0–1），与 [overlayColor] 的 alpha 相乘后用于绘制。 final double? overlayOpacity; - /// 是否以模态方式展示；为 true 时阻断背景交互与底层语义/焦点。 - /// - /// 结合 [showOverlay] 可表达三种模式： - /// * `modal=true, showOverlay=true`：标准模态弹层 - /// * `modal=true, showOverlay=false`：透明模态弹层 - /// * `modal=false, showOverlay=false`：非模态浮层 + /// 是否模态展示；为 true 时阻断背景交互与语义/焦点（与 [showOverlay] 组合见类文档）。 final bool modal; - /// 为 true 时路由 `maintainState` 为 false，关闭后不保留路由内 State。 + /// 关闭后销毁路由 State（`maintainState=false`），默认 false。 final bool destroyOnClose; - /// 打开/关闭动画时长。 + /// 打开/关闭动画时长，默认 240ms。 final Duration animationDuration; - /// bottom 头部；仅 [TPopupPlacement.bottom] 生效。三态见类文档「Builder 三态」。 - /// - /// 自定义时忽略 [titleWidget]、[cancelBuilder]、[confirmBuilder]。 + /// bottom 头部构建器（仅 bottom）；省略=内置，null=隐藏，自定义见类文档「Builder 三态」。 final TPopupHeaderBuilder? headerBuilder; - /// bottom 标题插槽；仅 [headerBuilder] 为内置默认时生效。`null` 表示无标题。 + /// bottom 标题（仅内置头部时）；`null` 表示不展示标题。 final Widget? titleWidget; - /// bottom 左侧操作槽；仅 [headerBuilder] 为内置默认时生效。 - /// - /// 内置默认为「取消」，点击触发 [TPopupTrigger.cancel]。 + /// bottom 左侧槽（仅内置头部时）；默认「取消」，触发 [TPopupTrigger.cancel]。 final TPopupSlotBuilder? cancelBuilder; - /// bottom 右侧操作槽；仅 [headerBuilder] 为内置默认时生效。 - /// - /// 内置默认为「确定」，点击触发 [TPopupTrigger.confirm]。 + /// bottom 右侧槽（仅内置头部时）；默认「确定」，触发 [TPopupTrigger.confirm]。 final TPopupSlotBuilder? confirmBuilder; - /// center 面板外下方关闭区；仅 [TPopupPlacement.center] 生效。三态见类文档「Builder 三态」。 - /// - /// 内置默认点击触发 [TPopupTrigger.close]。 + /// center 面板外下方关闭区（仅 center）；默认圆形关闭，触发 [TPopupTrigger.close]。 final TPopupSlotBuilder? closeBuilder; - /// 路由 push 时（打开动画开始前）。 + /// 路由 push 时触发（打开动画开始前）。 final VoidCallback? onOpen; - /// 打开动画结束。 + /// 打开动画结束后触发。 final VoidCallback? onOpened; - /// 开始关闭（与 [onVisibleChange] 的 `visible: false` 同期）。 + /// 开始关闭时触发（与 [onVisibleChange](false, …) 同期）。 final VoidCallback? onClose; - /// 当前展示周期真正结束。 - /// - /// 大多数场景下会在关闭动画结束后触发；非栈顶路由被直接移除时不保证存在关闭动画。 + /// 展示周期结束触发；通常于关闭动画结束后，被直接移除时可能无动画。 final VoidCallback? onClosed; - /// 显隐变化；第二个参数为 [TPopupTrigger]。 + /// 显隐变化回调；第二参数为 [TPopupTrigger]。 final TPopupVisibleChangeCallback? onVisibleChange; - /// 蒙层点击；是否关闭取决于 [closeOnOverlayClick]。 + /// 蒙层点击回调；是否关闭由 [closeOnOverlayClick] 决定。 final VoidCallback? onOverlayClick; + /// 是否避让系统安全区，默认 true；仅贴边方向生效，[TPopupPlacement.center] 忽略，与 [inset] 叠加。 + final bool useSafeArea; + /// 返回配置副本。 /// /// 未传入的字段保持原值；对头部/关闭相关插槽显式传入 `null` 表示隐藏该区域。 @@ -437,6 +432,7 @@ class TPopupOptions { Object? onClosed = _unset, Object? onVisibleChange = _unset, Object? onOverlayClick = _unset, + bool? useSafeArea, }) { return TPopupOptions( child: child ?? this.child, @@ -496,6 +492,7 @@ class TPopupOptions { onOverlayClick: identical(onOverlayClick, _unset) ? this.onOverlayClick : onOverlayClick as VoidCallback?, + useSafeArea: useSafeArea ?? this.useSafeArea, ); } @@ -530,6 +527,7 @@ class TPopupOptions { onClosed: onClosed, onVisibleChange: onVisibleChange, onOverlayClick: onOverlayClick, + useSafeArea: useSafeArea, ); } diff --git a/tdesign-component/lib/src/components/popup/t_popup_types.dart b/tdesign-component/lib/src/components/popup/t_popup_types.dart index 668ccf7cc..f45e3b155 100644 --- a/tdesign-component/lib/src/components/popup/t_popup_types.dart +++ b/tdesign-component/lib/src/components/popup/t_popup_types.dart @@ -5,19 +5,19 @@ part of 't_popup.dart'; /// 与 [TPopupOptions] 类文档中的「字段与 placement」表对应。 /// 方向固定时请用 [TPopupOptions.bottom]、[TPopupOptions.center] 等命名工厂。 enum TPopupPlacement { - /// 自顶部滑入；使用 [TPopupOptions.height]、[TPopupOptions.inset]（[TPopupTopInset]）。 + /// 自顶部滑入；无内置头部；使用 [TPopupOptions.height]、[TPopupOptions.inset]（[TPopupTopInset]）。 top, - /// 自左侧滑入；使用 [TPopupOptions.width]、[TPopupOptions.inset]（[TPopupLeftInset]）。 + /// 自左侧滑入；无内置头部；使用 [TPopupOptions.width]、[TPopupOptions.inset]（[TPopupLeftInset]）；未传 [width] 默认 280。 left, - /// 自右侧滑入；使用 [TPopupOptions.width]、[TPopupOptions.inset]（[TPopupRightInset]）。 + /// 自右侧滑入；无内置头部；使用 [TPopupOptions.width]、[TPopupOptions.inset]（[TPopupRightInset]）；未传 [width] 默认 280。 right, /// 自底部滑入；默认内置头部；使用 [TPopupOptions.height]、[TPopupOptions.inset]（[TPopupBottomInset]）。 bottom, - /// 屏幕居中；使用 [TPopupOptions.closeBuilder] 控制面板外下方关闭区。 + /// 屏幕居中弹出；默认面板外下方关闭按钮；使用 [TPopupOptions.width]、[TPopupOptions.height]、[TPopupOptions.closeBuilder]；不支持 [TPopupOptions.inset]。 center, } diff --git a/tdesign-component/test/t_popup_layout_test.dart b/tdesign-component/test/t_popup_layout_test.dart index 915520b70..0b7801afb 100644 --- a/tdesign-component/test/t_popup_layout_test.dart +++ b/tdesign-component/test/t_popup_layout_test.dart @@ -190,6 +190,89 @@ void main() { expect(center.child, isA()); }); + test('safePaddingFor 按 placement 提取 MediaQuery.padding', () { + const media = EdgeInsets.fromLTRB(11, 22, 33, 44); + expect( + PopupLayout.safePaddingFor(TPopupPlacement.top, media, true), + const EdgeInsets.only(top: 22), + ); + expect( + PopupLayout.safePaddingFor(TPopupPlacement.bottom, media, true), + const EdgeInsets.only(bottom: 44), + ); + expect( + PopupLayout.safePaddingFor(TPopupPlacement.left, media, true), + const EdgeInsets.only(left: 11, top: 22, bottom: 44), + ); + expect( + PopupLayout.safePaddingFor(TPopupPlacement.right, media, true), + const EdgeInsets.only(right: 33, top: 22, bottom: 44), + ); + expect( + PopupLayout.safePaddingFor(TPopupPlacement.center, media, true), + EdgeInsets.zero, + ); + expect( + PopupLayout.safePaddingFor(TPopupPlacement.bottom, media, false), + EdgeInsets.zero, + ); + }); + + testWidgets('bottom 应用 safePadding 时贴安全区上沿', (tester) async { + const safeBottom = 34.0; + final layout = PopupLayout( + placement: TPopupPlacement.bottom, + height: 200, + ); + await tester.pumpWidget( + MaterialApp( + home: Scaffold( + body: Stack( + children: [ + layout.wrapPositioned( + child: const SizedBox(), + safePadding: const EdgeInsets.only(bottom: safeBottom), + ), + ], + ), + ), + ), + ); + final positioned = tester.widget(find.byType(Positioned)); + expect(positioned.bottom, safeBottom); + expect(positioned.height, 200); + }); + + testWidgets('top 应用 safePadding 时 left/right 与 inset 叠加', (tester) async { + final layout = PopupLayout( + placement: TPopupPlacement.top, + inset: const TPopupTopInset(left: 8, right: 12), + height: 100, + ); + await tester.pumpWidget( + MaterialApp( + home: Scaffold( + body: Stack( + children: [ + layout.wrapPositioned( + child: const SizedBox(), + safePadding: const EdgeInsets.only( + top: 20, + left: 4, + right: 6, + ), + ), + ], + ), + ), + ), + ); + final positioned = tester.widget(find.byType(Positioned)); + expect(positioned.top, 20); + expect(positioned.left, 12); + expect(positioned.right, 18); + }); + test('alignment 各方向', () { expect( PopupLayout( diff --git a/tdesign-component/test/t_popup_options_test.dart b/tdesign-component/test/t_popup_options_test.dart index 55c7d4982..258739f4d 100644 --- a/tdesign-component/test/t_popup_options_test.dart +++ b/tdesign-component/test/t_popup_options_test.dart @@ -8,6 +8,7 @@ void main() { final options = TPopupOptions(child: const SizedBox()).normalized(); expect(options.placement, TPopupPlacement.bottom); expect(options.modal, isTrue); + expect(options.useSafeArea, isTrue); expect(options.closeOnOverlayClick, isTrue); expect(options.usesDefaultHeader, isTrue); expect(options.usesDefaultCancel, isTrue); @@ -377,6 +378,12 @@ void main() { ); }); + test('copyWith 可更新 useSafeArea', () { + final options = TPopupOptions(child: const SizedBox()) + .copyWith(useSafeArea: false); + expect(options.useSafeArea, isFalse); + }); + test('copyWith(closeOnOverlayClick: null) 可恢复为跟随 showOverlay 的默认值', () { final options = TPopupOptions( child: const SizedBox(), diff --git a/tdesign-site/src/action-sheet/README.md b/tdesign-site/src/action-sheet/README.md index 2c8614a1b..54a6d1f4b 100644 --- a/tdesign-site/src/action-sheet/README.md +++ b/tdesign-site/src/action-sheet/README.md @@ -897,7 +897,7 @@ Widget _buildIconListLeftActionSheet(BuildContext context) { | 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 | - | 标题 | @@ -907,31 +907,6 @@ Widget _buildIconListLeftActionSheet(BuildContext context) { ### 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 | - | 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 | 是否立即显示 | - #### 静态方法 @@ -951,14 +926,14 @@ Widget _buildIconListLeftActionSheet(BuildContext context) { | 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 | 使用安全区域 | @@ -979,8 +954,8 @@ Widget _buildIconListLeftActionSheet(BuildContext context) { | 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 | 使用安全区域 | @@ -1006,6 +981,31 @@ Widget _buildIconListLeftActionSheet(BuildContext context) { | 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 | - | 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 #### 枚举值 diff --git a/tdesign-site/src/avatar/README.md b/tdesign-site/src/avatar/README.md index 87922dfbb..a48492d30 100644 --- a/tdesign-site/src/avatar/README.md +++ b/tdesign-site/src/avatar/README.md @@ -312,6 +312,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ## API ### TAvatar +#### 简介 +用于头像显示 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-site/src/button/README.md b/tdesign-site/src/button/README.md index 99fb16e95..cf19849f8 100644 --- a/tdesign-site/src/button/README.md +++ b/tdesign-site/src/button/README.md @@ -739,6 +739,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ## API ### TButton +#### 简介 +TD常规按钮 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -771,17 +773,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TButtonStyle -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| backgroundColor | Color? | - | 背景颜色 | -| frameColor | Color? | - | 边框颜色 | -| frameWidth | double? | - | 边框宽度 | -| gradient | Gradient? | - | 渐变背景色 | -| radius | BorderRadiusGeometry? | - | 自定义圆角 | -| textColor | Color? | - | 文字颜色 | - +#### 简介 +TButton按钮样式 #### 工厂构造方法 @@ -828,6 +821,17 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; | theme | TButtonTheme? | - | - | | status | TButtonStatus | - | - | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| backgroundColor | Color? | - | 背景颜色 | +| frameColor | Color? | - | 边框颜色 | +| frameWidth | double? | - | 边框宽度 | +| gradient | Gradient? | - | 渐变背景色 | +| radius | BorderRadiusGeometry? | - | 自定义圆角 | +| textColor | Color? | - | 文字颜色 | + ### TButtonSize #### 枚举值 diff --git a/tdesign-site/src/calendar/README.md b/tdesign-site/src/calendar/README.md index bb1062ed8..c7c814c25 100644 --- a/tdesign-site/src/calendar/README.md +++ b/tdesign-site/src/calendar/README.md @@ -1446,6 +1446,8 @@ Widget _buildLunar(BuildContext context) { ## API ### TCalendar +#### 简介 +日历组件 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -1486,13 +1488,15 @@ Widget _buildLunar(BuildContext context) { ### TCalendarPopup +#### 简介 +单元格组件popup模式 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | context | BuildContext | - | 上下文 | | autoClose | bool? | true | 自动关闭；在点击关闭按钮、确认按钮、遮罩层时自动关闭 | -| builder | CalendarBuilder? | - | 控件构建器，优先级高于[child] | +| builder | CalendarBuilder? | - | 控件构建器，优先级高于`child` | | child | TCalendar? | - | 日历控件 | | confirmBtn | Widget? | - | 自定义确认按钮 | | onClose | VoidCallback? | - | 关闭时触发 | @@ -1502,30 +1506,8 @@ Widget _buildLunar(BuildContext context) { ### 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 | - +#### 简介 +日历组件样式 #### 工厂构造方法 @@ -1547,29 +1529,55 @@ Widget _buildLunar(BuildContext context) { | --- | --- | --- | --- | | 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? | 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? | 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 +#### 简介 +农历日期信息模型 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -1631,19 +1639,19 @@ Widget _buildLunar(BuildContext context) { | 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); ``` diff --git a/tdesign-site/src/cell/README.md b/tdesign-site/src/cell/README.md index d345ad750..ff079430c 100644 --- a/tdesign-site/src/cell/README.md +++ b/tdesign-site/src/cell/README.md @@ -217,6 +217,17 @@ Widget _buildCard(BuildContext context) { ### TCellStyle #### 简介 单元格组件样式 + +#### 工厂构造方法 + +##### TCellStyle.cellStyle + +生成单元格默认样式 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| context | BuildContext | - | 传递context，会生成默认样式 | + #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -241,15 +252,14 @@ Widget _buildCard(BuildContext context) { | titleStyle | TextStyle? | - | 标题文字样式 | -#### 工厂构造方法 - -##### TCellStyle.cellStyle +### TCellGroupTheme +#### 枚举值 -生成单元格默认样式 -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| context | BuildContext | - | 传递context，会生成默认样式 | +| 名称 | 说明 | +| --- | --- | +| defaultTheme | - | +| cardTheme | - | ### TCellAlign @@ -263,29 +273,19 @@ Widget _buildCard(BuildContext context) { | 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); ``` diff --git a/tdesign-site/src/checkbox/README.md b/tdesign-site/src/checkbox/README.md index 1252d2903..c3fc0d68a 100644 --- a/tdesign-site/src/checkbox/README.md +++ b/tdesign-site/src/checkbox/README.md @@ -427,6 +427,10 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ## API ### TCheckbox +#### 简介 +复选框组件。 +FuiCheckbox支持3种内置样式的的复选框，还支持各种自定义样式，除了提供勾选之外还提供了内 +容选项，内容包含一个主标题和副标题，并且支持完全自定义内容，支持指定内容的方向等等 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -461,6 +465,25 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TCheckboxGroup +#### 简介 +CheckBox组，可以通过控制器控制组内的多个CheckBox的选择状态 +child的属性可以是任意包含TCheckBox的容器组件，例如： +```dart +TCheckboxGroup( + child: Row( + children: [ + TCheckBox(), + Column( + children: [ + TCheckBox() + ... + ] + ) + ... + ] + ) +) +``` #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-site/src/collapse/README.md b/tdesign-site/src/collapse/README.md index 0174ec848..604572e27 100644 --- a/tdesign-site/src/collapse/README.md +++ b/tdesign-site/src/collapse/README.md @@ -169,7 +169,22 @@ Card Style 卡片样式 ## API ### TCollapse #### 简介 -折叠面板列表组件，需配合 [TCollapsePanel] 使用 +折叠面板列表组件，需配合 `TCollapsePanel` 使用 + +#### 工厂构造方法 + +##### TCollapse.accordion + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| children | List | - | 折叠面板列表的子组件 | +| style | TCollapseStyle | TCollapseStyle.block | 折叠面板列表的样式 - `TCollapseStyle.block` 通栏风格 - `TCollapseStyle.card` 卡片风格 | +| expansionCallback | ExpansionPanelCallback? | - | 折叠面板列表的回调函数； 回调时，入参为当前点击的折叠面板的索引 index 和是否展开的状态 isExpanded | +| animationDuration | Duration | kThemeAnimationDuration | 折叠面板列表的动画时长 | +| elevation | double | 0 | 折叠面板列表的阴影 | +| initialOpenPanelValue | Object? | - | 折叠面板列表的默认展开面板的值； 当使用 `TCollapse.accordion` 时，此值生效 | +| key | Key? | - | 组件标识，用于区分或保留组件状态。 | + #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -179,28 +194,13 @@ Card Style 卡片样式 | elevation | double | 0 | 折叠面板列表的阴影 | | expansionCallback | ExpansionPanelCallback? | - | 折叠面板列表的回调函数； 回调时，入参为当前点击的折叠面板的索引 index 和是否展开的状态 isExpanded | | key | Key? | - | 组件标识，用于区分或保留组件状态。 | -| style | TCollapseStyle | TCollapseStyle.block | 折叠面板列表的样式 - [TCollapseStyle.block] 通栏风格 - [TCollapseStyle.card] 卡片风格 | +| style | TCollapseStyle | TCollapseStyle.block | 折叠面板列表的样式 - `TCollapseStyle.block` 通栏风格 - `TCollapseStyle.card` 卡片风格 | #### 公开属性 | 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| initialOpenPanelValue | Object? | - | 折叠面板列表的默认展开面板的值； 当使用 [TCollapse.accordion] 时，此值生效 | - - -#### 工厂构造方法 - -##### TCollapse.accordion - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| children | List | - | 折叠面板列表的子组件 | -| style | TCollapseStyle | TCollapseStyle.block | 折叠面板列表的样式 - [TCollapseStyle.block] 通栏风格 - [TCollapseStyle.card] 卡片风格 | -| expansionCallback | ExpansionPanelCallback? | - | 折叠面板列表的回调函数； 回调时，入参为当前点击的折叠面板的索引 index 和是否展开的状态 isExpanded | -| animationDuration | Duration | kThemeAnimationDuration | 折叠面板列表的动画时长 | -| elevation | double | 0 | 折叠面板列表的阴影 | -| initialOpenPanelValue | Object? | - | 折叠面板列表的默认展开面板的值； 当使用 [TCollapse.accordion] 时，此值生效 | -| key | Key? | - | 组件标识，用于区分或保留组件状态。 | +| initialOpenPanelValue | Object? | - | 折叠面板列表的默认展开面板的值； 当使用 `TCollapse.accordion` 时，此值生效 | ### TCollapseStyle diff --git a/tdesign-site/src/dialog/README.md b/tdesign-site/src/dialog/README.md index 68ee496dc..355b6202e 100644 --- a/tdesign-site/src/dialog/README.md +++ b/tdesign-site/src/dialog/README.md @@ -704,37 +704,17 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ## API ### TAlertDialog -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| backgroundColor | Color? | - | 背景颜色 | -| buttonStyle | TDialogButtonStyle | TDialogButtonStyle.normal | - | -| buttonWidget | Widget? | - | 自定义按钮 | -| content | String? | - | 内容 | -| contentColor | Color? | - | 内容颜色 | -| contentMaxHeight | double | 0 | 内容的最大高度，默认为0，也就是不限制高度 | -| contentWidget | Widget? | - | 内容Widget | -| key | Key? | - | 组件标识，用于区分或保留组件状态。 | -| leftBtn | TDialogButtonOptions? | - | 左侧按钮配置 | -| leftBtnAction | Function()? | - | 左侧按钮默认点击 | -| padding | EdgeInsets? | const EdgeInsets.fromLTRB(24, 32, 24, 0) | 内容内边距 | -| radius | double | 12.0 | 圆角 | -| rightBtn | TDialogButtonOptions? | - | 右侧按钮配置 | -| rightBtnAction | Function()? | - | 右侧按钮默认点击 | -| showCloseButton | bool? | - | 显示右上角关闭按钮 | -| title | String? | - | 标题 | -| titleAlignment | AlignmentGeometry? | - | 标题对齐模式 | -| titleColor | Color? | - | 标题颜色 | - +#### 简介 +弹窗控件 +支持横向或竖向摆放按钮 +横向最多摆放两个按钮 #### 工厂构造方法 ##### TAlertDialog.vertical 纵向按钮排列的对话框 - - [buttons]参数是必须的，纵向按钮默认样式都是[TButtonTheme.primary] +`buttons`参数是必须的，纵向按钮默认样式都是`TButtonTheme.primary` | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | @@ -753,8 +733,34 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; | padding | EdgeInsets? | const EdgeInsets.fromLTRB(24, 32, 24, 0) | 内容内边距 | | buttonWidget | Widget? | - | 自定义按钮 | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| backgroundColor | Color? | - | 背景颜色 | +| buttonStyle | TDialogButtonStyle | TDialogButtonStyle.normal | - | +| buttonWidget | Widget? | - | 自定义按钮 | +| content | String? | - | 内容 | +| contentColor | Color? | - | 内容颜色 | +| contentMaxHeight | double | 0 | 内容的最大高度，默认为0，也就是不限制高度 | +| contentWidget | Widget? | - | 内容Widget | +| key | Key? | - | 组件标识，用于区分或保留组件状态。 | +| leftBtn | TDialogButtonOptions? | - | 左侧按钮配置 | +| leftBtnAction | Function()? | - | 左侧按钮默认点击 | +| padding | EdgeInsets? | const EdgeInsets.fromLTRB(24, 32, 24, 0) | 内容内边距 | +| radius | double | 12.0 | 圆角 | +| rightBtn | TDialogButtonOptions? | - | 右侧按钮配置 | +| rightBtnAction | Function()? | - | 右侧按钮默认点击 | +| showCloseButton | bool? | - | 显示右上角关闭按钮 | +| title | String? | - | 标题 | +| titleAlignment | AlignmentGeometry? | - | 标题对齐模式 | +| titleColor | Color? | - | 标题颜色 | + ### TConfirmDialog +#### 简介 +只有一个按钮的弹窗控件 +按钮样式支持普通和文字 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -781,6 +787,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TDialogButtonOptions +#### 简介 +弹窗按钮配置 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -797,6 +805,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TDialogScaffold +#### 简介 +TDialog手脚架 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -810,6 +820,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TDialogTitle +#### 简介 +弹窗标题 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -820,6 +832,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TDialogContent +#### 简介 +弹窗内容 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -830,6 +844,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TDialogInfoWidget +#### 简介 +弹窗信息 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -846,6 +862,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### HorizontalNormalButtons +#### 简介 +横向排列的两个按钮 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -856,6 +874,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### HorizontalTextButtons +#### 简介 +左右横向文字按钮，顶部和中间有分割线 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -866,6 +886,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TDialogButton +#### 简介 +弹窗标题 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -885,6 +907,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TImageDialog +#### 简介 +带有图片的弹窗控件 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -908,6 +932,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TInputDialog +#### 简介 +带有输入框的弹窗 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -934,9 +960,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TDialogButtonStyle #### 简介 Dialog按钮样式 - - 用于在Dialog层面配置按钮样式 - Dialog内支持配置每个按钮的样式 +用于在Dialog层面配置按钮样式 +Dialog内支持配置每个按钮的样式 #### 枚举值 diff --git a/tdesign-site/src/divider/README.md b/tdesign-site/src/divider/README.md index 37251b43a..cffb46a7a 100644 --- a/tdesign-site/src/divider/README.md +++ b/tdesign-site/src/divider/README.md @@ -141,6 +141,10 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ## API ### TDivider +#### 简介 +分割线 +对于非flutter原有的控件，则只需满足TDesign规范即可； +如果有业务在实际使用，还需兼容实际业务场景。 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-site/src/drawer/README.md b/tdesign-site/src/drawer/README.md index 1bdf26a3c..9cbce0706 100644 --- a/tdesign-site/src/drawer/README.md +++ b/tdesign-site/src/drawer/README.md @@ -296,7 +296,7 @@ Widget _buildBottomSimple(BuildContext context) { | backgroundColor | Color? | - | 组件背景颜色 | | bordered | bool? | true | 是否显示边框 | | closeOnOverlayClick | bool? | true | 点击蒙层时是否关闭抽屉 | -| contentWidget | Widget? | - | 自定义内容，优先级高于[items]/[footer]/[title] | +| contentWidget | Widget? | - | 自定义内容，优先级高于`items`/`footer`/`title` | | drawerTop | double? | - | 距离顶部的距离 | | footer | Widget? | - | 抽屉的底部 | | hover | bool? | true | 是否开启点击反馈 | @@ -316,14 +316,14 @@ Widget _buildBottomSimple(BuildContext context) { ### TDrawerWidget #### 简介 抽屉内容组件 - 可用于 Scaffold 中的 drawer 属性 +可用于 Scaffold 中的 drawer 属性 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | backgroundColor | Color? | - | 组件背景颜色 | | bordered | bool? | true | 是否显示边框 | -| contentWidget | Widget? | - | 自定义内容，优先级高于[items]/[footer]/[title] | +| contentWidget | Widget? | - | 自定义内容，优先级高于`items`/`footer`/`title` | | footer | Widget? | - | 抽屉的底部 | | hover | bool? | true | 是否开启点击反馈 | | isShowLastBordered | bool? | true | 是否显示最后一行分割线 | diff --git a/tdesign-site/src/dropdown-menu/README.md b/tdesign-site/src/dropdown-menu/README.md index cfa91abfd..29831ea43 100644 --- a/tdesign-site/src/dropdown-menu/README.md +++ b/tdesign-site/src/dropdown-menu/README.md @@ -275,7 +275,7 @@ TDropdownMenu _buildGroup(BuildContext context) { | --- | --- | --- | --- | | arrowColor | Color? | - | 自定义箭头颜色 | | arrowIcon | IconData? | - | 自定义箭头图标 | -| builder | TDropdownItemBuilder? | - | 下拉菜单构建器，优先级高于[items] | +| builder | TDropdownItemBuilder? | - | 下拉菜单构建器，优先级高于`items` | | closeOnClickOverlay | bool? | true | 是否在点击遮罩层后关闭菜单 | | decoration | Decoration? | - | 下拉菜单的装饰器 | | direction | TDropdownMenuDirection? | TDropdownMenuDirection.auto | 菜单展开方向（down、up、auto） | @@ -288,7 +288,7 @@ TDropdownMenu _buildGroup(BuildContext context) { | onMenuClosed | ValueChanged? | - | 关闭菜单事件 | | onMenuOpened | ValueChanged? | - | 展开菜单事件 | | showOverlay | bool? | true | 是否显示遮罩层 | -| tabBarAlign | MainAxisAlignment? | MainAxisAlignment.center | [TDropdownItem.label]和[arrowIcon]/[TDropdownItem.arrowIcon]的对齐方式 | +| tabBarAlign | MainAxisAlignment? | MainAxisAlignment.center | `TDropdownItem.label`和`arrowIcon`/`TDropdownItem.arrowIcon`的对齐方式 | | width | double? | - | menu的宽度 | @@ -314,9 +314,9 @@ TDropdownMenu _buildGroup(BuildContext context) { | onReset | VoidCallback? | - | 点击重置时触发 | | options | List? | const [] | 选项数据 | | optionsColumns | int? | 1 | 选项分栏（1-3） | -| tabBarAlign | MainAxisAlignment? | - | [label]和[arrowIcon]/[TDropdownMenu.arrowIcon]的对齐方式 | -| tabBarFlex | int? | 1 | 该item在menu上的宽度占比，仅在[TDropdownMenu.isScrollable]为false时有效 | -| tabBarWidth | double? | - | 该item在menu上的宽度，仅在[TDropdownMenu.isScrollable]为true时有效 | +| tabBarAlign | MainAxisAlignment? | - | `label`和`arrowIcon`/`TDropdownMenu.arrowIcon`的对齐方式 | +| tabBarFlex | int? | 1 | 该item在menu上的宽度占比，仅在`TDropdownMenu.isScrollable`为false时有效 | +| tabBarWidth | double? | - | 该item在menu上的宽度，仅在`TDropdownMenu.isScrollable`为true时有效 | #### 静态成员 @@ -358,39 +358,39 @@ TDropdownMenu _buildGroup(BuildContext context) { | auto | 根据内容高度动态展示方向 | -### TDropdownItemContentBuilder +### TDropdownItemBuilder +#### 简介 +下拉菜单构建器 #### 类型定义 ```dart -typedef TDropdownItemContentBuilder = Widget Function(BuildContext context, _TDropdownItemState itemState, TDropdownPopup? popupState); +typedef TDropdownItemBuilder = List Function(BuildContext context); ``` -### TDropdownItemOptionsCallback +### LabelBuilder +#### 简介 +自定义标签内容 #### 类型定义 ```dart -typedef TDropdownItemOptionsCallback = void Function(List? options); +typedef LabelBuilder = Widget Function(BuildContext context, String label, bool isOpened, int index); ``` -### TDropdownItemBuilder -#### 简介 -下拉菜单构建器 +### TDropdownItemContentBuilder #### 类型定义 ```dart -typedef TDropdownItemBuilder = List Function(BuildContext context); +typedef TDropdownItemContentBuilder = Widget Function(BuildContext context, _TDropdownItemState itemState, TDropdownPopup? popupState); ``` -### LabelBuilder -#### 简介 -自定义标签内容 +### TDropdownItemOptionsCallback #### 类型定义 ```dart -typedef LabelBuilder = Widget Function(BuildContext context, String label, bool isOpened, int index); +typedef TDropdownItemOptionsCallback = void Function(List? options); ``` diff --git a/tdesign-site/src/form/README.md b/tdesign-site/src/form/README.md index 02c02781a..f352c4e69 100644 --- a/tdesign-site/src/form/README.md +++ b/tdesign-site/src/form/README.md @@ -767,6 +767,9 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TFormValidation +#### 简介 +实现普通表单项的校验 +校验规则 和 错误提醒 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-site/src/image-viewer/README.md b/tdesign-site/src/image-viewer/README.md index f48679c44..7622bb11d 100644 --- a/tdesign-site/src/image-viewer/README.md +++ b/tdesign-site/src/image-viewer/README.md @@ -70,6 +70,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ## API ### TImageViewer +#### 简介 +图片预览工具 #### 静态方法 diff --git a/tdesign-site/src/image/README.md b/tdesign-site/src/image/README.md index ee95db5cb..e2d397620 100644 --- a/tdesign-site/src/image/README.md +++ b/tdesign-site/src/image/README.md @@ -1918,7 +1918,7 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; | excludeFromSemantics | bool | false | - | | filterQuality | FilterQuality | FilterQuality.low | - | | fit | BoxFit? | - | 适配样式 | -| frameBuilder | ImageFrameBuilder? | - | 以下系统Image属性，释义请参考系统[Image]中注释 | +| frameBuilder | ImageFrameBuilder? | - | 以下系统Image属性，释义请参考系统`Image`中注释 | | gaplessPlayback | bool | false | - | | height | double? | - | 自定义高 | | imageFile | File? | - | 图片文件路径 | diff --git a/tdesign-site/src/message/README.md b/tdesign-site/src/message/README.md index 5ed4b412f..74773b5da 100644 --- a/tdesign-site/src/message/README.md +++ b/tdesign-site/src/message/README.md @@ -287,24 +287,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ## API ### TMessage -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| closeBtn | dynamic | - | 关闭按钮 | -| content | String? | - | 通知内容 | -| duration | int? | 3000 | 消息内置计时器 | -| icon | dynamic | true | 自定义消息前面的图标 | -| key | Key? | - | 组件标识，用于区分或保留组件状态。 | -| link | dynamic | - | 链接名称 | -| marquee | MessageMarquee? | - | 跑马灯效果 | -| offset | List? | - | 相对于 placement 的偏移量 | -| onCloseBtnClick | VoidCallback? | - | 点击关闭按钮触发 | -| onDurationEnd | VoidCallback? | - | 计时结束后触发 | -| onLinkClick | VoidCallback? | - | 点击链接文本时触发 | -| theme | MessageTheme? | MessageTheme.info | 消息组件风格 info/success/warning/error | -| visible | bool? | true | 是否显示 | - +#### 简介 +TMessage 组件 #### 静态方法 @@ -328,8 +312,28 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; | onDurationEnd | VoidCallback? | - | 计时结束后触发 | | onLinkClick | VoidCallback? | - | 点击链接文本时触发 | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| closeBtn | dynamic | - | 关闭按钮 | +| content | String? | - | 通知内容 | +| duration | int? | 3000 | 消息内置计时器 | +| icon | dynamic | true | 自定义消息前面的图标 | +| key | Key? | - | 组件标识，用于区分或保留组件状态。 | +| link | dynamic | - | 链接名称 | +| marquee | MessageMarquee? | - | 跑马灯效果 | +| offset | List? | - | 相对于 placement 的偏移量 | +| onCloseBtnClick | VoidCallback? | - | 点击关闭按钮触发 | +| onDurationEnd | VoidCallback? | - | 计时结束后触发 | +| onLinkClick | VoidCallback? | - | 点击链接文本时触发 | +| theme | MessageTheme? | MessageTheme.info | 消息组件风格 info/success/warning/error | +| visible | bool? | true | 是否显示 | + ### MessageMarquee +#### 简介 +跑马灯配置 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -340,6 +344,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### MessageLink +#### 简介 +链接设置 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-site/src/notice-bar/README.md b/tdesign-site/src/notice-bar/README.md index 6ad02fea7..d38b81b3a 100644 --- a/tdesign-site/src/notice-bar/README.md +++ b/tdesign-site/src/notice-bar/README.md @@ -303,7 +303,7 @@ Widget _cardNoticeBar(BuildContext context) { | prefixIcon | IconData? | - | 左侧图标 | | right | Widget? | - | 右侧内容（自定义右侧内容，优先级高于suffixIcon） | | speed | double? | 50 | 滚动速度 | -| style | TNoticeBarStyle? | - | 公告栏样式 [TNoticeBarStyle] | +| style | TNoticeBarStyle? | - | 公告栏样式 `TNoticeBarStyle` | | suffixIcon | IconData? | - | 右侧图标 | | theme | TNoticeBarTheme? | TNoticeBarTheme.info | 主题 | @@ -311,17 +311,6 @@ Widget _cardNoticeBar(BuildContext context) { ### TNoticeBarStyle #### 简介 公告栏样式 -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| backgroundColor | Color? | - | 公告栏背景色 | -| context | BuildContext? | - | 上下文 | -| leftIconColor | Color? | - | 公告栏左侧图标颜色 | -| padding | EdgeInsetsGeometry? | - | 公告栏内边距 | -| rightIconColor | Color? | - | 公告栏右侧图标颜色 | -| textStyle | TextStyle? | - | 公告栏内容样式 | - #### 工厂构造方法 @@ -334,6 +323,17 @@ Widget _cardNoticeBar(BuildContext context) { | context | BuildContext | - | 上下文 | | theme | TNoticeBarTheme? | TNoticeBarTheme.info | - | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| backgroundColor | Color? | - | 公告栏背景色 | +| context | BuildContext? | - | 上下文 | +| leftIconColor | Color? | - | 公告栏左侧图标颜色 | +| padding | EdgeInsetsGeometry? | - | 公告栏内边距 | +| rightIconColor | Color? | - | 公告栏右侧图标颜色 | +| textStyle | TextStyle? | - | 公告栏内容样式 | + ### TNoticeBarType #### 简介 diff --git a/tdesign-site/src/picker/README.md b/tdesign-site/src/picker/README.md index f061a540b..533af80fd 100644 --- a/tdesign-site/src/picker/README.md +++ b/tdesign-site/src/picker/README.md @@ -508,29 +508,52 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ## API ### TPicker +#### 简介 +纯滚轮选择器组件 +数据决定形态（编译期类型安全）： +- `TPickerColumns` → 多列独立选择 +- `TPickerLinked` → 联动选择 +```dart +// 多列独立 +TPicker( + items: TPickerColumns.fromRaw([['北京', '上海', '广州']]), +) +// 联动 +TPicker( + items: TPickerLinked.fromRaw({'广东': {'深圳': ['南山', '福田']}}), +) +``` #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| cancel | Widget? | - | 工具栏左侧自定义插槽，默认使用 [TResourceDelegate.cancel] 可用于渲染图标、图标+文字组合等。点击事件依然由外层 [GestureDetector] 处理，触发 [onCancel] 回调——所以插槽内的 Widget 不需要自己处理点击。 ```dart // 简单改文字 TPicker( cancel: const Text('关闭'), onCancel: () => Navigator.of(context).pop(), ) // 带图标 TPicker( cancel: const Icon(Icons.close, size: 22), onCancel: () => Navigator.of(context).pop(), ) ``` | -| confirm | Widget? | - | 工具栏右侧自定义插槽，默认使用 [TResourceDelegate.confirm] 可用于渲染图标、图标+文字组合等。点击事件依然由外层 [GestureDetector] 处理，触发 [onConfirm] 回调——所以插槽内的 Widget 不需要自己处理点击。 ```dart // 简单改文字 TPicker( confirm: const Text('确定'), onConfirm: (v) => Navigator.of(context).pop(v), ) // 带图标 TPicker( confirm: const Icon(Icons.check, size: 22), onConfirm: (v) => Navigator.of(context).pop(v), ) ``` | +| cancel | Widget? | - | 工具栏左侧自定义插槽，默认使用 `TResourceDelegate.cancel` 可用于渲染图标、图标+文字组合等。点击事件依然由外层 `GestureDetector` 处理，触发 `onCancel` 回调——所以插槽内的 Widget 不需要自己处理点击。 ```dart // 简单改文字 TPicker( cancel: const Text('关闭'), onCancel: () => Navigator.of(context).pop(), ) // 带图标 TPicker( cancel: const Icon(Icons.close, size: 22), onCancel: () => Navigator.of(context).pop(), ) ``` | +| confirm | Widget? | - | 工具栏右侧自定义插槽，默认使用 `TResourceDelegate.confirm` 可用于渲染图标、图标+文字组合等。点击事件依然由外层 `GestureDetector` 处理，触发 `onConfirm` 回调——所以插槽内的 Widget 不需要自己处理点击。 ```dart // 简单改文字 TPicker( confirm: const Text('确定'), onConfirm: (v) => Navigator.of(context).pop(v), ) // 带图标 TPicker( confirm: const Icon(Icons.check, size: 22), onConfirm: (v) => Navigator.of(context).pop(v), ) ``` | | disabled | bool | false | 是否禁用整个选择器（禁止滚动和操作），默认 false | | height | double | 200 | 视窗高度，默认 200 | | initialValue | List? | - | 初始选中值列表（按 value 匹配） | | itemBuilder | ItemBuilderType? | - | 自定义子项构建器（disabled 项仍由内部统一渲染，不会走此 builder） | | itemCount | int | 5 | 每屏显示 item 数，默认 5 | | itemDistanceCalculator | ItemDistanceCalculator? | - | 自定义距离计算器（控制颜色/字重/字号随"离中心距离"的变化） | -| items | TPickerItems | - | 数据源（必填） 使用密封类 [TPickerItems] 编译期强制二选一： - [TPickerColumns] → 多列独立选择 - [TPickerLinked] → 联动选择 自由结构数据通过 `.fromRaw()` 工厂构造归一化。 | +| items | TPickerItems | - | 数据源（必填） 使用密封类 `TPickerItems` 编译期强制二选一： - `TPickerColumns` → 多列独立选择 - `TPickerLinked` → 联动选择 自由结构数据通过 `.fromRaw()` 工厂构造归一化。 | | key | Key? | - | 组件标识，用于区分或保留组件状态。 | | onCancel | VoidCallback? | - | 点击「取消」按钮回调 仅作为点击事件通知，不携带任何参数。组件本身不会做任何 popup 操作，业务层可在此自行决定是否关闭弹窗、重置状态等。 | -| onChange | void Function(TPickerValue)? | - | 值改变回调（滚动时实时触发） 触发时机： - 用户滚动经过某个 enabled 项并稳定时 - disabled 修正动画完成后，回调最终落点 **注意**：此回调代表"滚动时实时变化"，不代表"用户已确认选择"。 如需"已确认"语义，请使用 [onConfirm]。 如需做网络请求/埋点等去抖处理，请在业务层自行 debounce。 | -| onConfirm | void Function(TPickerValue)? | - | 点击「确认」按钮回调 携带当前选中的完整 [TPickerValue]，包含： - `selectedOptions`: 当前选中的所有 [TPickerOption] - `values`: 各列选中项的 value 列表 - `labels`: 各列选中项的 label 列表 - `indexes`: 各列选中项的索引 与 [onChange] 不同——只有用户点击「确认」时才触发，代表"已确认选择"。 组件本身不会做任何 popup 操作，业务层可在此自行决定是否关闭弹窗、 提交表单等。 | -| onLoad | void Function(TPickerLoadEvent)? | - | 列选中项变化的事件回调 **触发时机**：每次用户滚动到一个 enabled 项后都会触发（联动模式下还会 在新展开的列就位后触发）。组件本身不做"距底部多少项"的阈值判断——把 决策权交给业务层。 **事件参数**包含： - [TPickerLoadEvent.column]：触发列索引 - [TPickerLoadEvent.remaining]：当前列距底部剩余项数 - [TPickerLoadEvent.displayedCount]：当前列总项数 - [TPickerLoadEvent.parentValue]：联动模式下父级选中值（首列为 null） **典型用法**：业务层根据 [TPickerLoadEvent.remaining] 自行判断是否加载更多。 ```dart onLoad: (e) async { if (e.remaining > 5 \|\| _isLoading) return; // 距底部还远 / 已在加载，跳过 _isLoading = true; final more = await fetchMore(parent: e.parentValue); setState(() { _data.addAll(more); _isLoading = false; }); } ``` | -| title | String? | - | 工具栏中部标题（可选，不传时中部留白） 顶部工具栏永远显示，包含「取消」「标题」「确认」三块。 用户点击「取消」触发 [onCancel]，点击「确认」触发 [onConfirm]。 选择器与弹窗（popup）完全解耦——关闭/打开弹窗的逻辑由业务层在 这两个回调中自行控制。 典型用法（与 popup 弹窗组合）： ```dart TPicker( items: items, title: '请选择地区', onCancel: () => setState(() => visible = false), onConfirm: (value) { setState(() { selected = value; visible = false; }); }, ) ``` | -| titleWidget | Widget? | - | 工具栏中部自定义标题插槽 传入后会**完全替换**默认的 [title] 文字，可用于渲染更复杂的标题（副标题、图标+文字等）。 标题区域不响应点击。 | +| onChange | void Function(TPickerValue)? | - | 值改变回调（滚动时实时触发） 触发时机： - 用户滚动经过某个 enabled 项并稳定时 - disabled 修正动画完成后，回调最终落点 **注意**：此回调代表"滚动时实时变化"，不代表"用户已确认选择"。 如需"已确认"语义，请使用 `onConfirm`。 如需做网络请求/埋点等去抖处理，请在业务层自行 debounce。 | +| onConfirm | void Function(TPickerValue)? | - | 点击「确认」按钮回调 携带当前选中的完整 `TPickerValue`，包含： - `selectedOptions`: 当前选中的所有 `TPickerOption` - `values`: 各列选中项的 value 列表 - `labels`: 各列选中项的 label 列表 - `indexes`: 各列选中项的索引 与 `onChange` 不同——只有用户点击「确认」时才触发，代表"已确认选择"。 组件本身不会做任何 popup 操作，业务层可在此自行决定是否关闭弹窗、 提交表单等。 | +| onLoad | void Function(TPickerLoadEvent)? | - | 列选中项变化的事件回调 **触发时机**：每次用户滚动到一个 enabled 项后都会触发（联动模式下还会 在新展开的列就位后触发）。组件本身不做"距底部多少项"的阈值判断——把 决策权交给业务层。 **事件参数**包含： - `TPickerLoadEvent.column`：触发列索引 - `TPickerLoadEvent.remaining`：当前列距底部剩余项数 - `TPickerLoadEvent.displayedCount`：当前列总项数 - `TPickerLoadEvent.parentValue`：联动模式下父级选中值（首列为 null） **典型用法**：业务层根据 `TPickerLoadEvent.remaining` 自行判断是否加载更多。 ```dart onLoad: (e) async { if (e.remaining > 5 \|\| _isLoading) return; // 距底部还远 / 已在加载，跳过 _isLoading = true; final more = await fetchMore(parent: e.parentValue); setState(() { _data.addAll(more); _isLoading = false; }); } ``` | +| title | String? | - | 工具栏中部标题（可选，不传时中部留白） 顶部工具栏永远显示，包含「取消」「标题」「确认」三块。 用户点击「取消」触发 `onCancel`，点击「确认」触发 `onConfirm`。 选择器与弹窗（popup）完全解耦——关闭/打开弹窗的逻辑由业务层在 这两个回调中自行控制。 典型用法（与 popup 弹窗组合）： ```dart TPicker( items: items, title: '请选择地区', onCancel: () => setState(() => visible = false), onConfirm: (value) { setState(() { selected = value; visible = false; }); }, ) ``` | +| titleWidget | Widget? | - | 工具栏中部自定义标题插槽 传入后会**完全替换**默认的 `title` 文字，可用于渲染更复杂的标题（副标题、图标+文字等）。 标题区域不响应点击。 | ### TPickerOption +#### 简介 +选择器选项 +label 用于显示，value 用于 onChange 返回，两者分离以便自定义展示 +（emoji、单位、国际化）同时保持纯净的业务值。 +```dart +TPickerOption(label: '👨 男性', value: 'M') +TPickerOption(label: '广东省', value: 'GD', disabled: true) +``` #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -541,6 +564,12 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TPickerValue +#### 简介 +onChange 回调返回的选中信息 +```dart +onChange: (v) => setState(() => _lastValue = v); +Text(_lastValue?.labels.join(' / ') ?? ''); +``` #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -557,6 +586,12 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TPickerLoadEvent +#### 简介 +列选中变化的事件参数 +每当用户在某一列滚动到一个 enabled 项后，`TPicker.onLoad` 会收到一个该事件实例。 +事件里携带了"列索引、当前列总数、距底部剩余项数、联动模式下父级选中值"等 +上下文信息，业务层据此自行决定是否加载更多数据（例如： +`if (e.remaining > 5) return;`）。 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -568,68 +603,95 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TPickerColumns -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| columns | List> | - | 每列的选项列表 | - +#### 简介 +多列独立选择的数据源 +```dart +TPicker( + items: TPickerColumns([ + [TPickerOption(label: '北京', value: 'BJ'), ...], + [TPickerOption(label: '朝阳区', value: 'CY'), ...], + ]), +) +``` #### 工厂构造方法 ##### TPickerColumns.fromRaw 从自由结构的 raw 数据创建，自动归一化 - - ```dart - TPickerColumns.fromRaw( - [['北京', '上海', '广州']], - keys: const TPickerKeys(label: 'name', value: 'code'), - ) - ``` +```dart +TPickerColumns.fromRaw( + [['北京', '上海', '广州']], + keys: const TPickerKeys(label: 'name', value: 'code'), +) +``` | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | rawColumns | List | - | - | | keys | TPickerKeys | TPickerKeys.defaults | - | - -### TPickerLinked #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| tree | Map | - | 联动树结构：`Map` value 可以是： - `Map` → 下一级联动 - `List` → 叶子级选项 | +| columns | List> | - | 每列的选项列表 | +### TPickerLinked +#### 简介 +联动选择的数据源 +```dart +TPicker( + items: TPickerLinked({ + TPickerOption(label: '广东', value: 'GD'): { + TPickerOption(label: '深圳', value: 'SZ'): [ + TPickerOption(label: '南山', value: 'NS'), + ], + }, + }), +) +``` + #### 工厂构造方法 ##### TPickerLinked.fromRaw 从自由结构的 raw Map 数据创建，自动归一化 - - ```dart - TPickerLinked.fromRaw({ - '广东': {'深圳': ['南山', '福田'], '广州': ['天河']}, - '浙江': {'杭州': ['西湖']}, - }) - ``` +```dart +TPickerLinked.fromRaw({ + '广东': {'深圳': ['南山', '福田'], '广州': ['天河']}, + '浙江': {'杭州': ['西湖']}, +}) +``` | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | rawTree | Map | - | - | | keys | TPickerKeys | TPickerKeys.defaults | - | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| tree | Map | - | 联动树结构：`Map` value 可以是： - `Map` → 下一级联动 - `List` → 叶子级选项 | + ### TPickerItems #### 简介 选择器数据源密封类 - - 编译期强制二选一，消除运行时类型错误： - - [TPickerColumns] → 多列独立选择 - - [TPickerLinked] → 联动选择 +编译期强制二选一，消除运行时类型错误： +- `TPickerColumns` → 多列独立选择 +- `TPickerLinked` → 联动选择 ### TPickerKeys +#### 简介 +字段映射配置 +当 picker 数据源不是 `TPickerOption` 时，用于声明原始结构中的字段名。 +```dart +// 数据：[{ id: '1', name: '选项A', readonly: false }] +const keys = TPickerKeys(label: 'name', value: 'id', disabled: 'readonly'); +``` #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-site/src/popup/README.md b/tdesign-site/src/popup/README.md index b9588e4f2..3297b153b 100644 --- a/tdesign-site/src/popup/README.md +++ b/tdesign-site/src/popup/README.md @@ -541,345 +541,284 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TPopup #### 简介 弹出层入口：五向滑入 / 居中弹出，支持蒙层、bottom 操作区、center 面板外下方关闭区。 +通过 `show` 命令式打开；返回 `TPopupHandle` 用于关闭与再次打开。 +多次调用 `show` 会继续压入新的浮层路由，可用于叠加展示。 - 通过 [show] 命令式打开；返回 [TPopupHandle] 用于关闭与再次打开。 - 多次调用 [show] 会继续压入新的浮层路由，可用于叠加展示。 - - **示例** - - ```dart - final handle = TPopup.show( - context, - options: TPopupOptions.bottom( - titleWidget: const Text('标题'), - child: MyPanel(), - ), - ); - handle.close(); - handle.open(); - ``` - - 配置项见 [TPopupOptions]；方向见 [TPopupPlacement]。 - -#### 工厂构造方法 - -##### TPopup._ +配置项见 `TPopupOptions`；方向见 `TPopupPlacement`。 #### 静态方法 ##### TPopup.show -打开浮层并压入独立 [PopupRoute]。 - - [context] 用于查找 [Navigator] 并展示浮层。 - - [options] 浮层配置；方向固定时推荐 [TPopupOptions.bottom] 等命名工厂。 - - 返回 [TPopupHandle]，可用 [TPopupHandle.close]、[TPopupHandle.open]、 - [TPopupHandle.isShowing] 控制与查询。 - 重复调用会继续 push 新的浮层；若需互斥请在业务层管理。 - - [navigatorContext] 可选，指定承载浮层的 [Navigator] 的 context，默认 [context]。 - - [useRootNavigator] 为 true 时使用根 [Navigator]（嵌套导航场景）。 +打开浮层并压入 `PopupRoute`，返回 `TPopupHandle` 用于关闭/再次打开。 +连续调用会重复 push 新路由；互斥展示请在业务层自行管理。 返回类型：`TPopupHandle` | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| context | BuildContext | - | - | -| options | TPopupOptions | - | 创建时传入的配置；每次 [open] 会按 [TPopupOptions.placement] 裁剪无效字段后使用。 | -| navigatorContext | BuildContext? | - | 与 [TPopup.show] 的 [navigatorContext] 相同。 | -| useRootNavigator | bool | false | 与 [TPopup.show] 的 [useRootNavigator] 相同。 | +| context | BuildContext | - | 用于查找并展示 `Navigator`。 | +| options | TPopupOptions | - | 浮层配置；方向固定时建议 `TPopupOptions.bottom` 等命名工厂。 | +| navigatorContext | BuildContext? | - | 可选，指定承载浮层的 `Navigator` context，默认 `context`。 | +| useRootNavigator | bool | false | 为 true 时使用根 `Navigator`（嵌套导航场景）。 | ### TPopupOptions #### 简介 -[TPopup.show] 的配置对象。 - - ## 如何创建 - - | 场景 | 推荐用法 | - |------|----------| - | 弹出方向已知 | [TPopupOptions.bottom]、[TPopupOptions.center]、[TPopupOptions.top]、[TPopupOptions.left]、[TPopupOptions.right] | - | 方向由变量决定 | 默认构造并设置 [placement]；传错字段会在 [TPopup.show] / [TPopupHandle.open] 时抛 [FlutterError] | - - 命名工厂只暴露当前方向生效的字段（例如 [TPopupOptions.bottom] 无 [width] 参数）。 - - ## 字段与 [TPopupPlacement] +`TPopup.show` 的配置对象。 +## 如何创建 +| 场景 | 推荐用法 | +|------|----------| +| 弹出方向已知 | `TPopupOptions.bottom`、`TPopupOptions.center`、`TPopupOptions.top`、`TPopupOptions.left`、`TPopupOptions.right` | +| 方向由变量决定 | 默认构造并设置 `placement`；传错字段会在 `TPopup.show` / `TPopupHandle.open` 时抛 `FlutterError` | +命名工厂只暴露当前方向生效的字段（例如 `TPopupOptions.bottom` 无 `width` 参数）。 +## 字段与 `TPopupPlacement` +| `TPopupPlacement` | 头部 / 关闭区 | 尺寸 | +|-------------------|-------------|------| +| `TPopupPlacement.bottom` | `headerBuilder`、`titleWidget`、`cancelBuilder`、`confirmBuilder` | `height`、`inset` | +| `TPopupPlacement.center` | `closeBuilder` | `width`、`height` | +| `TPopupPlacement.top` | — | `height`、`inset` | +| `TPopupPlacement.left`、`TPopupPlacement.right` | — | `width`、`inset` | +`inset` 须为与 `placement` 匹配的类型（如 bottom 用 `TPopupBottomInset`），否则校验失败。 +## Builder 三态（`headerBuilder`、`cancelBuilder`、`confirmBuilder`、`closeBuilder`） +| 传参方式 | 效果 | +|----------|------| +| 省略（使用默认值） | 渲染内置 UI | +| 显式 `null` | 隐藏该区域 | +| 自定义 `TPopupHeaderBuilder` / `TPopupSlotBuilder` | 完全替换；需自行提供交互与语义，可调用 `close` 关闭浮层 | +`titleWidget` 默认为 `null`，表示无标题内容。 +生命周期回调见 `onOpen`、`onOpened`、`onClose`、`onClosed`、`onVisibleChange`、`onOverlayClick`。 +## modal 与 showOverlay 组合 +| modal | showOverlay | 表现 | +|-------|-------------|------| +| true | true | 标准模态弹层（半透明蒙层 + 阻断背景） | +| true | false | 透明模态弹层（无可见蒙层，仍阻断背景） | +| false | false | 非模态浮层（不阻断背景） | +## closeOnOverlayClick +构造参数类型为 `bool?`。省略（`null`）时按 `showOverlay` 推导：有蒙层为 true，无蒙层为 false。 +通过 `closeOnOverlayClick` getter 读取解析后的 `bool` 值。 - | [TPopupPlacement] | 头部 / 关闭区 | 尺寸 | - |-------------------|-------------|------| - | [TPopupPlacement.bottom] | [headerBuilder]、[titleWidget]、[cancelBuilder]、[confirmBuilder] | [height]、[inset] | - | [TPopupPlacement.center] | [closeBuilder] | [width]、[height] | - | [TPopupPlacement.top] | — | [height]、[inset] | - | [TPopupPlacement.left]、[TPopupPlacement.right] | — | [width]、[inset] | - - ## Builder 三态（[headerBuilder]、[cancelBuilder]、[confirmBuilder]、[closeBuilder]） +#### 工厂构造方法 - | 传参方式 | 效果 | - |----------|------| - | 省略（使用默认值） | 渲染内置 UI | - | 显式 `null` | 隐藏该区域 | - | 自定义 [TPopupHeaderBuilder] / [TPopupSlotBuilder] | 完全替换；需自行提供交互与语义，可调用 `close` 关闭浮层 | +##### 通用参数 - [titleWidget] 默认为 `null`，表示无标题内容。 - - 生命周期回调见 [onOpen]、[onOpened]、[onClose]、[onClosed]、[onVisibleChange]、[onOverlayClick]。 -#### 默认构造方法 +以下参数由各命名工厂统一透传，含义一致： | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| animationDuration | Duration | const Duration(milliseconds: 240) | 打开/关闭动画时长。 | +| animationDuration | Duration | const Duration(milliseconds: 240) | 打开/关闭动画时长，默认 240ms。 | | backgroundColor | Color? | - | 内容区背景色，默认主题容器色。 | -| cancelBuilder | TPopupSlotBuilder? | _kPopupDefaultCancel | bottom 左侧操作槽；仅 [headerBuilder] 为内置默认时生效。 内置默认为「取消」，点击触发 [TPopupTrigger.cancel]。 | | child | Widget | - | 浮层主体内容（必填）。 | -| closeBuilder | TPopupSlotBuilder? | _kPopupDefaultClose | center 面板外下方关闭区；仅 [TPopupPlacement.center] 生效。三态见类文档「Builder 三态」。 内置默认点击触发 [TPopupTrigger.close]。 | | closeOnOverlayClick | bool? | - | - | -| confirmBuilder | TPopupSlotBuilder? | _kPopupDefaultConfirm | bottom 右侧操作槽；仅 [headerBuilder] 为内置默认时生效。 内置默认为「确定」，点击触发 [TPopupTrigger.confirm]。 | -| destroyOnClose | bool | false | 为 true 时路由 `maintainState` 为 false，关闭后不保留路由内 State。 | -| headerBuilder | TPopupHeaderBuilder? | _kPopupDefaultHeader | bottom 头部；仅 [TPopupPlacement.bottom] 生效。三态见类文档「Builder 三态」。 自定义时忽略 [titleWidget]、[cancelBuilder]、[confirmBuilder]。 | -| height | double? | - | 高度；[TPopupPlacement.top]、[TPopupPlacement.bottom] 生效；[TPopupPlacement.center] 约束面板尺寸。 | -| inset | TPopupInset? | - | 交叉轴边缘留白；具体类型由 [placement] 决定。 * [TPopupPlacement.bottom] 使用 [TPopupBottomInset] * [TPopupPlacement.top] 使用 [TPopupTopInset] * [TPopupPlacement.left] 使用 [TPopupLeftInset] * [TPopupPlacement.right] 使用 [TPopupRightInset] * [TPopupPlacement.center] 不支持 | -| modal | bool | true | 是否以模态方式展示；为 true 时阻断背景交互与底层语义/焦点。 结合 [showOverlay] 可表达三种模式： * `modal=true, showOverlay=true`：标准模态弹层 * `modal=true, showOverlay=false`：透明模态弹层 * `modal=false, showOverlay=false`：非模态浮层 | -| onClose | VoidCallback? | - | 开始关闭（与 [onVisibleChange] 的 `visible: false` 同期）。 | -| onClosed | VoidCallback? | - | 当前展示周期真正结束。 大多数场景下会在关闭动画结束后触发；非栈顶路由被直接移除时不保证存在关闭动画。 | -| onOpen | VoidCallback? | - | 路由 push 时（打开动画开始前）。 | -| onOpened | VoidCallback? | - | 打开动画结束。 | -| onOverlayClick | VoidCallback? | - | 蒙层点击；是否关闭取决于 [closeOnOverlayClick]。 | -| onVisibleChange | TPopupVisibleChangeCallback? | - | 显隐变化；第二个参数为 [TPopupTrigger]。 | +| destroyOnClose | bool | false | 关闭后销毁路由 State（`maintainState=false`），默认 false。 | +| modal | bool | true | 是否模态展示；为 true 时阻断背景交互与语义/焦点（与 `showOverlay` 组合见类文档）。 | +| onClose | VoidCallback? | - | 开始关闭时触发（与 [onVisibleChange](false, …) 同期）。 | +| onClosed | VoidCallback? | - | 展示周期结束触发；通常于关闭动画结束后，被直接移除时可能无动画。 | +| onOpen | VoidCallback? | - | 路由 push 时触发（打开动画开始前）。 | +| onOpened | VoidCallback? | - | 打开动画结束后触发。 | +| onOverlayClick | VoidCallback? | - | 蒙层点击回调；是否关闭由 `closeOnOverlayClick` 决定。 | +| onVisibleChange | TPopupVisibleChangeCallback? | - | 显隐变化回调；第二参数为 `TPopupTrigger`。 | | overlayColor | Color? | - | 蒙层颜色，默认 black54。 | -| overlayOpacity | double? | - | 蒙层透明度系数（0–1），与 [overlayColor] 的 alpha 相乘后用于绘制。 | -| placement | TPopupPlacement | TPopupPlacement.bottom | 出现位置，默认 [TPopupPlacement.bottom]。 | +| overlayOpacity | double? | - | 蒙层透明度系数（0–1），与 `overlayColor` 的 alpha 相乘后用于绘制。 | | radius | double? | - | 内容区圆角，默认主题大圆角。 | -| showOverlay | bool | true | 是否绘制半透明蒙层。 当 [modal] 为 true 且此值为 false 时，为“透明模态弹层”。 | -| titleWidget | Widget? | - | bottom 标题插槽；仅 [headerBuilder] 为内置默认时生效。`null` 表示无标题。 | -| width | double? | - | 宽度；[TPopupPlacement.left]、[TPopupPlacement.right]、[TPopupPlacement.center] 生效。 | +| showOverlay | bool | true | 是否绘制蒙层；`modal`=true 且此值为 false 时为透明模态（见类文档「modal 与 showOverlay 组合」）。 | +| useSafeArea | bool | true | 是否避让系统安全区，默认 true；仅贴边方向生效，`TPopupPlacement.center` 忽略，与 `inset` 叠加。 | -#### 工厂构造方法 - ##### TPopupOptions.bottom -创建 [TPopupPlacement.bottom] 配置。 +创建 bottom 配置：固定 `placement`，默认内置头部，其余字段见成员文档。 - 固定 [placement] 为 [TPopupPlacement.bottom]；默认带内置头部。 - 蒙层、动画、生命周期等字段语义见同名成员文档。 +其余参数见「通用参数」。 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| child | Widget | - | 浮层主体内容（必填）。 | -| height | double? | - | 高度；[TPopupPlacement.top]、[TPopupPlacement.bottom] 生效；[TPopupPlacement.center] 约束面板尺寸。 | -| inset | TPopupBottomInset? | - | 交叉轴边缘留白；具体类型由 [placement] 决定。 * [TPopupPlacement.bottom] 使用 [TPopupBottomInset] * [TPopupPlacement.top] 使用 [TPopupTopInset] * [TPopupPlacement.left] 使用 [TPopupLeftInset] * [TPopupPlacement.right] 使用 [TPopupRightInset] * [TPopupPlacement.center] 不支持 | -| headerBuilder | TPopupHeaderBuilder? | _kPopupDefaultHeader | bottom 头部；仅 [TPopupPlacement.bottom] 生效。三态见类文档「Builder 三态」。 自定义时忽略 [titleWidget]、[cancelBuilder]、[confirmBuilder]。 | -| titleWidget | Widget? | - | bottom 标题插槽；仅 [headerBuilder] 为内置默认时生效。`null` 表示无标题。 | -| cancelBuilder | TPopupSlotBuilder? | _kPopupDefaultCancel | bottom 左侧操作槽；仅 [headerBuilder] 为内置默认时生效。 内置默认为「取消」，点击触发 [TPopupTrigger.cancel]。 | -| confirmBuilder | TPopupSlotBuilder? | _kPopupDefaultConfirm | bottom 右侧操作槽；仅 [headerBuilder] 为内置默认时生效。 内置默认为「确定」，点击触发 [TPopupTrigger.confirm]。 | -| radius | double? | - | 内容区圆角，默认主题大圆角。 | -| backgroundColor | Color? | - | 内容区背景色，默认主题容器色。 | -| showOverlay | bool | true | 是否绘制半透明蒙层。 当 [modal] 为 true 且此值为 false 时，为“透明模态弹层”。 | -| closeOnOverlayClick | bool? | - | - | -| overlayColor | Color? | - | 蒙层颜色，默认 black54。 | -| overlayOpacity | double? | - | 蒙层透明度系数（0–1），与 [overlayColor] 的 alpha 相乘后用于绘制。 | -| modal | bool | true | 是否以模态方式展示；为 true 时阻断背景交互与底层语义/焦点。 结合 [showOverlay] 可表达三种模式： * `modal=true, showOverlay=true`：标准模态弹层 * `modal=true, showOverlay=false`：透明模态弹层 * `modal=false, showOverlay=false`：非模态浮层 | -| destroyOnClose | bool | false | 为 true 时路由 `maintainState` 为 false，关闭后不保留路由内 State。 | -| animationDuration | Duration | const Duration(milliseconds: 240) | 打开/关闭动画时长。 | -| onOpen | VoidCallback? | - | 路由 push 时（打开动画开始前）。 | -| onOpened | VoidCallback? | - | 打开动画结束。 | -| onClose | VoidCallback? | - | 开始关闭（与 [onVisibleChange] 的 `visible: false` 同期）。 | -| onClosed | VoidCallback? | - | 当前展示周期真正结束。 大多数场景下会在关闭动画结束后触发；非栈顶路由被直接移除时不保证存在关闭动画。 | -| onVisibleChange | TPopupVisibleChangeCallback? | - | 显隐变化；第二个参数为 [TPopupTrigger]。 | -| onOverlayClick | VoidCallback? | - | 蒙层点击；是否关闭取决于 [closeOnOverlayClick]。 | +| height | double? | - | 内容高度；top/bottom 传值时固定高度，bottom 省略时由内容撑开；center 用于约束面板尺寸。 | +| inset | TPopupBottomInset? | - | 交叉轴边缘留白，类型须与 `placement` 匹配（见各类 *Inset）；`TPopupPlacement.center` 不支持。 | +| headerBuilder | TPopupHeaderBuilder? | _kPopupDefaultHeader | bottom 头部构建器（仅 bottom）；省略=内置，null=隐藏，自定义见类文档「Builder 三态」。 | +| titleWidget | Widget? | - | bottom 标题（仅内置头部时）；`null` 表示不展示标题。 | +| cancelBuilder | TPopupSlotBuilder? | _kPopupDefaultCancel | bottom 左侧槽（仅内置头部时）；默认「取消」，触发 `TPopupTrigger.cancel`。 | +| confirmBuilder | TPopupSlotBuilder? | _kPopupDefaultConfirm | bottom 右侧槽（仅内置头部时）；默认「确定」，触发 `TPopupTrigger.confirm`。 | ##### TPopupOptions.center -创建 [TPopupPlacement.center] 配置。 +创建 center 配置：固定 `placement`，默认面板外下方圆形关闭按钮。 - 固定 [placement] 为 [TPopupPlacement.center]；默认展示面板外下方圆形关闭按钮。 +其余参数见「通用参数」。 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| child | Widget | - | 浮层主体内容（必填）。 | -| width | double? | - | 宽度；[TPopupPlacement.left]、[TPopupPlacement.right]、[TPopupPlacement.center] 生效。 | -| height | double? | - | 高度；[TPopupPlacement.top]、[TPopupPlacement.bottom] 生效；[TPopupPlacement.center] 约束面板尺寸。 | -| closeBuilder | TPopupSlotBuilder? | _kPopupDefaultClose | center 面板外下方关闭区；仅 [TPopupPlacement.center] 生效。三态见类文档「Builder 三态」。 内置默认点击触发 [TPopupTrigger.close]。 | -| radius | double? | - | 内容区圆角，默认主题大圆角。 | -| backgroundColor | Color? | - | 内容区背景色，默认主题容器色。 | -| showOverlay | bool | true | 是否绘制半透明蒙层。 当 [modal] 为 true 且此值为 false 时，为“透明模态弹层”。 | -| closeOnOverlayClick | bool? | - | - | -| overlayColor | Color? | - | 蒙层颜色，默认 black54。 | -| overlayOpacity | double? | - | 蒙层透明度系数（0–1），与 [overlayColor] 的 alpha 相乘后用于绘制。 | -| modal | bool | true | 是否以模态方式展示；为 true 时阻断背景交互与底层语义/焦点。 结合 [showOverlay] 可表达三种模式： * `modal=true, showOverlay=true`：标准模态弹层 * `modal=true, showOverlay=false`：透明模态弹层 * `modal=false, showOverlay=false`：非模态浮层 | -| destroyOnClose | bool | false | 为 true 时路由 `maintainState` 为 false，关闭后不保留路由内 State。 | -| animationDuration | Duration | const Duration(milliseconds: 240) | 打开/关闭动画时长。 | -| onOpen | VoidCallback? | - | 路由 push 时（打开动画开始前）。 | -| onOpened | VoidCallback? | - | 打开动画结束。 | -| onClose | VoidCallback? | - | 开始关闭（与 [onVisibleChange] 的 `visible: false` 同期）。 | -| onClosed | VoidCallback? | - | 当前展示周期真正结束。 大多数场景下会在关闭动画结束后触发；非栈顶路由被直接移除时不保证存在关闭动画。 | -| onVisibleChange | TPopupVisibleChangeCallback? | - | 显隐变化；第二个参数为 [TPopupTrigger]。 | -| onOverlayClick | VoidCallback? | - | 蒙层点击；是否关闭取决于 [closeOnOverlayClick]。 | +| width | double? | - | 内容宽度；仅 `TPopupPlacement.left`、`TPopupPlacement.right`、`TPopupPlacement.center` 生效。 | +| height | double? | - | 内容高度；top/bottom 传值时固定高度，bottom 省略时由内容撑开；center 用于约束面板尺寸。 | +| closeBuilder | TPopupSlotBuilder? | _kPopupDefaultClose | center 面板外下方关闭区（仅 center）；默认圆形关闭，触发 `TPopupTrigger.close`。 | ##### TPopupOptions.left -创建 [TPopupPlacement.left] 配置。 +创建 left 配置：固定 `placement`，未传 `width` 时默认 280。 - 固定 [placement] 为 [TPopupPlacement.left]；未传 [width] 时布局默认宽度 280。 +其余参数见「通用参数」。 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| child | Widget | - | 浮层主体内容（必填）。 | -| width | double? | - | 宽度；[TPopupPlacement.left]、[TPopupPlacement.right]、[TPopupPlacement.center] 生效。 | -| inset | TPopupLeftInset? | - | 交叉轴边缘留白；具体类型由 [placement] 决定。 * [TPopupPlacement.bottom] 使用 [TPopupBottomInset] * [TPopupPlacement.top] 使用 [TPopupTopInset] * [TPopupPlacement.left] 使用 [TPopupLeftInset] * [TPopupPlacement.right] 使用 [TPopupRightInset] * [TPopupPlacement.center] 不支持 | -| radius | double? | - | 内容区圆角，默认主题大圆角。 | -| backgroundColor | Color? | - | 内容区背景色，默认主题容器色。 | -| showOverlay | bool | true | 是否绘制半透明蒙层。 当 [modal] 为 true 且此值为 false 时，为“透明模态弹层”。 | -| closeOnOverlayClick | bool? | - | - | -| overlayColor | Color? | - | 蒙层颜色，默认 black54。 | -| overlayOpacity | double? | - | 蒙层透明度系数（0–1），与 [overlayColor] 的 alpha 相乘后用于绘制。 | -| modal | bool | true | 是否以模态方式展示；为 true 时阻断背景交互与底层语义/焦点。 结合 [showOverlay] 可表达三种模式： * `modal=true, showOverlay=true`：标准模态弹层 * `modal=true, showOverlay=false`：透明模态弹层 * `modal=false, showOverlay=false`：非模态浮层 | -| destroyOnClose | bool | false | 为 true 时路由 `maintainState` 为 false，关闭后不保留路由内 State。 | -| animationDuration | Duration | const Duration(milliseconds: 240) | 打开/关闭动画时长。 | -| onOpen | VoidCallback? | - | 路由 push 时（打开动画开始前）。 | -| onOpened | VoidCallback? | - | 打开动画结束。 | -| onClose | VoidCallback? | - | 开始关闭（与 [onVisibleChange] 的 `visible: false` 同期）。 | -| onClosed | VoidCallback? | - | 当前展示周期真正结束。 大多数场景下会在关闭动画结束后触发；非栈顶路由被直接移除时不保证存在关闭动画。 | -| onVisibleChange | TPopupVisibleChangeCallback? | - | 显隐变化；第二个参数为 [TPopupTrigger]。 | -| onOverlayClick | VoidCallback? | - | 蒙层点击；是否关闭取决于 [closeOnOverlayClick]。 | +| width | double? | - | 内容宽度；仅 `TPopupPlacement.left`、`TPopupPlacement.right`、`TPopupPlacement.center` 生效。 | +| inset | TPopupLeftInset? | - | 交叉轴边缘留白，类型须与 `placement` 匹配（见各类 *Inset）；`TPopupPlacement.center` 不支持。 | ##### TPopupOptions.right -创建 [TPopupPlacement.right] 配置。 +创建 right 配置：固定 `placement`，未传 `width` 时默认 280。 - 固定 [placement] 为 [TPopupPlacement.right]；未传 [width] 时布局默认宽度 280。 +其余参数见「通用参数」。 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| child | Widget | - | 浮层主体内容（必填）。 | -| width | double? | - | 宽度；[TPopupPlacement.left]、[TPopupPlacement.right]、[TPopupPlacement.center] 生效。 | -| inset | TPopupRightInset? | - | 交叉轴边缘留白；具体类型由 [placement] 决定。 * [TPopupPlacement.bottom] 使用 [TPopupBottomInset] * [TPopupPlacement.top] 使用 [TPopupTopInset] * [TPopupPlacement.left] 使用 [TPopupLeftInset] * [TPopupPlacement.right] 使用 [TPopupRightInset] * [TPopupPlacement.center] 不支持 | -| radius | double? | - | 内容区圆角，默认主题大圆角。 | -| backgroundColor | Color? | - | 内容区背景色，默认主题容器色。 | -| showOverlay | bool | true | 是否绘制半透明蒙层。 当 [modal] 为 true 且此值为 false 时，为“透明模态弹层”。 | -| closeOnOverlayClick | bool? | - | - | -| overlayColor | Color? | - | 蒙层颜色，默认 black54。 | -| overlayOpacity | double? | - | 蒙层透明度系数（0–1），与 [overlayColor] 的 alpha 相乘后用于绘制。 | -| modal | bool | true | 是否以模态方式展示；为 true 时阻断背景交互与底层语义/焦点。 结合 [showOverlay] 可表达三种模式： * `modal=true, showOverlay=true`：标准模态弹层 * `modal=true, showOverlay=false`：透明模态弹层 * `modal=false, showOverlay=false`：非模态浮层 | -| destroyOnClose | bool | false | 为 true 时路由 `maintainState` 为 false，关闭后不保留路由内 State。 | -| animationDuration | Duration | const Duration(milliseconds: 240) | 打开/关闭动画时长。 | -| onOpen | VoidCallback? | - | 路由 push 时（打开动画开始前）。 | -| onOpened | VoidCallback? | - | 打开动画结束。 | -| onClose | VoidCallback? | - | 开始关闭（与 [onVisibleChange] 的 `visible: false` 同期）。 | -| onClosed | VoidCallback? | - | 当前展示周期真正结束。 大多数场景下会在关闭动画结束后触发；非栈顶路由被直接移除时不保证存在关闭动画。 | -| onVisibleChange | TPopupVisibleChangeCallback? | - | 显隐变化；第二个参数为 [TPopupTrigger]。 | -| onOverlayClick | VoidCallback? | - | 蒙层点击；是否关闭取决于 [closeOnOverlayClick]。 | +| width | double? | - | 内容宽度；仅 `TPopupPlacement.left`、`TPopupPlacement.right`、`TPopupPlacement.center` 生效。 | +| inset | TPopupRightInset? | - | 交叉轴边缘留白，类型须与 `placement` 匹配（见各类 *Inset）；`TPopupPlacement.center` 不支持。 | ##### TPopupOptions.top -创建 [TPopupPlacement.top] 配置。 +创建 top 配置：固定 `placement`，无内置头部。 - 固定 [placement] 为 [TPopupPlacement.top]；无内置头部。 +其余参数见「通用参数」。 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| child | Widget | - | 浮层主体内容（必填）。 | -| height | double? | - | 高度；[TPopupPlacement.top]、[TPopupPlacement.bottom] 生效；[TPopupPlacement.center] 约束面板尺寸。 | -| inset | TPopupTopInset? | - | 交叉轴边缘留白；具体类型由 [placement] 决定。 * [TPopupPlacement.bottom] 使用 [TPopupBottomInset] * [TPopupPlacement.top] 使用 [TPopupTopInset] * [TPopupPlacement.left] 使用 [TPopupLeftInset] * [TPopupPlacement.right] 使用 [TPopupRightInset] * [TPopupPlacement.center] 不支持 | -| radius | double? | - | 内容区圆角，默认主题大圆角。 | +| height | double? | - | 内容高度；top/bottom 传值时固定高度，bottom 省略时由内容撑开；center 用于约束面板尺寸。 | +| inset | TPopupTopInset? | - | 交叉轴边缘留白，类型须与 `placement` 匹配（见各类 *Inset）；`TPopupPlacement.center` 不支持。 | + +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| animationDuration | Duration | const Duration(milliseconds: 240) | 打开/关闭动画时长，默认 240ms。 | | backgroundColor | Color? | - | 内容区背景色，默认主题容器色。 | -| showOverlay | bool | true | 是否绘制半透明蒙层。 当 [modal] 为 true 且此值为 false 时，为“透明模态弹层”。 | +| cancelBuilder | TPopupSlotBuilder? | _kPopupDefaultCancel | bottom 左侧槽（仅内置头部时）；默认「取消」，触发 `TPopupTrigger.cancel`。 | +| child | Widget | - | 浮层主体内容（必填）。 | +| closeBuilder | TPopupSlotBuilder? | _kPopupDefaultClose | center 面板外下方关闭区（仅 center）；默认圆形关闭，触发 `TPopupTrigger.close`。 | | closeOnOverlayClick | bool? | - | - | +| confirmBuilder | TPopupSlotBuilder? | _kPopupDefaultConfirm | bottom 右侧槽（仅内置头部时）；默认「确定」，触发 `TPopupTrigger.confirm`。 | +| destroyOnClose | bool | false | 关闭后销毁路由 State（`maintainState=false`），默认 false。 | +| headerBuilder | TPopupHeaderBuilder? | _kPopupDefaultHeader | bottom 头部构建器（仅 bottom）；省略=内置，null=隐藏，自定义见类文档「Builder 三态」。 | +| height | double? | - | 内容高度；top/bottom 传值时固定高度，bottom 省略时由内容撑开；center 用于约束面板尺寸。 | +| inset | TPopupInset? | - | 交叉轴边缘留白，类型须与 `placement` 匹配（见各类 *Inset）；`TPopupPlacement.center` 不支持。 | +| modal | bool | true | 是否模态展示；为 true 时阻断背景交互与语义/焦点（与 `showOverlay` 组合见类文档）。 | +| onClose | VoidCallback? | - | 开始关闭时触发（与 [onVisibleChange](false, …) 同期）。 | +| onClosed | VoidCallback? | - | 展示周期结束触发；通常于关闭动画结束后，被直接移除时可能无动画。 | +| onOpen | VoidCallback? | - | 路由 push 时触发（打开动画开始前）。 | +| onOpened | VoidCallback? | - | 打开动画结束后触发。 | +| onOverlayClick | VoidCallback? | - | 蒙层点击回调；是否关闭由 `closeOnOverlayClick` 决定。 | +| onVisibleChange | TPopupVisibleChangeCallback? | - | 显隐变化回调；第二参数为 `TPopupTrigger`。 | | overlayColor | Color? | - | 蒙层颜色，默认 black54。 | -| overlayOpacity | double? | - | 蒙层透明度系数（0–1），与 [overlayColor] 的 alpha 相乘后用于绘制。 | -| modal | bool | true | 是否以模态方式展示；为 true 时阻断背景交互与底层语义/焦点。 结合 [showOverlay] 可表达三种模式： * `modal=true, showOverlay=true`：标准模态弹层 * `modal=true, showOverlay=false`：透明模态弹层 * `modal=false, showOverlay=false`：非模态浮层 | -| destroyOnClose | bool | false | 为 true 时路由 `maintainState` 为 false，关闭后不保留路由内 State。 | -| animationDuration | Duration | const Duration(milliseconds: 240) | 打开/关闭动画时长。 | -| onOpen | VoidCallback? | - | 路由 push 时（打开动画开始前）。 | -| onOpened | VoidCallback? | - | 打开动画结束。 | -| onClose | VoidCallback? | - | 开始关闭（与 [onVisibleChange] 的 `visible: false` 同期）。 | -| onClosed | VoidCallback? | - | 当前展示周期真正结束。 大多数场景下会在关闭动画结束后触发；非栈顶路由被直接移除时不保证存在关闭动画。 | -| onVisibleChange | TPopupVisibleChangeCallback? | - | 显隐变化；第二个参数为 [TPopupTrigger]。 | -| onOverlayClick | VoidCallback? | - | 蒙层点击；是否关闭取决于 [closeOnOverlayClick]。 | +| overlayOpacity | double? | - | 蒙层透明度系数（0–1），与 `overlayColor` 的 alpha 相乘后用于绘制。 | +| placement | TPopupPlacement | TPopupPlacement.bottom | 弹出位置，默认 `TPopupPlacement.bottom`。 | +| radius | double? | - | 内容区圆角，默认主题大圆角。 | +| showOverlay | bool | true | 是否绘制蒙层；`modal`=true 且此值为 false 时为透明模态（见类文档「modal 与 showOverlay 组合」）。 | +| titleWidget | Widget? | - | bottom 标题（仅内置头部时）；`null` 表示不展示标题。 | +| useSafeArea | bool | true | 是否避让系统安全区，默认 true；仅贴边方向生效，`TPopupPlacement.center` 忽略，与 `inset` 叠加。 | +| width | double? | - | 内容宽度；仅 `TPopupPlacement.left`、`TPopupPlacement.right`、`TPopupPlacement.center` 生效。 | ### TPopupHandle #### 简介 -[TPopup.show] 的返回值，用于控制同一份 [TPopupOptions] 的多次打开与关闭。 - - **示例** - - ```dart - final handle = TPopup.show( - context, - options: TPopupOptions.bottom(child: panel), - ); - handle.close(); - handle.open(); // 可省略 context，复用已缓存的 Navigator - ``` +`TPopup.show` 的返回值，用于控制同一份 `TPopupOptions` 的多次打开与关闭。 #### 公开属性 | 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| navigatorContext | BuildContext? | - | 与 [TPopup.show] 的 [navigatorContext] 相同。 | -| options | TPopupOptions | - | 创建时传入的配置；每次 [open] 会按 [TPopupOptions.placement] 裁剪无效字段后使用。 | -| useRootNavigator | bool | - | 与 [TPopup.show] 的 [useRootNavigator] 相同。 | +| navigatorContext | BuildContext? | - | 与 `TPopup.show` 的 `navigatorContext` 相同。 | +| options | TPopupOptions | - | 创建时传入的配置；每次 `open` 会按 `TPopupOptions.placement` 裁剪无效字段后使用。 | +| useRootNavigator | bool | - | 与 `TPopup.show` 的 `useRootNavigator` 相同。 | -#### 工厂构造方法 +### TPopupInset +#### 简介 +Popup 在交叉轴方向的边缘留白基类。 -##### TPopupHandle._ +### TPopupBottomInset +#### 简介 +`TPopupPlacement.bottom` 的 `TPopupOptions.inset`：内容区相对屏幕左右的留白。 +#### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | -| options | TPopupOptions | - | 创建时传入的配置；每次 [open] 会按 [TPopupOptions.placement] 裁剪无效字段后使用。 | -| navigatorContext | BuildContext? | - | 与 [TPopup.show] 的 [navigatorContext] 相同。 | -| useRootNavigator | bool | false | 与 [TPopup.show] 的 [useRootNavigator] 相同。 | +| left | double | 0 | - | +| right | double | 0 | - | -### TPopupPlacement +### TPopupTopInset #### 简介 -浮层出现方向；决定 [TPopupOptions] 中哪些字段生效。 +`TPopupPlacement.top` 的 `TPopupOptions.inset`：内容区相对屏幕左右的留白。 +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| left | double | 0 | - | +| right | double | 0 | - | - 与 [TPopupOptions] 类文档中的「字段与 placement」表对应。 - 方向固定时请用 [TPopupOptions.bottom]、[TPopupOptions.center] 等命名工厂。 + +### TPopupLeftInset +#### 简介 +`TPopupPlacement.left` 的 `TPopupOptions.inset`：内容区相对屏幕上下的留白。 +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| bottom | double | 0 | - | +| top | double | 0 | - | + + +### TPopupRightInset +#### 简介 +`TPopupPlacement.right` 的 `TPopupOptions.inset`：内容区相对屏幕上下的留白。 +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| bottom | double | 0 | - | +| top | double | 0 | - | + + +### TPopupPlacement +#### 简介 +浮层出现方向；决定 `TPopupOptions` 中哪些字段生效。 +与 `TPopupOptions` 类文档中的「字段与 placement」表对应。 +方向固定时请用 `TPopupOptions.bottom`、`TPopupOptions.center` 等命名工厂。 #### 枚举值 | 名称 | 说明 | | --- | --- | -| top | 自顶部滑入；使用 [TPopupOptions.height]、[TPopupOptions.inset]（[TPopupTopInset]）。 | -| left | 自左侧滑入；使用 [TPopupOptions.width]、[TPopupOptions.inset]（[TPopupLeftInset]）。 | -| right | 自右侧滑入；使用 [TPopupOptions.width]、[TPopupOptions.inset]（[TPopupRightInset]）。 | -| bottom | 自底部滑入；默认内置头部；使用 [TPopupOptions.height]、[TPopupOptions.inset]（[TPopupBottomInset]）。 | -| center | 屏幕居中；使用 [TPopupOptions.closeBuilder] 控制面板外下方关闭区。 | +| top | 自顶部滑入；无内置头部；使用 `TPopupOptions.height`、`TPopupOptions.inset`（`TPopupTopInset`）。 | +| left | 自左侧滑入；无内置头部；使用 `TPopupOptions.width`、`TPopupOptions.inset`（`TPopupLeftInset`）；未传 `width` 默认 280。 | +| right | 自右侧滑入；无内置头部；使用 `TPopupOptions.width`、`TPopupOptions.inset`（`TPopupRightInset`）；未传 `width` 默认 280。 | +| bottom | 自底部滑入；默认内置头部；使用 `TPopupOptions.height`、`TPopupOptions.inset`（`TPopupBottomInset`）。 | +| center | 屏幕居中弹出；默认面板外下方关闭按钮；使用 `TPopupOptions.width`、`TPopupOptions.height`、`TPopupOptions.closeBuilder`；不支持 `TPopupOptions.inset`。 | ### TPopupTrigger #### 简介 浮层关闭或显隐变化时的触发来源。 - - 作为 [TPopupVisibleChangeCallback] 的第二个参数，以及关闭流程中的语义标记。 - - 内置控件会映射为 [TPopupTrigger.overlay]、[TPopupTrigger.cancel]、 - [TPopupTrigger.confirm]、[TPopupTrigger.close]； - [TPopupHandle.close] 为 [TPopupTrigger.api]；系统返回为 - [TPopupTrigger.systemBack]；[headerBuilder] 内调用 `close` 等为 - [TPopupTrigger.custom]。 +作为 `TPopupVisibleChangeCallback` 的第二个参数，以及关闭流程中的语义标记。 +内置控件会映射为 `TPopupTrigger.overlay`、`TPopupTrigger.cancel`、 +`TPopupTrigger.confirm`、`TPopupTrigger.close`； +`TPopupHandle.close` 为 `TPopupTrigger.api`；系统返回为 +`TPopupTrigger.systemBack`；`headerBuilder` 内调用 `close` 等为 +`TPopupTrigger.custom`。 #### 枚举值 | 名称 | 说明 | | --- | --- | -| overlay | 点击蒙层，且 [TPopupOptions.closeOnOverlayClick] 为 true。 | -| cancel | 点击 bottom 取消语义槽位（含默认与自定义 [TPopupOptions.cancelBuilder]）。 | -| confirm | 点击 bottom 确认语义槽位（含默认与自定义 [TPopupOptions.confirmBuilder]）。 | -| close | 点击 center 关闭语义槽位（含默认与自定义 [TPopupOptions.closeBuilder]）。 | -| api | 外部 API 主动触发的显隐变化，如 [TPopupHandle.close] 或打开事件。 | +| overlay | 点击蒙层，且 `TPopupOptions.closeOnOverlayClick` 为 true。 | +| cancel | 点击 bottom 取消语义槽位（含默认与自定义 `TPopupOptions.cancelBuilder`）。 | +| confirm | 点击 bottom 确认语义槽位（含默认与自定义 `TPopupOptions.confirmBuilder`）。 | +| close | 点击 center 关闭语义槽位（含默认与自定义 `TPopupOptions.closeBuilder`）。 | +| api | 外部 API 主动触发的显隐变化，如 `TPopupHandle.close` 或打开事件。 | | systemBack | 系统返回键或系统路由返回触发的关闭。 | -| custom | 无框架预设动作语义的自定义关闭，如 [headerBuilder] 内调用 `close`。 | +| custom | 无框架预设动作语义的自定义关闭，如 `headerBuilder` 内调用 `close`。 | \ No newline at end of file diff --git a/tdesign-site/src/pull-down-refresh/README.md b/tdesign-site/src/pull-down-refresh/README.md index 8bc3e0705..ba2157fc6 100644 --- a/tdesign-site/src/pull-down-refresh/README.md +++ b/tdesign-site/src/pull-down-refresh/README.md @@ -84,7 +84,7 @@ import 'package:easy_refresh/easy_refresh.dart'; ### TRefreshHeader #### 简介 TDesign刷新头部 - 结合EasyRefresh类实现下拉刷新,继承自Header类，字段含义与父类一致 +结合EasyRefresh类实现下拉刷新,继承自Header类，字段含义与父类一致 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -109,7 +109,7 @@ TDesign刷新头部 | loadingIcon | TLoadingIcon | TLoadingIcon.circle | loading样式 | | maxOverOffset | - | - | - | | notifyWhenInvisible | - | - | - | -| overScroll | bool | true | 越界滚动([enableInfiniteRefresh]为true或[infiniteOffset]有值时生效) | +| overScroll | bool | true | 越界滚动(`enableInfiniteRefresh`为true或`infiniteOffset`有值时生效) | | position | - | - | - | | processedDuration | Duration? | - | - | | readySpringBuilder | - | - | - | @@ -120,7 +120,7 @@ TDesign刷新头部 | secondaryVelocity | - | - | - | | spring | - | - | - | | springRebound | - | - | - | -| triggerDistance | double | 48.0 | 触发刷新任务的偏移量，同[triggerOffset] | +| triggerDistance | double | 48.0 | 触发刷新任务的偏移量，同`triggerOffset` | | triggerOffset | double? | - | - | | triggerWhenReach | - | - | - | | triggerWhenRelease | - | - | - | diff --git a/tdesign-site/src/radio/README.md b/tdesign-site/src/radio/README.md index 4c9136787..3edc13fa6 100644 --- a/tdesign-site/src/radio/README.md +++ b/tdesign-site/src/radio/README.md @@ -368,10 +368,9 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TRadioGroup #### 简介 RadioGroup分组对象，继承自TCheckboxGroup，字段含义与父类一致 - RadioGroup应该嵌套在RadioGroup内，所有在RadioGroup的RadioButton只能有一个被选中 - - cardMode: 使用卡片样式，需要配合direction 和 directionalTdRadios 使用， - 组合为横向、纵向卡片，同时需要在每个TRadio上设置cardMode参数。 +RadioGroup应该嵌套在RadioGroup内，所有在RadioGroup的RadioButton只能有一个被选中 +cardMode: 使用卡片样式，需要配合direction 和 directionalTdRadios 使用， +组合为横向、纵向卡片，同时需要在每个TRadio上设置cardMode参数。 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-site/src/rate/README.md b/tdesign-site/src/rate/README.md index 5d53b6ba7..4631d4303 100644 --- a/tdesign-site/src/rate/README.md +++ b/tdesign-site/src/rate/README.md @@ -212,28 +212,30 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ## API ### TRate +#### 简介 +评分组件 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | allowHalf | bool? | false | 是否允许半选 | -| builderText | Widget Function(BuildContext context, double value)? | - | 评分等级对应的辅助文字自定义构建，优先级高于[texts] 配置后，会忽略[texts],[textWidth],[iconTextGap] | -| color | List? | - | 评分图标的颜色，示例：[选中颜色] / [选中颜色，未选中颜色]，默认：[TTheme.of(context).warningColor5, TTheme.of(context).grayColor4] | +| builderText | Widget Function(BuildContext context, double value)? | - | 评分等级对应的辅助文字自定义构建，优先级高于`texts` 配置后，会忽略`texts`,`textWidth`,`iconTextGap` | +| color | List? | - | 评分图标的颜色，示例：`选中颜色` / `选中颜色，未选中颜色`，默认：`TTheme.of(context).warningColor5, TTheme.of(context).grayColor4` | | count | int? | 5 | 评分的数量 | | crossAxisAlignment | CrossAxisAlignment? | CrossAxisAlignment.center | 评分图标与辅助文字的交叉轴对齐方式 | | direction | Axis? | Axis.horizontal | 评分图标与辅助文字的布局方向 | | disabled | bool? | false | 是否禁用评分 | | gap | double? | - | 评分图标的间距，默认：TTheme.of(context).spacer8 | -| icon | List? | - | 自定义评分图标，[选中和未选中图标] / [选中图标，未选中图标]，默认：[TIcons.star_filled] | -| iconTextGap | double? | - | 评分图标与辅助文字的间距，默认：[TTheme.of(context).spacer16] | +| icon | List? | - | 自定义评分图标，`选中和未选中图标` / `选中图标，未选中图标`，默认：`TIcons.star_filled` | +| iconTextGap | double? | - | 评分图标与辅助文字的间距，默认：`TTheme.of(context).spacer16` | | key | Key? | - | 组件标识，用于区分或保留组件状态。 | | mainAxisAlignment | MainAxisAlignment? | MainAxisAlignment.start | 评分图标与辅助文字的主轴对齐方式 | | mainAxisSize | MainAxisSize? | MainAxisSize.min | 评分图标与辅助文字主轴方向上如何占用空间 | | onChange | void Function(double value)? | - | 评分数改变时触发 | -| placement | PlacementEnum? | PlacementEnum.top | 选择评分弹框的位置，值为[PlacementEnum.none]表示不显示评分弹框。 | +| placement | PlacementEnum? | PlacementEnum.top | 选择评分弹框的位置，值为`PlacementEnum.none`表示不显示评分弹框。 | | showText | bool? | false | 是否显示对应的辅助文字 | | size | double? | 24.0 | 评分图标的大小 | -| texts | List? | const ['极差', '失望', '一般', '满意', '惊喜'] | 评分等级对应的辅助文字， 当[allowHalf]为false时长度应与[count]一致， 当[allowHalf]为true时长度应为[count]的两倍， 自定义值示例：['1分', '2分', '3分', '4分', '5分']。 | +| texts | List? | const ['极差', '失望', '一般', '满意', '惊喜'] | 评分等级对应的辅助文字， 当`allowHalf`为false时长度应与`count`一致， 当`allowHalf`为true时长度应为`count`的两倍， 自定义值示例：`'1分', '2分', '3分', '4分', '5分'`。 | | textWidth | double? | 48.0 | 评分等级对应的辅助文字宽度 | | value | double? | 0 | 选择评分的值 | diff --git a/tdesign-site/src/slider/README.md b/tdesign-site/src/slider/README.md index 6e309ab97..84c0739b2 100644 --- a/tdesign-site/src/slider/README.md +++ b/tdesign-site/src/slider/README.md @@ -767,6 +767,8 @@ onThumbTextTap ## API ### TSlider +#### 简介 +单滑动选择器 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -785,6 +787,8 @@ onThumbTextTap ### TRangeSlider +#### 简介 +范围滑动选择器 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-site/src/stepper/README.md b/tdesign-site/src/stepper/README.md index 6c8d1f950..de5854a37 100644 --- a/tdesign-site/src/stepper/README.md +++ b/tdesign-site/src/stepper/README.md @@ -116,6 +116,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ## API ### TStepper +#### 简介 +步进器 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-site/src/steps/README.md b/tdesign-site/src/steps/README.md index e23a2da3f..521501ce9 100644 --- a/tdesign-site/src/steps/README.md +++ b/tdesign-site/src/steps/README.md @@ -704,6 +704,8 @@ Vertical Customize Steps 垂直自定义步骤条 ## API ### TSteps +#### 简介 +Steps步骤条 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -719,6 +721,8 @@ Vertical Customize Steps 垂直自定义步骤条 ### TStepsItemData +#### 简介 +Steps步骤条数据类型 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-site/src/swipe-cell/README.md b/tdesign-site/src/swipe-cell/README.md index 0947a8d2e..dc4da7579 100644 --- a/tdesign-site/src/swipe-cell/README.md +++ b/tdesign-site/src/swipe-cell/README.md @@ -340,34 +340,13 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TSwipeCell #### 简介 滑动单元格组件 -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| cell | Widget | - | 单元格 [TCell] | -| closeWhenOpened | bool? | true | 当同一组（[groupTag]）中的一个[TSwipeCell]打开时，是否关闭组中的所有其他[TSwipeCell] | -| closeWhenTapped | bool? | true | 当同一组（[groupTag]）中的一个[TSwipeCell]被点击时，是否应该关闭组中的所有[TSwipeCell] [cell]组件被点击时必须传递点击事件，执行`TSwipeCellInherited.of(context)?.cellClick()` | -| controller | SlidableController? | - | 自定义控制滑动窗口 | -| direction | Axis? | Axis.horizontal | 可拖动的方向 | -| disabled | bool? | false | 是否禁用滑动 | -| dragStartBehavior | DragStartBehavior? | DragStartBehavior.start | 处理拖动开始行为的方式[GestureDetector.dragStartBehavior] | -| duration | Duration? | const Duration(milliseconds: 200) | 打开关闭动画时长 | -| groupTag | Object? | - | 组，配置后，[closeWhenOpened]、[closeWhenTapped]才起作用 | -| key | Key? | - | 组件标识，用于区分或保留组件状态。 | -| left | TSwipeCellPanel? | - | 左侧滑动操作项面板 | -| onChange | Function(TSwipeDirection direction, bool open)? | - | 滑动展开事件 | -| opened | List? | const [false, false] | 默认打开，[left, right] | -| right | TSwipeCellPanel? | - | 右侧滑动操作项面板 | -| slidableKey | Key? | - | 滑动组件的 Key | - #### 静态方法 ##### TSwipeCell.close -根据[groupTag]关闭[TSwipeCell] - - current：保留当前不关闭 +根据`groupTag`关闭`TSwipeCell` +current：保留当前不关闭 返回类型：`void` @@ -379,7 +358,7 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ##### TSwipeCell.of -获取上下文最近的[controller] +获取上下文最近的`controller` 返回类型：`SlidableController?` @@ -387,6 +366,26 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; | --- | --- | --- | --- | | context | BuildContext | - | - | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| cell | Widget | - | 单元格 `TCell` | +| closeWhenOpened | bool? | true | 当同一组（`groupTag`）中的一个`TSwipeCell`打开时，是否关闭组中的所有其他`TSwipeCell` | +| closeWhenTapped | bool? | true | 当同一组（`groupTag`）中的一个`TSwipeCell`被点击时，是否应该关闭组中的所有`TSwipeCell` `cell`组件被点击时必须传递点击事件，执行`TSwipeCellInherited.of(context)?.cellClick()` | +| controller | SlidableController? | - | 自定义控制滑动窗口 | +| direction | Axis? | Axis.horizontal | 可拖动的方向 | +| disabled | bool? | false | 是否禁用滑动 | +| dragStartBehavior | DragStartBehavior? | DragStartBehavior.start | 处理拖动开始行为的方式`GestureDetector.dragStartBehavior` | +| duration | Duration? | const Duration(milliseconds: 200) | 打开关闭动画时长 | +| groupTag | Object? | - | 组，配置后，`closeWhenOpened`、`closeWhenTapped`才起作用 | +| key | Key? | - | 组件标识，用于区分或保留组件状态。 | +| left | TSwipeCellPanel? | - | 左侧滑动操作项面板 | +| onChange | Function(TSwipeDirection direction, bool open)? | - | 滑动展开事件 | +| opened | List? | const [false, false] | 默认打开，`left, right` | +| right | TSwipeCellPanel? | - | 右侧滑动操作项面板 | +| slidableKey | Key? | - | 滑动组件的 Key | + ### TSwipeDirection #### 枚举值 diff --git a/tdesign-site/src/swiper/README.md b/tdesign-site/src/swiper/README.md index 1d0d2ed98..bb1019d88 100644 --- a/tdesign-site/src/swiper/README.md +++ b/tdesign-site/src/swiper/README.md @@ -292,14 +292,6 @@ TDesign风格的Swiper指示器样式，与flutter_swiper的Swiper结合使用 ### TPageTransformer #### 简介 TD默认PageTransformer -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| fade | double? | - | 淡化比例 | -| margin | double? | - | 左右间隔 | -| scale | double? | - | 缩放比例 | - #### 工厂构造方法 @@ -321,5 +313,13 @@ TD默认PageTransformer | fade | double? | 1 | 淡化比例 | | scale | double? | 0.8 | 缩放比例 | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| fade | double? | - | 淡化比例 | +| margin | double? | - | 左右间隔 | +| scale | double? | - | 缩放比例 | + \ No newline at end of file diff --git a/tdesign-site/src/tab-bar/README.md b/tdesign-site/src/tab-bar/README.md index e60bc0c42..07a905780 100644 --- a/tdesign-site/src/tab-bar/README.md +++ b/tdesign-site/src/tab-bar/README.md @@ -602,6 +602,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### BadgeConfig +#### 简介 +飘新配置 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -613,6 +615,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TBottomTabBarTabConfig +#### 简介 +单个 tab 配置 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -630,6 +634,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TBottomTabBarPopUpBtnConfig +#### 简介 +展开项配置 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -640,6 +646,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TBottomTabBarPopUpShapeConfig +#### 简介 +弹窗UI配置 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -653,6 +661,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### PopUpMenuItem +#### 简介 +弹窗菜单item #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-site/src/table/README.md b/tdesign-site/src/table/README.md index 8203fc29c..e6519783f 100644 --- a/tdesign-site/src/table/README.md +++ b/tdesign-site/src/table/README.md @@ -302,6 +302,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TTableCol +#### 简介 +表格列配置 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -321,6 +323,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ### TTableEmpty +#### 简介 +空数据状态 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -351,51 +355,51 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; | right | - | -### SelectableFunc +### OnCellTap #### 类型定义 ```dart -typedef SelectableFunc = bool Function(int index, dynamic row); +typedef OnCellTap = void Function(int rowIndex, dynamic row, TTableCol col); ``` -### RowCheckFunc +### OnScroll #### 类型定义 ```dart -typedef RowCheckFunc = bool Function(int index, dynamic row); +typedef OnScroll = void Function(ScrollController controller); ``` -### OnCellTap +### OnSelect #### 类型定义 ```dart -typedef OnCellTap = void Function(int rowIndex, dynamic row, TTableCol col); +typedef OnSelect = void Function(List? data); ``` -### OnScroll +### OnRowSelect #### 类型定义 ```dart -typedef OnScroll = void Function(ScrollController controller); +typedef OnRowSelect = void Function(int index, bool checked); ``` -### OnSelect +### SelectableFunc #### 类型定义 ```dart -typedef OnSelect = void Function(List? data); +typedef SelectableFunc = bool Function(int index, dynamic row); ``` -### OnRowSelect +### RowCheckFunc #### 类型定义 ```dart -typedef OnRowSelect = void Function(int index, bool checked); +typedef RowCheckFunc = bool Function(int index, dynamic row); ``` diff --git a/tdesign-site/src/tabs/README.md b/tdesign-site/src/tabs/README.md index 99da59326..7bc5eec2b 100644 --- a/tdesign-site/src/tabs/README.md +++ b/tdesign-site/src/tabs/README.md @@ -372,28 +372,28 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; | key | Key? | - | 组件标识，用于区分或保留组件状态。 | -### TTabSize +### TTabBarOutlineType #### 枚举值 | 名称 | 说明 | | --- | --- | -| large | - | -| small | - | +| filled | 填充样式 | +| capsule | 胶囊样式 | +| card | 卡片 | -### TTabOutlineType +### TTabSize #### 枚举值 | 名称 | 说明 | | --- | --- | -| filled | 填充样式 | -| capsule | 胶囊样式 | -| card | 卡片 | +| large | - | +| small | - | -### TTabBarOutlineType +### TTabOutlineType #### 枚举值 diff --git a/tdesign-site/src/tag/README.md b/tdesign-site/src/tag/README.md index 056f0bab4..8201d455c 100644 --- a/tdesign-site/src/tag/README.md +++ b/tdesign-site/src/tag/README.md @@ -503,6 +503,9 @@ Mark标签 ## API ### TTag +#### 简介 +展示型标签组件，仅展示，内部不可更改自身状态 +支持样式：方形/圆角/半圆/带关闭图标 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -531,6 +534,9 @@ Mark标签 ### TSelectTag +#### 简介 +点击型标签组件，点击时内部更改自身状态 +支持样式：方形/圆角/半圆/带关闭图标 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -558,25 +564,8 @@ Mark标签 ### TTagStyle -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| backgroundColor | Color? | - | 背景颜色 | -| border | double | 0 | 线框粗细 | -| borderColor | Color? | - | 边框颜色 | -| borderRadius | BorderRadiusGeometry? | - | 圆角 | -| context | BuildContext? | - | 上下文，方便获取主题内容 | -| font | Font? | - | 字体尺寸 | -| fontWeight | FontWeight? | - | 字体粗细 | -| textColor | Color? | - | 文字颜色 | - -#### 公开属性 - -| 属性 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| closeIconColor | Color? | - | 关闭图标颜色 | - +#### 简介 +标签样式 #### 工厂构造方法 @@ -615,6 +604,25 @@ Mark标签 | light | bool | - | - | | shape | TTagShape | - | - | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| backgroundColor | Color? | - | 背景颜色 | +| border | double | 0 | 线框粗细 | +| borderColor | Color? | - | 边框颜色 | +| borderRadius | BorderRadiusGeometry? | - | 圆角 | +| context | BuildContext? | - | 上下文，方便获取主题内容 | +| font | Font? | - | 字体尺寸 | +| fontWeight | FontWeight? | - | 字体粗细 | +| textColor | Color? | - | 文字颜色 | + +#### 公开属性 + +| 属性 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| closeIconColor | Color? | - | 关闭图标颜色 | + ### TTagTheme #### 简介 diff --git a/tdesign-site/src/text/README.md b/tdesign-site/src/text/README.md index a72595af3..0a9495aa9 100644 --- a/tdesign-site/src/text/README.md +++ b/tdesign-site/src/text/README.md @@ -195,42 +195,27 @@ TText.rich测试: ## API ### TText -#### 默认构造方法 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| data | - | - | 以下系统 text 属性，释义请参考系统 [Text] 中注释 | -| backgroundColor | Color? | - | 背景颜色 | -| font | Font? | - | 字体尺寸，包含 大小size 和 行高height | -| fontFamily | FontFamily? | - | 字体ttf | -| fontFamilyUrl | String? | - | 是否禁用懒加载 FontFamily 的能力 | -| fontWeight | FontWeight? | - | 字体粗细 | -| forceVerticalCenter | bool | false | 是否强制居中 | -| isInFontLoader | bool | false | 是否在 FontLoader 中使用 | -| isTextThrough | bool? | false | 是否是横线穿过样式（删除线） | -| key | Key? | - | 组件标识，用于区分或保留组件状态。 | -| lineThroughColor | Color? | - | 删除线颜色，对应 TestStyle 的 decorationColor | -| locale | Locale? | - | - | -| maxLines | int? | - | - | -| overflow | TextOverflow? | - | - | -| package | String? | - | 字体包名 | -| semanticsLabel | String? | - | - | -| softWrap | bool? | - | - | -| strutStyle | StrutStyle? | - | - | -| style | TextStyle? | - | 自定义的 TextStyle，其中指定的属性，将覆盖扩展的外层属性 | -| textAlign | TextAlign? | - | - | -| textColor | Color? | - | 文本颜色 | -| textDirection | TextDirection? | - | - | -| textHeightBehavior | ui.TextHeightBehavior? | - | - | -| textScaleFactor | double? | - | - | -| textWidthBasis | TextWidthBasis? | - | - | - -#### 公开属性 - -| 属性 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| textSpan | InlineSpan? | - | - | - +#### 简介 +文本控件 +设计原则： +1. 为了使用更方便，所以对系统组件进行的扩展，需兼容系统控件所有功能，不能让用户使用 TDesign 时，因不能满足系统功能而弃用。 +2. 非系统已有属性，尽量添加注释 +需求：把一部分在 TextStyle 中的属性扁平化，放到外层。 +1. 暴露系统的所有属性，支持系统所有操作 +2. 约束使用主题配置的几种字体 +3. 提供转换为系统 Text 的方法，以使某些系统组件指定接收系统 Text 时可使用。（Image 组件同理） +4. 支持自定义 TextStyle +5. 兼容 TextSpan 形式 +技巧： +命名参数替换属性的正则： +第一步，把 Text 中的可选参数拷贝过来，变成如下格式： +Text(data, +this.style, +this.strutStyle, +……) +第二步，正则替换如下： +匹配(前半有默认值，后半无默认值)：this\.(`a-z|A-Z`+)[]*`\=`+[]*`a-z|A-Z`+\,|this\.(`a-z|A-Z`+)\, +替换：$1$2: this.$1$2, #### 工厂构造方法 @@ -266,8 +251,46 @@ TText.rich测试: | isInFontLoader | bool | false | 是否在 FontLoader 中使用 | | fontFamilyUrl | String? | - | 是否禁用懒加载 FontFamily 的能力 | +#### 默认构造方法 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| data | - | - | 以下系统 text 属性，释义请参考系统 `Text` 中注释 | +| backgroundColor | Color? | - | 背景颜色 | +| font | Font? | - | 字体尺寸，包含 大小size 和 行高height | +| fontFamily | FontFamily? | - | 字体ttf | +| fontFamilyUrl | String? | - | 是否禁用懒加载 FontFamily 的能力 | +| fontWeight | FontWeight? | - | 字体粗细 | +| forceVerticalCenter | bool | false | 是否强制居中 | +| isInFontLoader | bool | false | 是否在 FontLoader 中使用 | +| isTextThrough | bool? | false | 是否是横线穿过样式（删除线） | +| key | Key? | - | 组件标识，用于区分或保留组件状态。 | +| lineThroughColor | Color? | - | 删除线颜色，对应 TestStyle 的 decorationColor | +| locale | Locale? | - | - | +| maxLines | int? | - | - | +| overflow | TextOverflow? | - | - | +| package | String? | - | 字体包名 | +| semanticsLabel | String? | - | - | +| softWrap | bool? | - | - | +| strutStyle | StrutStyle? | - | - | +| style | TextStyle? | - | 自定义的 TextStyle，其中指定的属性，将覆盖扩展的外层属性 | +| textAlign | TextAlign? | - | - | +| textColor | Color? | - | 文本颜色 | +| textDirection | TextDirection? | - | - | +| textHeightBehavior | ui.TextHeightBehavior? | - | - | +| textScaleFactor | double? | - | - | +| textWidthBasis | TextWidthBasis? | - | - | + +#### 公开属性 + +| 属性 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| textSpan | InlineSpan? | - | - | + ### TTextSpan +#### 简介 +TextSpan 的 TDesign 扩展，将部分 TextStyle 中的参数扁平化。 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -291,6 +314,8 @@ TText.rich测试: ### TTextConfiguration +#### 简介 +存储可以自定义 TText 居中算法数据的内部控件 #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | diff --git a/tdesign-site/src/textarea/README.md b/tdesign-site/src/textarea/README.md index 2de7d101d..0cdb4a055 100644 --- a/tdesign-site/src/textarea/README.md +++ b/tdesign-site/src/textarea/README.md @@ -256,9 +256,9 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; | --- | --- | --- | --- | | additionInfo | String? | '' | 错误提示信息 | | additionInfoColor | Color? | - | 错误提示颜色 | -| allowInputOverMax | bool? | false | 超出[maxLength]之后是否还允许输入 | +| allowInputOverMax | bool? | false | 超出`maxLength`之后是否还允许输入 | | autofocus | bool? | false | 是否自动获取焦点 | -| autosize | bool? | - | 是否自动增高，值为 true 时，[maxLines]不生效 | +| autosize | bool? | - | 是否自动增高，值为 true 时，`maxLines`不生效 | | backgroundColor | Color? | - | 输入框背景色 | | bordered | bool? | - | 是否显示外边框 | | controller | TextEditingController? | - | controller 用户获取或者赋值输入内容 | diff --git a/tdesign-site/src/time-counter/README.md b/tdesign-site/src/time-counter/README.md index d0eb22c69..20a8eec00 100644 --- a/tdesign-site/src/time-counter/README.md +++ b/tdesign-site/src/time-counter/README.md @@ -638,6 +638,20 @@ TTimeCounter _buildCustomUnitLargeSize(BuildContext context) { ### TTimeCounterStyle #### 简介 计时组件样式 + +#### 工厂构造方法 + +##### TTimeCounterStyle.generateStyle + +生成默认样式 + +| 参数 | 类型 | 默认值 | 说明 | +| --- | --- | --- | --- | +| context | BuildContext | - | - | +| size | TTimeCounterSize? | - | - | +| theme | TTimeCounterTheme? | - | - | +| splitWithUnit | bool? | - | - | + #### 默认构造方法 | 参数 | 类型 | 默认值 | 说明 | @@ -659,35 +673,6 @@ TTimeCounter _buildCustomUnitLargeSize(BuildContext context) { | timeWidth | double? | - | 时间容器宽度 | -#### 工厂构造方法 - -##### TTimeCounterStyle.generateStyle - -生成默认样式 - -| 参数 | 类型 | 默认值 | 说明 | -| --- | --- | --- | --- | -| context | BuildContext | - | - | -| size | TTimeCounterSize? | - | - | -| theme | TTimeCounterTheme? | - | - | -| splitWithUnit | bool? | - | - | - - -### TTimeCounterStatus -#### 简介 -计时组件控制器转态 -#### 枚举值 - - -| 名称 | 说明 | -| --- | --- | -| start | 开始 | -| pause | 暂停 | -| resume | 继续 | -| reset | 重置 | -| idle | 空，默认值 | - - ### TTimeCounterDirection #### 简介 计时组件计时方向 @@ -726,4 +711,19 @@ TTimeCounter _buildCustomUnitLargeSize(BuildContext context) { | square | 方形 | +### TTimeCounterStatus +#### 简介 +计时组件控制器转态 +#### 枚举值 + + +| 名称 | 说明 | +| --- | --- | +| start | 开始 | +| pause | 暂停 | +| resume | 继续 | +| reset | 重置 | +| idle | 空，默认值 | + + \ No newline at end of file diff --git a/tdesign-site/src/toast/README.md b/tdesign-site/src/toast/README.md index 9b836d4a5..a0f245acc 100644 --- a/tdesign-site/src/toast/README.md +++ b/tdesign-site/src/toast/README.md @@ -383,6 +383,8 @@ import 'package:tdesign_flutter/tdesign_flutter.dart'; ## API ### TToast +#### 简介 +改进的Toast组件，支持多个实例和独立样式 #### 静态方法