honeymoose
/
angular-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: update api ref doc for platform browser (#37186) 

Edit descriptions, usage examples, and add links to be complete and consistent with API reference doc style

PR Close #37186
This commit is contained in:
Judy Bogart 2020-05-18 11:45:49 -07:00 committed by Misko Hevery
parent bf682d73d4
commit 886e3ebcca
3 changed files with 97 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
packages/core/src/application_ref.ts
View File

@ -135,7 +135,7 @@ export class NgProbeToken {
/**
* Creates a platform.
* Platforms have to be eagerly created via this function.
* Platforms must be created on launch using this function.
*
* @publicApi
*/
@ -153,7 +153,13 @@ export function createPlatform(injector: Injector): PlatformRef {
}
/**
* Creates a factory for a platform
* Creates a factory for a platform. Can be used to provide or override `Providers` specific to
* your applciation's runtime needs, such as `PLATFORM_INITIALIZER` and `PLATFORM_ID`.
* @param parentPlatformFactory Another platform factory to modify. Allows you to compose factories
* to build up configurations that might be required by different libraries or parts of the
* application.
* @param name Identifies the new platform factory.
* @param providers A set of dependency providers for platforms created with the new factory.
*
* @publicApi
*/
@ -182,7 +188,7 @@ export function createPlatformFactory(
}
/**
* Checks that there currently is a platform which contains the given token as a provider.
* Checks that there is currently a platform that contains the given token as a provider.
*
* @publicApi
*/
@ -202,7 +208,8 @@ export function assertPlatform(requiredToken: any): PlatformRef {
}
/**
* Destroy the existing platform.
* Destroys the current Angular platform and all Angular applications on the page.
* Destroys all modules and listeners registered with the platform.
*
* @publicApi
*/
@ -259,12 +266,11 @@ export interface BootstrapOptions {
}
/**
* The Angular platform is the entry point for Angular on a web page. Each page
* has exactly one platform, and services (such as reflection) which are common
* The Angular platform is the entry point for Angular on a web page.
* Each page has exactly one platform. Services (such as reflection) which are common
* to every Angular application running on the page are bound in its scope.
*
* A page's platform is initialized implicitly when a platform is created via a platform factory
* (e.g. {@link platformBrowser}), or explicitly by calling the {@link createPlatform} function.
* A page's platform is initialized implicitly when a platform is created using a platform
* factory such as `PlatformBrowser`, or explicitly by calling the `createPlatform()` function.
*
* @publicApi
*/
@ -278,11 +284,11 @@ export class PlatformRef {
constructor(private _injector: Injector) {}
/**
* Creates an instance of an `@NgModule` for the given platform
* for offline compilation.
* Creates an instance of an `@NgModule` for the given platform for offline compilation.
*
* @usageNotes
* ### Simple Example
*
* The following example creates the NgModule for a browser platform.
*
* ```typescript
* my_module.ts:
@ -384,14 +390,14 @@ export class PlatformRef {
}
/**
* Register a listener to be called when the platform is disposed.
* Registers a listener to be called when the platform is destroyed.
*/
onDestroy(callback: () => void): void {
this._destroyListeners.push(callback);
}
/**
* Retrieve the platform {@link Injector}, which is the parent injector for
* Retrieves the platform {@link Injector}, which is the parent injector for
* every Angular application on the page and provides singleton providers.
*/
get injector(): Injector {
@ -399,7 +405,8 @@ export class PlatformRef {
}
/**
* Destroy the Angular platform and all Angular applications on the page.
* Destroys the current Angular platform and all Angular applications on the page.
* Destroys all modules and listeners registered with the platform.
*/
destroy() {
if (this._destroyed) {

3
packages/platform-browser/src/browser.ts
View File

@ -58,6 +58,9 @@ export const BROWSER_SANITIZATION_PROVIDERS__POST_R3__ = [];
export const BROWSER_SANITIZATION_PROVIDERS = BROWSER_SANITIZATION_PROVIDERS__PRE_R3__;
/**
* A factory function that returns a `PlatformRef` instance associated with browser service
* providers.
*
* @publicApi
*/
export const platformBrowser: (extraProviders?: StaticProvider[]) => PlatformRef =

76
packages/platform-browser/src/browser/meta.ts
View File

@ -10,7 +10,11 @@ import {DOCUMENT, ɵDomAdapter as DomAdapter, ɵgetDOM as getDOM} from '@angular
import {Inject, Injectable, ɵɵinject} from '@angular/core';
/**
* Represents a meta element.
* Represents the attributes of an HTML `<meta>` element. The element itself is
* represented by the internal `HTMLMetaElement`.
*
* @see [HTML meta tag](https://developer.mozilla.org/docs/Web/HTML/Element/meta)
* @see `Meta`
*
* @publicApi
*/
@ -30,14 +34,31 @@ export type MetaDefinition = {
};
/**
* Factory to create Meta service.
* Factory to create a `Meta` service instance for the current DOM document.
*/
export function createMeta() {
return new Meta(ɵɵinject(DOCUMENT));
}
/**
* A service that can be used to get and add meta tags.
* A service for managing HTML `<meta>` tags.
*
* Properties of the `MetaDefinition` object match the attributes of the
* HTML `<meta>` tag. These tags define document metadata that is important for
* things like configuring a Content Security Policy, defining browser compatibility
* and security settings, setting HTTP Headers, defining rich content for social sharing,
* and Search Engine Optimization (SEO).
*
* To identify specific `<meta>` tags in a document, use an attribute selection
* string in the format `"tag_attribute='value string'"`.
* For example, an `attrSelector` value of `"name='description'"` matches a tag
* whose `name` attribute has the value `"description"`.
* Selectors are used with the `querySelector()` Document method,
* in the format `meta[{attrSelector}]`.
*
* @see [HTML meta tag](https://developer.mozilla.org/docs/Web/HTML/Element/meta)
* @see [Document.querySelector()](https://developer.mozilla.org/docs/Web/API/Document/querySelector)
*
*
* @publicApi
*/
@ -47,12 +68,29 @@ export class Meta {
constructor(@Inject(DOCUMENT) private _doc: any) {
this._dom = getDOM();
}
/**
* Retrieves or creates a specific `<meta>` tag element in the current HTML document.
* In searching for an existing tag, Angular attempts to match the `name` or `property` attribute
* values in the provided tag definition, and verifies that all other attribute values are equal.
* If an existing element is found, it is returned and is not modified in any way.
* @param tag The definition of a `<meta>` element to match or create.
* @param forceCreation True to create a new element without checking whether one already exists.
* @returns The existing element with the same attributes and values if found,
* the new element if no match is found, or `null` if the tag parameter is not defined.
*/
addTag(tag: MetaDefinition, forceCreation: boolean = false): HTMLMetaElement|null {
if (!tag) return null;
return this._getOrCreateElement(tag, forceCreation);
}
/**
* Retrieves or creates a set of `<meta>` tag elements in the current HTML document.
* In searching for an existing tag, Angular attempts to match the `name` or `property` attribute
* values in the provided tag definition, and verifies that all other attribute values are equal.
* @param tags An array of tag definitions to match or create.
* @param forceCreation True to create new elements without checking whether they already exist.
* @returns The matching elements if found, or the new elements.
*/
addTags(tags: MetaDefinition[], forceCreation: boolean = false): HTMLMetaElement[] {
if (!tags) return [];
return tags.reduce((result: HTMLMetaElement[], tag: MetaDefinition) => {
@ -63,17 +101,38 @@ export class Meta {
}, []);
}
/**
* Retrieves a `<meta>` tag element in the current HTML document.
* @param attrSelector The tag attribute and value to match against, in the format
* `"tag_attribute='value string'"`.
* @returns The matching element, if any.
*/
getTag(attrSelector: string): HTMLMetaElement|null {
if (!attrSelector) return null;
return this._doc.querySelector(`meta[${attrSelector}]`) || null;
}
/**
* Retrieves a set of `<meta>` tag elements in the current HTML document.
* @param attrSelector The tag attribute and value to match against, in the format
* `"tag_attribute='value string'"`.
* @returns The matching elements, if any.
*/
getTags(attrSelector: string): HTMLMetaElement[] {
if (!attrSelector) return [];
const list /*NodeList*/ = this._doc.querySelectorAll(`meta[${attrSelector}]`);
return list ? [].slice.call(list) : [];
}
/**
* Modifies an existing `<meta>` tag element in the current HTML document.
* @param tag The tag description with which to replace the existing tag content.
* @param selector A tag attribute and value to match against, to identify
* an existing tag. A string in the format `"tag_attribute=`value string`"`.
* If not supplied, matches a tag with the same `name` or `property` attribute value as the
* replacement tag.
* @return The modified element.
*/
updateTag(tag: MetaDefinition, selector?: string): HTMLMetaElement|null {
if (!tag) return null;
selector = selector || this._parseSelector(tag);
@ -84,10 +143,19 @@ export class Meta {
return this._getOrCreateElement(tag, true);
}
/**
* Removes an existing `<meta>` tag element from the current HTML document.
* @param attrSelector A tag attribute and value to match against, to identify
* an existing tag. A string in the format `"tag_attribute=`value string`"`.
*/
removeTag(attrSelector: string): void {
this.removeTagElement(this.getTag(attrSelector)!);
}
/**
* Removes an existing `<meta>` tag element from the current HTML document.
* @param meta The tag definition to match against to identify an existing tag.
*/
removeTagElement(meta: HTMLMetaElement): void {
if (meta) {
this._dom.remove(meta);