Exploring Metadata Annotations in Dart

Sakshi Rai

20 November 2024

Metadata annotations in Dart add additional information to our code. Tools, libraries, or the Dart runtime can utilize this information.

These annotations can help with various tasks, including code generation, documentation, and runtime behaviour modification.

What Are Metadata Annotations:-

In Dart, we create metadata annotations using the @ symbol followed by the name of a class, which may include constructor arguments.

We can apply these annotations to classes, methods, fields, or parameters. Dart offers several built-in annotations. We can define custom annotations.

Here’s an example of a simple metadata annotation:

@deprecated
void oldMethod() {
  // This method is deprecated and should not be used
}

@deprecated

void oldMethod() {

// This method is deprecated and should not be used

}

Using Metadata Annotations in Flutter:-

In Flutter, developers use metadata annotations extensively to provide additional information about widgets, classes, and methods.

@required: This indicates that a parameter is required and must be provided when calling a method.
@deprecated: Marks a feature as deprecated.
@override: Indicates that a method is overriding a method in a superclass.
@optional: This indicates that a method or variable is for internal use only and should not receive direct access.
@protected: This indicates that a method or variable is for internal use only and should not receive direct access.
@visibleForTesting: This indicates that a method or variable is for testing purposes only and should not receive direct access.

Here’s an example of how the @required annotation is used in Flutter:

class MyWidget extends StatelessWidget {
  final String title;

  MyWidget(@required this.title);

  @override
  Widget build(BuildContext context) {
    return Text(title);
  }
}

class MyWidget extends StatelessWidget {

final String title;

MyWidget(@required this.title);

@override

Widget build(BuildContext context) {

return Text(title);

}

Creating Custom Annotations:-

Creating a custom annotation in Dart is simple. We define a class that accepts parameters. We annotate our code using instances of this class.

Example: Defining a Custom Annotation:-

We will create a custom annotation called @CustomAnnotations to add descriptive information to classes or methods.

class CustomAnnotations {
  final String description;

  const Info(this.description);
}

class CustomAnnotations {

final String description;

const Info(this.description);

}

In this example, we define a custom metadata annotation called CustomAnnotations that takes a description argument.

To use this annotation, we can apply it to a class or method:

@CustomAnnotations('This is a custom annotation')
class DemoClass {
  @CustomAnnotations('This is a annotation example')
  int add(int a, int b) => a + b;
  @CustomAnnotations('Subtracts the second number from the first.')
  int subtract(int a, int b) => a - b;
}

@CustomAnnotations('This is a custom annotation')

class DemoClass {

@CustomAnnotations('This is a annotation example')

int add(int a, int b) => a + b;

@CustomAnnotations('Subtracts the second number from the first.')

int subtract(int a, int b) => a - b;

}

Using Metadata Annotations for Code Generation:-

To access metadata annotations at runtime, we can utilize Dart’s reflection capabilities through the dart:mirrors library.

However, it’s important to note that dart:mirrors has limitations, particularly in web applications where tree shaking is applied. Here’s a guide on how to retrieve our custom annotations:

import 'dart:mirrors';

void getAnnotations(Type type) {
  final classMirror = reflectClass(type);
  final classAnnotations = classMirror.metadata;

  for (var annotation in classAnnotations) {
    if (annotation.reflectee is CustomAnnotations) {
      final CustomAnnotations = annotation.reflectee as CustomAnnotations;
      print('Class Annotation: ${CustomAnnotations.description}');
    }
  }

  // Check method annotations
  classMirror.declarations.forEach((key, value) {
    if (value is MethodMirror) {
      final methodAnnotations = value.metadata;
      for (var annotation in methodAnnotations) {
        if (annotation.reflectee is CustomAnnotations) {
          final customAnnotations = annotation.reflectee as CustomAnnotations;
          print('Method ${MirrorSystem.getName(key)} Annotation:             ${customAnnotations.description}');
        }
      }
    }
  });
}

void main() {
  getAnnotations(DemoClass);
}

import 'dart:mirrors';

void getAnnotations(Type type) {

final classMirror = reflectClass(type);

final classAnnotations = classMirror.metadata;

for (var annotation in classAnnotations) {

if (annotation.reflectee is CustomAnnotations) {

final CustomAnnotations = annotation.reflectee as CustomAnnotations;

print('Class Annotation: ${CustomAnnotations.description}');

}

// Check method annotations

classMirror.declarations.forEach((key, value) {

if (value is MethodMirror) {

final methodAnnotations = value.metadata;

for (var annotation in methodAnnotations) {

if (annotation.reflectee is CustomAnnotations) {

final customAnnotations = annotation.reflectee as CustomAnnotations;

print('Method ${MirrorSystem.getName(key)} Annotation: ${customAnnotations.description}');

}

});

}

void main() {

getAnnotations(DemoClass);

}

Output:-

Running the above code outputs the annotations associated with the DemoClass class and its methods:

Class Annotation: This is a custom annotation
Method demo Annotation: This is a annotation example
Method subtract Annotation: Create a demo class for annotation example

Class Annotation: This is a custom annotation

Method demo Annotation: This is a annotation example

Method subtract Annotation: Create a demo class for annotation example

Conclusion:-

Custom annotations in Dart are a powerful feature that allows us to add metadata to our classes and methods, enhancing the readability and maintainability of our code.

You can explore other blogs from this site.

Thanks for reading this blog ❤️

Hope this blog helped you to better understand Exploring Metadata Annotations in Dart.

References:-

https://30dayscoding.com/blog/building-flutter-apps-with-dart-metadata-annotations