1.0.5 • Published 1 month ago
@a11y-ngx/responsive-image-maps v1.0.5
Responsive Image Maps
A responsive image map directive that updates the areas' coordinates according to the image size.
⚠️ IMPORTANT: Currently
rect
andcircle
shapes are supported,poly
will be supported in future releases.
This library was generated with Angular CLI version 12.2.0.
Installation
Install npm package:
npm install @a11y-ngx/responsive-image-maps --save
Import
A11yResponsiveImageMapsModule
into your module:
import { A11yResponsiveImageMapsModule } from '@a11y-ngx/responsive-image-maps';
@NgModule({
declarations: [...],
imports: [
...
A11yResponsiveImageMapsModule
]
})
export class AppModule { }
Use
Create an image map.
The Map Directive
- The Map directive will pick any
<map>
tag with[name]
attribute in it and search for the<img>
with[usemap]
matching that name. - When the main
<img>
resize, all<area>
elements will update their coordinates based on the new image size. - The directive can be accessed using a template variable with
responsiveImageMap
. - The directive will auto update sizes when the page resize (using Window Resize Service).
- If the image changes size (through window resize),
(sizeChanged)
output will emit the newMapSize
. - If the image changes size (programmatically), sizes can be manually updated using the
update()
method from the exported directive. - The HTML
<map>
element can be reached through thenativeElement
property.
Map Directive public Properties, Getters and Methods
Property | Type | Returns | Description |
---|---|---|---|
loaded | BehaviorSubject | boolean | Will return true when the image has loaded |
sizeChanged | EventEmitter | MapSize | Will emit the new image's size & position when page resize and it changes the width and height values |
areas | QueryList | ResponsiveImageAreaDirective | To access all <area> children directives |
scaleFactor | getter | { width: number, height: number } | The scale factor from the image's original full size and the resized size |
imageSize | MapSize | object | To access all the values (size & position) from the main image |
nativeElement | getter | HTMLMapElement | To access the HTML <map> element |
imageElement | getter | HTMLImageElement | To access the HTML <img> element that the <map> is attached to |
update() | method | void | Will update the image new values and all the <area> 's new coordinates accordingly |
The MapSize Interface
Property | Type | Description |
---|---|---|
top | number | The image DOMRect 's top value |
left | number | The image DOMRect 's left value |
width | number | The image DOMRect 's width value |
height | number | The image DOMRect 's height value |
fullWidth | number | The image's original full width size (resized or not) |
fullHeight | number | The image's original full height size (resized or not) |
The Area Directive
- The Area directive will pick any
<area>
tag with[shape]
attribute of value"rect"
or"circle"
. - This directive will manage the area size (either relative to the image or to the viewport).
- These directives can be accessed from the Map directive through the
areas
property, which will return aQueryList<ResponsiveImageAreaDirective>
. - The HTML
<area>
element can be reached through thenativeElement
property.
Area Directive public Properties, Getters and Methods
Property | Type | Returns | Description |
---|---|---|---|
areaSize | AreaSize | object | To access all the values (size & position) from the area (relative to the image) |
nativeElement | getter | HTMLAreaElement | To access the HTML <area> element |
getBoundingClientRect() | method | DOMRect | To get the calculated position of the <area> element (relative to the viewport) |
updateCoords() | method | void | Will update the [coords] attribute based on the image size. (NOTE: there's no need to trigger this manually, the map directive will update when needed) |
The AreaSize Interface
Property | Type | Description |
---|---|---|
top | number | The area's (relative to image) top value |
left | number | The area's (relative to image) left value |
width | number | The area's (relative to image) width value |
height | number | The area's (relative to image) height value |
Working Example
TypeScript
import { ResponsiveImageMapDirective, MapSize, AreaSize } from '@a11y-ngx/responsive-image-maps';
@Component({ ... })
export class MyComponent {
@ViewChild('imageMap') imageMap: ResponsiveImageMapDirective;
updateOtherElements(newSize: MapSize): void {
const width = newSize.width;
const height = newSize.height;
...
this.imageMap.areas.forEach(area => {
const areaElement = area.nativeElement;
const areaSize: AreaSize = area.AreaSize;
...
});
}
updateMapSizes(): void {
this.imageMap.update();
}
}
HTML
<img src="https://www.w3schools.com/html/workplace.jpg" alt="Workplace" usemap="#workmap">
<map name="workmap" #imageMap="responsiveImageMap" (sizeChanged)="updateOtherElements($event)">
<area shape="rect" coords="34,44,270,350" alt="Computer" href="...">
<area shape="rect" coords="290,172,333,250" alt="Phone" href="...">
<area shape="circle" coords="337,300,44" alt="Coffee" href="...">
</map>