diff --git a/CHANGELOG.md b/CHANGELOG.md index 8204b3745..d0e70ebe4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,31 @@ All notable changes to AtomUI are documented in this file. `AtomUI` follows Semantic Versioning 2.0.0. +## 6.2.3 + +`2026-10-05` + +- Breaking Changes + - Calendar: replace `CalendarCellType` with `DateViewerCellType` and make `CalendarCellContext` inherit `DateViewerCellContext`; rebuild custom cell contexts and templates. See the [6.2.3 API migration guide](docs/releases/6.2.3-api-changes.md). + - DatePicker: remove the public legacy `CalendarView` types, move and seal `DateSelectedEventArgs`, and seal `ChoosingStatusEventArgs`; migrate to the shared viewer contracts described in the guide. + - Theme and Tokens: replace legacy date-panel templates and Semantic Part targets, remove obsolete DatePicker token keys, rename `RangeCalendarSpacing` to `RangePanelSpacing`, and change generated Calendar/DatePicker token enum values. Rebuild custom themes and use named token members; see the migration guide. + - Registration: version-specific generated `ControlPackageGroup_*` identities change in six control packages; rebuild generated-registration consumers and republish trimmed/NativeAOT applications. See the migration guide. +- DateViewer, Calendar and DatePicker + - Add standalone DateViewer and RangeDateViewer with Date, Week, Month, Quarter and Year selection, Compact/Content presentation, typed templates, atomic ranges and Semantic Part styles. + - Share date panels across Calendar, LunarCalendar and DatePicker, preserving Calendar business headers, lunar content and range bars. + - Improve date-panel geometry, Today/focus visuals, week formatting and language switching; align range highlights and endpoint corners. + - Fix RangeDatePicker endpoint rotation, popup anchoring, reverse hover previews and partial confirmation across close/reopen; keep reusable confirm and time controls interactive. +- Input and Window Lifecycle + - Prevent cross-window pointer input from changing Rate, Slider, TimePicker, ButtonSpinner, ToolTip and TreeView drag state; release transient state safely on disable, detach and window close. + - Remove inherited dividers from CandidateList, Select and Cascader dropdown items. +- Watermark and Layout + - Fix localized Watermark glyph resources, owner attachment and theme/language updates; skip invalid or fully clipped tiles without changing rotation, stagger or mirror phases. + - Correct final-bounds geometry for Rate, ToggleSwitch, Segmented, Skeleton, ColorBlock and popup shadow/arrow layouts, including margins and scaling. +- Gallery and Generator + - Add localized DateViewer examples and Semantic Part previews. + - Fix deferred ShowCase materialization and placeholder visuals; improve zoomed content bounds, overlays and hit testing while preserving scrolling. + - Cache generated registration descriptors to reduce startup work without changing registration contracts. + ## 6.2.2 `2026-09-30` diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md index 2a423d2d1..27383d362 100644 --- a/CHANGELOG.zh-CN.md +++ b/CHANGELOG.zh-CN.md @@ -6,6 +6,31 @@ AtomUI 的重要变更记录在此文件中。 英文版本见 [CHANGELOG.md](CHANGELOG.md)。 +## 6.2.3 + +`2026-10-05` + +- Breaking Changes + - Calendar：将 `CalendarCellType` 替换为 `DateViewerCellType`，`CalendarCellContext` 改为继承 `DateViewerCellContext`；自定义单元格上下文和模板需要重新编译。详见 [6.2.3 API 迁移指南](docs/releases/6.2.3-api-changes.zh-CN.md)。 + - DatePicker：移除旧 `CalendarView` 公共类型，迁移并密封 `DateSelectedEventArgs`，密封 `ChoosingStatusEventArgs`；请按迁移指南使用共享面板契约。 + - Theme 与 Token：替换旧日期面板模板和 Semantic Part 目标，移除过时的 DatePicker Token 键，将 `RangeCalendarSpacing` 更名为 `RangePanelSpacing`，并调整生成的 Calendar/DatePicker Token 枚举值。请重新编译自定义主题并使用具名 Token 成员，详见迁移指南。 + - Registration：六个控件包中版本相关的生成 `ControlPackageGroup_*` 标识变化；请重新编译生成注册消费方并重新发布 trimming/NativeAOT 应用，详见迁移指南。 +- DateViewer、Calendar 与 DatePicker + - 新增独立 DateViewer 和 RangeDateViewer，支持日期、周、月、季度、年选择，Compact/Content 展示、强类型模板、原子范围和 Semantic Part 专用样式。 + - Calendar、LunarCalendar 与 DatePicker 共享日期面板，保留 Calendar 业务 Header、农历内容和范围条。 + - 改进日期面板几何、Today/焦点视觉、周格式与语言切换，统一范围高亮和端点圆角。 + - 修复 RangeDatePicker 端点轮换、弹层锚点、反向 Hover 预览和关闭/重开后的部分确认；保持复用的确认按钮和时间控件可交互。 +- 输入与窗口生命周期 + - 防止跨窗口指针输入改变 Rate、Slider、TimePicker、ButtonSpinner、ToolTip 和 TreeView 拖拽状态；禁用、卸载和窗口关闭时安全释放临时状态。 + - 移除 CandidateList、Select 和 Cascader 下拉项继承的分隔线。 +- Watermark 与布局 + - 修复 Watermark 本地化 Glyph 资源、owner 挂载及主题/语言更新；跳过无效和完全裁剪的平铺项，同时保持旋转、交错和镜像相位。 + - 修正 Rate、ToggleSwitch、Segmented、Skeleton、ColorBlock 和 Popup 阴影/箭头布局的最终 Bounds 几何，覆盖 Margin 和缩放。 +- Gallery 与 Generator + - 新增本地化 DateViewer 示例和 Semantic Part 预览。 + - 修复 ShowCase 延迟物化和占位视觉，改进放大内容边界、覆盖层与命中，同时保留滚动行为。 + - 缓存生成的注册描述符，减少启动工作并保持注册契约。 + ## 6.2.2 `2026-09-30` diff --git a/README.md b/README.md index b75e65589..81a540102 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@
[![AntDesign](https://img.shields.io/badge/AntDesign%20-6.0-1677ff?style=flat-square&logo=antdesign)](https://ant-design.antgroup.com/components/overview) -[![AtomUI](https://img.shields.io/badge/AtomUI-6.2.2-1677ff?style=flat-square)](https://www.nuget.org/packages/AtomUI.Desktop.Controls) +[![AtomUI](https://img.shields.io/badge/AtomUI-6.2.3-1677ff?style=flat-square)](https://www.nuget.org/packages/AtomUI.Desktop.Controls) [![][github-contributors-shield]][github-contributors-link] [![][github-stars-shield]][github-stars-link] [![NuGet Download](https://img.shields.io/nuget/dt/AtomUI.Desktop.Controls?style=flat-square&logo=nuget&label=downloads)](https://www.nuget.org/packages/AtomUI.Desktop.Controls) @@ -75,10 +75,10 @@ Windows, macOS and Linux
#### Latest Release Notes -AtomUI 6.2.2 moves product packages to .NET 10 and replaces the legacy AOT registration pipeline with TypeMap. -It also adds DataGrid pagination content options and fixes control interaction and layout issues. This release removes -the .NET 8 package assets and old registration, theme discovery, and build-tool contracts. Read the -[6.2.2 API migration guide](docs/releases/6.2.2-api-changes.md) and [Changelog](./CHANGELOG.md) before upgrading. +AtomUI 6.2.3 adds standalone DateViewer and RangeDateViewer panels shared by Calendar and DatePicker. +It improves range picking, cross-window input, Watermark resources and Gallery zoom layouts. This patch release includes +breaking date-context, legacy CalendarView, template, token and generated-registration changes. Read the +[6.2.3 API migration guide](docs/releases/6.2.3-api-changes.md) and [Changelog](./CHANGELOG.md) before upgrading. #### Incubator @@ -133,10 +133,10 @@ The packages we have released are as follows: | AtomUI.Generator | Source generators for custom controls, tokens and localization | ```bash -dotnet add package AtomUI.Desktop.Controls --version 6.2.2 -dotnet add package AtomUI.Desktop.Controls.DataGrid --version 6.2.2 -dotnet add package AtomUI.Desktop.Controls.ColorPicker --version 6.2.2 -dotnet add package AtomUI.Desktop.Controls.Extras --version 6.2.2 +dotnet add package AtomUI.Desktop.Controls --version 6.2.3 +dotnet add package AtomUI.Desktop.Controls.DataGrid --version 6.2.3 +dotnet add package AtomUI.Desktop.Controls.ColorPicker --version 6.2.3 +dotnet add package AtomUI.Desktop.Controls.Extras --version 6.2.3 ``` You can also install the packages from your IDE's NuGet package manager. In Rider, open: @@ -164,10 +164,10 @@ Search for "AtomUI" and install the packages your project needs. - - - - + + + + diff --git a/README.zh-CN.md b/README.zh-CN.md index f8674fd66..7a585ce7e 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -3,7 +3,7 @@
[![AntDesign](https://img.shields.io/badge/AntDesign%20-6.0-1677ff?style=flat-square&logo=antdesign)](https://ant-design.antgroup.com/components/overview-cn) -[![AtomUI](https://img.shields.io/badge/AtomUI-6.2.2-1677ff?style=flat-square)](https://www.nuget.org/packages/AtomUI.Desktop.Controls) +[![AtomUI](https://img.shields.io/badge/AtomUI-6.2.3-1677ff?style=flat-square)](https://www.nuget.org/packages/AtomUI.Desktop.Controls) [![NuGet Download](https://img.shields.io/nuget/dt/AtomUI.Desktop.Controls?style=flat-square&logo=nuget&label=downloads)](https://www.nuget.org/packages/AtomUI.Desktop.Controls) [![][github-license-shield]][github-license-link] @@ -69,9 +69,10 @@ Avalonia 12.1.3
#### 最新版本说明 -AtomUI 6.2.2 将产品包迁移到 .NET 10，并以 TypeMap 替换旧 AOT 注册管线；同时增加 DataGrid 分页内容选项， -修复控件交互与布局问题。本版本移除了 .NET 8 包资产及旧注册、主题发现和构建工具契约。升级前请阅读 -[6.2.2 API 迁移指南](docs/releases/6.2.2-api-changes.zh-CN.md)和[更新日志](./CHANGELOG.zh-CN.md)。 +AtomUI 6.2.3 新增独立 DateViewer 和 RangeDateViewer，并与 Calendar、DatePicker 共享日期面板。 +本版改进范围选择、跨窗口输入、Watermark 资源和 Gallery 放大布局。此补丁版本包含日期上下文、旧 CalendarView、 +模板、Token 和生成注册标识的破坏性变更。升级前请阅读 [6.2.3 API 迁移指南](docs/releases/6.2.3-api-changes.zh-CN.md) +和 [更新日志](./CHANGELOG.zh-CN.md)。 #### 感谢通明湖中心孵化 AtomUI OSS @@ -128,10 +129,10 @@ AtomUI 推荐通过 NuGet 安装。先安装主桌面控件包，再根据应用 | AtomUI.Generator | 面向自定义控件、Token 与本地化开发的源代码生成器 | ```bash -dotnet add package AtomUI.Desktop.Controls --version 6.2.2 -dotnet add package AtomUI.Desktop.Controls.DataGrid --version 6.2.2 -dotnet add package AtomUI.Desktop.Controls.ColorPicker --version 6.2.2 -dotnet add package AtomUI.Desktop.Controls.Extras --version 6.2.2 +dotnet add package AtomUI.Desktop.Controls --version 6.2.3 +dotnet add package AtomUI.Desktop.Controls.DataGrid --version 6.2.3 +dotnet add package AtomUI.Desktop.Controls.ColorPicker --version 6.2.3 +dotnet add package AtomUI.Desktop.Controls.Extras --version 6.2.3 ``` 您也可以在 IDE 的 NuGet 包管理器中安装。以 Rider 为例，可以依次点击： @@ -158,10 +159,10 @@ NuGet -> 软件包 - - - - + + + + diff --git a/build/Versions.props b/build/Versions.props index a4ecb52fc..8cc0e453a 100644 --- a/build/Versions.props +++ b/build/Versions.props @@ -1,6 +1,6 @@ 12.1.3 - 6.2.2 + 6.2.3 diff --git a/docs/releases/6.2.3-api-changes.md b/docs/releases/6.2.3-api-changes.md new file mode 100644 index 000000000..e9b6381b7 --- /dev/null +++ b/docs/releases/6.2.3-api-changes.md @@ -0,0 +1,142 @@ +# AtomUI 6.2.3 API Change Examples + +Despite its patch version, AtomUI 6.2.3 includes breaking date-context, legacy CalendarView, theme and generated-token changes. This guide describes migration from 6.2.2. Rebuild consumers and custom themes together; replacing package binaries alone is insufficient. + +Chinese version: [AtomUI 6.2.3 API 变更示例](6.2.3-api-changes.zh-CN.md). + +## Quick reference + +| Area | 6.2.2 | 6.2.3 migration | +| --- | --- | --- | +| Calendar cell type | `CalendarCellType.Date/Month` | `DateViewerCellType.Date/Month`; update C# and AXAML type references. | +| Calendar context | Positional `CalendarCellContext` with eight fields | Inherits `DateViewerCellContext`; update constructor calls, named arguments, derived records and deconstruction. | +| Legacy picker namespace | Public types under `AtomUI.Desktop.Controls.CalendarView` | Use standalone `DateViewer`/`RangeDateViewer` and their public contexts, ranges and events. | +| Event extensibility | Unsealed `ChoosingStatusEventArgs` and legacy `DateSelectedEventArgs` | Both current event-argument classes are sealed; use composition instead of subclasses. | +| Date-panel templates | CalendarView/CalendarItem/Button themes and `PART_CalendarView` | Shared viewer themes and `PART_DateViewer` / `PART_RangeDateViewer`; rebuild complete custom templates. | +| Semantic Parts | Old header/body/content/cell targets and marker routes | Recompile dedicated generated Style classes; review Setters against the new target contracts. | +| DatePicker tokens | Cell/header/panel tokens and `RangeCalendarSpacing` | DateViewer owns date-panel resources; picker spacing becomes `RangePanelSpacing`. | +| Generated registration groups | Version-specific public `ControlPackageGroup_*` types | Rebuild consumers and republish trimmed/AOT output; do not reference generated group names directly. | +| Generated token enums | Previous Calendar/DatePicker integer constants | Rebuild consumers and use named members; migrate serialized numeric values. | + +## 1. Migrate Calendar cell contexts + +`CalendarCellType` is removed. `CalendarCellContext` now derives from `DateViewerCellContext`, and its constructor accepts `DateViewerCellType` plus an optional `isFocused` argument. `LunarCalendarCellContext` also accepts `DateViewerCellType`. + +Before: + +```csharp +var context = new CalendarCellContext(date, DateTime.Today, + CalendarCellType.Date, "5", false, true, false, false); +``` + +After: + +```csharp +var context = new CalendarCellContext(date, DateTime.Today, + DateViewerCellType.Date, "5", false, true, false, false); +``` + +The old positional-record constructor used PascalCase parameter names; the new Calendar constructor uses camelCase (`value`, `today`, `cellType`, `displayValue`, `isToday`, `isInView`, `isSelected`, `isDisabled`, `isFocused`). Update named arguments and constructors of derived records. The record inheritance change also changes generated clone/equality/printing override metadata; rebuild consumer derived records rather than reusing their old binaries. The old eight-output generated `Deconstruct` is removed; read named properties or use the inherited fifteen-field context shape instead. Cell properties are inherited, so binaries compiled against the former declaring type must be rebuilt. + +Update typed AXAML expressions that compare `CalendarCellType` to use `DateViewerCellType`. The new enum inserts `Week`: the old `CalendarCellType.Month` value is `1`, while `DateViewerCellType.Month` is `2`. Map stored cell-type integers through the old names instead of directly casting them to the new enum. Calendar's `Value`, `Mode`, cell/header templates and business events remain its public owner contracts; ordinary value bindings do not move to the nested viewer. + +## 2. Replace legacy CalendarView public types and event subclasses + +The following public types under `AtomUI.Desktop.Controls.CalendarView` are removed: + +- `CalendarMode` (the legacy Month/Year/Decade panel enum). +- `CalendarDateRange` (the legacy non-null range type). +- `DateSelectedEventArgs` and `RangeDateSelectedEventArgs`. + +For standalone date-panel integrations, use `DateViewer` or `RangeDateViewer`. Use `DateViewerSelectionUnit` for selection granularity and `DateViewerPanelKind` for the displayed panel. Legacy Month/Year/Decade panel browsing corresponds to Date/Month/Year panels. Panel kind is exposed as read-only state; use `DisplayDate`, selection configuration and header navigation rather than assigning the removed display-mode API. + +Use atomic `DateViewerRange` values for the new range viewer: + +```csharp +var viewer = new RangeDateViewer +{ + SelectionUnit = DateViewerSelectionUnit.Date, + Value = new DateViewerRange(new DateTime(2026, 10, 5), new DateTime(2026, 10, 9)) +}; +viewer.Selected += (_, args) => Console.WriteLine(args.Value); +``` + +Use `DateViewerSelectedEventArgs` / `RangeDateViewerSelectedEventArgs` for viewer selection and the corresponding `ValueChanged` arguments for value changes. The removed `RangeDateSelectedEventArgs.IsFixedRange` is not a new viewer confirmation flag: a picker owns confirmation, while a viewer reports panel selection. Keep application confirmation state in the application's own model. + +`DateSelectedEventArgs` is now `AtomUI.Desktop.Controls.DateSelectedEventArgs` and is sealed. `AtomUI.Desktop.Controls.ChoosingStatusEventArgs` is also sealed. Remove subclasses and store extra state in an application model or wrapper. Ordinary applications should consume the public DatePicker/RangeDatePicker owner events and values rather than relying on internal presenter events. The separate `AtomUI.Desktop.Controls.CalendarMode` and `CalendarDateRange` contracts used by Calendar remain available. + +## 3. Rebuild custom date templates and Semantic Part styles + +The old CalendarView, CalendarViewCell, LunarCalendarViewCell, CalendarItem, CalendarButton, CalendarDayButton, HeadTextButton, range and dual-month theme assets are removed. The timed and dual-month picker presenter variants are consolidated. Remove custom includes and references to those assets, including compiler-generated AXAML Build/Populate methods, and rebuild against the current viewer-based themes. + +Calendar's date template part changes from `PART_CalendarView` to `PART_DateViewer`. Picker presenters compose `PART_DateViewer` or `PART_RangeDateViewer` with time controls and the picker footer. A renamed part alone does not migrate a complete custom template; copy the current composition and retain its bindings and resource owners. See [Calendar implementation](../controls/desktop/data-display/calendar/implementation.md) and [DatePicker implementation](../controls/desktop/data-entry/date-picker/implementation.md). + +Semantic Part names remain recognizable, but target contracts and routes change: + +| Part | Previous target | Current target | +| --- | --- | --- | +| Calendar / LunarCalendar `body` | `DockPanel` | `Panel` | +| Calendar / LunarCalendar `item`, `itemContent` | Direct calendar-cell topology | Shared viewer/panel/cell templates; generated routes cross nested owners. | +| Picker `popup.header` | `Border` | `TemplatedControl`; RangeDatePicker headers are `Multiple`. | +| Picker `popup.body` | `UniformGrid` | `Panel` | +| Picker `popup.content` | `Grid` | `TemplatedControl` | +| Picker `popup.cell` | `Button` | `TemplatedControl` | + +Remove old raw selectors based on `.semantic-popup-header`, `.semantic-popup-body`, `.semantic-popup-content`, `.semantic-item` or the previous template nesting. Recompile and apply the dedicated generated styles declaratively: + +```xml + + + + + +``` + +Here `atom` is `xmlns:atom="https://atomui.net"`. Review Setters for properties specific to the old Button, Grid or Border targets; those properties may no longer exist. Use the [DatePicker Semantic Part contract](../controls/desktop/data-entry/date-picker/semantic-part.md) and [Calendar Semantic Part contract](../controls/desktop/data-display/calendar/semantic-part.md) for the supported customization surface. + +## 4. Migrate generated tokens and resource ownership + +DatePicker now owns only `PanelContentPadding`, `ButtonsPanelMargin` and `RangePanelSpacing`. The generated DatePicker TokenKind/TokenKey members and resource entries for these former date-panel names are removed: + +`CellHoverBg`, `CellActiveWithRangeBg`, `CellHoverWithRangeBg`, `CellBgDisabled`, `CellRangeBorderColor`, `CellHeight`, `CellWidth`, `CellLineHeight`, `CellMargin`, `ItemPanelMinWidth`, `MonthViewMinWidth`, `ItemPanelMinHeight`, `TextHeight`, `YearMonthCellWidth`, `WithoutTimeCellHeight`, `DayTitleHeight`, `HeaderMargin`, `HeaderPadding`, `RangeCalendarSpacing`. + +Migration examples: + +| Former DatePicker resource | Current customization | +| --- | --- | +| `CellHoverBg` | DateViewer `CellHoverBg` | +| `CellActiveWithRangeBg` | DateViewer `CellRangeBg` | +| `CellHeight`, `CellWidth` | DateViewer members with the same names | +| `YearMonthCellWidth` | DateViewer `PeriodCellWidth` | +| `RangeCalendarSpacing` | DatePicker `RangePanelSpacing` | +| Other removed dimensions, header or state colors | Review current DateViewer geometry, shared tokens and dedicated Semantic Styles; there is no universal one-to-one alias. | + +Use the actual date-panel resource owner for local overrides; old picker resources no longer affect the shared panel. See [DateViewer tokens](../controls/desktop/data-entry/date-viewer/token.md) and [DatePicker tokens](../controls/desktop/data-entry/date-picker/token.md). + +Calendar adds `WeekHeaderHeight` and `WeekHeaderPadding`. This insertion changes integer values of later generated Calendar token members; DatePicker token removal/reordering also changes its generated constants. Rebuild all compiled token consumers. Do not persist enum integers as stable identities; map previously serialized values through their 6.2.2 member names before upgrading. + +## 5. Rebuild generated registration consumers + +Public `ControlPackageGroup_*` identities change in `AtomUI.Controls`, `AtomUI.Desktop.Controls`, `AtomUI.Toolkits.GalleryBase`, `AtomUI.Desktop.Controls.DataGrid`, `AtomUI.Desktop.Controls.ColorPicker` and `AtomUI.Desktop.Controls.Extras`. The TypeMap writer derives these names from the package assembly identity, which includes its version. ApiCompat detects six removed 6.2.2 group types when comparing the 6.2.3 artifacts. + +Keep ordinary `UseAtomUI()` and package registration calls, upgrade the related packages together, and rebuild applications and custom control packages that consume generated registration metadata. Republish trimmed/NativeAOT output so linking uses the current groups. Replace direct references to `AtomUI.Generated.*.ControlPackageGroup_*` with supported package registration APIs; old hashed names have no stable alias. The registration mechanism remains TypeMap; this is a generated public-identity compatibility change rather than a new registration system. + +## 6. Validate the upgrade + +1. Upgrade AtomUI packages together and rebuild consuming applications and custom control packages. +2. Update contexts, removed namespace references, event subclasses, template assets and token overrides. +3. Verify single/range/date-time pickers, close/reopen confirmation, reverse previews, language changes, Calendar/LunarCalendar templates and range bars. +4. Exercise dedicated Semantic Styles, theme changes, keyboard focus and pointer input in the actual application. +5. Republish trimmed/NativeAOT applications and exercise the date controls in the published output. + +The product TFM remains `net10.0`, Avalonia remains 12.1.3 and the .NET 10 SDK requirement is unchanged from 6.2.2. Package API validation against 6.2.2 is expected to detect the intentional breaks above; it must not be suppressed or described as compatibility success. Package-layout and NativeAOT checks are separate release gates. + +## Release-gate audit record + +The 20 Release packages are produced and their layouts match 6.2.2. ApiCompat reports 11 removed types (`CP0001`), 52 removed members (`CP0002`), one newly sealed type (`CP0009`), six changed enum constants (`CP0011`) and four changed virtual-member diagnostics (`CP0012`). The removed-type set consists of five date types and six generated registration groups. Removed members cover date-context constructors/accessors/deconstruction, DatePicker tokens and retired generated AXAML entry methods. The virtual-member diagnostics concern CalendarCellContext record inheritance; the sealed-type diagnostic concerns ChoosingStatusEventArgs. No unresolved-reference diagnostics are reported. These compatibility errors remain visible and are not suppressed; publication must not claim binary compatibility with 6.2.2. diff --git a/docs/releases/6.2.3-api-changes.zh-CN.md b/docs/releases/6.2.3-api-changes.zh-CN.md new file mode 100644 index 000000000..b0a210801 --- /dev/null +++ b/docs/releases/6.2.3-api-changes.zh-CN.md @@ -0,0 +1,142 @@ +# AtomUI 6.2.3 API 变更示例 + +虽然版本号是补丁版本，AtomUI 6.2.3 仍包含日期上下文、旧 CalendarView、主题和生成 Token 的破坏性变更。本文说明从 6.2.2 升级的方法。消费方和自定义主题需要一起重新编译，仅替换包二进制不足以完成迁移。 + +English version: [AtomUI 6.2.3 API Change Examples](6.2.3-api-changes.md)。 + +## 快速对照 + +| 范围 | 6.2.2 | 6.2.3 迁移 | +| --- | --- | --- | +| Calendar 单元格类型 | `CalendarCellType.Date/Month` | `DateViewerCellType.Date/Month`；更新 C# 与 AXAML 类型引用。 | +| Calendar 上下文 | 八个字段的位置记录 `CalendarCellContext` | 继承 `DateViewerCellContext`；更新构造、具名参数、派生记录和解构。 | +| 旧 Picker 命名空间 | `AtomUI.Desktop.Controls.CalendarView` 下的公共类型 | 使用独立 `DateViewer`/`RangeDateViewer` 及其公共上下文、范围和事件。 | +| 事件扩展 | 可继承的 `ChoosingStatusEventArgs` 和旧 `DateSelectedEventArgs` | 当前两个事件参数类均已密封；以组合代替继承。 | +| 日期面板模板 | CalendarView/CalendarItem/Button 主题和 `PART_CalendarView` | 共享 Viewer 主题及 `PART_DateViewer` / `PART_RangeDateViewer`；重建完整自定义模板。 | +| Semantic Parts | 旧 Header/Body/Content/Cell 目标和 marker 路由 | 重新编译生成的专用 Style，并按新目标契约检查 Setter。 | +| DatePicker Token | Cell/Header/Panel Token 与 `RangeCalendarSpacing` | DateViewer 拥有日期面板资源；Picker 间距更名为 `RangePanelSpacing`。 | +| 生成注册组 | 版本相关的公共 `ControlPackageGroup_*` 类型 | 重新编译消费方并重新发布裁剪/AOT 产物；不直接引用生成组名。 | +| 生成 Token 枚举 | 原 Calendar/DatePicker 整数常量 | 重新编译消费方，使用具名成员，迁移已序列化的整数值。 | + +## 1. 迁移 Calendar 单元格上下文 + +`CalendarCellType` 已移除。`CalendarCellContext` 现在继承 `DateViewerCellContext`，构造函数接收 `DateViewerCellType` 和可选的 `isFocused` 参数。`LunarCalendarCellContext` 同样改用 `DateViewerCellType`。 + +升级前： + +```csharp +var context = new CalendarCellContext(date, DateTime.Today, + CalendarCellType.Date, "5", false, true, false, false); +``` + +升级后： + +```csharp +var context = new CalendarCellContext(date, DateTime.Today, + DateViewerCellType.Date, "5", false, true, false, false); +``` + +旧位置记录的构造参数采用 PascalCase；新 Calendar 构造参数使用 camelCase（`value`、`today`、`cellType`、`displayValue`、`isToday`、`isInView`、`isSelected`、`isDisabled`、`isFocused`）。请更新具名参数和派生记录的构造函数。记录继承变化也改变生成的克隆、相等性和打印方法的 override 元数据；消费方派生记录应重新编译，不复用旧二进制。旧八输出生成 `Deconstruct` 已移除；改为读取具名属性，或使用继承的十五字段上下文结构。单元格属性改为继承成员，依赖旧声明类型的二进制必须重新编译。 + +比较 `CalendarCellType` 的强类型 AXAML 表达式也需要改用 `DateViewerCellType`。新枚举插入了 `Week`：旧 `CalendarCellType.Month` 的值为 `1`，新 `DateViewerCellType.Month` 的值为 `2`。存储的单元格类型整数必须先按旧成员名称映射，不能直接强转为新枚举。Calendar 的 `Value`、`Mode`、单元格/Header 模板和业务事件仍由 Calendar 拥有，普通值绑定不迁移到内嵌 Viewer。 + +## 2. 替换旧 CalendarView 公共类型和事件子类 + +`AtomUI.Desktop.Controls.CalendarView` 下的以下公共类型已移除： + +- `CalendarMode`（旧 Month/Year/Decade 面板枚举）。 +- `CalendarDateRange`（旧非空范围类型）。 +- `DateSelectedEventArgs` 与 `RangeDateSelectedEventArgs`。 + +独立日期面板接入请使用 `DateViewer` 或 `RangeDateViewer`。选择粒度使用 `DateViewerSelectionUnit`，当前面板类型使用 `DateViewerPanelKind`。旧 Month/Year/Decade 面板浏览分别对应 Date/Month/Year 面板。面板类型是只读状态，应通过 `DisplayDate`、选择配置和 Header 导航控制浏览，不再赋值给已删除的显示模式 API。 + +新范围 Viewer 使用原子 `DateViewerRange` 值： + +```csharp +var viewer = new RangeDateViewer +{ + SelectionUnit = DateViewerSelectionUnit.Date, + Value = new DateViewerRange(new DateTime(2026, 10, 5), new DateTime(2026, 10, 9)) +}; +viewer.Selected += (_, args) => Console.WriteLine(args.Value); +``` + +Viewer 选择事件使用 `DateViewerSelectedEventArgs` / `RangeDateViewerSelectedEventArgs`，值变更使用对应的 `ValueChanged` 参数。被移除的 `RangeDateSelectedEventArgs.IsFixedRange` 不对应新 Viewer 的确认标志：Picker 拥有确认流程，Viewer 报告面板选择。应用自己的确认状态应保留在应用模型中。 + +`DateSelectedEventArgs` 现在位于 `AtomUI.Desktop.Controls`，并已密封。`AtomUI.Desktop.Controls.ChoosingStatusEventArgs` 也已密封。请移除子类，将附加状态放在应用模型或包装对象中。普通应用应消费 DatePicker/RangeDatePicker 的公共 owner 事件和值，不依赖内部 Presenter 事件。Calendar 使用的另一个 `AtomUI.Desktop.Controls.CalendarMode` 和 `CalendarDateRange` 契约仍然保留。 + +## 3. 重建自定义日期模板和 Semantic Part 样式 + +旧 CalendarView、CalendarViewCell、LunarCalendarViewCell、CalendarItem、CalendarButton、CalendarDayButton、HeadTextButton、范围和双月主题资产已移除。带时间和双月 Picker Presenter 变体已合并。删除自定义资源包含和对这些资产的引用，包括编译器生成的 AXAML Build/Populate 方法，并按当前 Viewer 主题重建。 + +Calendar 日期模板部件从 `PART_CalendarView` 改为 `PART_DateViewer`。Picker Presenter 组合 `PART_DateViewer` 或 `PART_RangeDateViewer`、时间控件和 Picker Footer。只改部件名称无法迁移完整模板；应参考当前组合结构并保留绑定和资源 owner。详见 [Calendar 实现](../controls/desktop/data-display/calendar/implementation.md)和 [DatePicker 实现](../controls/desktop/data-entry/date-picker/implementation.md)。 + +Semantic Part 名称仍可识别，但目标契约和路由发生变化： + +| 部件 | 原目标 | 当前目标 | +| --- | --- | --- | +| Calendar / LunarCalendar `body` | `DockPanel` | `Panel` | +| Calendar / LunarCalendar `item`、`itemContent` | Calendar Cell 直接拓扑 | 共享 Viewer/Panel/Cell 模板；生成路由跨越嵌套 owner。 | +| Picker `popup.header` | `Border` | `TemplatedControl`；RangeDatePicker Header 为 `Multiple`。 | +| Picker `popup.body` | `UniformGrid` | `Panel` | +| Picker `popup.content` | `Grid` | `TemplatedControl` | +| Picker `popup.cell` | `Button` | `TemplatedControl` | + +删除依赖 `.semantic-popup-header`、`.semantic-popup-body`、`.semantic-popup-content`、`.semantic-item` 或旧模板层次的原始选择器。重新编译并声明式应用生成的专用 Style： + +```xml + + + + + +``` + +这里 `atom` 对应 `xmlns:atom="https://atomui.net"`。原 Button、Grid 或 Border 特有属性可能已不适用，应逐项检查 Setter。支持的定制表面见 [DatePicker Semantic Part 契约](../controls/desktop/data-entry/date-picker/semantic-part.md)和 [Calendar Semantic Part 契约](../controls/desktop/data-display/calendar/semantic-part.md)。 + +## 4. 迁移生成 Token 与资源所有权 + +DatePicker 现在只拥有 `PanelContentPadding`、`ButtonsPanelMargin` 和 `RangePanelSpacing`。以下旧日期面板名称对应的 DatePicker TokenKind/TokenKey 成员和资源入口已移除： + +`CellHoverBg`、`CellActiveWithRangeBg`、`CellHoverWithRangeBg`、`CellBgDisabled`、`CellRangeBorderColor`、`CellHeight`、`CellWidth`、`CellLineHeight`、`CellMargin`、`ItemPanelMinWidth`、`MonthViewMinWidth`、`ItemPanelMinHeight`、`TextHeight`、`YearMonthCellWidth`、`WithoutTimeCellHeight`、`DayTitleHeight`、`HeaderMargin`、`HeaderPadding`、`RangeCalendarSpacing`。 + +迁移示例： + +| 原 DatePicker 资源 | 当前定制方式 | +| --- | --- | +| `CellHoverBg` | DateViewer `CellHoverBg` | +| `CellActiveWithRangeBg` | DateViewer `CellRangeBg` | +| `CellHeight`、`CellWidth` | DateViewer 同名成员 | +| `YearMonthCellWidth` | DateViewer `PeriodCellWidth` | +| `RangeCalendarSpacing` | DatePicker `RangePanelSpacing` | +| 其他移除的尺寸、Header 或状态颜色 | 按当前 DateViewer 几何、共享 Token 和专用 Semantic Style 重建，不存在通用一对一别名。 | + +局部覆盖应作用于真实日期面板资源 owner；旧 Picker 资源不再影响共享面板。详见 [DateViewer Token](../controls/desktop/data-entry/date-viewer/token.md)和 [DatePicker Token](../controls/desktop/data-entry/date-picker/token.md)。 + +Calendar 新增 `WeekHeaderHeight` 和 `WeekHeaderPadding`，插入位置改变后续生成 Calendar Token 成员的整数值；DatePicker Token 的移除和重排也改变生成常量。请重新编译所有 Token 消费方。不要将枚举整数作为稳定标识；升级前根据 6.2.2 的成员名称迁移已序列化的数值。 + +## 5. 重新编译生成注册的消费方 + +`AtomUI.Controls`、`AtomUI.Desktop.Controls`、`AtomUI.Toolkits.GalleryBase`、`AtomUI.Desktop.Controls.DataGrid`、`AtomUI.Desktop.Controls.ColorPicker` 和 `AtomUI.Desktop.Controls.Extras` 中的公共 `ControlPackageGroup_*` 标识发生变化。TypeMap writer 根据包含版本的包程序集标识生成这些名称。比对 6.2.3 产物时，ApiCompat 检测到六个旧 6.2.2 注册组类型移除。 + +保留普通 `UseAtomUI()` 和包注册调用，同步升级相关包，并重新编译消费生成注册元数据的应用和自定义控件包。重新发布 trimming/NativeAOT 产物，使链接过程使用当前注册组。对 `AtomUI.Generated.*.ControlPackageGroup_*` 的直接引用应改为受支持的包注册 API，旧哈希名称没有稳定别名。注册机制仍为 TypeMap；这是生成公共标识的兼容性变化，不是另一套注册系统。 + +## 6. 验证升级 + +1. 同步升级 AtomUI 包并重新编译应用和自定义控件包。 +2. 更新上下文、旧命名空间引用、事件子类、模板资产和 Token 覆盖。 +3. 验证单值/范围/带时间 Picker、关闭/重开确认、反向预览、语言切换、Calendar/LunarCalendar 模板和范围条。 +4. 在真实应用中验证专用 Semantic Style、主题切换、键盘焦点和指针输入。 +5. 重新发布 trimming/NativeAOT 应用，并在产物中实际使用日期控件。 + +产品 TFM 仍为 `net10.0`，Avalonia 仍为 12.1.3，.NET 10 SDK 要求与 6.2.2 一致。以 6.2.2 为基线的包 API 校验预期会发现上述有意破坏，不能抑制这些诊断或宣称兼容性通过。包布局与 NativeAOT 检查属于独立发布门禁。 + +## 发布门禁审计记录 + +20 个 Release 包均已生成，布局与 6.2.2 一致。ApiCompat 报告 11 个移除类型（`CP0001`）、52 个移除成员（`CP0002`）、一个新增密封类型（`CP0009`）、六个变化的枚举常量（`CP0011`）和四个虚成员变化诊断（`CP0012`）。移除类型包含五个日期类型和六个生成注册组。移除成员涵盖日期上下文构造/访问器/解构、DatePicker Token 和旧生成 AXAML 入口方法。虚成员诊断对应 CalendarCellContext 记录继承变化，密封诊断对应 ChoosingStatusEventArgs。未报告无法解析引用的诊断。这些兼容性错误完整保留且没有抑制；发布不能宣称与 6.2.2 二进制兼容。 diff --git a/docs/releases/overview.md b/docs/releases/overview.md index 2ae8b9948..614804622 100644 --- a/docs/releases/overview.md +++ b/docs/releases/overview.md @@ -3,6 +3,11 @@ 本目录按版本维护公共 API 变化和迁移示例。正式发布摘要继续由仓库根目录的 `CHANGELOG.md` 与 `CHANGELOG.zh-CN.md` 维护。 +## 6.2.3 + +- [API Change Examples](6.2.3-api-changes.md) +- [API 变更示例](6.2.3-api-changes.zh-CN.md) + ## 6.2.2 - [API Change Examples](6.2.2-api-changes.md)