index.d.ts 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464
  1. import { _AbstractConstructor } from '@angular/material/core';
  2. import { AfterViewChecked } from '@angular/core';
  3. import { BooleanInput } from '@angular/cdk/coercion';
  4. import { CanColor } from '@angular/material/core';
  5. import { _Constructor } from '@angular/material/core';
  6. import { DomSanitizer } from '@angular/platform-browser';
  7. import { ElementRef } from '@angular/core';
  8. import { ErrorHandler } from '@angular/core';
  9. import { HttpClient } from '@angular/common/http';
  10. import * as i0 from '@angular/core';
  11. import * as i2 from '@angular/material/core';
  12. import { InjectionToken } from '@angular/core';
  13. import { Observable } from 'rxjs';
  14. import { OnDestroy } from '@angular/core';
  15. import { OnInit } from '@angular/core';
  16. import { Optional } from '@angular/core';
  17. import { SafeHtml } from '@angular/platform-browser';
  18. import { SafeResourceUrl } from '@angular/platform-browser';
  19. import { ThemePalette } from '@angular/material/core';
  20. /**
  21. * Returns an exception to be thrown when a HTML string couldn't be sanitized.
  22. * @param literal HTML that was attempted to be sanitized.
  23. * @docs-private
  24. */
  25. export declare function getMatIconFailedToSanitizeLiteralError(literal: SafeHtml): Error;
  26. /**
  27. * Returns an exception to be thrown when a URL couldn't be sanitized.
  28. * @param url URL that was attempted to be sanitized.
  29. * @docs-private
  30. */
  31. export declare function getMatIconFailedToSanitizeUrlError(url: SafeResourceUrl): Error;
  32. /**
  33. * Returns an exception to be thrown in the case when attempting to
  34. * load an icon with a name that cannot be found.
  35. * @docs-private
  36. */
  37. export declare function getMatIconNameNotFoundError(iconName: string): Error;
  38. /**
  39. * Returns an exception to be thrown when the consumer attempts to use
  40. * `<mat-icon>` without including @angular/common/http.
  41. * @docs-private
  42. */
  43. export declare function getMatIconNoHttpProviderError(): Error;
  44. declare namespace i1 {
  45. export {
  46. MAT_ICON_LOCATION_FACTORY,
  47. MatIconDefaultOptions,
  48. MAT_ICON_DEFAULT_OPTIONS,
  49. MAT_ICON_LOCATION,
  50. MatIconLocation,
  51. MatIcon
  52. }
  53. }
  54. /** @docs-private */
  55. export declare const ICON_REGISTRY_PROVIDER: {
  56. provide: typeof MatIconRegistry;
  57. deps: (Optional[] | typeof DomSanitizer | typeof ErrorHandler)[];
  58. useFactory: typeof ICON_REGISTRY_PROVIDER_FACTORY;
  59. };
  60. /** @docs-private */
  61. export declare function ICON_REGISTRY_PROVIDER_FACTORY(parentRegistry: MatIconRegistry, httpClient: HttpClient, sanitizer: DomSanitizer, errorHandler: ErrorHandler, document?: any): MatIconRegistry;
  62. /** Options that can be used to configure how an icon or the icons in an icon set are presented. */
  63. export declare interface IconOptions {
  64. /** View box to set on the icon. */
  65. viewBox?: string;
  66. /** Whether or not to fetch the icon or icon set using HTTP credentials. */
  67. withCredentials?: boolean;
  68. }
  69. /**
  70. * Function that will be invoked by the icon registry when trying to resolve the
  71. * URL from which to fetch an icon. The returned URL will be used to make a request for the icon.
  72. */
  73. export declare type IconResolver = (name: string, namespace: string) => SafeResourceUrl | SafeResourceUrlWithIconOptions | null;
  74. /** Injection token to be used to override the default options for `mat-icon`. */
  75. export declare const MAT_ICON_DEFAULT_OPTIONS: InjectionToken<MatIconDefaultOptions>;
  76. /**
  77. * Injection token used to provide the current location to `MatIcon`.
  78. * Used to handle server-side rendering and to stub out during unit tests.
  79. * @docs-private
  80. */
  81. export declare const MAT_ICON_LOCATION: InjectionToken<MatIconLocation>;
  82. /** @docs-private */
  83. export declare function MAT_ICON_LOCATION_FACTORY(): MatIconLocation;
  84. /**
  85. * Component to display an icon. It can be used in the following ways:
  86. *
  87. * - Specify the svgIcon input to load an SVG icon from a URL previously registered with the
  88. * addSvgIcon, addSvgIconInNamespace, addSvgIconSet, or addSvgIconSetInNamespace methods of
  89. * MatIconRegistry. If the svgIcon value contains a colon it is assumed to be in the format
  90. * "[namespace]:[name]", if not the value will be the name of an icon in the default namespace.
  91. * Examples:
  92. * `<mat-icon svgIcon="left-arrow"></mat-icon>
  93. * <mat-icon svgIcon="animals:cat"></mat-icon>`
  94. *
  95. * - Use a font ligature as an icon by putting the ligature text in the `fontIcon` attribute or the
  96. * content of the `<mat-icon>` component. If you register a custom font class, don't forget to also
  97. * include the special class `mat-ligature-font`. It is recommended to use the attribute alternative
  98. * to prevent the ligature text to be selectable and to appear in search engine results.
  99. * By default, the Material icons font is used as described at
  100. * http://google.github.io/material-design-icons/#icon-font-for-the-web. You can specify an
  101. * alternate font by setting the fontSet input to either the CSS class to apply to use the
  102. * desired font, or to an alias previously registered with MatIconRegistry.registerFontClassAlias.
  103. * Examples:
  104. * `<mat-icon fontIcon="home"></mat-icon>
  105. * <mat-icon>home</mat-icon>
  106. * <mat-icon fontSet="myfont" fontIcon="sun"></mat-icon>
  107. * <mat-icon fontSet="myfont">sun</mat-icon>`
  108. *
  109. * - Specify a font glyph to be included via CSS rules by setting the fontSet input to specify the
  110. * font, and the fontIcon input to specify the icon. Typically the fontIcon will specify a
  111. * CSS class which causes the glyph to be displayed via a :before selector, as in
  112. * https://fortawesome.github.io/Font-Awesome/examples/
  113. * Example:
  114. * `<mat-icon fontSet="fa" fontIcon="alarm"></mat-icon>`
  115. */
  116. export declare class MatIcon extends _MatIconBase implements OnInit, AfterViewChecked, CanColor, OnDestroy {
  117. private _iconRegistry;
  118. private _location;
  119. private readonly _errorHandler;
  120. /**
  121. * Whether the icon should be inlined, automatically sizing the icon to match the font size of
  122. * the element the icon is contained in.
  123. */
  124. get inline(): boolean;
  125. set inline(inline: BooleanInput);
  126. private _inline;
  127. /** Name of the icon in the SVG icon set. */
  128. get svgIcon(): string;
  129. set svgIcon(value: string);
  130. private _svgIcon;
  131. /** Font set that the icon is a part of. */
  132. get fontSet(): string;
  133. set fontSet(value: string);
  134. private _fontSet;
  135. /** Name of an icon within a font set. */
  136. get fontIcon(): string;
  137. set fontIcon(value: string);
  138. private _fontIcon;
  139. private _previousFontSetClass;
  140. private _previousFontIconClass;
  141. _svgName: string | null;
  142. _svgNamespace: string | null;
  143. /** Keeps track of the current page path. */
  144. private _previousPath?;
  145. /** Keeps track of the elements and attributes that we've prefixed with the current path. */
  146. private _elementsWithExternalReferences?;
  147. /** Subscription to the current in-progress SVG icon request. */
  148. private _currentIconFetch;
  149. constructor(elementRef: ElementRef<HTMLElement>, _iconRegistry: MatIconRegistry, ariaHidden: string, _location: MatIconLocation, _errorHandler: ErrorHandler, defaults?: MatIconDefaultOptions);
  150. /**
  151. * Splits an svgIcon binding value into its icon set and icon name components.
  152. * Returns a 2-element array of [(icon set), (icon name)].
  153. * The separator for the two fields is ':'. If there is no separator, an empty
  154. * string is returned for the icon set and the entire value is returned for
  155. * the icon name. If the argument is falsy, returns an array of two empty strings.
  156. * Throws an error if the name contains two or more ':' separators.
  157. * Examples:
  158. * `'social:cake' -> ['social', 'cake']
  159. * 'penguin' -> ['', 'penguin']
  160. * null -> ['', '']
  161. * 'a:b:c' -> (throws Error)`
  162. */
  163. private _splitIconName;
  164. ngOnInit(): void;
  165. ngAfterViewChecked(): void;
  166. ngOnDestroy(): void;
  167. _usingFontIcon(): boolean;
  168. private _setSvgElement;
  169. private _clearSvgElement;
  170. private _updateFontIconClasses;
  171. /**
  172. * Cleans up a value to be used as a fontIcon or fontSet.
  173. * Since the value ends up being assigned as a CSS class, we
  174. * have to trim the value and omit space-separated values.
  175. */
  176. private _cleanupFontValue;
  177. /**
  178. * Prepends the current path to all elements that have an attribute pointing to a `FuncIRI`
  179. * reference. This is required because WebKit browsers require references to be prefixed with
  180. * the current path, if the page has a `base` tag.
  181. */
  182. private _prependPathToReferences;
  183. /**
  184. * Caches the children of an SVG element that have `url()`
  185. * references that we need to prefix with the current path.
  186. */
  187. private _cacheChildrenWithExternalReferences;
  188. /** Sets a new SVG icon with a particular name. */
  189. private _updateSvgIcon;
  190. static ɵfac: i0.ɵɵFactoryDeclaration<MatIcon, [null, null, { attribute: "aria-hidden"; }, null, null, { optional: true; }]>;
  191. static ɵcmp: i0.ɵɵComponentDeclaration<MatIcon, "mat-icon", ["matIcon"], { "color": { "alias": "color"; "required": false; }; "inline": { "alias": "inline"; "required": false; }; "svgIcon": { "alias": "svgIcon"; "required": false; }; "fontSet": { "alias": "fontSet"; "required": false; }; "fontIcon": { "alias": "fontIcon"; "required": false; }; }, {}, never, ["*"], false, never>;
  192. }
  193. /** @docs-private */
  194. declare const _MatIconBase: _Constructor<CanColor> & _AbstractConstructor<CanColor> & {
  195. new (_elementRef: ElementRef): {
  196. _elementRef: ElementRef;
  197. };
  198. };
  199. /** Default options for `mat-icon`. */
  200. export declare interface MatIconDefaultOptions {
  201. /** Default color of the icon. */
  202. color?: ThemePalette;
  203. /** Font set that the icon is a part of. */
  204. fontSet?: string;
  205. }
  206. /**
  207. * Stubbed out location for `MatIcon`.
  208. * @docs-private
  209. */
  210. export declare interface MatIconLocation {
  211. getPathname: () => string;
  212. }
  213. export declare class MatIconModule {
  214. static ɵfac: i0.ɵɵFactoryDeclaration<MatIconModule, never>;
  215. static ɵmod: i0.ɵɵNgModuleDeclaration<MatIconModule, [typeof i1.MatIcon], [typeof i2.MatCommonModule], [typeof i1.MatIcon, typeof i2.MatCommonModule]>;
  216. static ɵinj: i0.ɵɵInjectorDeclaration<MatIconModule>;
  217. }
  218. /**
  219. * Service to register and display icons used by the `<mat-icon>` component.
  220. * - Registers icon URLs by namespace and name.
  221. * - Registers icon set URLs by namespace.
  222. * - Registers aliases for CSS classes, for use with icon fonts.
  223. * - Loads icons from URLs and extracts individual icons from icon sets.
  224. */
  225. export declare class MatIconRegistry implements OnDestroy {
  226. private _httpClient;
  227. private _sanitizer;
  228. private readonly _errorHandler;
  229. private _document;
  230. /**
  231. * URLs and cached SVG elements for individual icons. Keys are of the format "[namespace]:[icon]".
  232. */
  233. private _svgIconConfigs;
  234. /**
  235. * SvgIconConfig objects and cached SVG elements for icon sets, keyed by namespace.
  236. * Multiple icon sets can be registered under the same namespace.
  237. */
  238. private _iconSetConfigs;
  239. /** Cache for icons loaded by direct URLs. */
  240. private _cachedIconsByUrl;
  241. /** In-progress icon fetches. Used to coalesce multiple requests to the same URL. */
  242. private _inProgressUrlFetches;
  243. /** Map from font identifiers to their CSS class names. Used for icon fonts. */
  244. private _fontCssClassesByAlias;
  245. /** Registered icon resolver functions. */
  246. private _resolvers;
  247. /**
  248. * The CSS classes to apply when an `<mat-icon>` component has no icon name, url, or font
  249. * specified. The default 'material-icons' value assumes that the material icon font has been
  250. * loaded as described at http://google.github.io/material-design-icons/#icon-font-for-the-web
  251. */
  252. private _defaultFontSetClass;
  253. constructor(_httpClient: HttpClient, _sanitizer: DomSanitizer, document: any, _errorHandler: ErrorHandler);
  254. /**
  255. * Registers an icon by URL in the default namespace.
  256. * @param iconName Name under which the icon should be registered.
  257. * @param url
  258. */
  259. addSvgIcon(iconName: string, url: SafeResourceUrl, options?: IconOptions): this;
  260. /**
  261. * Registers an icon using an HTML string in the default namespace.
  262. * @param iconName Name under which the icon should be registered.
  263. * @param literal SVG source of the icon.
  264. */
  265. addSvgIconLiteral(iconName: string, literal: SafeHtml, options?: IconOptions): this;
  266. /**
  267. * Registers an icon by URL in the specified namespace.
  268. * @param namespace Namespace in which the icon should be registered.
  269. * @param iconName Name under which the icon should be registered.
  270. * @param url
  271. */
  272. addSvgIconInNamespace(namespace: string, iconName: string, url: SafeResourceUrl, options?: IconOptions): this;
  273. /**
  274. * Registers an icon resolver function with the registry. The function will be invoked with the
  275. * name and namespace of an icon when the registry tries to resolve the URL from which to fetch
  276. * the icon. The resolver is expected to return a `SafeResourceUrl` that points to the icon,
  277. * an object with the icon URL and icon options, or `null` if the icon is not supported. Resolvers
  278. * will be invoked in the order in which they have been registered.
  279. * @param resolver Resolver function to be registered.
  280. */
  281. addSvgIconResolver(resolver: IconResolver): this;
  282. /**
  283. * Registers an icon using an HTML string in the specified namespace.
  284. * @param namespace Namespace in which the icon should be registered.
  285. * @param iconName Name under which the icon should be registered.
  286. * @param literal SVG source of the icon.
  287. */
  288. addSvgIconLiteralInNamespace(namespace: string, iconName: string, literal: SafeHtml, options?: IconOptions): this;
  289. /**
  290. * Registers an icon set by URL in the default namespace.
  291. * @param url
  292. */
  293. addSvgIconSet(url: SafeResourceUrl, options?: IconOptions): this;
  294. /**
  295. * Registers an icon set using an HTML string in the default namespace.
  296. * @param literal SVG source of the icon set.
  297. */
  298. addSvgIconSetLiteral(literal: SafeHtml, options?: IconOptions): this;
  299. /**
  300. * Registers an icon set by URL in the specified namespace.
  301. * @param namespace Namespace in which to register the icon set.
  302. * @param url
  303. */
  304. addSvgIconSetInNamespace(namespace: string, url: SafeResourceUrl, options?: IconOptions): this;
  305. /**
  306. * Registers an icon set using an HTML string in the specified namespace.
  307. * @param namespace Namespace in which to register the icon set.
  308. * @param literal SVG source of the icon set.
  309. */
  310. addSvgIconSetLiteralInNamespace(namespace: string, literal: SafeHtml, options?: IconOptions): this;
  311. /**
  312. * Defines an alias for CSS class names to be used for icon fonts. Creating an matIcon
  313. * component with the alias as the fontSet input will cause the class name to be applied
  314. * to the `<mat-icon>` element.
  315. *
  316. * If the registered font is a ligature font, then don't forget to also include the special
  317. * class `mat-ligature-font` to allow the usage via attribute. So register like this:
  318. *
  319. * ```ts
  320. * iconRegistry.registerFontClassAlias('f1', 'font1 mat-ligature-font');
  321. * ```
  322. *
  323. * And use like this:
  324. *
  325. * ```html
  326. * <mat-icon fontSet="f1" fontIcon="home"></mat-icon>
  327. * ```
  328. *
  329. * @param alias Alias for the font.
  330. * @param classNames Class names override to be used instead of the alias.
  331. */
  332. registerFontClassAlias(alias: string, classNames?: string): this;
  333. /**
  334. * Returns the CSS class name associated with the alias by a previous call to
  335. * registerFontClassAlias. If no CSS class has been associated, returns the alias unmodified.
  336. */
  337. classNameForFontAlias(alias: string): string;
  338. /**
  339. * Sets the CSS classes to be used for icon fonts when an `<mat-icon>` component does not
  340. * have a fontSet input value, and is not loading an icon by name or URL.
  341. */
  342. setDefaultFontSetClass(...classNames: string[]): this;
  343. /**
  344. * Returns the CSS classes to be used for icon fonts when an `<mat-icon>` component does not
  345. * have a fontSet input value, and is not loading an icon by name or URL.
  346. */
  347. getDefaultFontSetClass(): string[];
  348. /**
  349. * Returns an Observable that produces the icon (as an `<svg>` DOM element) from the given URL.
  350. * The response from the URL may be cached so this will not always cause an HTTP request, but
  351. * the produced element will always be a new copy of the originally fetched icon. (That is,
  352. * it will not contain any modifications made to elements previously returned).
  353. *
  354. * @param safeUrl URL from which to fetch the SVG icon.
  355. */
  356. getSvgIconFromUrl(safeUrl: SafeResourceUrl): Observable<SVGElement>;
  357. /**
  358. * Returns an Observable that produces the icon (as an `<svg>` DOM element) with the given name
  359. * and namespace. The icon must have been previously registered with addIcon or addIconSet;
  360. * if not, the Observable will throw an error.
  361. *
  362. * @param name Name of the icon to be retrieved.
  363. * @param namespace Namespace in which to look for the icon.
  364. */
  365. getNamedSvgIcon(name: string, namespace?: string): Observable<SVGElement>;
  366. ngOnDestroy(): void;
  367. /**
  368. * Returns the cached icon for a SvgIconConfig if available, or fetches it from its URL if not.
  369. */
  370. private _getSvgFromConfig;
  371. /**
  372. * Attempts to find an icon with the specified name in any of the SVG icon sets.
  373. * First searches the available cached icons for a nested element with a matching name, and
  374. * if found copies the element to a new `<svg>` element. If not found, fetches all icon sets
  375. * that have not been cached, and searches again after all fetches are completed.
  376. * The returned Observable produces the SVG element if possible, and throws
  377. * an error if no icon with the specified name can be found.
  378. */
  379. private _getSvgFromIconSetConfigs;
  380. /**
  381. * Searches the cached SVG elements for the given icon sets for a nested icon element whose "id"
  382. * tag matches the specified name. If found, copies the nested element to a new SVG element and
  383. * returns it. Returns null if no matching element is found.
  384. */
  385. private _extractIconWithNameFromAnySet;
  386. /**
  387. * Loads the content of the icon URL specified in the SvgIconConfig and creates an SVG element
  388. * from it.
  389. */
  390. private _loadSvgIconFromConfig;
  391. /**
  392. * Loads the content of the icon set URL specified in the
  393. * SvgIconConfig and attaches it to the config.
  394. */
  395. private _loadSvgIconSetFromConfig;
  396. /**
  397. * Searches the cached element of the given SvgIconConfig for a nested icon element whose "id"
  398. * tag matches the specified name. If found, copies the nested element to a new SVG element and
  399. * returns it. Returns null if no matching element is found.
  400. */
  401. private _extractSvgIconFromSet;
  402. /**
  403. * Creates a DOM element from the given SVG string.
  404. */
  405. private _svgElementFromString;
  406. /**
  407. * Converts an element into an SVG node by cloning all of its children.
  408. */
  409. private _toSvgElement;
  410. /**
  411. * Sets the default attributes for an SVG element to be used as an icon.
  412. */
  413. private _setSvgAttributes;
  414. /**
  415. * Returns an Observable which produces the string contents of the given icon. Results may be
  416. * cached, so future calls with the same URL may not cause another HTTP request.
  417. */
  418. private _fetchIcon;
  419. /**
  420. * Registers an icon config by name in the specified namespace.
  421. * @param namespace Namespace in which to register the icon config.
  422. * @param iconName Name under which to register the config.
  423. * @param config Config to be registered.
  424. */
  425. private _addSvgIconConfig;
  426. /**
  427. * Registers an icon set config in the specified namespace.
  428. * @param namespace Namespace in which to register the icon config.
  429. * @param config Config to be registered.
  430. */
  431. private _addSvgIconSetConfig;
  432. /** Parses a config's text into an SVG element. */
  433. private _svgElementFromConfig;
  434. /** Tries to create an icon config through the registered resolver functions. */
  435. private _getIconConfigFromResolvers;
  436. static ɵfac: i0.ɵɵFactoryDeclaration<MatIconRegistry, [{ optional: true; }, null, { optional: true; }, null]>;
  437. static ɵprov: i0.ɵɵInjectableDeclaration<MatIconRegistry>;
  438. }
  439. /** Object that specifies a URL from which to fetch an icon and the options to use for it. */
  440. export declare interface SafeResourceUrlWithIconOptions {
  441. url: SafeResourceUrl;
  442. options: IconOptions;
  443. }
  444. export { }