angular-cn/public/docs/dart/latest/guide/dependency-injection.jade

include ../_util-fns

+includeShared('{ts}', 'intro')

:marked
  The complete source code for the example app in this chapter is
  [in GitHub](https://github.com/angular/angular.io/tree/master/public/docs/_examples/dependency-injection/dart).

+includeShared('{ts}', 'why-1')
+makeExample('dependency-injection/dart/lib/car/car_no_di.dart', 'car', 'lib/car/car.dart (without DI)')
+includeShared('{ts}', 'why-2')
+makeTabs(
  'dependency-injection/dart/lib/car/car.dart, dependency-injection/dart/lib/car/car_no_di.dart',
  'car-ctor, car-ctor',
  'lib/car/car.dart (excerpt with DI), lib/car/car.dart (excerpt without DI)')(format=".")
+includeShared('{ts}', 'why-3-1')
+includeShared('{ts}', 'why-3-2')
- var stylePattern = { otl: /(new Car.*$)/gm };
+makeExample('dependency-injection/dart/lib/car/car_creations.dart', 'car-ctor-instantiation', '', stylePattern)(format=".")
+includeShared('{ts}', 'why-4')
.l-sub-section
  :marked
    The _consumer_ of `Car` has the problem. The consumer must update the car creation code to
    something like this:
  - var stylePattern = { otl: /(new Car.*$)/gm };
  +makeExample('dependency-injection/dart/lib/car/car_creations.dart', 'car-ctor-instantiation-with-param', '', stylePattern)(format=".")
  :marked
    The critical point is this: `Car` itself did not have to change.
    We'll take care of the consumer's problem soon enough.
+includeShared('{ts}', 'why-6')
- var stylePattern = { otl: /(new Car.*$)/gm };
+makeExample('dependency-injection/dart/lib/car/car_creations.dart', 'car-ctor-instantiation-with-mocks', '', stylePattern)(format=".")
+includeShared('{ts}', 'why-7')
+makeExample('dependency-injection/dart/lib/car/car_factory.dart', null, 'lib/car/car_factory.dart')
+includeShared('{ts}', 'why-8')
+makeExample('dependency-injection/dart/lib/car/car_injector.dart','injector-call')(format=".")
+includeShared('{ts}', 'why-9')

+includeShared('{ts}', 'di-1')
+makeTabs(
  `dependency-injection/dart/lib/heroes/heroes_component_1.dart,
  dependency-injection/dart/lib/heroes/hero_list_component_1.dart,
  dependency-injection/dart/lib/heroes/hero.dart,
  dependency-injection/dart/lib/heroes/mock_heroes.dart`,
  'v1,,,',
  `lib/heroes/heroes_component.dart,
  lib/heroes/hero_list_component.dart,
  lib/heroes/hero.dart,
  lib/heroes/mock_heroes.dart`)
+includeShared('{ts}', 'di-2')
+includeShared('{ts}', 'di-3')
+makeExample('dependency-injection/dart/lib/heroes/hero_service_1.dart',null, 'lib/heroes/hero_service.dart' )
+includeShared('{ts}', 'di-4')
.l-sub-section
  :marked
    We aren't even pretending this is a real service.
    If we were actually getting data from a remote server, the API would have to be asynchronous,
    returning a `Future`.
    We'd also have to rewrite the way components consume our service.
    This is important in general, but not to our current story.
+includeShared('{ts}', 'di-6')
+includeShared('{ts}', 'di-configure-injector-1')
+makeExample('dependency-injection/dart/web/main.dart', 'bootstrap', 'web/main.dart (excerpt)')(format='.')
+includeShared('{ts}', 'di-configure-injector-2')
+makeExample('dependency-injection/dart/web/main_1.dart', 'bootstrap')(format='.')
+includeShared('{ts}', 'di-configure-injector-3')
+includeShared('{ts}', 'di-register-providers-1')
+makeExample('dependency-injection/dart/lib/heroes/heroes_component_1.dart',null,'lib/heroes/heroes_component.dart')
+includeShared('{ts}', 'di-register-providers-2')
+makeExample('dependency-injection/dart/lib/heroes/heroes_component_1.dart','providers')(format='.')
+includeShared('{ts}', 'di-register-providers-3')
+includeShared('{ts}', 'di-prepare-for-injection-1')
+makeTabs(
  `dependency-injection/dart/lib/heroes/hero_list_component_2.dart,
  dependency-injection/dart/lib/heroes/hero_list_component_1.dart`,
  null,
  `lib/heroes/hero_list_component (with DI),
   lib/heroes/hero_list_component (without DI)`)
.l-sub-section
  :marked
    ### Focus on the constructor

    Adding a parameter to the constructor isn't all that's happening here.
  +makeExample('dependency-injection/dart/lib/heroes/hero_list_component_2.dart', 'ctor')(format=".")
  :marked
    The constructor parameter has a type: `HeroService`.
    The `HeroListComponent` class is also annotated with `@Component`
    (scroll up to confirm that fact).
    Also recall that the parent component (`HeroesComponent`)
    has `providers` information for `HeroService`.

    The constructor parameter type, the `@Component` annotation,
    and the parent's `providers` information combine to tell the
    Angular injector to inject an instance of
    `HeroService` whenever it creates a new `HeroListComponent`.
+includeShared('{ts}', 'di-create-injector-implicitly-1')
+makeExample('dependency-injection/dart/lib/car/car_injector.dart','injector-create-and-call')(format=".")
+includeShared('{ts}', 'di-create-injector-implicitly-2')
+includeShared('{ts}', 'di-singleton-services')

// Skip the testing section, for now.
// includeShared('{ts}', 'di-testing-component-1')
// includeShared('{ts}', 'di-testing-component-2')

+includeShared('{ts}', 'di-service-service-1')
+makeTabs(
  `dependency-injection/dart/lib/heroes/hero_service_2.dart,
  dependency-injection/dart/lib/heroes/hero_service_1.dart`,
  null,
  `lib/heroes/hero_service (v.2),
  lib/heroes/hero_service (v.1)`)
+includeShared('{ts}', 'di-service-service-2')
+includeShared('{ts}', 'di-injectable-1')
:marked
  Forgetting the `@Injectable()` can cause a runtime error:
code-example(format, language="html").
  Cannot find reflection information on <Type>
+includeShared('{ts}', 'di-injectable-2')
.callout.is-critical
  header Always include the parentheses
  :marked
    Always use `@Injectable()`, not just `@Injectable`.
    A metadata annotation must be either a reference to a
    compile-time constant variable or a call to a constant
    constructor such as `Injectable()`.
    If we forget the parentheses, the analyzer will complain:
    "Annotation creation must have arguments". If we try to run the
    app anyway, it won't work, and the console will say
    "expression must be a compile-time constant".
+includeShared('{ts}', 'logger-service-1')
+makeExample(
  'dependency-injection/dart/lib/logger_service.dart',null, 'lib/logger_service')
.l-sub-section
  :marked
    ### Implementing a logger

    Our examples use a simple logger.
    A real implementation would probably use the
    [logging package](https://pub.dartlang.org/packages/logging).
:marked
  We're likely to need the same logger service everywhere in our application,
  so we put it in the `lib/` folder, and
  we register it in the `providers` array of the metadata for our application root component, `AppComponent`.
+makeExample('dependency-injection/dart/lib/providers_component.dart','providers-logger', 'lib/app_component.dart (excerpt)')
+includeShared('{ts}', 'logger-service-3')
+includeShared('{ts}', 'logger-service-4')
+includeShared('{ts}', 'logger-service-5')
+makeExample('dependency-injection/dart/lib/providers_component.dart','provider-10-ctor')(format='.')
+includeShared('{ts}', 'logger-service-6')
+makeExample('dependency-injection/dart/lib/providers_component.dart','provider-10-logger')(format='.')
+includeShared('{ts}', 'logger-service-7')

+includeShared('{ts}', 'providers-1')
+makeExample('dependency-injection/dart/lib/providers_component.dart','providers-logger')
+includeShared('{ts}', 'providers-2')
+includeShared('{ts}', 'providers-provide-1')
:marked
  ### The *Provider* class
+includeShared('{ts}', 'providers-provide-1-1')
+makeExample('dependency-injection/dart/lib/providers_component.dart','providers-1')
+includeShared('{ts}', 'providers-provide-2')
+makeExample('dependency-injection/dart/lib/providers_component.dart','providers-2')
// includeShared('{ts}', 'providers-provide-3')
// includeShared('{ts}', 'providers-provide-4-1')
// Don't discuss provide function.
:marked
  We supply two arguments (or more) to the `Provider` constructor.
+includeShared('{ts}', 'providers-provide-4-2')
:marked
  The second is a named parameter, such as `useClass`,
  that we can think of as a *recipe* for creating the dependency value.
  There are many ways to create dependency values... and many ways to write a recipe.
+includeShared('{ts}', 'providers-alternative-1')
+makeExample('dependency-injection/dart/lib/providers_component.dart','providers-4')
.callout.is-helpful
  header Dart difference: Constants in metadata
  :marked
    In Dart, the value of a metadata annotation must be a compile-time constant.
    For that reason, we can't call functions to get values
    to use within an annotation.
    Instead, we use constant literals or constant constructors.
    For example, a TypeScript program might use the
    function call `provide(Logger, {useClass: BetterLogger})`,
    which is equivalent to the TypeScript code
    `new Provider(Logger, {useClass: BetterLogger})`.
    A Dart annotation would instead use the constant value `const Provider(Logger, useClass: BetterLogger)`.
+includeShared('{ts}', 'providers-alternative-2')
+makeExample('dependency-injection/dart/lib/providers_component.dart','EvenBetterLogger')
+includeShared('{ts}', 'providers-alternative-3')
+makeExample('dependency-injection/dart/lib/providers_component.dart','providers-5')(format=".")
+includeShared('{ts}', 'providers-aliased-1')
+makeExample('dependency-injection/dart/lib/providers_component.dart','providers-6a')(format=".")
+includeShared('{ts}', 'providers-aliased-2')
- var stylePattern = { otl: /(useExisting.*\))/gm };
+makeExample('dependency-injection/dart/lib/providers_component.dart','providers-6b','', stylePattern)(format=".")

+includeShared('{ts}', 'providers-value-1')
:marked
  We can provide objects directly,
  instead of asking the injector to create an instance of a class,
  by specifying a `useValue` parameter to `Provider`.

  Because Dart annotations must be compile-time constants,
  `useValue` is often used with string or list literals.
  However, `useValue` works with any constant object.

  To create a class that can provide constant objects,
  make sure all its instance variables are `final`,
  and give it a `const` constructor:

+makeExample('dependency-injection/dart/lib/app_config.dart','const-class','lib/app_config.dart (excerpt)')(format='.')

:marked
  Create a constant instance of the class by using `const` instead of `new`:

+makeExample('dependency-injection/dart/lib/app_config.dart','const-object','lib/app_config.dart (excerpt)')(format='.')

:marked
  Then specify the object using the `useValue` argument to `Provider`:

- var stylePattern = { otl: /(useValue.*\))/gm };
+makeExample('dependency-injection/dart/lib/providers_component.dart','providers-9','', stylePattern)(format='.')

:marked
  See more `useValue` examples in the
  [Non-class dependencies](#non-class-dependencies) and
  [OpaqueToken](#opaquetoken) sections.

+includeShared('{ts}', 'providers-factory-1')
+makeExample('dependency-injection/dart/lib/heroes/hero_service.dart','internals', 'lib/heroes/hero_service.dart (excerpt)')(format='.')
+includeShared('{ts}', 'providers-factory-2')
+makeExample('dependency-injection/dart/lib/heroes/hero_service_provider.dart','factory', 'lib/heroes/hero_service_provider.dart (excerpt)')(format='.')
+includeShared('{ts}', 'providers-factory-3')
+makeExample('dependency-injection/dart/lib/heroes/hero_service_provider.dart','provider', 'lib/heroes/hero_service_provider.dart (excerpt)')(format='.')
+includeShared('{ts}', 'providers-factory-4')
+includeShared('{ts}', 'providers-factory-5')
- var stylePattern = { otl: /(providers.*),$/gm };
+makeTabs(
  `dependency-injection/dart/lib/heroes/heroes_component.dart,
  dependency-injection/dart/lib/heroes/heroes_component_1.dart`,
  null,
  `lib/heroes/heroes_component (v.3),
  lib/heroes/heroes_component (v.2)`,
  stylePattern)
+includeShared('{ts}', 'tokens-1')
+makeExample('dependency-injection/dart/lib/injector_component.dart','get-hero-service')(format='.')
+includeShared('{ts}', 'tokens-2')
// [PENDING: How about a better name than ProviderComponent8?]
+makeExample('dependency-injection/dart/lib/providers_component.dart','provider-8-ctor')(format=".")
+includeShared('{ts}', 'tokens-3')
.callout.is-helpful
  header Dart difference: Interfaces are valid tokens
  :marked
    In TypeScript, interfaces don't work as provider tokens.
    Dart doesn't have this problem;
    every class implicitly defines an interface,
    so interface names are just class names.
+includeShared('{ts}', 'tokens-non-class-deps-1')
:marked
  We know we can register an object with a [value provider](#value-provider).
  But what do we use for the token?
+includeShared('{ts}', 'tokens-opaque-1')
+makeExample('dependency-injection/dart/lib/providers_component.dart','opaque-token')(format='.')
+includeShared('{ts}', 'tokens-opaque-2')
+makeExample('dependency-injection/dart/lib/providers_component.dart','use-opaque-token')(format=".")
:marked
  Here's an example of providing configuration information
  for an injected class. First define the class:
+makeExample('dependency-injection/dart/lib/providers_component.dart','configurable-logger')(format=".")
:marked
  Then inject that class and its configuration information:
+makeExample('dependency-injection/dart/lib/providers_component.dart','providers-7')(format=".")


+includeShared('{ts}', 'summary')

+includeShared('{ts}', 'appendix-explicit-injector-1')
+makeExample('dependency-injection/dart/lib/injector_component.dart', 'injector', 'lib/injector_component.dart')
+includeShared('{ts}', 'appendix-explicit-injector-2')