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

271 lines
5.9 KiB
Markdown
Raw Normal View History

2023-01-05 23:33:49 +00:00
---
title: CapacitorJS
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: 5
sidebar_custom_props:
summary: JS + Web View
---
2023-04-27 09:12:19 +00:00
import current from '/version.js';
2023-05-07 13:58:36 +00:00
import CodeBlock from '@theme/CodeBlock';
2023-04-27 09:12:19 +00:00
2023-04-01 20:13:16 +00:00
The [NodeJS Module](/docs/getting-started/installation/nodejs) can be imported
from the main entrypoint or any script in the project.
2023-01-05 23:33:49 +00:00
2023-04-01 20:13:16 +00:00
The "Complete Example" creates an app that looks like the screenshots below:
2023-01-05 23:33:49 +00:00
2023-04-01 20:13:16 +00:00
<table><thead><tr>
<th><a href="#demo">iOS</a></th>
<th><a href="#demo">Android</a></th>
</tr></thead><tbody><tr><td>
2023-01-05 23:33:49 +00:00
2023-04-01 20:13:16 +00:00
![iOS screenshot](pathname:///cap/ios.png)
2023-01-05 23:33:49 +00:00
2023-04-01 20:13:16 +00:00
</td><td>
![Android screenshot](pathname:///cap/and.png)
</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
npx @capacitor/cli telemetry off
```
To verify telemetry was disabled:
```bash
npx @capacitor/cli telemetry
```
:::
2023-04-01 20:13:16 +00:00
## Integration Details
2023-01-05 23:33:49 +00:00
This example uses Svelte, but the same principles apply to other frameworks.
#### Reading data
The standard HTML5 File Input element logic works in CapacitorJS:
```html
<script>
import { read, utils } from 'xlsx';
let html = "";
/* show file picker, read file, load table */
async function importFile(evt) {
// highlight-start
const f = evt.target.files[0];
const wb = read(await f.arrayBuffer());
// highlight-end
const ws = wb.Sheets[wb.SheetNames[0]]; // get the first worksheet
html = utils.sheet_to_html(ws); // generate HTML and update state
}
</script>
<main>
<!-- highlight-next-line -->
<input type="file" on:change={importFile}/>
<div bind:this={tbl}>{@html html}</div>
</main>
```
#### Writing data
`@capacitor/filesystem` can write Base64 strings:
```html
<script>
import { Filesystem, Directory } from '@capacitor/filesystem';
import { utils, writeXLSX } from 'xlsx';
let html = "";
let tbl;
/* get state data and export to XLSX */
async function exportFile() {
const elt = tbl.getElementsByTagName("TABLE")[0];
const wb = utils.table_to_book(elt);
/* generate Base64 string for Capacitor */
// highlight-start
const data = writeXLSX(wb, { type: "base64" });
await Filesystem.writeFile({
data,
path: "SheetJSCap.xlsx",
directory: Directory.Documents
}); // write file
// highlight-end
}
</script>
<main>
<button on:click={exportFile}>Export XLSX</button>
<div bind:this={tbl}>{@html html}</div>
</main>
```
2023-04-01 20:13:16 +00:00
## Demo
:::note
2023-09-05 18:04:23 +00:00
The Android demo was last tested on 2023 September 03 with CapacitorJS `5.3.0`
and filesystem `5.1.3` on an emulated Pixel 3 + Android 13 ("Tiramisu") API 33.
2023-04-01 20:13:16 +00:00
2023-09-05 18:04:23 +00:00
The iOS demo was last tested on 2023 September 03 with CapacitorJS `5.3.0`
and filesystem `5.1.3` on an emulated iPhone SE (3rd generation) + iOS 16.4.
2023-04-01 20:13:16 +00:00
:::
2023-01-05 23:33:49 +00:00
2023-04-01 20:13:16 +00:00
### Base Project
2023-01-05 23:33:49 +00:00
2023-09-05 18:04:23 +00:00
0) Follow the official "Environment Setup"[^1] instructions to set up Android
and iOS targets
:::caution pass
iOS development is only supported on macOS.
:::
<details><summary><b>Installation Notes</b> (click to show)</summary>
CapacitorJS requires Java 17.
</details>
2023-04-01 20:13:16 +00:00
1) Disable telemetry.
```bash
npx @capacitor/cli telemetry off
```
Verify that telemetry is disabled by running
```bash
npx @capacitor/cli telemetry
```
2023-01-05 23:33:49 +00:00
2023-04-01 20:13:16 +00:00
(it should print `Telemetry is off`)
2023-01-05 23:33:49 +00:00
2023-04-01 20:13:16 +00:00
2) Create a new Svelte project:
2023-01-05 23:33:49 +00:00
```bash
npm create vite@latest sheetjs-cap -- --template svelte
cd sheetjs-cap
```
2023-04-01 20:13:16 +00:00
3) Install dependencies:
2023-01-05 23:33:49 +00:00
2023-05-07 13:58:36 +00:00
<CodeBlock language="bash">{`\
2023-04-27 09:12:19 +00:00
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz
npm i --save @capacitor/core @capacitor/cli @capacitor/filesystem`}
2023-05-07 13:58:36 +00:00
</CodeBlock>
2023-01-05 23:33:49 +00:00
2023-04-01 20:13:16 +00:00
4) Create CapacitorJS structure:
2023-01-05 23:33:49 +00:00
```bash
npx cap init sheetjs-cap com.sheetjs.cap --web-dir=dist
2023-04-01 20:13:16 +00:00
npm run build
```
5) Download [`src/App.svelte`](pathname:///cap/App.svelte) and replace:
```bash
curl -o src/App.svelte -L https://docs.sheetjs.com/cap/App.svelte
```
2023-09-05 18:04:23 +00:00
### Android
2023-04-01 20:13:16 +00:00
2023-09-05 18:04:23 +00:00
6) Create Android app
2023-04-01 20:13:16 +00:00
```bash
2023-09-05 18:04:23 +00:00
npm i --save @capacitor/android
npx cap add android
2023-01-05 23:33:49 +00:00
```
2023-09-05 18:04:23 +00:00
7) Enable file reading and writing in the Android app.
The following lines must be added to `android/app/src/main/AndroidManifest.xml`
after the `Permissions` comment:
```xml title="android/app/src/main/AndroidManifest.xml (add to file)"
<!-- Permissions -->
2023-04-01 20:13:16 +00:00
<!-- highlight-start -->
2023-09-05 18:04:23 +00:00
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
2023-09-11 04:44:15 +00:00
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
2023-04-01 20:13:16 +00:00
<!-- highlight-end -->
2023-01-05 23:33:49 +00:00
2023-09-05 18:04:23 +00:00
<uses-permission android:name="android.permission.INTERNET" />
```
2023-01-05 23:33:49 +00:00
2023-09-05 18:04:23 +00:00
8) Run the app in the simulator
2023-01-05 23:33:49 +00:00
2023-04-01 20:13:16 +00:00
```bash
npm run build
npx cap sync
2023-09-05 18:04:23 +00:00
npx cap run android
2023-04-01 20:13:16 +00:00
```
2023-01-05 23:33:49 +00:00
2023-09-05 18:04:23 +00:00
9) Test the app
2023-01-05 23:33:49 +00:00
2023-04-01 20:13:16 +00:00
Open the app and observe that presidents are listed in the table.
2023-01-05 23:33:49 +00:00
2023-09-05 18:04:23 +00:00
Touch "Export XLSX" and the emulator will ask for permission:
2023-04-01 20:13:16 +00:00
2023-09-05 18:04:23 +00:00
Tap "Allow" and a popup will be displayed with a path.
2023-04-01 20:13:16 +00:00
2023-09-05 18:04:23 +00:00
To see the generated file, switch to the "Files" app in the simulator, tap the
`≡` icon and tap "Documents". Tap "Documents" folder to find `SheetJSCap.xlsx`.
2023-04-01 20:13:16 +00:00
2023-09-05 18:04:23 +00:00
### iOS
2023-04-01 20:13:16 +00:00
2023-09-05 18:04:23 +00:00
10) Create iOS app
2023-04-01 20:13:16 +00:00
```bash
2023-09-05 18:04:23 +00:00
npm i --save @capacitor/ios
npx cap add ios
2023-01-05 23:33:49 +00:00
```
2023-09-05 18:04:23 +00:00
11) Enable file sharing and make the documents folder visible in the iOS app.
The following lines must be added to `ios/App/App/Info.plist`:
2023-04-01 20:13:16 +00:00
2023-09-05 18:04:23 +00:00
```xml title="ios/App/App/Info.plist (add to file)"
<plist version="1.0">
<dict>
2023-04-01 20:13:16 +00:00
<!-- highlight-start -->
2023-09-05 18:04:23 +00:00
<key>UIFileSharingEnabled</key>
<true/>
<key>LSSupportsOpeningDocumentsInPlace</key>
<true/>
2023-04-01 20:13:16 +00:00
<!-- highlight-end -->
2023-09-05 18:04:23 +00:00
<key>CFBundleDevelopmentRegion</key>
2023-04-01 20:13:16 +00:00
```
2023-09-05 18:04:23 +00:00
(The root element of the document is `plist` and it contains one `dict` child)
12) Run the app in the simulator
2023-01-05 23:33:49 +00:00
```bash
2023-04-01 20:13:16 +00:00
npm run build
npx cap sync
2023-09-05 18:04:23 +00:00
npx cap run ios
2023-01-05 23:33:49 +00:00
```
2023-09-05 18:04:23 +00:00
13) Test the app
2023-04-01 20:13:16 +00:00
Open the app and observe that presidents are listed in the table.
2023-09-05 18:04:23 +00:00
Touch "Export XLSX" and a popup will be displayed.
2023-04-01 20:13:16 +00:00
2023-09-05 18:04:23 +00:00
To see the generated file, switch to the "Files" app in the simulator and look
for `SheetJSCap.xlsx` in "On My iPhone" > "`sheetjs-cap`"
2023-01-05 23:33:49 +00:00
2023-09-05 18:04:23 +00:00
[^1]: See ["Environment Setup"](https://capacitorjs.com/docs/getting-started/environment-setup) in the CapacitorJS documentation.