contributing
This commit is contained in:
parent
57312901e1
commit
3f137265cc
@ -196,7 +196,7 @@ These demos have been tested with Dojo Toolkit `1.10.4` and `1.17.3`.
|
||||
The official Google CDN is out of date. This is a known CDN bug.
|
||||
|
||||
The script <https://docs.sheetjs.com/dojo/dojo.js> was fetched from the official
|
||||
`1.17.3` uncompresssed release artifact[^2] on 2023-08-16.
|
||||
`1.17.3` uncompressed release artifact[^2] on 2023-08-16.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
@ -293,9 +293,11 @@ function SheetJSFetchUL() {
|
||||
|
||||
### jQuery
|
||||
|
||||
`jQuery.ajax` (`$.ajax`) does not support binary data out of the box. A custom
|
||||
`ajaxTransport` can add required functionality. SheetJS users have reported
|
||||
success with `jquery.binarytransport.js` in IE10.
|
||||
[jQuery](https://jquery.com/) is a JavaScript library that includes helpers for
|
||||
performing "Ajax" network requests. `jQuery.ajax` (`$.ajax`) does not support
|
||||
binary data out of the box[^1]. A custom `ajaxTransport` can add support.
|
||||
|
||||
SheetJS users have reported success with `jquery.binarytransport.js`[^2] in IE10.
|
||||
|
||||
After including the main `jquery.js` and `jquery.binarytransport.js` scripts,
|
||||
`$.ajax` will support `dataType: "binary"` and `processData: false`.
|
||||
@ -344,8 +346,8 @@ are still relevant.
|
||||
|
||||
#### axios
|
||||
|
||||
The `axios` library presents a Promise interface. Setting `responseType` to
|
||||
`arraybuffer` ensures the return type is an ArrayBuffer:
|
||||
[`axios`](https://axios-http.com/) presents a Promise based interface. Setting
|
||||
`responseType` to `arraybuffer` ensures the return type is an ArrayBuffer:
|
||||
|
||||
```js
|
||||
async function workbook_dl_axios(url) {
|
||||
@ -446,17 +448,22 @@ function SheetJSAxiosUL() {
|
||||
|
||||
#### superagent
|
||||
|
||||
The `superagent` library usage mirrors XHR:
|
||||
[`superagent`](https://github.com/visionmedia/superagent) is a network request
|
||||
library with a "Fluent Interface"[^3]. Calling the `responseType` method with
|
||||
`"arraybuffer"` will ensure the final response object is an `ArrayBuffer`:
|
||||
|
||||
```js
|
||||
/* set up an async GET request with superagent */
|
||||
superagent.get(url).responseType('arraybuffer').end(function(err, res) {
|
||||
/* parse the data when it is received */
|
||||
var data = new Uint8Array(res.body);
|
||||
var workbook = XLSX.read(data, {type:"array"});
|
||||
superagent
|
||||
.get(url)
|
||||
.responseType('arraybuffer')
|
||||
.end(function(err, res) {
|
||||
/* parse the data when it is received */
|
||||
var data = new Uint8Array(res.body);
|
||||
var workbook = XLSX.read(data, {type:"array"});
|
||||
|
||||
/* DO SOMETHING WITH workbook HERE */
|
||||
});
|
||||
/* DO SOMETHING WITH workbook HERE */
|
||||
});
|
||||
```
|
||||
|
||||
<details><summary><b>Live Download demo</b> (click to show)</summary>
|
||||
@ -582,7 +589,7 @@ https.get('https://sheetjs.com/pres.numbers', function(res) {
|
||||
|
||||
:::note
|
||||
|
||||
This demo was last tested on 2023 May 21 against NodeJS `18.16.0`
|
||||
This demo was last tested on 2023 August 29 against NodeJS `20.5.1`
|
||||
|
||||
:::
|
||||
|
||||
@ -616,7 +623,7 @@ async function parse_from_url(url) {
|
||||
|
||||
:::note
|
||||
|
||||
This demo was last tested on 2023 May 21 against NodeJS `18.16.0`
|
||||
This demo was last tested on 2023 August 29 against NodeJS `20.5.1`
|
||||
|
||||
:::
|
||||
|
||||
@ -675,7 +682,7 @@ var url = 'https://sheetjs.com/pres.numbers';
|
||||
request(url, {encoding: null}, function(err, res, data) {
|
||||
if(err || res.statusCode !== 200) return;
|
||||
|
||||
/* if the request was succesful, parse the data */
|
||||
/* if the request was successful, parse the data */
|
||||
// highlight-next-line
|
||||
var wb = XLSX.read(data);
|
||||
|
||||
@ -689,7 +696,7 @@ request(url, {encoding: null}, function(err, res, data) {
|
||||
|
||||
:::note
|
||||
|
||||
This demo was last tested on 2023 May 21 against request `2.88.2`
|
||||
This demo was last tested on 2023 August 29 against request `2.88.2`
|
||||
|
||||
:::
|
||||
|
||||
@ -725,14 +732,14 @@ async function workbook_dl_axios(url) {
|
||||
|
||||
:::note
|
||||
|
||||
This demo was last tested on 2023 May 21 against Axios `1.4.0`
|
||||
This demo was last tested on 2023 August 29 against Axios `1.5.0`
|
||||
|
||||
:::
|
||||
|
||||
1) Install the [NodeJS module](/docs/getting-started/installation/nodejs)
|
||||
|
||||
<CodeBlock language="bash">{`\
|
||||
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz axios@1.4.0`}
|
||||
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz axios@1.5.0`}
|
||||
</CodeBlock>
|
||||
|
||||
2) Save the following to `SheetJSAxios.js`:
|
||||
@ -765,3 +772,7 @@ Other demos show network operations in special platforms:
|
||||
|
||||
- [React Native "Fetching Remote Data"](/docs/demos/mobile/reactnative#fetching-remote-data)
|
||||
- [NativeScript "Fetching Remote Files"](/docs/demos/mobile/nativescript#fetching-remote-files)
|
||||
|
||||
[^1]: See [`dataType` in `jQuery.ajax`](https://api.jquery.com/jQuery.ajax/#:~:text=the%20%27dataType%27%20parameter.-,dataType,-(default%3A%20Intelligent) in the official jQuery documentation.
|
||||
[^2]: See [the official `jquery.binarytransport.js` repo](https://github.com/henrya/js-jquery/tree/master/BinaryTransport) for more details.
|
||||
[^3]: See ["Fluent interface"](https://en.wikipedia.org/wiki/Fluent_interface) on Wikipedia.
|
||||
@ -340,7 +340,7 @@ manually open the `SheetJSNS` app.
|
||||
|
||||
The app can be tested with the following sequence in the simulator:
|
||||
|
||||
- Tap "Export File". A dialog will print where the file was written. Typicaly
|
||||
- Tap "Export File". A dialog will print where the file was written. Typically
|
||||
the URL is `/data/user/0/org.nativescript.SheetJSNS/files/SheetJSNS.xls`
|
||||
|
||||
- Pull the file from the simulator:
|
||||
|
||||
@ -18,7 +18,7 @@ For other APIs, user code can pass data to `XLSX.read` or use data generated by
|
||||
This demo looks at various web APIs. More specific approaches for deployments
|
||||
like mobile apps are covered in their respective demos.
|
||||
|
||||
:::note
|
||||
:::note pass
|
||||
|
||||
Some snippets are also available in the "Common Use Cases" section:
|
||||
|
||||
@ -27,7 +27,9 @@ Some snippets are also available in the "Common Use Cases" section:
|
||||
|
||||
:::
|
||||
|
||||
:::warning
|
||||
## Web Browsers
|
||||
|
||||
:::warning pass
|
||||
|
||||
Not all web APIs are supported in all browsers. For example, Firefox does not
|
||||
support the "File System Access API".
|
||||
@ -37,7 +39,7 @@ client browser. Some APIs do not give any feedback.
|
||||
|
||||
:::
|
||||
|
||||
## Binary Data
|
||||
### Binary Data
|
||||
|
||||
Modern browser APIs typically use typed arrays or `Blob` or `File` structures.
|
||||
|
||||
@ -120,7 +122,7 @@ const u8 = XLSX.write(workbook, { type: "buffer", bookType: "xlsx" });
|
||||
const blob = new Blob([u8], { type: "application/vnd.ms-excel" });
|
||||
```
|
||||
|
||||
## HTML5 Download Attribute
|
||||
### HTML5 Download Attribute
|
||||
|
||||
_Writing Files_
|
||||
|
||||
@ -173,7 +175,7 @@ includes a live demo.
|
||||
|
||||
:::
|
||||
|
||||
## File API
|
||||
### File API
|
||||
|
||||
_Reading Files_
|
||||
|
||||
@ -193,7 +195,7 @@ async function handleFileAsync(e) {
|
||||
input_dom_element.addEventListener("change", handleFileAsync, false);
|
||||
```
|
||||
|
||||
## HTML Drag and Drop API
|
||||
### HTML Drag and Drop API
|
||||
|
||||
_Reading Files_
|
||||
|
||||
@ -221,7 +223,7 @@ drop_dom_element.addEventListener("dragover", suppress, false);
|
||||
drop_dom_element.addEventListener("dragenter", suppress, false);
|
||||
```
|
||||
|
||||
## File System Access API
|
||||
### File System Access API
|
||||
|
||||
:::caution Limited Browser Support
|
||||
|
||||
@ -235,7 +237,8 @@ the feature in version 86. Safari did not support File System Access API.
|
||||
This live example reads a file then tries to save as XLSX.
|
||||
|
||||
```jsx live
|
||||
function SheetJSRoundTripFileSystemAPI() { return ( <button onClick={async () => {
|
||||
function SheetJSRoundTripFileSystemAPI() { return window.showSaveFilePicker ? (
|
||||
<button onClick={async () => {
|
||||
/* Show picker and get data */
|
||||
const [rFile] = await window.showOpenFilePicker({
|
||||
types: [{
|
||||
@ -264,7 +267,8 @@ function SheetJSRoundTripFileSystemAPI() { return ( <button onClick={async () =>
|
||||
/* close stream to commit file */
|
||||
wstream.close();
|
||||
|
||||
}}>Click to read then save as XLSX</button> ) }
|
||||
}}>Click to read then save as XLSX</button>
|
||||
) : ( <b>This browser does not support File System Access API</b> ); }
|
||||
```
|
||||
|
||||
</details>
|
||||
@ -323,7 +327,7 @@ wstream.write(XLSX.write(wb, { bookType: ext, type: "buffer" }))
|
||||
wstream.close();
|
||||
```
|
||||
|
||||
## File and Directory Entries API
|
||||
### File and Directory Entries API
|
||||
|
||||
:::caution Deprecated
|
||||
|
||||
@ -355,7 +359,7 @@ window.requestFileSystem(window.PERSISTENT, 0, (fs) => {
|
||||
});
|
||||
```
|
||||
|
||||
## Internet Explorer
|
||||
### Internet Explorer
|
||||
|
||||
Internet Explorer offered proprietary APIs that were not adopted by Chromium.
|
||||
|
||||
|
||||
@ -265,6 +265,7 @@ This demo was tested in the following deployments:
|
||||
| `darwin-x64` | `2788d71` | 2023-07-24 |
|
||||
| `darwin-arm` | `2788d71` | 2023-06-05 |
|
||||
| `linux-x64` | `2788d71` | 2023-06-02 |
|
||||
| `linux-arm` | `2788d71` | 2023-08-29 |
|
||||
| `win10-x64` | `2788d71` | 2023-07-24 |
|
||||
|
||||
When the demo was tested, commit `2788d71` corresponded to the latest release.
|
||||
@ -40,7 +40,7 @@ These instructions were tested on the following platforms:
|
||||
| Platform | Test Date |
|
||||
|:------------------------------|:-----------|
|
||||
| Linux (Steam Deck Holo 3.4.8) | 2023-07-12 |
|
||||
| Linux (Ubuntu 18.04 AArch64) | 2023-04-13 |
|
||||
| Linux (Debian 11 AArch64) | 2023-08-29 |
|
||||
| MacOS 10.13 (x64) | 2023-04-04 |
|
||||
| MacOS 13.0 (ARM64) | 2023-04-13 |
|
||||
| Windows 10 (x64) + WSL Ubuntu | 2023-07-23 |
|
||||
@ -277,16 +277,17 @@ make init
|
||||
|
||||
This step may take a while as it will be downloading a number of test files.
|
||||
|
||||
3) Run a short test, then run a build
|
||||
3) Run a build and verify with a short test:
|
||||
|
||||
```bash
|
||||
# Short test
|
||||
make test_misc
|
||||
|
||||
# Full Build
|
||||
cd modules; make clean; make; cd ..
|
||||
make
|
||||
make dist
|
||||
|
||||
# Short test
|
||||
make test_misc
|
||||
|
||||
# Reset repo
|
||||
git checkout -- .
|
||||
```
|
||||
@ -374,8 +375,30 @@ The `xlsx.js` and `xlsx.mjs` files are constructed from the files in the `bits`
|
||||
subfolder. The build script (run `make`) will concatenate the individual bits
|
||||
to produce the scripts.
|
||||
|
||||
To produce the dist files, run `make dist`. The dist files are updated in each
|
||||
version release and *should not be committed between versions*.
|
||||
When changing the `.js` scripts in `bits`, the following sequence rebuilds the
|
||||
`xlsx.js` and `xlsx.mjs` scripts:
|
||||
|
||||
```bash
|
||||
make
|
||||
```
|
||||
|
||||
When changing the `.ts` scripts in `modules`, the following sequence rebuilds
|
||||
the `xlsx.js` and `xlsx.mjs` scripts:
|
||||
|
||||
```bash
|
||||
cd modules; make clean; make; cd ..
|
||||
```
|
||||
|
||||
To produce the dist files, run `make dist`.
|
||||
|
||||
:::info pass
|
||||
|
||||
The various `xlsx.*` scripts in the base folder and the files in the `dist`
|
||||
folder are updated on each version release.
|
||||
|
||||
**They should not be committed between versions!**
|
||||
|
||||
:::
|
||||
|
||||
## Tests
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user