ng-images-preview 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +171 -0
- package/fesm2022/ng-images-preview.mjs +971 -0
- package/fesm2022/ng-images-preview.mjs.map +1 -0
- package/package.json +23 -0
- package/types/ng-images-preview.d.ts +117 -0
package/README.md
ADDED
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# ngImagesPreview
|
|
4
|
+
|
|
5
|
+
A lightweight, modern, and accessible Image Preview library for Angular 18+, built with Signals and Vanilla CSS.
|
|
6
|
+
|
|
7
|
+
[](https://npmjs.org/package/ng-images-preview)
|
|
8
|
+
[](https://github.com/lanxuexing/ng-images-preview/releases)
|
|
9
|
+
[](https://github.com/lanxuexing/ng-images-preview)
|
|
10
|
+
[](https://github.com/lanxuexing/ng-images-preview/stargazers)
|
|
11
|
+
[](https://github.com/lanxuexing/ng-images-preview/actions)
|
|
12
|
+
[](https://angular.dev)
|
|
13
|
+
[](https://angular.dev/guide/signals)
|
|
14
|
+
[](https://github.com/prettier/prettier)
|
|
15
|
+
|
|
16
|
+
[δΈζη](./README.zh-CN.md) | English
|
|
17
|
+
|
|
18
|
+
## π Live Demo
|
|
19
|
+
Check out the component in action: **[https://lanxuexing.github.io/ng-images-preview/](https://lanxuexing.github.io/ng-images-preview/)** (After deployment)
|
|
20
|
+
|
|
21
|
+
</div>
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## β¨ Features
|
|
26
|
+
|
|
27
|
+
- π **Signals-Based**: High performance and reactive by design.
|
|
28
|
+
- π¨ **Vanilla CSS**: Zero dependencies, fully customizable via CSS variables.
|
|
29
|
+
- πΌοΈ **Multi-Image Gallery**: Navigate through a list of images with arrows or swipe gestures.
|
|
30
|
+
- π± **Mobile Ready**: Swipe to navigate, double-tap to zoom, pinch-to-zoom gestures.
|
|
31
|
+
- β¨οΈ **Keyboard Support**: Arrow keys to navigate, ESC to close.
|
|
32
|
+
- π **Zoom & Pan**: Smooth zooming and panning interactions.
|
|
33
|
+
- π **Rotate & Flip**: Built-in toolbar for image manipulation.
|
|
34
|
+
- 𧩠**Custom Template**: Complete control over the preview UI via `ng-template`.
|
|
35
|
+
- βΏ **Accessible**: ARIA labels and focus management.
|
|
36
|
+
- π **Dark Mode Ready**: Inherits system preferences or app styles seamlessly.
|
|
37
|
+
|
|
38
|
+
## π¦ Installation
|
|
39
|
+
|
|
40
|
+
This component is available as an Angular Library.
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
npm install ng-images-preview
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## π Quick Start
|
|
47
|
+
|
|
48
|
+
### 1. Import Directive
|
|
49
|
+
|
|
50
|
+
Register `ImagesPreviewDirective` in your standalone component or module.
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
import { ImagesPreviewDirective } from 'ng-images-preview';
|
|
54
|
+
|
|
55
|
+
@Component({
|
|
56
|
+
standalone: true,
|
|
57
|
+
imports: [ImagesPreviewDirective, ...]
|
|
58
|
+
})
|
|
59
|
+
export class MyComponent {}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### 2. Basic Usage
|
|
63
|
+
|
|
64
|
+
**Option A: Zero Config** (Auto-detects source)
|
|
65
|
+
```html
|
|
66
|
+
<!-- Direct usage on an img tag -->
|
|
67
|
+
<img src="small.jpg" ngImagesPreview>
|
|
68
|
+
|
|
69
|
+
<!-- Usage on a container (finds inner img) -->
|
|
70
|
+
<div ngImagesPreview><img src="small.jpg"></div>
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
**Option B: Separate High-Res Source**
|
|
74
|
+
```html
|
|
75
|
+
<img src="small.jpg" [ngImagesPreview]="'huge-original.jpg'">
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
**Option C: Gallery Mode**
|
|
79
|
+
Pass a list of images to `previewImages` to enable gallery navigation (arrows, swipe).
|
|
80
|
+
```html
|
|
81
|
+
<img
|
|
82
|
+
src="item1.jpg"
|
|
83
|
+
[ngImagesPreview]="'item1-highres.jpg'"
|
|
84
|
+
[previewImages]="['item1-highres.jpg', 'item2-highres.jpg', 'item3-highres.jpg']">
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### 3. Custom Template
|
|
88
|
+
|
|
89
|
+
Take full control of the UI by providing a template.
|
|
90
|
+
|
|
91
|
+
```html
|
|
92
|
+
<ng-template #myPreview let-state let-actions="actions">
|
|
93
|
+
<div class="custom-overlay">
|
|
94
|
+
<img [src]="state.src" [style.transform]="'scale(' + state.scale + ') rotate(' + state.rotate + 'deg)'">
|
|
95
|
+
<button (click)="actions.zoomIn()">Zoom +</button>
|
|
96
|
+
<button (click)="actions.close()">Close</button>
|
|
97
|
+
</div>
|
|
98
|
+
</ng-template>
|
|
99
|
+
|
|
100
|
+
<img src="thumb.jpg" ngImagesPreview="large.jpg" [previewTemplate]="myPreview">
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## βοΈ Configuration
|
|
104
|
+
|
|
105
|
+
### Directive Inputs (`ImagesPreviewDirective`)
|
|
106
|
+
|
|
107
|
+
| Property | Type | Default | Description |
|
|
108
|
+
| :--- | :--- | :--- | :--- |
|
|
109
|
+
| `ngImagesPreview` | `string` | `''` | High-res URL. If empty, tries to read `src` from host or child `img`. |
|
|
110
|
+
| `previewImages` | `string[]` | `[]` | List of image URLs for gallery navigation. |
|
|
111
|
+
| `previewTemplate` | `TemplateRef` | `undefined` | Custom template to render instead of the default viewer. |
|
|
112
|
+
|
|
113
|
+
### Component Inputs (`ImagesPreviewComponent`)
|
|
114
|
+
|
|
115
|
+
If you use the component directly:
|
|
116
|
+
|
|
117
|
+
| Property | Type | Default | Description |
|
|
118
|
+
| :--- | :--- | :--- | :--- |
|
|
119
|
+
| `src` | `string` | **Required** | The image source to display. |
|
|
120
|
+
| `images` | `string[]` | `[]` | List of images for gallery. |
|
|
121
|
+
| `initialIndex` | `number` | `0` | Initial image index in gallery. |
|
|
122
|
+
| `customTemplate` | `TemplateRef` | `undefined` | Custom template for the overlay content. |
|
|
123
|
+
|
|
124
|
+
### Template Context (for Custom Templates)
|
|
125
|
+
|
|
126
|
+
When using `previewTemplate`, you get access to:
|
|
127
|
+
|
|
128
|
+
#### `state`
|
|
129
|
+
| Property | Type | Description |
|
|
130
|
+
| :--- | :--- | :--- |
|
|
131
|
+
| `src` | `string` | Current image source. |
|
|
132
|
+
| `scale` | `number` | Current zoom level (min: 0.5, max: 5). |
|
|
133
|
+
| `rotate` | `number` | Rotation angle in degrees. |
|
|
134
|
+
| `flipH` | `boolean` | Horizontal flip state. |
|
|
135
|
+
| `flipV` | `boolean` | Vertical flip state. |
|
|
136
|
+
| `isLoading` | `boolean` | True if image is loading. |
|
|
137
|
+
| `hasError` | `boolean` | True if image failed to load. |
|
|
138
|
+
|
|
139
|
+
#### `actions`
|
|
140
|
+
| Method | Description |
|
|
141
|
+
| :--- | :--- |
|
|
142
|
+
| `zoomIn()` | Increase zoom level. |
|
|
143
|
+
| `zoomOut()` | Decrease zoom level. |
|
|
144
|
+
| `rotateLeft()` | Rotate -90 degrees. |
|
|
145
|
+
| `rotateRight()` | Rotate +90 degrees. |
|
|
146
|
+
| `flipHorizontal()` | Flip horizontally. |
|
|
147
|
+
| `flipVertical()` | Flip vertically. |
|
|
148
|
+
| `reset()` | Reset all transformations. |
|
|
149
|
+
| `close()` | Close the preview. |
|
|
150
|
+
| `next()` | Go to next image (if gallery). |
|
|
151
|
+
| `prev()` | Go to previous image (if gallery). |
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
## π Development
|
|
156
|
+
|
|
157
|
+
This repository is structured as an Angular Workspace.
|
|
158
|
+
|
|
159
|
+
- **Library Path**: `projects/ng-images-preview`
|
|
160
|
+
- **Demo Path**: `projects/demo`
|
|
161
|
+
|
|
162
|
+
### Scripts
|
|
163
|
+
- `npm start`: Run the demo application.
|
|
164
|
+
- `npm run build:lib`: Build the library for production.
|
|
165
|
+
- `npm run build:demo`: Build the demo application.
|
|
166
|
+
- `npm test`: Run unit tests.
|
|
167
|
+
- `npm list`: Run linting.
|
|
168
|
+
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
Built with β€οΈ for the Angular Community.
|