docs.sheetjs.com/docz/docs/03-demos/05-mobile/04-ionic.md

261 lines
5.2 KiB
Markdown
Raw Normal View History

2023-01-05 23:33:49 +00:00
---
title: Ionic
2023-02-28 11:40:44 +00:00
pagination_prev: demos/static/index
2023-01-05 23:33:49 +00:00
pagination_next: demos/desktop/index
sidebar_position: 4
sidebar_custom_props:
summary: Native Components + Web View
---
2023-04-27 09:12:19 +00:00
import current from '/version.js';
2023-01-05 23:33:49 +00:00
The [NodeJS Module](/docs/getting-started/installation/nodejs) can be imported
from the main entrypoint or any script in the project.
2023-03-20 05:44:17 +00:00
The "Complete Example" creates an app that looks like the screenshots below:
<table><thead><tr>
<th><a href="#demo">iOS</a></th>
2023-03-29 00:26:39 +00:00
<th><a href="#demo">Android</a></th>
2023-03-20 05:44:17 +00:00
</tr></thead><tbody><tr><td>
![iOS screenshot](pathname:///ionic/ios.png)
2023-03-29 00:26:39 +00:00
</td><td>
![Android screenshot](pathname:///ionic/and.png)
2023-03-20 05:44:17 +00:00
</td></tr></tbody></table>
2023-01-05 23:33:49 +00:00
:::warning Telemetry
Before starting this demo, manually disable telemetry. On Linux and MacOS:
```bash
rm -rf ~/.ionic/
mkdir ~/.ionic
cat <<EOF > ~/.ionic/config.json
{
"version": "6.20.1",
"telemetry": false,
"npmClient": "npm"
}
EOF
npx @capacitor/cli telemetry off
```
To verify telemetry was disabled:
```bash
npx @ionic/cli config get -g telemetry
npx @capacitor/cli telemetry
```
:::
2023-03-20 05:44:17 +00:00
## Integration Details
2023-01-05 23:33:49 +00:00
:::caution
The latest version of Ionic uses CapacitorJS. These notes are for Cordova apps.
:::
2023-03-20 05:44:17 +00:00
### Angular
2023-01-05 23:33:49 +00:00
`Array<Array<any>>` neatly maps to a table with `ngFor`:
```html
<ion-grid>
<ion-row *ngFor="let row of data">
<ion-col *ngFor="let val of row">
{{val}}
</ion-col>
</ion-row>
</ion-grid>
```
2023-03-20 05:44:17 +00:00
### Cordova
`@ionic-native/file` reads and writes files on devices.
_Reading Files_
`readAsArrayBuffer` returns `ArrayBuffer` objects suitable for `array` type:
2023-01-05 23:33:49 +00:00
```ts
/* read a workbook */
const ab: ArrayBuffer = await this.file.readAsArrayBuffer(url, filename);
2023-03-20 05:44:17 +00:00
const wb: XLSX.WorkBook = XLSX.read(ab, {type: 'array'});
```
2023-01-05 23:33:49 +00:00
2023-03-20 05:44:17 +00:00
_Writing Files_
`array` type can be converted to blobs that can be exported with `writeFile`:
```ts
2023-01-05 23:33:49 +00:00
/* write a workbook */
const wbout: ArrayBuffer = XLSX.write(wb, { bookType: 'xlsx', type: 'array' });
let blob = new Blob([wbout], {type: 'application/octet-stream'});
this.file.writeFile(url, filename, blob, {replace: true});
```
## Demo
:::note
2023-03-29 00:26:39 +00:00
This demo was tested on an Intel Mac on 2023 March 28 with Cordova.
2023-01-05 23:33:49 +00:00
The file integration uses `@ionic-native/file` version `5.36.0`.
2023-04-08 08:42:15 +00:00
The iOS simulator runs iOS 15.5 on an iPhone SE (3rd Generation).
2023-01-05 23:33:49 +00:00
2023-03-29 00:26:39 +00:00
The Android simulator runs Android 12.0 (S) API 31 on a Pixel 3.
2023-01-05 23:33:49 +00:00
:::
0) Disable telemetry as noted in the warning.
Install required global dependencies:
```bash
2023-03-29 00:26:39 +00:00
npm i -g cordova-res @angular/cli native-run @ionic/cli
2023-01-05 23:33:49 +00:00
```
2023-03-20 05:44:17 +00:00
Follow the [React Native demo](/docs/demos/mobile/reactnative) to ensure iOS and Android sims are ready.
2023-01-05 23:33:49 +00:00
1) Create a new project:
```bash
2023-03-29 00:26:39 +00:00
ionic start SheetJSIonic blank --type angular --cordova --quiet --no-git --no-link --confirm
2023-01-05 23:33:49 +00:00
```
2023-03-20 05:44:17 +00:00
If a prompt asks to confirm Cordova use, enter `Yes` to continue.
2023-01-05 23:33:49 +00:00
If a prompt asks about creating an Ionic account, enter `N` to opt out.
2) Set up Cordova:
```bash
2023-03-20 05:44:17 +00:00
cd SheetJSIonic
2023-03-29 00:26:39 +00:00
ionic cordova plugin add cordova-plugin-file
ionic cordova platform add ios --confirm
ionic cordova platform add android --confirm
2023-01-05 23:33:49 +00:00
npm install --save @ionic-native/core @ionic-native/file @ionic/cordova-builders
```
2023-03-29 00:26:39 +00:00
:::note
2023-03-20 05:44:17 +00:00
2023-03-29 00:26:39 +00:00
If `cordova-plugin-file` is added before the platforms, installation may fail:
2023-03-20 05:44:17 +00:00
```
CordovaError: Could not load API for ios project
```
2023-03-29 00:26:39 +00:00
This can be resolved by removing and reinstalling the `ios` platform:
2023-03-20 05:44:17 +00:00
```bash
2023-03-29 00:26:39 +00:00
ionic cordova platform rm ios
ionic cordova platform add ios --confirm
```
:::
:::caution
If the `npm install` fails due to `rxjs` resolution, add the highlighted lines
to `package.json` to force a resolution:
```js title="package.json"
"private": true,
// highlight-start
"overrides": {
"rxjs": "~7.5.0"
},
// highlight-end
"dependencies": {
2023-03-20 05:44:17 +00:00
```
2023-03-29 00:26:39 +00:00
After adding the lines, the `npm install` command will succeed.
2023-03-20 05:44:17 +00:00
:::
2023-01-05 23:33:49 +00:00
3) Install dependencies:
```bash
npm install --save https://cdn.sheetjs.com/xlsx-latest/xlsx-latest.tgz
```
4) Add `@ionic-native/file` to the module. Differences highlighted below:
```ts title="src/app/app.module.ts"
import { AppComponent } from './app.component';
import { AppRoutingModule } from './app-routing.module';
// highlight-next-line
import { File } from '@ionic-native/file/ngx';
@NgModule({
declarations: [AppComponent],
imports: [BrowserModule, IonicModule.forRoot(), AppRoutingModule],
// highlight-next-line
providers: [File, { provide: RouteReuseStrategy, useClass: IonicRouteStrategy }],
bootstrap: [AppComponent],
})
export class AppModule {}
```
5) Download [`home.page.ts`](pathname:///ionic/home.page.ts) and replace:
```bash
curl -o src/app/home/home.page.ts -L https://docs.sheetjs.com/ionic/home.page.ts
```
2023-03-20 05:44:17 +00:00
**iOS Testing**
2023-01-05 23:33:49 +00:00
```bash
2023-03-29 00:26:39 +00:00
ionic cordova emulate ios
2023-01-05 23:33:49 +00:00
```
2023-03-20 05:44:17 +00:00
:::caution
2023-01-05 23:33:49 +00:00
2023-03-20 05:44:17 +00:00
In some test runs, the `cordova build ios --emulator` step failed with error:
```
> cordova build ios --emulator
Could not load API for ios project
```
This was resolved by forcefully installing `cordova-ios`:
```bash
npm i --save cordova-ios
```
:::
2023-03-29 00:26:39 +00:00
**Android Testing**
```bash
ionic cordova emulate android
```
:::caution
In some test runs, `cordova build android --emulator` step failed with error:
```
Could not find or parse valid build output file
```
This was resolved by forcefully installing `cordova-android`:
```bash
npm i --save cordova-android
```
:::