[flutter_svg] feat: Expose the colorMapper property in SvgPicture (#9043)

## Description

This pull request exposes the existing `colorMapper` functionality in the `flutter_svg` package, allowing developers to customize SVG colors during parsing. 

## Related Issue

- flutter/flutter#158634

## Motivation

The `colorMapper` functionality was already present within the `flutter_svg` package but was not directly accessible through the `SvgPicture` constructors. By exposing this property, developers gain a powerful and flexible way to dynamically modify the colors of SVG assets based on custom logic. This can be useful for various scenarios, such as theming or branding.

## Example Usage

```dart
import 'package:flutter/material.dart';
import 'package:flutter_svg/flutter_svg.dart';

const String svgString = '''
<svg viewBox="0 0 100 100">
  <rect width="50" height="50" fill="#FF0000" />
  <circle cx="75" cy="75" r="25" fill="#00FF00" />
</svg>
''';

class MyColorMapper extends ColorMapper {
  const MyColorMapper();

  @OverRide
  Color substitute(
      String? id, String elementName, String attributeName, Color color) {
    if (color == const Color(0xFFFF0000)) {
      return Colors.blue;
    }
    if (color == const Color(0xFF00FF00)) {
      return Colors.yellow;
    }
    return color;
  }
}

void main() {
  runApp(MaterialApp(
    home: Scaffold(
      body: Center(
        child: SvgPicture.string(
          svgString,
          width: 200,
          height: 200,
          colorMapper: const MyColorMapper(),
        ),
      ),
    ),
  ));
}
```

Author: ricardodalarme

AUTHORS

@@ -78,3 +78,4 @@ Taskulu LDA <[email protected]>
 Alexander Rabin <[email protected]>
 LinXunFeng <[email protected]>
 Hashir Shoaib <[email protected]>
+Ricardo Dalarme <[email protected]>

third_party/packages/flutter_svg/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.1.0
+
+* Exposes `colorMapper` in `SvgPicture` constructors.
+
 ## 2.0.17
 
 * Implement errorBuilder callback

third_party/packages/flutter_svg/README.md

@@ -33,6 +33,53 @@ final Widget svgIcon = SvgPicture.asset(
 );
 ```
 
+For more advanced color manipulation, you can use the `colorMapper` property.
+This allows you to define a custom mapping function that will be called for
+every color encountered during SVG parsing, enabling you to substitute colors
+based on various criteria like the color value itself, the element name, or the
+attribute name.
+
+To use this feature, you need to create a class that extends `ColorMapper` and
+override the `substitute` method.
+
+Here's an example of how to implement a `ColorMapper` to replace specific colors in an SVG:
+
+<?code-excerpt "example/lib/readme_excerpts.dart (ColorMapper)"?>
+```dart
+class _MyColorMapper extends ColorMapper {
+  const _MyColorMapper();
+
+  @override
+  Color substitute(
+    String? id,
+    String elementName,
+    String attributeName,
+    Color color,
+  ) {
+    if (color == const Color(0xFFFF0000)) {
+      return Colors.blue;
+    }
+    if (color == const Color(0xFF00FF00)) {
+      return Colors.yellow;
+    }
+    return color;
+  }
+}
+// ···
+  const String svgString = '''
+<svg viewBox="0 0 100 100">
+  <rect width="50" height="50" fill="#FF0000" />
+  <circle cx="75" cy="75" r="25" fill="#00FF00" />
+</svg>
+''';
+  final Widget svgIcon = SvgPicture.string(
+    svgString,
+    colorMapper: const _MyColorMapper(),
+  );
+```
+
+In this example, all red colors in the SVG will be rendered as blue, and all green colors will be rendered as yellow. You can customize the `substitute` method to implement more complex color mapping logic based on your requirements.
+
 The default placeholder is an empty box (`LimitedBox`) - although if a `height`
 or `width` is specified on the `SvgPicture`, a `SizedBox` will be used instead
 (which ensures better layout experience). There is currently no way to show an
@@ -67,6 +114,7 @@ If you'd like to render the SVG to some other canvas, you can do something like:
 <?code-excerpt "example/lib/readme_excerpts.dart (OutputConversion)"?>
 ```dart
 import 'dart:ui' as ui;
+
 // ···
   const String rawSvg = '''<svg ...>...</svg>''';
   final PictureInfo pictureInfo =

third_party/packages/flutter_svg/example/lib/readme_excerpts.dart

@@ -7,6 +7,7 @@
 
 // #docregion OutputConversion
 import 'dart:ui' as ui;
+
 // #enddocregion OutputConversion
 
 import 'package:flutter/material.dart';
@@ -101,3 +102,42 @@ Future<ui.Image> convertSvgOutput() async {
   // #enddocregion OutputConversion
   return image;
 }
+
+// #docregion ColorMapper
+class _MyColorMapper extends ColorMapper {
+  const _MyColorMapper();
+
+  @override
+  Color substitute(
+    String? id,
+    String elementName,
+    String attributeName,
+    Color color,
+  ) {
+    if (color == const Color(0xFFFF0000)) {
+      return Colors.blue;
+    }
+    if (color == const Color(0xFF00FF00)) {
+      return Colors.yellow;
+    }
+    return color;
+  }
+}
+// #enddocregion ColorMapper
+
+/// Demonstrates loading an SVG asset with a color mapping.
+Widget loadWithColorMapper() {
+  // #docregion ColorMapper
+  const String svgString = '''
+<svg viewBox="0 0 100 100">
+  <rect width="50" height="50" fill="#FF0000" />
+  <circle cx="75" cy="75" r="25" fill="#00FF00" />
+</svg>
+''';
+  final Widget svgIcon = SvgPicture.string(
+    svgString,
+    colorMapper: const _MyColorMapper(),
+  );
+  // #enddocregion ColorMapper
+  return svgIcon;
+}

third_party/packages/flutter_svg/lib/svg.dart

@@ -195,6 +195,7 @@ class SvgPicture extends StatelessWidget {
     this.clipBehavior = Clip.hardEdge,
     this.errorBuilder,
     SvgTheme? theme,
+    ColorMapper? colorMapper,
     ui.ColorFilter? colorFilter,
     @Deprecated('Use colorFilter instead.') ui.Color? color,
     @Deprecated('Use colorFilter instead.')
@@ -205,6 +206,7 @@ class SvgPicture extends StatelessWidget {
           packageName: package,
           assetBundle: bundle,
           theme: theme,
+          colorMapper: colorMapper,
         ),
         colorFilter = colorFilter ?? _getColorFilter(color, colorBlendMode);
 
@@ -261,11 +263,13 @@ class SvgPicture extends StatelessWidget {
     this.errorBuilder,
     @Deprecated('This no longer does anything.') bool cacheColorFilter = false,
     SvgTheme? theme,
+    ColorMapper? colorMapper,
     http.Client? httpClient,
   })  : bytesLoader = SvgNetworkLoader(
           url,
           headers: headers,
           theme: theme,
+          colorMapper: colorMapper,
           httpClient: httpClient,
         ),
         colorFilter = colorFilter ?? _getColorFilter(color, colorBlendMode);
@@ -319,8 +323,13 @@ class SvgPicture extends StatelessWidget {
     this.clipBehavior = Clip.hardEdge,
     this.errorBuilder,
     SvgTheme? theme,
+    ColorMapper? colorMapper,
     @Deprecated('This no longer does anything.') bool cacheColorFilter = false,
-  })  : bytesLoader = SvgFileLoader(file, theme: theme),
+  })  : bytesLoader = SvgFileLoader(
+          file,
+          theme: theme,
+          colorMapper: colorMapper,
+        ),
         colorFilter = colorFilter ?? _getColorFilter(color, colorBlendMode);
 
   /// Creates a widget that displays an SVG obtained from a [Uint8List].
@@ -369,8 +378,13 @@ class SvgPicture extends StatelessWidget {
     this.clipBehavior = Clip.hardEdge,
     this.errorBuilder,
     SvgTheme? theme,
+    ColorMapper? colorMapper,
     @Deprecated('This no longer does anything.') bool cacheColorFilter = false,
-  })  : bytesLoader = SvgBytesLoader(bytes, theme: theme),
+  })  : bytesLoader = SvgBytesLoader(
+          bytes,
+          theme: theme,
+          colorMapper: colorMapper,
+        ),
         colorFilter = colorFilter ?? _getColorFilter(color, colorBlendMode);
 
   /// Creates a widget that displays an SVG obtained from a [String].
@@ -419,8 +433,13 @@ class SvgPicture extends StatelessWidget {
     this.clipBehavior = Clip.hardEdge,
     this.errorBuilder,
     SvgTheme? theme,
+    ColorMapper? colorMapper,
     @Deprecated('This no longer does anything.') bool cacheColorFilter = false,
-  })  : bytesLoader = SvgStringLoader(string, theme: theme),
+  })  : bytesLoader = SvgStringLoader(
+          string,
+          theme: theme,
+          colorMapper: colorMapper,
+        ),
         colorFilter = colorFilter ?? _getColorFilter(color, colorBlendMode);
 
   static ColorFilter? _getColorFilter(

third_party/packages/flutter_svg/pubspec.yaml

@@ -2,7 +2,7 @@ name: flutter_svg
 description: An SVG rendering and widget library for Flutter, which allows painting and displaying Scalable Vector Graphics 1.1 files.
 repository: https://github.com/flutter/packages/tree/main/third_party/packages/flutter_svg
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+flutter_svg%22
-version: 2.0.17
+version: 2.1.0
 
 environment:
   sdk: ^3.4.0

third_party/packages/flutter_svg/test/golden_widget/flutter_logo.asset.color_mapper.png

@@ -39,6 +39,29 @@ Future<void> _checkWidgetAndGolden(Key key, String filename) async {
   await expectLater(widgetFinder, matchesGoldenFile('golden_widget/$filename'));
 }
 
+class _TestColorMapper extends ColorMapper {
+  const _TestColorMapper();
+
+  /// Substitutes specific colors for testing the SVG rendering.
+  @override
+  Color substitute(
+      String? id, String elementName, String attributeName, Color color) {
+    if (color == const Color(0xFF42A5F5)) {
+      return const Color(0xFF00FF00); // Green
+    }
+    if (color == const Color(0xFF0D47A1)) {
+      return const Color(0xFFFF0000); // Red
+    }
+    if (color == const Color(0xFF616161)) {
+      return const Color(0xFF0000FF); // Blue
+    }
+    if (color == const Color(0xFF000000)) {
+      return const Color(0xFFFFFF00); // Yellow
+    }
+    return color;
+  }
+}
+
 void main() {
   final MediaQueryData mediaQueryData =
       MediaQueryData.fromView(PlatformDispatcher.instance.implicitView!);
@@ -116,6 +139,28 @@ void main() {
     await _checkWidgetAndGolden(key, 'flutter_logo.string.png');
   });
 
+  testWidgets('SvgPicture.string with colorMapper',
+      (WidgetTester tester) async {
+    final GlobalKey key = GlobalKey();
+    await tester.pumpWidget(
+      MediaQuery(
+        data: mediaQueryData,
+        child: RepaintBoundary(
+          key: key,
+          child: SvgPicture.string(
+            svgStr,
+            width: 100.0,
+            height: 100.0,
+            colorMapper: const _TestColorMapper(),
+          ),
+        ),
+      ),
+    );
+
+    await tester.pumpAndSettle();
+    await _checkWidgetAndGolden(key, 'flutter_logo.string.color_mapper.png');
+  });
+
   testWidgets('SvgPicture natural size', (WidgetTester tester) async {
     final GlobalKey key = GlobalKey();
     await tester.pumpWidget(
@@ -250,6 +295,26 @@ void main() {
     await _checkWidgetAndGolden(key, 'flutter_logo.memory.png');
   });
 
+  testWidgets('SvgPicture.memory with colorMapper',
+      (WidgetTester tester) async {
+    final GlobalKey key = GlobalKey();
+    await tester.pumpWidget(
+      MediaQuery(
+        data: mediaQueryData,
+        child: RepaintBoundary(
+          key: key,
+          child: SvgPicture.memory(
+            svgBytes,
+            colorMapper: const _TestColorMapper(),
+          ),
+        ),
+      ),
+    );
+    await tester.pumpAndSettle();
+
+    await _checkWidgetAndGolden(key, 'flutter_logo.memory.color_mapper.png');
+  });
+
   testWidgets('SvgPicture.asset', (WidgetTester tester) async {
     final FakeAssetBundle fakeAsset = FakeAssetBundle();
     final GlobalKey key = GlobalKey();
@@ -269,6 +334,26 @@ void main() {
     await _checkWidgetAndGolden(key, 'flutter_logo.asset.png');
   });
 
+  testWidgets('SvgPicture.asset with colorMapper', (WidgetTester tester) async {
+    final FakeAssetBundle fakeAsset = FakeAssetBundle();
+    final GlobalKey key = GlobalKey();
+    await tester.pumpWidget(
+      MediaQuery(
+        data: mediaQueryData,
+        child: RepaintBoundary(
+          key: key,
+          child: SvgPicture.asset(
+            'test.svg',
+            bundle: fakeAsset,
+            colorMapper: const _TestColorMapper(),
+          ),
+        ),
+      ),
+    );
+    await tester.pumpAndSettle();
+    await _checkWidgetAndGolden(key, 'flutter_logo.asset.color_mapper.png');
+  });
+
   testWidgets('SvgPicture.asset DefaultAssetBundle',
       (WidgetTester tester) async {
     final FakeAssetBundle fakeAsset = FakeAssetBundle();
@@ -295,6 +380,33 @@ void main() {
     await _checkWidgetAndGolden(key, 'flutter_logo.asset.png');
   });
 
+  testWidgets('SvgPicture.asset DefaultAssetBundle with colorMapper',
+      (WidgetTester tester) async {
+    final FakeAssetBundle fakeAsset = FakeAssetBundle();
+    final GlobalKey key = GlobalKey();
+    await tester.pumpWidget(
+      Directionality(
+        textDirection: TextDirection.ltr,
+        child: MediaQuery(
+          data: mediaQueryData,
+          child: DefaultAssetBundle(
+            bundle: fakeAsset,
+            child: RepaintBoundary(
+              key: key,
+              child: SvgPicture.asset(
+                'test.svg',
+                semanticsLabel: 'Test SVG',
+                colorMapper: const _TestColorMapper(),
+              ),
+            ),
+          ),
+        ),
+      ),
+    );
+    await tester.pumpAndSettle();
+    await _checkWidgetAndGolden(key, 'flutter_logo.asset.color_mapper.png');
+  });
+
   testWidgets('SvgPicture.network', (WidgetTester tester) async {
     final GlobalKey key = GlobalKey();
     await tester.pumpWidget(
@@ -313,6 +425,26 @@ void main() {
     await _checkWidgetAndGolden(key, 'flutter_logo.network.png');
   });
 
+  testWidgets('SvgPicture.network with colorMapper',
+      (WidgetTester tester) async {
+    final GlobalKey key = GlobalKey();
+    await tester.pumpWidget(
+      MediaQuery(
+        data: mediaQueryData,
+        child: RepaintBoundary(
+          key: key,
+          child: SvgPicture.network(
+            'test.svg',
+            httpClient: FakeHttpClient(),
+            colorMapper: const _TestColorMapper(),
+          ),
+        ),
+      ),
+    );
+    await tester.pumpAndSettle();
+    await _checkWidgetAndGolden(key, 'flutter_logo.network.color_mapper.png');
+  });
+
   testWidgets('SvgPicture.network with headers', (WidgetTester tester) async {
     final GlobalKey key = GlobalKey();
     final FakeHttpClient client = FakeHttpClient();