diff --git a/README.md b/README.md index 1111865..a9abcfa 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # angularx-qrcode - Angular QR Code Generator -`angularx-qrcode` - a fast and easy-to-use Ivy compatible Ionic and Angular QR Code Generator library +The `angularx-qrcode` is a fast and easy-to-use Ivy compatible Ionic and Angular QR Code Generator library. - [Features](#features) - [Installation](#installation) @@ -21,94 +21,110 @@ - Trusted and used by thousands of developers like you - Easy to use, [sample web app](#demo-app) included -`angularx-qrcode` is compatible with Ionic 3/4/5/6/7/8 and Angular 4/5/6/7/8/9/10/11/12/13/14/15/16/17/18+ with support for the Ivy compiler. It is a drop-in replacement for the no-longer-maintained angular component ng2-qrcode and based on node-qrcode. +The `angularx-qrcode` library is compatible with [Ionic](https://github.com/ionic-team/ionic-framework) 3/4/5/6/7/8 and [Angular](https://angular.dev) 4/5/6/7/8/9/10/11/12/13/14/15/16/17/18+ with support for the Ivy compiler. It is a drop-in replacement for the no-longer-maintained Angular component `ng2-qrcode` and based on `node-qrcode`. ## Installation -**Angular 18 and Ionic with angularx-qrcode 18** - -``` -npm install angularx-qrcode --save -# Or with yarn -yarn add angularx-qrcode +```console +npm i --save angularx-qrcode ``` -**Angular 17 and Ionic with angularx-qrcode 17** +Or with yarn: +```console +yarn add angularx-qrcode ``` -npm install angularx-qrcode@17.0.1 --save -# Or with yarn -yarn add angularx-qrcode@17.0.1 + +### All supported Angular versions + +| Angular Version | `angularx-qrcode` Version | Install command | +|-----------------|---------------------------|----------------------------------------| +| ^18 | ^18.0.1 | `npm i --save angularx-qrcode@latest` | +| ^17 | ^17.0.1 | `npm i --save angularx-qrcode@17.0.1` | +| ^16 | ^16.0.2 | `npm i --save angularx-qrcode@16.0.2` | +| ^15 | ^15.0.1 | `npm i --save angularx-qrcode@15.0.1` | +| ^14 | ^14.0.0 | `npm i --save angularx-qrcode@14.0.0` | +| ^13 | ^13.0.15 | `npm i --save angularx-qrcode@13.0.15` | +| ^12 | ^12.0.3 | `npm i --save angularx-qrcode@12.0.3` | +| ^11 | ^11.0.0 | `npm i --save angularx-qrcode@11.0.0` | +| ^10 | ^10.0.12 | `npm i --save angularx-qrcode@10.0.12` | +| ^9 | ^2.3.7 | `npm i --save angularx-qrcode@2.3.7` | +| ^8 | ^2.1.4 | `npm i --save angularx-qrcode@2.1.4` | +| ^5 / ^6 / ^7 | ^1.6.4 | `npm i --save angularx-qrcode@1.6.4` | +| ^4 | ^1.0.3 | `npm i --save angularx-qrcode@1.0.3` | + +## Demo App + +
+ + **[Working online demo of the Angular QR Code Generator](https://cordobo.github.io/angularx-qrcode/)** + Working online demo of Angular QR Code Generator + +
+ +### Run the demo application locally + +Clone this repository: + +```console +git clone https://github.com/Cordobo/angularx-qrcode.git ``` -**Angular 16 and Ionic with angularx-qrcode 16** +Go to the `./angularx-qrcode` folder and run the command: -``` -npm install angularx-qrcode@16.0.2 --save -# Or with yarn -yarn add angularx-qrcode@16.0.2 +```console +npm i && npm start ``` -**All supported angular versions** +And navigate to `http://localhost:4200/` in your browser. -| Angular Version | angularx-qrcode Version | -|-----------------|-------------------------| -| ^18 | ^18.0.1 | -| ^17 | ^17.0.1 | -| ^16 | ^16.0.2 | -| ^15 | ^15.0.1 | -| ^14 | ^14.0.0 | -| ^13 | ^13.0.15 | -| ^12 | ^12.0.3 | -| ^11 | ^11.0.0 | -| ^10 | ^10.0.12 | -| ^9 | ^2.3.7 | -| ^8 | ^2.1.4 | -| ^5 / ^6 / ^7 | ^1.6.4 | -| ^4 | ^1.0.3 | +> [!NOTE] +> The source code of the live `angularx-qrcode` [demo app](https://cordobo.github.io/angularx-qrcode/) and more examples how to implement this library is in the folder [`projects/demo-app`](projects/demo-app/src/app) in this repository. +## Usage and Example Implementations -# Demo App +Import the `angularx-qrcode` library to your standalone app component: -**[Working online demo of Angular QR Code Generator](https://cordobo.github.io/angularx-qrcode/)** - -The source for the working angular app is available in [`projects/demo-app`](projects/demo-app). +```ts +// File: app.component.ts +// all your other imports... -Run the command: +import { QRCodeModule } from 'angularx-qrcode'; -``` -npm start +@Component({ + selector: 'app-root', + standalone: true, + imports: [QRCodeModule], + templateUrl: './app.component.html', + styleUrl: './app.component.scss', +}) +export class AppComponent {} ``` -and open the url `http://localhost:4200/` in your browser +Or to your main AppModule, if you're using `NgModule`: -# Usage and Example Implementations - -The source for **[a live angularx-qrcode demo app](https://cordobo.github.io/angularx-qrcode/)** and more examples how to implement angularx-qrcode is in the folder [`projects/demo-app`](projects/demo-app/src/app) in this repository. - -### Import the module and add it to your imports section in your main AppModule: - -``` +```ts // File: app.module.ts // all your other imports... + import { QRCodeModule } from 'angularx-qrcode'; @NgModule({ -declarations: [ - AppComponent -], -imports: [ - QRCodeModule -], -providers: [], -bootstrap: [AppComponent] + declarations: [ + AppComponent + ], + imports: [ + QRCodeModule + ], + providers: [], + bootstrap: [AppComponent] }) -export class AppModule { } +export class AppModule {} ``` -``` -// File: app.component.html -// all your HTML... +```html + + ``` @@ -120,7 +136,7 @@ let's invoke it from our template with a directive. If we use a simple text-string, we need no additional code in our controller. -``` +```html ``` @@ -129,17 +145,22 @@ code in our controller. In addition to our ``-directive in `app.component.html`, lets add two lines of code to our controller `app.component.ts`. -``` +```ts // File: app.component.ts + export class QRCodeComponent { public myAngularxQrCode: string = null; + constructor () { // assign a value this.myAngularxQrCode = 'Your QR code data string'; } } +``` + +```html + -// File: app.component.html ``` @@ -153,8 +174,9 @@ To download the QR Code, we have to use the `qrCodeURL` attribute of the `` which returns a sanitized URL representing the location of the QR Code. -``` +```ts // File: example.ts + export class QRCodeComponent { public myAngularxQrCode: string = ""; public qrCodeDownloadLink: SafeUrl = ""; @@ -167,9 +189,18 @@ export class QRCodeComponent { this.qrCodeDownloadLink = url; } } +``` + +```html + + + -// File: example.html - Download ``` @@ -179,26 +210,26 @@ it returns an image as `.png`, if it's svg, returns a `.svg` file. ## Available Parameters -| Attribute | Type | Default | Description | -| -------------------- | ----------------------- | ----------- | -------------------------------------------------------------- | -| allowEmptyString | Boolean | false | Allow qrdata to be an empty string | -| alt | String | null | HTML alt attribute (supported by img, url) | -| ariaLabel | String | null | HTML aria-label attribute (supported by canvas, img, url) | -| colorDark | String | '#000000ff' | RGBA color, color of dark module (foreground) | -| colorLight | String | '#ffffffff' | RGBA color, color of light module (background) | -| cssClass | String | 'qrcode' | CSS Class | -| elementType | String | 'canvas' | 'canvas', 'svg', 'img', 'url' (alias for 'img') | -| errorCorrectionLevel | String | 'M' | QR Correction level ('L', 'M', 'Q', 'H') | -| imageSrc | String | null | Link to your image | -| imageHeight | Number | null | height of your image | -| imageWidth | Number | null | width of your image | -| margin | Number | 4 | Define how much wide the quiet zone should be. | -| qrCodeURL | EventEmitter\ | | Returns the QR Code URL | -| qrdata | String | '' | String to encode | -| scale | Number | 4 | Scale factor. A value of 1 means 1px per modules (black dots). | -| title | String | null | HTML title attribute (supported by canvas, img, url) | -| version | Number | (auto) | 1-40 | -| width | Number | 10 | Height/Width (any value) | +| Attribute | Type | Default | Description | +| -------------------- | ----------------------- | ------------- | -------------------------------------------------------------- | +| allowEmptyString | Boolean | `false` | Allow qrdata to be an empty string | +| alt | String | `null` | HTML alt attribute (supported by img, url) | +| ariaLabel | String | `null` | HTML aria-label attribute (supported by canvas, img, url) | +| colorDark | String | `'#000000ff'` | RGBA color, color of dark module (foreground) | +| colorLight | String | `'#ffffffff'` | RGBA color, color of light module (background) | +| cssClass | String | `'qrcode'` | CSS Class | +| elementType | String | `'canvas'` | 'canvas', 'svg', 'img', 'url' (alias for 'img') | +| errorCorrectionLevel | String | `'M'` | QR Correction level ('L', 'M', 'Q', 'H') | +| imageSrc | String | `null` | Link to your image | +| imageHeight | Number | `null` | height of your image | +| imageWidth | Number | `null` | width of your image | +| margin | Number | `4` | Define how much wide the quiet zone should be. | +| qrCodeURL | EventEmitter\ | | Returns the QR Code URL | +| qrdata | String | `''` | String to encode | +| scale | Number | `4` | Scale factor. A value of 1 means 1px per modules (black dots). | +| title | String | `null` | HTML title attribute (supported by canvas, img, url) | +| version | Number | `(auto)` | 1-40 | +| width | Number | `10` | Height/Width (any value) | ## QR Code capacity @@ -206,21 +237,27 @@ Depending on the amount of data of the **qrdata** to encode, a minimum **width** ## AOT - Ahead Of Time Compilation -`angularx-qrcode` supports AOT Compilation (Ahead-of-Time Compilation) which results in significant faster rendering. An AOT-enabled module is included. Further reading: https://angular.io/guide/aot-compiler +The `angularx-qrcode` library supports AOT Compilation (Ahead-of-Time Compilation) which results in significant faster rendering. An AOT-enabled module is included. + +Further reading: https://angular.dev/tools/cli/aot-compiler ## SSR - Server Side Rendering -As of version 1.6.0, SSR support is fully implemented, the following workaround is no longer needed. [HowTo use Angular QRCode with SSR](https://github.com/Cordobo/angularx-qrcode/issues/5) +As of version 1.6.0, SSR support is fully implemented, the following workaround is no longer needed. + +[How to use Angular QRCode with SSR](https://github.com/Cordobo/angularx-qrcode/issues/5) ## Contribute - Please open your PR against the development branch. -- Make sure your editor uses **prettier** to minimize commited code changes. +- Make sure your editor uses [Prettier](https://prettier.io/) to minimize commited code changes. - You cannot contribute but want to support development? Consider a [sponsorship](https://github.com/sponsors/Cordobo). ## Sponsoring -Support the development of angularx-qrcode (or even see your logo here?), consider [sponsoring angularx-qrcode](https://github.com/sponsors/Cordobo). Your support is much appreciated! +Support the development of the `angularx-qrcode` library (or even see your logo here?), consider [sponsoring angularx-qrcode](https://github.com/sponsors/Cordobo). + +Your support is much appreciated! ❤️ ## License