# Migration guide for wide gamut CupertinoDynamicColor

> Addressing previously missed deprecations in CupertinoDynamicColor to align with wide gamut Color API.




:::important
These breaking change docs are accurate, as of the release
under which they are published. Over time, the
workarounds described here might become inaccurate.
We don't, in general, keep these breaking change docs up
to date as of each release.

这些破坏性改动文档的准确性仅限于其发布时对应的版本。
随着时间的推移，文档中描述的方案可能会逐渐失效。
通常情况下，我们不会在每次发布新版本时都对这些文档进行同步更新。

The [breaking change index file](/release/breaking-changes)
lists the docs created for each release.

[破坏性改动列表](/release/breaking-changes) 
列出了每个版本的文档。

:::


## Summary

Certain properties and methods in [`CupertinoDynamicColor`][] were deprecated
to align with the [`Color`][] class due to [wide gamut color spaces][] support
added in [Flutter 3.27][Migration guide for wide gamut Color].

## Context

The `Color` class was updated to support wide gamut color spaces,
but some corresponding deprecations were not initially applied to
`CupertinoDynamicColor` due to its implementation rather than
due to the extension of `Color`.

## Description of change

1.  The [`CupertinoDynamicColor.red`][] field is deprecated in
    favor of [`CupertinoDynamicColor.r`].
1.  The [`CupertinoDynamicColor.green`][] is deprecated in
    favor of [`CupertinoDynamicColor.g`].
1.  The [`CupertinoDynamicColor.blue`][] is deprecated in
    favor of [`CupertinoDynamicColor.b`].
1.  The [`CupertinoDynamicColor.opacity`][] is deprecated in
    favor of [`CupertinoDynamicColor.a`].
1.  The [`CupertinoDynamicColor.withOpacity()`][] is deprecated in
    favor of [`CupertinoDynamicColor.withValues()`].


## Migration guide

### Access color components

If your app accesses a single color component, consider
taking advantage of the floating-point components.
In the short term, you can scale the components themselves.

```dart
int _floatToInt8(double x) {
  return (x * 255.0).round().clamp(0, 255);
}

const CupertinoDynamicColor color = CupertinoColors.systemBlue;
final intRed = _floatToInt8(color.r);
final intGreen = _floatToInt8(color.g);
final intBlue = _floatToInt8(color.b);
```

### Opacity

Before Flutter 3.27, `Color` had the concept of "opacity", which
showed up in the methods `opacity` and `withOpacity()`.
Since Flutter 3.27, the alpha channel has been stored as a floating-point value.
Using `.a` and `.withValues()` will give the full expression of
a floating-point value and won't be quantized (restricted to a limited range).
That means "alpha" expresses the intent of "opacity" more correctly.

#### Migrate `opacity`

```dart
// Before: Access the alpha channel as a (converted) floating-point value.
final x = color.opacity;

// After: Access the alpha channel directly.
final x = color.a;
```

#### Migrate `withOpacity`

```dart
// Before: Create a new color with the specified opacity.
final x = color.withOpacity(0.5);

// After: Create a new color with the specified alpha channel value,
// accounting for the current or specified color space.
final x = color.withValues(alpha: 0.5);
```

## Timeline

Landed in version: 3.36.0-0.1.pre<br>
Stable release: 3.38

## References

Relevant guides:

* [Migration guide for wide gamut Color][]

Relevant issues:

* [Implement wide gamut color support in the Framework][]
* [CupertinoDynamicColor is missing deprecation notices][]

Relevant PRs:

* [Add missing deprecations to CupertinoDynamicColor][]

[`Color`]: https://api.flutter-io.cn/flutter/dart-ui/Color-class.html
[`CupertinoDynamicColor`]: https://api.flutter-io.cn/flutter/cupertino/CupertinoDynamicColor-class.html
[wide gamut color spaces]: https://en.wikipedia.org/wiki/RGB_color_spaces
[`CupertinoDynamicColor.red`]: https://api.flutter-io.cn/flutter/cupertino/CupertinoDynamicColor/red.html
[`CupertinoDynamicColor.r`]: https://api.flutter-io.cn/flutter/cupertino/CupertinoDynamicColor/r.html
[`CupertinoDynamicColor.green`]: https://api.flutter-io.cn/flutter/cupertino/CupertinoDynamicColor/green.html
[`CupertinoDynamicColor.g`]: https://api.flutter-io.cn/flutter/cupertino/CupertinoDynamicColor/g.html
[`CupertinoDynamicColor.blue`]: https://api.flutter-io.cn/flutter/cupertino/CupertinoDynamicColor/blue.html
[`CupertinoDynamicColor.b`]: https://api.flutter-io.cn/flutter/cupertino/CupertinoDynamicColor/b.html
[`CupertinoDynamicColor.opacity`]: https://api.flutter-io.cn/flutter/cupertino/CupertinoDynamicColor/opacity.html
[`CupertinoDynamicColor.a`]: https://api.flutter-io.cn/flutter/cupertino/CupertinoDynamicColor/a.html
[`CupertinoDynamicColor.withOpacity()`]: https://api.flutter-io.cn/flutter/cupertino/CupertinoDynamicColor/withOpacity.html
[`CupertinoDynamicColor.withValues()`]: https://api.flutter-io.cn/flutter/cupertino/CupertinoDynamicColor/withValues.html
[Migration guide for wide gamut Color]: /release/breaking-changes/wide-gamut-framework
[Implement wide gamut color support in the Framework]: https://github.com/flutter/flutter/issues/127855
[CupertinoDynamicColor is missing deprecation notices]: https://github.com/flutter/flutter/issues/171059
[Add missing deprecations to CupertinoDynamicColor]: https://github.com/flutter/flutter/pull/171160