mirror of
https://github.com/danielsogl/awesome-cordova-plugins.git
synced 2026-05-02 00:07:23 +08:00
docs: update guide to reflect latest Angular APIs
This commit is contained in:
Daniel Sogl
+2
-2
@@ -1,6 +1,6 @@
|
||||
# Ionic Native Developer Guide
|
||||
# Awesome Cordova Plugins Developer Guide
|
||||
|
||||
This is a short guide on creating new plugin wrappers for Ionic Native.
|
||||
This is a short guide on creating new plugin wrappers for Awesome Cordova Plugins.
|
||||
|
||||
## Creating Plugin Wrappers
|
||||
|
||||
|
||||
@@ -28,58 +28,53 @@ For the full Awesome Cordova Plugins documentation, please visit [https://ionicf
|
||||
|
||||
### Basic Usage
|
||||
|
||||
#### Ionic/Angular apps
|
||||
#### Ionic/Angular apps (Standalone)
|
||||
|
||||
To use a plugin, import and add the plugin provider to your `@NgModule`, and then inject it where you wish to use it.
|
||||
Angular v14+ uses standalone components by default. To use a plugin, register it as a provider in your application bootstrap and inject it using Angular's `inject()` function.
|
||||
Make sure to import the injectable class from the `/ngx` directory as shown in the following examples:
|
||||
|
||||
```typescript
|
||||
// app.module.ts
|
||||
// main.ts
|
||||
import { bootstrapApplication } from '@angular/platform-browser';
|
||||
import { Camera } from '@awesome-cordova-plugins/camera/ngx';
|
||||
import { Geolocation } from '@awesome-cordova-plugins/geolocation/ngx';
|
||||
import { AppComponent } from './app/app.component';
|
||||
|
||||
...
|
||||
|
||||
@NgModule({
|
||||
...
|
||||
|
||||
providers: [
|
||||
...
|
||||
Camera
|
||||
...
|
||||
]
|
||||
...
|
||||
})
|
||||
export class AppModule { }
|
||||
bootstrapApplication(AppComponent, {
|
||||
providers: [Camera, Geolocation],
|
||||
});
|
||||
```
|
||||
|
||||
```typescript
|
||||
import { Component, OnInit } from '@angular/core';
|
||||
import { inject } from '@angular/core';
|
||||
import { Geolocation } from '@awesome-cordova-plugins/geolocation/ngx';
|
||||
import { Platform } from 'ionic-angular';
|
||||
import { Platform } from '@ionic/angular';
|
||||
|
||||
@Component({ ... })
|
||||
export class MyComponent {
|
||||
@Component({
|
||||
selector: 'app-my-component',
|
||||
standalone: true,
|
||||
template: `<p>My Component</p>`,
|
||||
})
|
||||
export class MyComponent implements OnInit {
|
||||
private geolocation = inject(Geolocation);
|
||||
private platform = inject(Platform);
|
||||
|
||||
constructor(private geolocation: Geolocation, private platform: Platform) {
|
||||
async ngOnInit() {
|
||||
await this.platform.ready();
|
||||
|
||||
this.platform.ready().then(() => {
|
||||
// get position
|
||||
const pos = await this.geolocation.getCurrentPosition();
|
||||
console.log(`lat: ${pos.coords.latitude}, lon: ${pos.coords.longitude}`);
|
||||
|
||||
// get position
|
||||
this.geolocation.getCurrentPosition().then(pos => {
|
||||
console.log(`lat: ${pos.coords.latitude}, lon: ${pos.coords.longitude}`)
|
||||
});
|
||||
|
||||
|
||||
// watch position
|
||||
const watch = geolocation.watchPosition().subscribe(pos => {
|
||||
console.log(`lat: ${pos.coords.latitude}, lon: ${pos.coords.longitude}`)
|
||||
});
|
||||
|
||||
// to stop watching
|
||||
watch.unsubscribe();
|
||||
// watch position
|
||||
const watch = this.geolocation.watchPosition().subscribe((pos) => {
|
||||
console.log(`lat: ${pos.coords.latitude}, lon: ${pos.coords.longitude}`);
|
||||
});
|
||||
|
||||
// to stop watching
|
||||
watch.unsubscribe();
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
@@ -126,9 +121,9 @@ const Tab1: React.FC = () => {
|
||||
};
|
||||
```
|
||||
|
||||
#### ES2015+/TypeScript
|
||||
#### ES2015+/TypeScript (without Angular)
|
||||
|
||||
These modules can work in any ES2015+/TypeScript app (including Angular/Ionic apps). To use any plugin, import the class from the appropriate package, and use it's static methods.
|
||||
These modules can also be used without Angular by calling static methods directly:
|
||||
|
||||
```js
|
||||
import { Camera } from '@awesome-cordova-plugins/camera';
|
||||
@@ -140,64 +135,17 @@ document.addEventListener('deviceready', () => {
|
||||
});
|
||||
```
|
||||
|
||||
#### AngularJS
|
||||
|
||||
Awesome Cordova Plugins generates an AngularJS module in runtime and prepares a service for each plugin. To use the plugins in your AngularJS app:
|
||||
|
||||
1. Download the latest bundle from the [Github releases](https://github.com/danielsogl/awesome-cordova-plugins/releases) page.
|
||||
2. Include it in `index.html` before your app's code.
|
||||
3. Inject `ionic.native` module in your app.
|
||||
4. Inject any plugin you would like to use with a `$cordova` prefix.
|
||||
|
||||
```js
|
||||
angular.module('myApp', ['ionic.native']).controller('MyPageController', function ($cordovaCamera) {
|
||||
$cordovaCamera.getPicture().then(
|
||||
function (data) {
|
||||
console.log('Took a picture!', data);
|
||||
},
|
||||
function (err) {
|
||||
console.log('Error occurred while taking a picture', err);
|
||||
}
|
||||
);
|
||||
});
|
||||
```
|
||||
|
||||
#### Vanilla JS
|
||||
|
||||
To use Awesome Cordova Plugins in any other setup:
|
||||
|
||||
1. Download the latest bundle from the [Github releases](https://github.com/danielsogl/awesome-cordova-plugins/releases) page.
|
||||
2. Include it in `index.html` before your app's code.
|
||||
3. Access any plugin using the global `IonicNative` variable.
|
||||
|
||||
```js
|
||||
document.addEventListener('deviceready', function () {
|
||||
IonicNative.Camera.getPicture().then(
|
||||
function (data) {
|
||||
console.log('Took a picture!', data);
|
||||
},
|
||||
function (err) {
|
||||
console.log('Error occurred while taking a picture', err);
|
||||
}
|
||||
);
|
||||
});
|
||||
```
|
||||
|
||||
### Mocking and Browser Development (Ionic/Angular apps only)
|
||||
|
||||
Awesome Cordova Plugins makes it possible to mock plugins and develop nearly the entirety of your app in the browser or in `ionic serve`.
|
||||
|
||||
To do this, you need to provide a mock implementation of the plugins you wish to use. Here's an example of mocking the `Camera` plugin to return a stock image while in development:
|
||||
|
||||
First import the `Camera` class in your `src/app/app.module.ts` file:
|
||||
First create a mock class that extends the `Camera` class:
|
||||
|
||||
```typescript
|
||||
import { Camera } from '@awesome-cordova-plugins/camera/ngx';
|
||||
```
|
||||
|
||||
Then create a new class that extends the `Camera` class with a mock implementation:
|
||||
|
||||
```typescript
|
||||
class CameraMock extends Camera {
|
||||
getPicture(options) {
|
||||
return new Promise((resolve, reject) => {
|
||||
@@ -207,45 +155,23 @@ class CameraMock extends Camera {
|
||||
}
|
||||
```
|
||||
|
||||
Finally, override the previous `Camera` class in your `providers` for this module:
|
||||
Then override the `Camera` provider in your application bootstrap:
|
||||
|
||||
```typescript
|
||||
providers: [{ provide: Camera, useClass: CameraMock }];
|
||||
```
|
||||
|
||||
Here's the full example:
|
||||
|
||||
```typescript
|
||||
import { ErrorHandler, NgModule } from '@angular/core';
|
||||
import { BrowserModule } from '@angular/platform-browser';
|
||||
import { IonicApp, IonicModule, IonicErrorHandler } from 'ionic-angular';
|
||||
import { MyApp } from './app.component';
|
||||
import { HomePage } from '../pages/home/home';
|
||||
|
||||
// main.ts
|
||||
import { bootstrapApplication } from '@angular/platform-browser';
|
||||
import { Camera } from '@awesome-cordova-plugins/camera/ngx';
|
||||
|
||||
import { HomePage } from '../pages/home/home';
|
||||
import { MyApp } from './app.component';
|
||||
import { AppComponent } from './app/app.component';
|
||||
|
||||
class CameraMock extends Camera {
|
||||
getPicture(options) {
|
||||
return new Promise((resolve, reject) => {
|
||||
resolve('BASE_64_ENCODED_DATA_GOES_HERE');
|
||||
});
|
||||
return Promise.resolve('BASE_64_ENCODED_DATA_GOES_HERE');
|
||||
}
|
||||
}
|
||||
|
||||
@NgModule({
|
||||
declarations: [MyApp, HomePage],
|
||||
imports: [BrowserModule, IonicModule.forRoot(MyApp)],
|
||||
bootstrap: [IonicApp],
|
||||
entryComponents: [MyApp, HomePage],
|
||||
providers: [
|
||||
{ provide: ErrorHandler, useClass: IonicErrorHandler },
|
||||
{ provide: Camera, useClass: CameraMock },
|
||||
],
|
||||
})
|
||||
export class AppModule {}
|
||||
bootstrapApplication(AppComponent, {
|
||||
providers: [{ provide: Camera, useClass: CameraMock }],
|
||||
});
|
||||
```
|
||||
|
||||
### Runtime Diagnostics
|
||||
|
||||
+51
-56
@@ -8,68 +8,56 @@ These plugins are submitted and maintained by the Ionic community. While communi
|
||||
|
||||
For professional developers and teams that require dedicated native plugin support & SLAs, ongoing maintenance, and security patches, please explore our [premium options](https://ionicframework.com/native), including plugin support and pre-built solutions for common native use cases.
|
||||
|
||||
> These docs are for apps built with Ionic Framework 4.0.0 and greater. For older Ionic v3 projects, please [see here](https://ionicframework.com/docs/v3/native).
|
||||
|
||||
### [Capacitor Support](https://ionicframework.com/docs/native/community#capacitor-support) <a id="capacitor-support"></a>
|
||||
|
||||
In addition to Cordova, Ionic Native also works with [Capacitor](https://capacitor.ionicframework.com/), Ionic's official native runtime. Basic usage below. For complete details, [see the Capacitor documentation](https://capacitor.ionicframework.com/docs/cordova/using-cordova-plugins).
|
||||
In addition to Cordova, Awesome Cordova Plugins also works with [Capacitor](https://capacitorjs.com/), Ionic's official native runtime. Basic usage below. For complete details, [see the Capacitor documentation](https://capacitorjs.com/docs/cordova/using-cordova-plugins).
|
||||
|
||||
### [Usage](https://ionicframework.com/docs/native/community#usage) <a id="usage"></a>
|
||||
|
||||
All plugins have two components - the native code \(Cordova\) and the TypeScript code \(Ionic Native\). Cordova plugins are also wrapped in a `Promise` or `Observable` in order to provide a common plugin interface and modernized development approach.
|
||||
All plugins have two components - the native code (Cordova) and the TypeScript code (Awesome Cordova Plugins). Cordova plugins are also wrapped in a `Promise` or `Observable` in order to provide a common plugin interface and modernized development approach.
|
||||
|
||||
Using the [Camera plugin](https://ionicframework.com/docs/native/camera) as an example, first install it:CORDOVACAPACITOR
|
||||
Using the [Camera plugin](https://ionicframework.com/docs/native/camera) as an example, first install it:
|
||||
|
||||
```text
|
||||
// Install Cordova plugin
|
||||
$ ionic cordova plugin add cordova-plugin-camera
|
||||
```bash
|
||||
# Install Cordova plugin
|
||||
ionic cordova plugin add cordova-plugin-camera
|
||||
|
||||
// Install Ionic Native TypeScript wrapper
|
||||
$ npm install @ionic-native/camera
|
||||
# Install Awesome Cordova Plugins TypeScript wrapper
|
||||
npm install @awesome-cordova-plugins/camera
|
||||
|
||||
// Install Ionic Native core library (once per project)
|
||||
$ npm install @ionic-native/core
|
||||
# Install Awesome Cordova Plugins core library (once per project)
|
||||
npm install @awesome-cordova-plugins/core
|
||||
```
|
||||
|
||||
Next, begin using the plugin, following the various framework usage options below. For FAQ, see [here](https://ionicframework.com/docs/native/faq).
|
||||
|
||||
### [Angular](https://ionicframework.com/docs/native/community#angular) <a id="angular"></a>
|
||||
### [Angular (Standalone)](https://ionicframework.com/docs/native/community#angular) <a id="angular"></a>
|
||||
|
||||
Angular apps can use either Cordova or Capacitor to build native mobile apps. Import the plugin in a `@NgModule` and add it to the list of Providers. For Angular, the import path should end with `/ngx`. Angular's change detection is automatically handled.
|
||||
Angular apps can use either Cordova or Capacitor to build native mobile apps. Register the plugin as a provider in your application bootstrap. For Angular, the import path should end with `/ngx`. Angular's change detection is automatically handled.
|
||||
|
||||
```text
|
||||
// app.module.ts
|
||||
import { Camera } from '@ionic-native/camera/ngx';
|
||||
```typescript
|
||||
// main.ts
|
||||
import { bootstrapApplication } from '@angular/platform-browser';
|
||||
import { Camera } from '@awesome-cordova-plugins/camera/ngx';
|
||||
import { AppComponent } from './app/app.component';
|
||||
|
||||
...
|
||||
|
||||
@NgModule({
|
||||
...
|
||||
|
||||
providers: [
|
||||
...
|
||||
Camera
|
||||
...
|
||||
]
|
||||
...
|
||||
})
|
||||
export class AppModule { }
|
||||
bootstrapApplication(AppComponent, {
|
||||
providers: [Camera],
|
||||
});
|
||||
```
|
||||
|
||||
CopyCopied
|
||||
After the plugin has been registered, inject it in any component or service using Angular's `inject()` function:
|
||||
|
||||
After the plugin has been declared, it can be imported and injected like any other service:
|
||||
|
||||
```text
|
||||
```typescript
|
||||
// camera.service.ts
|
||||
import { Injectable } from "@angular/core";
|
||||
import { Camera, CameraOptions } from "@ionic-native/camera/ngx";
|
||||
import { Injectable, inject } from '@angular/core';
|
||||
import { Camera, CameraOptions } from '@awesome-cordova-plugins/camera/ngx';
|
||||
|
||||
@Injectable({
|
||||
providedIn: "root",
|
||||
providedIn: 'root',
|
||||
})
|
||||
export class PhotoService {
|
||||
constructor(private camera: Camera) {}
|
||||
private camera = inject(Camera);
|
||||
|
||||
takePicture() {
|
||||
const options: CameraOptions = {
|
||||
@@ -85,26 +73,35 @@ export class PhotoService {
|
||||
},
|
||||
(err) => {
|
||||
// Handle error
|
||||
console.log("Camera issue: " + err);
|
||||
console.log('Camera issue: ' + err);
|
||||
}
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
CopyCopied
|
||||
|
||||
### [React](https://ionicframework.com/docs/native/community#react) <a id="react"></a>
|
||||
|
||||
React apps must use Capacitor to build native mobile apps. However, Ionic Native \(and therefore, Cordova plugins\) can still be used.// Install Core library \(once per project\)npm install @ionic-native/core
|
||||
// Install Ionic Native TypeScript wrappernpm install @ionic-native/barcode-scanner
|
||||
// Install Cordova pluginnpm install phonegap-plugin-barcodescanner
|
||||
// Update native platform project\(s\) to include newly added pluginionic cap sync
|
||||
React apps must use Capacitor to build native mobile apps. However, Awesome Cordova Plugins (and therefore, Cordova plugins) can still be used.
|
||||
|
||||
```bash
|
||||
# Install Core library (once per project)
|
||||
npm install @awesome-cordova-plugins/core
|
||||
|
||||
# Install Awesome Cordova Plugins TypeScript wrapper
|
||||
npm install @awesome-cordova-plugins/barcode-scanner
|
||||
|
||||
# Install Cordova plugin
|
||||
npm install phonegap-plugin-barcodescanner
|
||||
|
||||
# Update native platform project(s) to include newly added plugin
|
||||
ionic cap sync
|
||||
```
|
||||
|
||||
Import the plugin object then use its static methods:
|
||||
|
||||
```text
|
||||
import { BarcodeScanner } from "@ionic-native/barcode-scanner";
|
||||
```typescript
|
||||
import { BarcodeScanner } from '@awesome-cordova-plugins/barcode-scanner';
|
||||
|
||||
const Tab1: React.FC = () => {
|
||||
const openScanner = async () => {
|
||||
@@ -126,19 +123,17 @@ const Tab1: React.FC = () => {
|
||||
};
|
||||
```
|
||||
|
||||
CopyCopied
|
||||
### [ES2015+/TypeScript](https://ionicframework.com/docs/native/community#vanilla-javascript) <a id="vanilla-javascript"></a>
|
||||
|
||||
### [Vanilla JavaScript](https://ionicframework.com/docs/native/community#vanilla-javascript) <a id="vanilla-javascript"></a>
|
||||
ES2015+ and TypeScript apps can use either Cordova or Capacitor to build native mobile apps. To use any plugin, import the class from the appropriate package and use its static methods:
|
||||
|
||||
Vanilla JavaScript apps, targeting ES2015+ and/or TypeScript, can use either Cordova or Capacitor to build native mobile apps. To use any plugin, import the class from the appropriate package and use its static methods:
|
||||
```typescript
|
||||
import { Camera } from '@awesome-cordova-plugins/camera';
|
||||
|
||||
```text
|
||||
import { Camera } from "@ionic-native/camera";
|
||||
|
||||
document.addEventListener("deviceready", () => {
|
||||
document.addEventListener('deviceready', () => {
|
||||
Camera.getPicture()
|
||||
.then((data) => console.log("Took a picture!", data))
|
||||
.catch((e) => console.log("Error occurred while taking a picture", e));
|
||||
.then((data) => console.log('Took a picture!', data))
|
||||
.catch((e) => console.log('Error occurred while taking a picture', e));
|
||||
});
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user