forked from sheetjs/docs.sheetjs.com
chore/docs: [Electron Demo] - fix mistakes in docs.
This commit is contained in:
parent
8c4bd369c4
commit
3b81f8931b
@ -50,7 +50,7 @@ The renderer process is sandboxed and cannot run any non-browser code.
|
||||
|
||||
The main process can run any NodeJS code, but it cannot access the DOM or any browser APIs.
|
||||
|
||||
To allow communication between the main and renderer processes, Electron recommends building a [context bridge](https://www.electronjs.org/docs/latest/api/context-bridge) to expose low-level system calls and NodeJS APIs to the renderer process.
|
||||
To allow communication between the main and renderer processes, Electron recommends building a [context bridge](https://www.electronjs.org/docs/latest/api/context-bridge) to expose low-level system calls and NodeJS APIs to the renderer process. Such as the [SheetJS NodeJS Module](/docs/getting-started/installation/nodejs) which we will be using here.
|
||||
|
||||
Exposed APIs are available as `SheetJSDemoAPI` on the window object and proxied from the main process.
|
||||
|
||||
@ -61,6 +61,7 @@ const path = require('path');
|
||||
const XLSX = require('xlsx');
|
||||
|
||||
// The contextBridge API allows us to expose APIs to the renderer process.
|
||||
// highlight-next-line
|
||||
contextBridge.exposeInMainWorld('SheetJSDemoAPI', {
|
||||
// request OS file dialogs from the main process
|
||||
openFile: (filters) => ipcRenderer.invoke('dialog:openFile', filters),
|
||||
@ -75,7 +76,8 @@ contextBridge.exposeInMainWorld('SheetJSDemoAPI', {
|
||||
basename: (p) => path.basename(p),
|
||||
extname: (p) => path.extname(p),
|
||||
|
||||
// Here for example we are exposing the sheetjs package to the renderer process.
|
||||
// Here for example we are exposing the sheetjs package to the renderer process.
|
||||
// highlight-next-line
|
||||
xlsx: XLSX,
|
||||
});
|
||||
```
|
||||
@ -123,6 +125,8 @@ For example, assuming a DIV on the page:
|
||||
The event handler would process the event as if it were a web event:
|
||||
|
||||
```js title="index.js -- renderer process"
|
||||
const XLSX = window.SheetJSDemoAPI.xlsx; // use xlsx package from bridge process
|
||||
|
||||
async function handleDrop(e) {
|
||||
e.stopPropagation();
|
||||
e.preventDefault();
|
||||
@ -146,10 +150,10 @@ We can now use the exposed APIs from our preload script above to show the open d
|
||||
|
||||
```js title="index.js -- renderer process"
|
||||
// our exposed bridge APIs are available as SheetJSDemoAPI on the window object
|
||||
const openFile = SheetJSDemoAPI.openFile; // request the open file dialog from the main process
|
||||
const openFile = window.SheetJSDemoAPI.openFile; // request the open file dialog from the main process
|
||||
// We can also access the SheetJS package from the exposed bridge APIs
|
||||
// highlight-next-line
|
||||
const XLSX = SheetJSDemoAPI.xlsx;
|
||||
const XLSX = window.SheetJSDemoAPI.xlsx;
|
||||
|
||||
/* this function will show the open dialog and try to parse the workbook */
|
||||
async function importFile() {
|
||||
@ -164,8 +168,7 @@ async function importFile() {
|
||||
return XLSX.readFile(result.filePaths[0]);
|
||||
}
|
||||
```
|
||||
The xslx package here is being proxied from the main process via the bridge API.
|
||||
The actual implementation of the `openFile` function is handled within the main process in `main.js`.
|
||||
In order to interact with the file system, the `xlsx` package here depends on the Node.js. Which means we need to utilize the Bridge here and make it possible to call these methods from the renderer process. The appropriate IPC event can be found below.
|
||||
|
||||
```js title="main.js -- main process"
|
||||
const { ipcMain, dialog } = require('electron');
|
||||
@ -195,7 +198,7 @@ async function exportFile(workbook) {
|
||||
XLSX.writeFile(workbook, result.filePaths[0]);
|
||||
}
|
||||
```
|
||||
And here is the implementation of the `saveFile` function in `main.js`:
|
||||
And here is the implementation of the `saveFile` event listener in `main.js`:
|
||||
```js title="main.js -- main process"
|
||||
const { ipcMain, dialog } = require('electron');
|
||||
|
||||
@ -206,10 +209,19 @@ ipcMain.handle('dialog:saveFile', (_e, filters) =>
|
||||
|
||||
### Working with OS level file open events.
|
||||
|
||||
The demo has been preconfigured to handle OS level file open events, such as the "open with" context menu or `open` CLI command for all file types SheetJS supports.
|
||||
In order to pre-register your application as a handler for any other file types, it is necessary to modify the `package.json` file as such.
|
||||
Electron makes it possible to handle OS level file open events, such as the "open with" context menu or `open` CLI command.
|
||||
|
||||
```json
|
||||
The example below shows the configuration required to register your application as a handler supporting such events for all file extensions SheetJS supports.
|
||||
|
||||
:::caution
|
||||
|
||||
It is also possible to open files using the "open with" context menu without registering the application as a handler for the specified file types. This however, requires manually selecting the application binary as a target to open the file with.
|
||||
|
||||
**This action might not be supported by some file managers on Linux based systems.**
|
||||
:::
|
||||
|
||||
```json title="package.json"
|
||||
{
|
||||
// ...existing content
|
||||
"build": {
|
||||
"appId": "com.sheetjs.electron",
|
||||
@ -228,14 +240,10 @@ In order to pre-register your application as a handler for any other file types,
|
||||
"win": { "target": "nsis" },
|
||||
"linux": { "target": "deb" }
|
||||
},
|
||||
}
|
||||
```
|
||||
this snippet makes it possible to generate installers for MacOS, Windows and Linux which will automatically register the application as a handler for the specified file types.
|
||||
This makes it possible to generate installers for MacOS, Windows and Linux which will automatically register the application as a handler for the specified file types avoiding manual registration processes that differ across operating systems.
|
||||
|
||||
:::info pass
|
||||
|
||||
It is also possible to open files using the "open with" context menu without registering the application as a handler for the specified file types. This however, requires manually selecting the application binary as a target to open the file with.
|
||||
|
||||
:::
|
||||
## Complete Example
|
||||
|
||||
:::note Tested Deployments
|
||||
@ -327,13 +335,8 @@ The app will run.
|
||||
```bash
|
||||
npm run make
|
||||
```
|
||||
or
|
||||
```bash
|
||||
npm run dist
|
||||
```
|
||||
if you want to generate an installer binary.
|
||||
|
||||
This will create a package in the `out\make` folder and a standalone binary, or an installer binary in `/dist` if you used `npm run dist`.
|
||||
This will create a package in the `out\make` folder and a standalone binary.
|
||||
|
||||
:::caution pass
|
||||
|
||||
@ -365,10 +368,10 @@ The program will run on ARM64 Windows.
|
||||
|
||||
#### Electron API
|
||||
|
||||
7) Click "Click here to select a file from your computer". With the file picker,
|
||||
7) Click "Click here to select a file. With the file picker,
|
||||
navigate to the Downloads folder and select `pres.numbers`.
|
||||
|
||||
The application should show data in a table.
|
||||
The application should show a dropdown component for each worksheet contained in your file, clicking on it should display its data within a table.
|
||||
|
||||
8) Click "Export" and click "Save" in the popup. By default, it will try
|
||||
to write to `Untitled.xls` in the Downloads folder.
|
||||
@ -393,9 +396,12 @@ spreadsheet editor and compare the data to the table shown in the application.
|
||||
|
||||
12) Select your application binary by navigating to the folder where the application was built (see step 4).
|
||||
|
||||
:::info
|
||||
On some Linux based systems, depending on the file manager in use selecting the binary directly may not be possible.
|
||||
:::
|
||||
|
||||
|
||||
The application should show data in a table.
|
||||
The application should show a dropdown component for each worksheet contained in your file, clicking on it should display its data within a table.
|
||||
|
||||
#### Drag and Drop
|
||||
|
||||
@ -403,16 +409,24 @@ The application should show data in a table.
|
||||
|
||||
14) Open the Downloads folder in a file explorer or finder window.
|
||||
|
||||
15) Click and drag the `pres.numbers` file from the Downloads folder to the
|
||||
bordered "Drop a spreadsheet file" box. The file data should be displayed.
|
||||
15) Click and drag the `pres.numbers` file from the Downloads folder
|
||||
into the application window.
|
||||
|
||||
#### File Input Element
|
||||
The application should show a dropdown component for each worksheet contained in your file, clicking on it should display its data within a table.
|
||||
|
||||
:::info
|
||||
On some Linux based systems, the experience can differ depending on the window manager / desktop environment in use.
|
||||
:::
|
||||
|
||||
#### File Picker Element
|
||||
|
||||
16) Close the application, end the terminal process and re-launch (see step 6)
|
||||
|
||||
17) Click "Choose File". With the file picker, navigate to the Downloads folder
|
||||
and select `pres.numbers`.
|
||||
|
||||
The application should show a dropdown component for each worksheet contained in your file, clicking on it should display its data within a table.
|
||||
|
||||
|
||||
## Electron Breaking Changes
|
||||
|
||||
|
||||
@ -69,4 +69,4 @@
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue
Block a user