UpgradeAdapter

Use UpgradeAdapter to allow AngularJS and Angular to coexist in a single application.

查看"说明"...

已弃用: Deprecated since v5. Use upgrade/static instead, which also supports Ahead-of-Time compilation.

      
      class UpgradeAdapter {
  constructor(ng2AppModule: Type<any>, compilerOptions?: CompilerOptions)
  downgradeNg2Component(component: Type<any>): Function
  upgradeNg1Component(name: string): Type<any>
  registerForNg1Tests(modules?: string[]): UpgradeAdapterRef
  bootstrap(element: Element, modules?: any[], config?: IAngularBootstrapConfig): UpgradeAdapterRef
  upgradeNg1Provider(name: string, options?: { asToken: any; })
  downgradeNg2Provider(token: any): Function
}
    

说明

The UpgradeAdapter allows: 1. creation of Angular component from AngularJS component directive (See [UpgradeAdapter#upgradeNg1Component()]) 2. creation of AngularJS directive from Angular component. (See [UpgradeAdapter#downgradeNg2Component()]) 3. Bootstrapping of a hybrid Angular application which contains both of the frameworks coexisting in a single application.

构造函数

constructor(ng2AppModule: Type<any>, compilerOptions?: CompilerOptions)
      
      constructor(ng2AppModule: Type<any>, compilerOptions?: CompilerOptions)
    
参数
ng2AppModule Type
compilerOptions CompilerOptions

可选. 默认值是 undefined.

方法

Allows Angular Component to be used from AngularJS.

downgradeNg2Component(component: Type<any>): Function
      
      downgradeNg2Component(component: Type<any>): Function
    
参数
component Type
返回值

Function

Use downgradeNg2Component to create an AngularJS Directive Definition Factory from Angular Component. The adapter will bootstrap Angular component from within the AngularJS template.

使用说明

Mental Model
  1. The component is instantiated by being listed in AngularJS template. This means that the host element is controlled by AngularJS, but the component's view will be controlled by Angular.
  2. Even thought the component is instantiated in AngularJS, it will be using Angular syntax. This has to be done, this way because we must follow Angular components do not declare how the attributes should be interpreted.
  3. ng-model is controlled by AngularJS and communicates with the downgraded Angular component by way of the ControlValueAccessor interface from @angular/forms. Only components that implement this interface are eligible.
Supported Features
  • Bindings:

    • Attribute: <comp name="World">
    • Interpolation: <comp greeting="Hello {{name}}!">
    • Expression: <comp [name]="username">
    • Event: <comp (close)="doSomething()">
    • ng-model: <comp ng-model="name">
  • Content projection: yes
Example
const adapter = new UpgradeAdapter(forwardRef(() => MyNg2Module)); const module = angular.module('myExample', []); module.directive('greet', adapter.downgradeNg2Component(Greeter)); @Component({ selector: 'greet', template: '{{salutation}} {{name}}! - <ng-content></ng-content>' }) class Greeter { @Input() salutation: string; @Input() name: string; } @NgModule({ declarations: [Greeter], imports: [BrowserModule] }) class MyNg2Module {} document.body.innerHTML = 'ng1 template: <greet salutation="Hello" [name]="world">text</greet>'; adapter.bootstrap(document.body, ['myExample']).ready(function() { expect(document.body.textContent).toEqual("ng1 template: Hello world! - text"); });
      
      
  1. const adapter = new UpgradeAdapter(forwardRef(() => MyNg2Module));
  2. const module = angular.module('myExample', []);
  3. module.directive('greet', adapter.downgradeNg2Component(Greeter));
  4.  
  5. @Component({
  6. selector: 'greet',
  7. template: '{{salutation}} {{name}}! - <ng-content></ng-content>'
  8. })
  9. class Greeter {
  10. @Input() salutation: string;
  11. @Input() name: string;
  12. }
  13.  
  14. @NgModule({
  15. declarations: [Greeter],
  16. imports: [BrowserModule]
  17. })
  18. class MyNg2Module {}
  19.  
  20. document.body.innerHTML =
  21. 'ng1 template: <greet salutation="Hello" [name]="world">text</greet>';
  22.  
  23. adapter.bootstrap(document.body, ['myExample']).ready(function() {
  24. expect(document.body.textContent).toEqual("ng1 template: Hello world! - text");
  25. });

Allows AngularJS Component to be used from Angular.

upgradeNg1Component(name: string): Type<any>
      
      upgradeNg1Component(name: string): Type<any>
    
参数
name string
返回值

Type<any>

Use upgradeNg1Component to create an Angular component from AngularJS Component directive. The adapter will bootstrap AngularJS component from within the Angular template.

使用说明

Mental Model
  1. The component is instantiated by being listed in Angular template. This means that the host element is controlled by Angular, but the component's view will be controlled by AngularJS.
Supported Features
  • Bindings:

    • Attribute: <comp name="World">
    • Interpolation: <comp greeting="Hello {{name}}!">
    • Expression: <comp [name]="username">
    • Event: <comp (close)="doSomething()">
  • Transclusion: yes
  • Only some of the features of Directive Definition Object are supported:

    • compile: not supported because the host element is owned by Angular, which does not allow modifying DOM structure during compilation.
    • controller: supported. (NOTE: injection of $attrs and $transclude is not supported.)
    • controllerAs: supported.
    • bindToController: supported.
    • link: supported. (NOTE: only pre-link function is supported.)
    • name: supported.
    • priority: ignored.
    • replace: not supported.
    • require: supported.
    • restrict: must be set to 'E'.
    • scope: supported.
    • template: supported.
    • templateUrl: supported.
    • terminal: ignored.
    • transclude: supported.
Example
const adapter = new UpgradeAdapter(forwardRef(() => MyNg2Module)); const module = angular.module('myExample', []); module.directive('greet', function() { return { scope: {salutation: '=', name: '=' }, template: '{{salutation}} {{name}}! - <span ng-transclude></span>' }; }); module.directive('ng2', adapter.downgradeNg2Component(Ng2Component)); @Component({ selector: 'ng2', template: 'ng2 template: <greet salutation="Hello" [name]="world">text</greet>' }) class Ng2Component { } @NgModule({ declarations: [Ng2Component, adapter.upgradeNg1Component('greet')], imports: [BrowserModule] }) class MyNg2Module {} document.body.innerHTML = '<ng2></ng2>'; adapter.bootstrap(document.body, ['myExample']).ready(function() { expect(document.body.textContent).toEqual("ng2 template: Hello world! - text"); });
      
      
  1. const adapter = new UpgradeAdapter(forwardRef(() => MyNg2Module));
  2. const module = angular.module('myExample', []);
  3.  
  4. module.directive('greet', function() {
  5. return {
  6. scope: {salutation: '=', name: '=' },
  7. template: '{{salutation}} {{name}}! - <span ng-transclude></span>'
  8. };
  9. });
  10.  
  11. module.directive('ng2', adapter.downgradeNg2Component(Ng2Component));
  12.  
  13. @Component({
  14. selector: 'ng2',
  15. template: 'ng2 template: <greet salutation="Hello" [name]="world">text</greet>'
  16. })
  17. class Ng2Component {
  18. }
  19.  
  20. @NgModule({
  21. declarations: [Ng2Component, adapter.upgradeNg1Component('greet')],
  22. imports: [BrowserModule]
  23. })
  24. class MyNg2Module {}
  25.  
  26. document.body.innerHTML = '<ng2></ng2>';
  27.  
  28. adapter.bootstrap(document.body, ['myExample']).ready(function() {
  29. expect(document.body.textContent).toEqual("ng2 template: Hello world! - text");
  30. });

Registers the adapter's AngularJS upgrade module for unit testing in AngularJS. Use this instead of angular.mock.module() to load the upgrade module into the AngularJS testing injector.

registerForNg1Tests(modules?: string[]): UpgradeAdapterRef
      
      registerForNg1Tests(modules?: string[]): UpgradeAdapterRef
    
参数
modules string[]

可选. 默认值是 undefined.

any AngularJS modules that the upgrade module should depend upon

返回值

UpgradeAdapterRef: an UpgradeAdapterRef, which lets you register a ready() callback to run assertions once the Angular components are ready to test through AngularJS.

使用说明

Example
const upgradeAdapter = new UpgradeAdapter(MyNg2Module); // configure the adapter with upgrade/downgrade components and services upgradeAdapter.downgradeNg2Component(MyComponent); let upgradeAdapterRef: UpgradeAdapterRef; let $compile, $rootScope; // We must register the adapter before any calls to `inject()` beforeEach(() => { upgradeAdapterRef = upgradeAdapter.registerForNg1Tests(['heroApp']); }); beforeEach(inject((_$compile_, _$rootScope_) => { $compile = _$compile_; $rootScope = _$rootScope_; })); it("says hello", (done) => { upgradeAdapterRef.ready(() => { const element = $compile("<my-component></my-component>")($rootScope); $rootScope.$apply(); expect(element.html()).toContain("Hello World"); done(); }) });
      
      
  1. const upgradeAdapter = new UpgradeAdapter(MyNg2Module);
  2.  
  3. // configure the adapter with upgrade/downgrade components and services
  4. upgradeAdapter.downgradeNg2Component(MyComponent);
  5.  
  6. let upgradeAdapterRef: UpgradeAdapterRef;
  7. let $compile, $rootScope;
  8.  
  9. // We must register the adapter before any calls to `inject()`
  10. beforeEach(() => {
  11. upgradeAdapterRef = upgradeAdapter.registerForNg1Tests(['heroApp']);
  12. });
  13.  
  14. beforeEach(inject((_$compile_, _$rootScope_) => {
  15. $compile = _$compile_;
  16. $rootScope = _$rootScope_;
  17. }));
  18.  
  19. it("says hello", (done) => {
  20. upgradeAdapterRef.ready(() => {
  21. const element = $compile("<my-component></my-component>")($rootScope);
  22. $rootScope.$apply();
  23. expect(element.html()).toContain("Hello World");
  24. done();
  25. })
  26. });

Bootstrap a hybrid AngularJS / Angular application.

bootstrap(element: Element, modules?: any[], config?: IAngularBootstrapConfig): UpgradeAdapterRef
      
      bootstrap(element: Element, modules?: any[], config?: IAngularBootstrapConfig): UpgradeAdapterRef
    
参数
element Element
modules any[]

可选. 默认值是 undefined.

config IAngularBootstrapConfig

可选. 默认值是 undefined.

返回值

UpgradeAdapterRef

This bootstrap method is a direct replacement (takes same arguments) for AngularJS bootstrapmethod. Unlike AngularJS, this bootstrap is asynchronous.

使用说明

Example
const adapter = new UpgradeAdapter(MyNg2Module); const module = angular.module('myExample', []); module.directive('ng2', adapter.downgradeNg2Component(Ng2)); module.directive('ng1', function() { return { scope: { title: '=' }, template: 'ng1[Hello {{title}}!](<span ng-transclude></span>)' }; }); @Component({ selector: 'ng2', inputs: ['name'], template: 'ng2[<ng1 [title]="name">transclude</ng1>](<ng-content></ng-content>)' }) class Ng2 { } @NgModule({ declarations: [Ng2, adapter.upgradeNg1Component('ng1')], imports: [BrowserModule] }) class MyNg2Module {} document.body.innerHTML = '<ng2 name="World">project</ng2>'; adapter.bootstrap(document.body, ['myExample']).ready(function() { expect(document.body.textContent).toEqual( "ng2[ng1[Hello World!](transclude)](project)"); });
      
      
  1. const adapter = new UpgradeAdapter(MyNg2Module);
  2. const module = angular.module('myExample', []);
  3. module.directive('ng2', adapter.downgradeNg2Component(Ng2));
  4.  
  5. module.directive('ng1', function() {
  6. return {
  7. scope: { title: '=' },
  8. template: 'ng1[Hello {{title}}!](<span ng-transclude></span>)'
  9. };
  10. });
  11.  
  12.  
  13. @Component({
  14. selector: 'ng2',
  15. inputs: ['name'],
  16. template: 'ng2[<ng1 [title]="name">transclude</ng1>](<ng-content></ng-content>)'
  17. })
  18. class Ng2 {
  19. }
  20.  
  21. @NgModule({
  22. declarations: [Ng2, adapter.upgradeNg1Component('ng1')],
  23. imports: [BrowserModule]
  24. })
  25. class MyNg2Module {}
  26.  
  27. document.body.innerHTML = '<ng2 name="World">project</ng2>';
  28.  
  29. adapter.bootstrap(document.body, ['myExample']).ready(function() {
  30. expect(document.body.textContent).toEqual(
  31. "ng2[ng1[Hello World!](transclude)](project)");
  32. });

Allows AngularJS service to be accessible from Angular.

upgradeNg1Provider(name: string, options?: { asToken: any; })
      
      upgradeNg1Provider(name: string, options?: { asToken: any; })
    
参数
name string
options { asToken: any; }

可选. 默认值是 undefined.

使用说明

Example
class Login { ... } class Server { ... } @Injectable() class Example { constructor(@Inject('server') server, login: Login) { ... } } const module = angular.module('myExample', []); module.service('server', Server); module.service('login', Login); const adapter = new UpgradeAdapter(MyNg2Module); adapter.upgradeNg1Provider('server'); adapter.upgradeNg1Provider('login', {asToken: Login}); adapter.bootstrap(document.body, ['myExample']).ready((ref) => { const example: Example = ref.ng2Injector.get(Example); });
      
      
  1. class Login { ... }
  2. class Server { ... }
  3.  
  4. @Injectable()
  5. class Example {
  6. constructor(@Inject('server') server, login: Login) {
  7. ...
  8. }
  9. }
  10.  
  11. const module = angular.module('myExample', []);
  12. module.service('server', Server);
  13. module.service('login', Login);
  14.  
  15. const adapter = new UpgradeAdapter(MyNg2Module);
  16. adapter.upgradeNg1Provider('server');
  17. adapter.upgradeNg1Provider('login', {asToken: Login});
  18.  
  19. adapter.bootstrap(document.body, ['myExample']).ready((ref) => {
  20. const example: Example = ref.ng2Injector.get(Example);
  21. });

Allows Angular service to be accessible from AngularJS.

downgradeNg2Provider(token: any): Function
      
      downgradeNg2Provider(token: any): Function
    
参数
token any
返回值

Function

使用说明

Example
class Example { } const adapter = new UpgradeAdapter(MyNg2Module); const module = angular.module('myExample', []); module.factory('example', adapter.downgradeNg2Provider(Example)); adapter.bootstrap(document.body, ['myExample']).ready((ref) => { const example: Example = ref.ng1Injector.get('example'); });
      
      class Example {
}

const adapter = new UpgradeAdapter(MyNg2Module);

const module = angular.module('myExample', []);
module.factory('example', adapter.downgradeNg2Provider(Example));

adapter.bootstrap(document.body, ['myExample']).ready((ref) => {
  const example: Example = ref.ng1Injector.get('example');
});
    

使用说明

Mental Model

When reasoning about how a hybrid application works it is useful to have a mental model which describes what is happening and explains what is happening at the lowest level.

  1. There are two independent frameworks running in a single application, each framework treats the other as a black box.
  2. Each DOM element on the page is owned exactly by one framework. Whichever framework instantiated the element is the owner. Each framework only updates/interacts with its own DOM elements and ignores others.
  3. AngularJS directives always execute inside AngularJS framework codebase regardless of where they are instantiated.
  4. Angular components always execute inside Angular framework codebase regardless of where they are instantiated.
  5. An AngularJS component can be upgraded to an Angular component. This creates an Angular directive, which bootstraps the AngularJS component directive in that location.
  6. An Angular component can be downgraded to an AngularJS component directive. This creates an AngularJS directive, which bootstraps the Angular component in that location.
  7. Whenever an adapter component is instantiated the host element is owned by the framework doing the instantiation. The other framework then instantiates and owns the view for that component. This implies that component bindings will always follow the semantics of the instantiation framework. The syntax is always that of Angular syntax.
  8. AngularJS is always bootstrapped first and owns the bottom most view.
  9. The new application is running in Angular zone, and therefore it no longer needs calls to $apply().

Example

const adapter = new UpgradeAdapter(forwardRef(() => MyNg2Module), myCompilerOptions); const module = angular.module('myExample', []); module.directive('ng2Comp', adapter.downgradeNg2Component(Ng2Component)); module.directive('ng1Hello', function() { return { scope: { title: '=' }, template: 'ng1[Hello {{title}}!](<span ng-transclude></span>)' }; }); @Component({ selector: 'ng2-comp', inputs: ['name'], template: 'ng2[<ng1-hello [title]="name">transclude</ng1-hello>](<ng-content></ng-content>)', directives: }) class Ng2Component { } @NgModule({ declarations: [Ng2Component, adapter.upgradeNg1Component('ng1Hello')], imports: [BrowserModule] }) class MyNg2Module {} document.body.innerHTML = '<ng2-comp name="World">project</ng2-comp>'; adapter.bootstrap(document.body, ['myExample']).ready(function() { expect(document.body.textContent).toEqual( "ng2[ng1[Hello World!](transclude)](project)"); });
      
      
  1. const adapter = new UpgradeAdapter(forwardRef(() => MyNg2Module), myCompilerOptions);
  2. const module = angular.module('myExample', []);
  3. module.directive('ng2Comp', adapter.downgradeNg2Component(Ng2Component));
  4.  
  5. module.directive('ng1Hello', function() {
  6. return {
  7. scope: { title: '=' },
  8. template: 'ng1[Hello {{title}}!](<span ng-transclude></span>)'
  9. };
  10. });
  11.  
  12.  
  13. @Component({
  14. selector: 'ng2-comp',
  15. inputs: ['name'],
  16. template: 'ng2[<ng1-hello [title]="name">transclude</ng1-hello>](<ng-content></ng-content>)',
  17. directives:
  18. })
  19. class Ng2Component {
  20. }
  21.  
  22. @NgModule({
  23. declarations: [Ng2Component, adapter.upgradeNg1Component('ng1Hello')],
  24. imports: [BrowserModule]
  25. })
  26. class MyNg2Module {}
  27.  
  28.  
  29. document.body.innerHTML = '<ng2-comp name="World">project</ng2-comp>';
  30.  
  31. adapter.bootstrap(document.body, ['myExample']).ready(function() {
  32. expect(document.body.textContent).toEqual(
  33. "ng2[ng1[Hello World!](transclude)](project)");
  34. });