mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-16 21:21:03 +08:00
release: prepare AtomUI 6.2.3
This commit is contained in:
chinboy
@@ -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`
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
<div align="center">
|
||||
|
||||
[](https://ant-design.antgroup.com/components/overview)
|
||||
[](https://www.nuget.org/packages/AtomUI.Desktop.Controls)
|
||||
[](https://www.nuget.org/packages/AtomUI.Desktop.Controls)
|
||||
[![][github-contributors-shield]][github-contributors-link]
|
||||
[![][github-stars-shield]][github-stars-link]
|
||||
[](https://www.nuget.org/packages/AtomUI.Desktop.Controls)
|
||||
@@ -75,10 +75,10 @@ Windows, macOS and Linux<br>
|
||||
|
||||
#### 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.
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<PackageReference Include="AtomUI.Desktop.Controls" Version="6.2.2"/>
|
||||
<PackageReference Include="AtomUI.Desktop.Controls.DataGrid" Version="6.2.2"/>
|
||||
<PackageReference Include="AtomUI.Desktop.Controls.ColorPicker" Version="6.2.2"/>
|
||||
<PackageReference Include="AtomUI.Desktop.Controls.Extras" Version="6.2.2"/>
|
||||
<PackageReference Include="AtomUI.Desktop.Controls" Version="6.2.3"/>
|
||||
<PackageReference Include="AtomUI.Desktop.Controls.DataGrid" Version="6.2.3"/>
|
||||
<PackageReference Include="AtomUI.Desktop.Controls.ColorPicker" Version="6.2.3"/>
|
||||
<PackageReference Include="AtomUI.Desktop.Controls.Extras" Version="6.2.3"/>
|
||||
<PackageReference Include="AvaloniaUI.DiagnosticsSupport" Version="2.2.1"/>
|
||||
</ItemGroup>
|
||||
</Project>
|
||||
|
||||
+13
-12
@@ -3,7 +3,7 @@
|
||||
<div align="center">
|
||||
|
||||
[](https://ant-design.antgroup.com/components/overview-cn)
|
||||
[](https://www.nuget.org/packages/AtomUI.Desktop.Controls)
|
||||
[](https://www.nuget.org/packages/AtomUI.Desktop.Controls)
|
||||
[](https://www.nuget.org/packages/AtomUI.Desktop.Controls)
|
||||
[![][github-license-shield]][github-license-link]
|
||||
|
||||
@@ -69,9 +69,10 @@ Avalonia 12.1.3<br>
|
||||
|
||||
#### 最新版本说明
|
||||
|
||||
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 -> 软件包
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<PackageReference Include="AtomUI.Desktop.Controls" Version="6.2.2"/>
|
||||
<PackageReference Include="AtomUI.Desktop.Controls.DataGrid" Version="6.2.2"/>
|
||||
<PackageReference Include="AtomUI.Desktop.Controls.ColorPicker" Version="6.2.2"/>
|
||||
<PackageReference Include="AtomUI.Desktop.Controls.Extras" Version="6.2.2"/>
|
||||
<PackageReference Include="AtomUI.Desktop.Controls" Version="6.2.3"/>
|
||||
<PackageReference Include="AtomUI.Desktop.Controls.DataGrid" Version="6.2.3"/>
|
||||
<PackageReference Include="AtomUI.Desktop.Controls.ColorPicker" Version="6.2.3"/>
|
||||
<PackageReference Include="AtomUI.Desktop.Controls.Extras" Version="6.2.3"/>
|
||||
<PackageReference Include="AvaloniaUI.DiagnosticsSupport" Version="2.2.1"/>
|
||||
</ItemGroup>
|
||||
</Project>
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
<Project>
|
||||
<PropertyGroup>
|
||||
<AvaloniaVersion>12.1.3</AvaloniaVersion>
|
||||
<AtomUIVersion>6.2.2</AtomUIVersion>
|
||||
<AtomUIVersion>6.2.3</AtomUIVersion>
|
||||
</PropertyGroup>
|
||||
</Project>
|
||||
|
||||
@@ -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
|
||||
<atom:DatePicker xmlns="https://github.com/avaloniaui"
|
||||
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
|
||||
xmlns:atom="https://atomui.net">
|
||||
<atom:DatePicker.Styles>
|
||||
<Style Selector="atom|DatePicker">
|
||||
<atom:DatePickerPopupCellStyle x:SetterTargetType="TemplatedControl">
|
||||
<Setter Property="Background" Value="AliceBlue" />
|
||||
</atom:DatePickerPopupCellStyle>
|
||||
</Style>
|
||||
</atom:DatePicker.Styles>
|
||||
</atom:DatePicker>
|
||||
```
|
||||
|
||||
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.
|
||||
@@ -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:DatePicker xmlns="https://github.com/avaloniaui"
|
||||
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
|
||||
xmlns:atom="https://atomui.net">
|
||||
<atom:DatePicker.Styles>
|
||||
<Style Selector="atom|DatePicker">
|
||||
<atom:DatePickerPopupCellStyle x:SetterTargetType="TemplatedControl">
|
||||
<Setter Property="Background" Value="AliceBlue" />
|
||||
</atom:DatePickerPopupCellStyle>
|
||||
</Style>
|
||||
</atom:DatePicker.Styles>
|
||||
</atom:DatePicker>
|
||||
```
|
||||
|
||||
这里 `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 二进制兼容。
|
||||
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user