k-qr-scanner 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +22 -1
- package/README.md +38 -10
- package/dist/chunks/chunk-PUUIGXID.js +149 -0
- package/dist/chunks/engine-EJ4OC3LZ.js +1 -0
- package/dist/cli.js +22 -9
- package/dist/element.d.ts +11 -1
- package/dist/emv.d.ts +89 -0
- package/dist/engine.d.ts +5 -0
- package/dist/index.cjs +24 -10
- package/dist/index.d.ts +2 -0
- package/dist/index.js +1 -2
- package/dist/kqrcode.engine.js +1 -1
- package/dist/kqrcode.global.js +24 -10
- package/dist/kqrcode.jsqr.js +0 -1
- package/dist/react-native.d.ts +4 -0
- package/dist/react.cjs +1 -2
- package/dist/react.d.ts +2 -0
- package/dist/react.js +1 -2
- package/dist/rn/index.js +5 -6
- package/dist/rn/runtime.js +1 -1
- package/dist/scan-qr.d.ts +2 -0
- package/dist/sr.cjs +0 -1
- package/dist/sr.js +1 -2
- package/dist/svelte.cjs +1 -2
- package/dist/svelte.d.ts +2 -0
- package/dist/svelte.js +1 -2
- package/dist/vue.cjs +1 -2
- package/dist/vue.d.ts +2 -0
- package/dist/vue.js +1 -2
- package/llms.txt +15 -8
- package/package.json +2 -3
- package/dist/chunks/chunk-E66QYIQI.js +0 -135
- package/dist/chunks/chunk-E66QYIQI.js.map +0 -6
- package/dist/chunks/chunk-HCGRA6GM.js +0 -2
- package/dist/chunks/chunk-HCGRA6GM.js.map +0 -6
- package/dist/chunks/decoder-jsqr-54X2IQSI.js +0 -2
- package/dist/chunks/decoder-jsqr-54X2IQSI.js.map +0 -6
- package/dist/chunks/engine-QWSAAVKN.js +0 -2
- package/dist/chunks/engine-QWSAAVKN.js.map +0 -6
- package/dist/chunks/worker-source.generated-24WX42PC.js +0 -2
- package/dist/chunks/worker-source.generated-24WX42PC.js.map +0 -6
- package/dist/cli.d.ts +0 -17
- package/dist/decoder-jsqr.d.ts +0 -3
- package/dist/decoder-zxing.d.ts +0 -3
- package/dist/engine-host.d.ts +0 -48
- package/dist/engine.cjs +0 -1
- package/dist/index.cjs.map +0 -6
- package/dist/index.js.map +0 -6
- package/dist/jsqr.cjs +0 -2
- package/dist/jsqr.cjs.map +0 -6
- package/dist/kqrcode.global.js.map +0 -6
- package/dist/kqrcode.jsqr.js.map +0 -6
- package/dist/react.cjs.map +0 -6
- package/dist/react.js.map +0 -6
- package/dist/rn/index.js.map +0 -6
- package/dist/rn-bridge.d.ts +0 -103
- package/dist/rn-runtime.generated.d.ts +0 -2
- package/dist/sr-model.generated.d.ts +0 -4
- package/dist/sr.cjs.map +0 -6
- package/dist/sr.js.map +0 -6
- package/dist/svelte.cjs.map +0 -6
- package/dist/svelte.js.map +0 -6
- package/dist/vue.cjs.map +0 -6
- package/dist/vue.js.map +0 -6
- package/dist/worker-source.generated.d.ts +0 -2
- package/dist/worker.d.ts +0 -1
- package/docs/API.md +0 -292
- package/docs/BENCHMARK.md +0 -101
- package/docs/CUSTOMIZE.md +0 -150
- package/docs/FRAMEWORKS.md +0 -241
- package/docs/REACT_NATIVE.md +0 -181
- package/docs/TESTING.md +0 -90
package/docs/FRAMEWORKS.md
DELETED
|
@@ -1,241 +0,0 @@
|
|
|
1
|
-
# Frameworks
|
|
2
|
-
|
|
3
|
-
The quickest start in any project is:
|
|
4
|
-
|
|
5
|
-
```bash
|
|
6
|
-
npx k-qr-scanner init
|
|
7
|
-
```
|
|
8
|
-
|
|
9
|
-
It detects the framework and writes a component like the ones below.
|
|
10
|
-
|
|
11
|
-
The scanner is a standard custom element, `<kqr-scanner>`, so it works anywhere the DOM does. React, Vue and Svelte get small wrappers on top of it, and React Native gets its own component. Every entry point can be imported during server-side rendering: the element only activates in the browser.
|
|
12
|
-
|
|
13
|
-
- [React](#react)
|
|
14
|
-
- [Next.js](#nextjs)
|
|
15
|
-
- [Vue](#vue)
|
|
16
|
-
- [Nuxt](#nuxt)
|
|
17
|
-
- [Svelte and SvelteKit](#svelte-and-sveltekit)
|
|
18
|
-
- [Angular](#angular)
|
|
19
|
-
- [React Native and Expo](#react-native-and-expo)
|
|
20
|
-
- [Plain HTML](#plain-html)
|
|
21
|
-
- [Content-Security-Policy](#content-security-policy)
|
|
22
|
-
|
|
23
|
-
## Names across frameworks
|
|
24
|
-
|
|
25
|
-
Attributes become camelCase props in the wrappers:
|
|
26
|
-
|
|
27
|
-
| `<kqr-scanner>` attribute | React / Vue / Svelte | default |
|
|
28
|
-
| :--- | :--- | :--- |
|
|
29
|
-
| `theme` | `theme` | `wechat` |
|
|
30
|
-
| `locale` | `locale` | browser language |
|
|
31
|
-
| `heading` | `heading` | – |
|
|
32
|
-
| `facing` | `facing` | `environment` |
|
|
33
|
-
| `continuous` | `continuous` | off: stop after the first code |
|
|
34
|
-
| `inline` | `inline` | off: full screen |
|
|
35
|
-
| `success`, `torch` | `success`, `torch` | `dot`, `auto` |
|
|
36
|
-
| `zoom-control` | `zoomControl` | `none` |
|
|
37
|
-
| `max-zoom` | `maxZoom` | `8` |
|
|
38
|
-
| `super-resolution` | `superResolution` | `js` |
|
|
39
|
-
| `formats` | `formats` (an array) | all |
|
|
40
|
-
| `no-auto-zoom`, `no-gallery`, `no-torch`, `no-beep`, `no-vibrate`, `no-close` | `noAutoZoom`, `noGallery`, `noTorch`, `noBeep`, `noVibrate`, `noClose` | off |
|
|
41
|
-
| property `accept` | `accept` | – |
|
|
42
|
-
| property `labels` | `labels` | – |
|
|
43
|
-
|
|
44
|
-
| element event | React / Svelte | Vue |
|
|
45
|
-
| :--- | :--- | :--- |
|
|
46
|
-
| `scan` | `onScan(result)` | `@scan` |
|
|
47
|
-
| `reject` | `onReject(result, message?)` | `@reject` |
|
|
48
|
-
| `error` | `onError(error)` | `@error` |
|
|
49
|
-
| `close` | `onClose()` | `@close` |
|
|
50
|
-
| `ready` | `onReady()` | `@ready` |
|
|
51
|
-
|
|
52
|
-
Svelte has no `noClose`; use the `<kqr-scanner>` tag with `no-close` instead. Every option is described in [API.md](API.md).
|
|
53
|
-
|
|
54
|
-
## React
|
|
55
|
-
|
|
56
|
-
```tsx
|
|
57
|
-
import { useState } from 'react';
|
|
58
|
-
import { QRScanner } from 'k-qr-scanner/react';
|
|
59
|
-
|
|
60
|
-
export function PayButton() {
|
|
61
|
-
const [open, setOpen] = useState(false);
|
|
62
|
-
return (
|
|
63
|
-
<>
|
|
64
|
-
<button onClick={() => setOpen(true)}>Scan to pay</button>
|
|
65
|
-
{open && (
|
|
66
|
-
<QRScanner
|
|
67
|
-
locale="lo"
|
|
68
|
-
style={{ '--kqr-accent': '#e60012' }}
|
|
69
|
-
onScan={(r) => { setOpen(false); pay(r.text); }}
|
|
70
|
-
onClose={() => setOpen(false)}
|
|
71
|
-
onError={(e) => console.warn(e.code)}
|
|
72
|
-
>
|
|
73
|
-
<button slot="actions-left" onClick={showMyCode}>My QR code</button>
|
|
74
|
-
</QRScanner>
|
|
75
|
-
)}
|
|
76
|
-
</>
|
|
77
|
-
);
|
|
78
|
-
}
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
Mount the component to open the scanner and unmount it to close. Children with `slot="…"` go into the scanner UI ([slots](CUSTOMIZE.md#slots)). Callbacks always see your latest props, so they can use the current state.
|
|
82
|
-
|
|
83
|
-
## Next.js
|
|
84
|
-
|
|
85
|
-
The React wrapper ships with `'use client'`, so you can use it straight from a server component file. To download the engine only on the page that scans, load it lazily:
|
|
86
|
-
|
|
87
|
-
```tsx
|
|
88
|
-
// app/scan/page.tsx
|
|
89
|
-
import dynamic from 'next/dynamic';
|
|
90
|
-
|
|
91
|
-
const QRScanner = dynamic(() => import('k-qr-scanner/react').then((m) => m.QRScanner), { ssr: false });
|
|
92
|
-
|
|
93
|
-
export default function Page() {
|
|
94
|
-
return <QRScanner locale="lo" onScan={(r) => console.log(r.text)} />;
|
|
95
|
-
}
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
## Vue
|
|
99
|
-
|
|
100
|
-
```vue
|
|
101
|
-
<script setup lang="ts">
|
|
102
|
-
import { ref } from 'vue';
|
|
103
|
-
import { QRScanner } from 'k-qr-scanner/vue';
|
|
104
|
-
import type { ScanResult } from 'k-qr-scanner';
|
|
105
|
-
|
|
106
|
-
const open = ref(false);
|
|
107
|
-
function onScan(r: ScanResult) {
|
|
108
|
-
open.value = false;
|
|
109
|
-
pay(r.text);
|
|
110
|
-
}
|
|
111
|
-
</script>
|
|
112
|
-
|
|
113
|
-
<template>
|
|
114
|
-
<button @click="open = true">Scan</button>
|
|
115
|
-
<QRScanner v-if="open" theme="alipay" locale="zh" @scan="onScan" @close="open = false">
|
|
116
|
-
<nav slot="footer"><b>扫码</b><span>识物</span><span>AR</span></nav>
|
|
117
|
-
</QRScanner>
|
|
118
|
-
</template>
|
|
119
|
-
```
|
|
120
|
-
|
|
121
|
-
If you use the raw `<kqr-scanner>` tag in Vue templates instead of the wrapper, tell Vue it is a custom element:
|
|
122
|
-
|
|
123
|
-
```ts
|
|
124
|
-
// vite.config.ts
|
|
125
|
-
vue({ template: { compilerOptions: { isCustomElement: (tag) => tag === 'kqr-scanner' } } });
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
## Nuxt
|
|
129
|
-
|
|
130
|
-
Render the scanner on the client only, with `<ClientOnly>` or a `*.client.vue` component:
|
|
131
|
-
|
|
132
|
-
```vue
|
|
133
|
-
<!-- pages/scan.vue -->
|
|
134
|
-
<script setup lang="ts">
|
|
135
|
-
import { QRScanner } from 'k-qr-scanner/vue';
|
|
136
|
-
</script>
|
|
137
|
-
|
|
138
|
-
<template>
|
|
139
|
-
<ClientOnly>
|
|
140
|
-
<QRScanner locale="lo" @scan="(r) => navigateTo(`/pay?qr=${encodeURIComponent(r.text)}`)" />
|
|
141
|
-
</ClientOnly>
|
|
142
|
-
</template>
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
## Svelte and SvelteKit
|
|
146
|
-
|
|
147
|
-
The Svelte entry is an action. Actions only run in the browser, so it is safe in SvelteKit without `browser` checks.
|
|
148
|
-
|
|
149
|
-
```svelte
|
|
150
|
-
<script lang="ts">
|
|
151
|
-
import { qrScanner } from 'k-qr-scanner/svelte';
|
|
152
|
-
let open = $state(false);
|
|
153
|
-
</script>
|
|
154
|
-
|
|
155
|
-
<button onclick={() => (open = true)}>Scan</button>
|
|
156
|
-
|
|
157
|
-
{#if open}
|
|
158
|
-
<div use:qrScanner={{ locale: 'lo', onScan: (r) => { open = false; pay(r.text); }, onClose: () => (open = false) }}>
|
|
159
|
-
<button data-slot="actions-left">My QR code</button>
|
|
160
|
-
</div>
|
|
161
|
-
{/if}
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
Svelte 5 only allows `slot="…"` inside custom elements, so children of the action use `data-slot="…"`. You can also use the element directly, where `slot` works and events are `on…` attributes:
|
|
165
|
-
|
|
166
|
-
```svelte
|
|
167
|
-
<script>
|
|
168
|
-
import 'k-qr-scanner';
|
|
169
|
-
</script>
|
|
170
|
-
|
|
171
|
-
<kqr-scanner theme="alipay" locale="lo" onscan={(e) => pay(e.detail.text)}>
|
|
172
|
-
<button slot="actions-left">My QR code</button>
|
|
173
|
-
</kqr-scanner>
|
|
174
|
-
```
|
|
175
|
-
|
|
176
|
-
## Angular
|
|
177
|
-
|
|
178
|
-
Import the package once to register the element, and allow custom elements in the component:
|
|
179
|
-
|
|
180
|
-
```ts
|
|
181
|
-
import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
|
|
182
|
-
import 'k-qr-scanner';
|
|
183
|
-
import type { ScanResult } from 'k-qr-scanner';
|
|
184
|
-
|
|
185
|
-
@Component({
|
|
186
|
-
selector: 'app-scan',
|
|
187
|
-
standalone: true,
|
|
188
|
-
schemas: [CUSTOM_ELEMENTS_SCHEMA],
|
|
189
|
-
template: `
|
|
190
|
-
<button (click)="open = true">Scan</button>
|
|
191
|
-
@if (open) {
|
|
192
|
-
<kqr-scanner locale="lo" (scan)="onScan($any($event).detail)" (close)="open = false"></kqr-scanner>
|
|
193
|
-
}
|
|
194
|
-
`,
|
|
195
|
-
})
|
|
196
|
-
export class ScanComponent {
|
|
197
|
-
open = false;
|
|
198
|
-
onScan(r: ScanResult) {
|
|
199
|
-
this.open = false;
|
|
200
|
-
console.log(r.text);
|
|
201
|
-
}
|
|
202
|
-
}
|
|
203
|
-
```
|
|
204
|
-
|
|
205
|
-
The import is safe with Angular SSR; the element only activates in the browser. To set `accept` or `labels`, get the element with a template reference and `ViewChild`, then assign the property.
|
|
206
|
-
|
|
207
|
-
## React Native and Expo
|
|
208
|
-
|
|
209
|
-
```tsx
|
|
210
|
-
import { QRScanner } from 'k-qr-scanner/react-native';
|
|
211
|
-
|
|
212
|
-
<QRScanner style={{ flex: 1 }} locale="lo" onScan={(r) => pay(r.text)} onClose={() => setOpen(false)} />
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
It needs `react-native-webview` and the camera permissions; `npx k-qr-scanner init` sets up both. Everything else is in [REACT_NATIVE.md](REACT_NATIVE.md).
|
|
216
|
-
|
|
217
|
-
## Plain HTML
|
|
218
|
-
|
|
219
|
-
```html
|
|
220
|
-
<script src="https://cdn.jsdelivr.net/npm/k-qr-scanner/dist/kqrcode.global.js"></script>
|
|
221
|
-
|
|
222
|
-
<button id="scan">Scan</button>
|
|
223
|
-
<script>
|
|
224
|
-
document.getElementById('scan').onclick = async () => {
|
|
225
|
-
const { text } = await KQRCode.scanQR({ locale: 'lo' });
|
|
226
|
-
alert(text);
|
|
227
|
-
};
|
|
228
|
-
</script>
|
|
229
|
-
```
|
|
230
|
-
|
|
231
|
-
The script build (17 kB gzip) defines the global `KQRCode` and registers `<kqr-scanner>`. It loads the engine from `kqrcode.engine.js` in the same directory when the scanner first opens. Pin a version in production, e.g. `k-qr-scanner@0.2.0`, or self-host `kqrcode.global.js`, `kqrcode.engine.js` and `kqrcode.jsqr.js` together.
|
|
232
|
-
|
|
233
|
-
## Content-Security-Policy
|
|
234
|
-
|
|
235
|
-
The engine runs WebAssembly in a worker created from a `blob:` URL, so a CSP needs:
|
|
236
|
-
|
|
237
|
-
```
|
|
238
|
-
worker-src blob:; script-src 'self' 'wasm-unsafe-eval'
|
|
239
|
-
```
|
|
240
|
-
|
|
241
|
-
With `superResolution: 'webgpu'`, also allow the ONNX Runtime CDN in `script-src` and `connect-src`, or self-host it and set `onnx-runtime-url`. If workers or WebAssembly are blocked, the scanner falls back to jsQR on the main thread: it still works, but slower, without super-resolution, and for regular QR codes only. `npx k-qr-scanner doctor` finds a CSP in your HTML and checks it.
|
package/docs/REACT_NATIVE.md
DELETED
|
@@ -1,181 +0,0 @@
|
|
|
1
|
-
# React Native
|
|
2
|
-
|
|
3
|
-
`k-qr-scanner/react-native` brings the same scanner to iOS and Android apps, Expo included: the themes, auto-zoom, Micro QR and rMQR, the `accept` callback and album import.
|
|
4
|
-
|
|
5
|
-
- [Setup](#setup)
|
|
6
|
-
- [Usage](#usage)
|
|
7
|
-
- [Props](#props)
|
|
8
|
-
- [Ref methods](#ref-methods)
|
|
9
|
-
- [What the component handles for you](#what-the-component-handles-for-you)
|
|
10
|
-
- [Platform notes](#platform-notes)
|
|
11
|
-
- [Troubleshooting](#troubleshooting)
|
|
12
|
-
|
|
13
|
-
## How it works
|
|
14
|
-
|
|
15
|
-
React Native has no DOM and no camera API in JavaScript, and Hermes cannot run WebAssembly. So the component renders a [`react-native-webview`](https://github.com/react-native-webview/react-native-webview) and runs the regular web scanner inside it. Events and the `accept` callback cross between the WebView and your app automatically.
|
|
16
|
-
|
|
17
|
-
The engine is bundled with the component, about 0.8 MB (0.5 MB gzip). The scanner works offline, and there are no assets to configure.
|
|
18
|
-
|
|
19
|
-
## Setup
|
|
20
|
-
|
|
21
|
-
```bash
|
|
22
|
-
npx k-qr-scanner init
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
In a React Native or Expo project, this one command:
|
|
26
|
-
|
|
27
|
-
1. installs `k-qr-scanner` and `react-native-webview` (on Expo through `npx expo install`, so the WebView matches your SDK);
|
|
28
|
-
2. adds the camera permissions (see below);
|
|
29
|
-
3. writes a starter component, `components/QrScanner`.
|
|
30
|
-
|
|
31
|
-
Then:
|
|
32
|
-
|
|
33
|
-
- **bare React Native**: run `cd ios && pod install` and rebuild the app;
|
|
34
|
-
- **Expo Go**: nothing to do, it already includes the WebView and the camera permission;
|
|
35
|
-
- **Expo development or EAS builds**: the next `npx expo prebuild` or EAS build applies the permissions.
|
|
36
|
-
|
|
37
|
-
### Camera permissions
|
|
38
|
-
|
|
39
|
-
| project | what `init` adds |
|
|
40
|
-
| :--- | :--- |
|
|
41
|
-
| Expo | `"plugins": ["k-qr-scanner"]` in `app.json`. The plugin writes both entries during prebuild. |
|
|
42
|
-
| bare iOS | `NSCameraUsageDescription` in `ios/<App>/Info.plist` |
|
|
43
|
-
| bare Android | `<uses-permission android:name="android.permission.CAMERA" />` in `android/app/src/main/AndroidManifest.xml` |
|
|
44
|
-
|
|
45
|
-
> [!IMPORTANT]
|
|
46
|
-
> Without `NSCameraUsageDescription`, iOS ends the app the moment the camera opens.
|
|
47
|
-
|
|
48
|
-
To set your own iOS permission text with Expo:
|
|
49
|
-
|
|
50
|
-
```json
|
|
51
|
-
{ "expo": { "plugins": [["k-qr-scanner", { "cameraPermission": "Scan QR codes to pay" }]] } }
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
You don't need to write any permission code. On Android the component asks for the camera before it opens the scanner; on iOS the system asks once when the camera starts.
|
|
55
|
-
|
|
56
|
-
`npx k-qr-scanner doctor` checks that the WebView is installed and that both permissions are in place.
|
|
57
|
-
|
|
58
|
-
### Setting up by hand
|
|
59
|
-
|
|
60
|
-
```bash
|
|
61
|
-
npm install k-qr-scanner react-native-webview
|
|
62
|
-
cd ios && pod install
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
Then add the two permission entries from the table above.
|
|
66
|
-
|
|
67
|
-
## Usage
|
|
68
|
-
|
|
69
|
-
```tsx
|
|
70
|
-
import { useRef, useState } from 'react';
|
|
71
|
-
import { Button, Modal } from 'react-native';
|
|
72
|
-
import { QRScanner, type QRScannerHandle } from 'k-qr-scanner/react-native';
|
|
73
|
-
|
|
74
|
-
export function PayScreen() {
|
|
75
|
-
const [open, setOpen] = useState(false);
|
|
76
|
-
const scanner = useRef<QRScannerHandle>(null);
|
|
77
|
-
|
|
78
|
-
return (
|
|
79
|
-
<>
|
|
80
|
-
<Button title="Scan to pay" onPress={() => setOpen(true)} />
|
|
81
|
-
<Modal visible={open} animationType="slide" presentationStyle="fullScreen" onRequestClose={() => setOpen(false)}>
|
|
82
|
-
<QRScanner
|
|
83
|
-
ref={scanner}
|
|
84
|
-
style={{ flex: 1 }}
|
|
85
|
-
theme="wechat"
|
|
86
|
-
locale="lo"
|
|
87
|
-
heading="ສະແກນເພື່ອຈ່າຍ"
|
|
88
|
-
cssVars={{ '--kqr-accent': '#e60012' }}
|
|
89
|
-
accept={async (r) => r.text.startsWith('000201') || 'ນີ້ບໍ່ແມ່ນ QR ຈ່າຍເງິນ'}
|
|
90
|
-
onScan={(r) => { setOpen(false); pay(r.text); }}
|
|
91
|
-
onClose={() => setOpen(false)}
|
|
92
|
-
onError={(e) => console.warn(e.code)}
|
|
93
|
-
slots={{ 'actions-left': '<button data-kqr-id="my-code">My QR code</button>' }}
|
|
94
|
-
onSlotPress={(slot, id) => { if (id === 'my-code') showMyCode(); }}
|
|
95
|
-
/>
|
|
96
|
-
</Modal>
|
|
97
|
-
</>
|
|
98
|
-
);
|
|
99
|
-
}
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
Mount the component to open the scanner and unmount it to close.
|
|
103
|
-
|
|
104
|
-
## Props
|
|
105
|
-
|
|
106
|
-
These work exactly as on the web (see [API.md](API.md#scanqr)): `theme`, `locale`, `heading`, `labels`, `facing`, `continuous`, `success`, `torch`, `zoomControl`, `maxZoom`, `superResolution`, `formats`, `accept`, `noAutoZoom`, `noGallery`, `noTorch`, `noBeep`, `noVibrate` and `noClose`.
|
|
107
|
-
|
|
108
|
-
Callbacks:
|
|
109
|
-
|
|
110
|
-
| prop | called with | when |
|
|
111
|
-
| :--- | :--- | :--- |
|
|
112
|
-
| `onScan` | `ScanResult` | a code was read and accepted; `result.bytes` is a `Uint8Array` |
|
|
113
|
-
| `onReject` | `ScanResult`, `message?` | `accept` turned a code down |
|
|
114
|
-
| `onError` | `ScanError` | the camera could not start, e.g. `permission-denied` |
|
|
115
|
-
| `onClose` | – | the user pressed ✕ |
|
|
116
|
-
| `onReady` | – | the camera is running |
|
|
117
|
-
| `onSlotPress` | `slot`, `id?` | something inside `slots` was tapped; `id` is the `data-kqr-id` of the tapped element |
|
|
118
|
-
|
|
119
|
-
Only for React Native:
|
|
120
|
-
|
|
121
|
-
| prop | type | description |
|
|
122
|
-
| :--- | :--- | :--- |
|
|
123
|
-
| `keepCamera` | `boolean` | keep the camera on after a result; call `resume()` to scan again |
|
|
124
|
-
| `cssVars` | `Record<string, string>` | [CSS variables](CUSTOMIZE.md#css-variables) for the scanner UI |
|
|
125
|
-
| `slots` | `Record<string, string>` | extra UI as **HTML strings** by [slot name](CUSTOMIZE.md#slots); React Native views can't be placed inside a WebView |
|
|
126
|
-
| `scriptUrl` | `string` | load the scanner from a URL instead of the bundled copy |
|
|
127
|
-
| `style` | `StyleProp<ViewStyle>` | style of the scanner view; default `{ flex: 1, backgroundColor: '#000' }` |
|
|
128
|
-
| `webViewProps` | `WebViewProps` | extra props for `react-native-webview` |
|
|
129
|
-
|
|
130
|
-
Changing a callback is free. Changing any other prop reloads the scanner and restarts the camera, so keep them stable while the scanner is open.
|
|
131
|
-
|
|
132
|
-
## Ref methods
|
|
133
|
-
|
|
134
|
-
| method | description |
|
|
135
|
-
| :--- | :--- |
|
|
136
|
-
| `resume()` | scan again after a result; reopens the camera if it was stopped |
|
|
137
|
-
| `start()` / `stop()` | open or release the camera |
|
|
138
|
-
| `close()` | stop the camera and fire `onClose` |
|
|
139
|
-
| `toggleTorch(on?)` | switch the flashlight |
|
|
140
|
-
| `pickImage()` | open the photo picker |
|
|
141
|
-
|
|
142
|
-
## What the component handles for you
|
|
143
|
-
|
|
144
|
-
The defaults are tuned for scanning, so most apps never need `webViewProps`:
|
|
145
|
-
|
|
146
|
-
- **Permissions.** On Android it requests the camera permission before showing the scanner. On iOS it skips the second, web-level prompt, so the user is asked only once.
|
|
147
|
-
- **Camera quality.** The stream starts at 1080p and goes up to 4K where the phone has no hardware zoom. Continuous autofocus, tap to focus, and hardware zoom and flashlight wherever the WebView offers them.
|
|
148
|
-
- **Background.** While the app is in the background, the camera is released, so the camera indicator turns off and other apps can use the camera. It reopens when the app returns, unless a result is showing; then `resume()` reopens it.
|
|
149
|
-
- **Recovery.** If the system kills the WebView process to free memory, the scanner reloads instead of leaving a black screen.
|
|
150
|
-
- **A native feel.** Full screen, laid out around the notch, with no scrolling, bouncing, zoom gestures, link previews or text selection.
|
|
151
|
-
- **Debugging.** In development builds, inspect the scanner page with Safari (iOS) or `chrome://inspect` (Android).
|
|
152
|
-
|
|
153
|
-
## Loading the scanner from a URL
|
|
154
|
-
|
|
155
|
-
```tsx
|
|
156
|
-
<QRScanner scriptUrl="https://cdn.jsdelivr.net/npm/k-qr-scanner@0.2.0/dist/kqrcode.global.js" />
|
|
157
|
-
```
|
|
158
|
-
|
|
159
|
-
This loads that version instead of the bundled one, which is useful to try a fix without an app update. `kqrcode.engine.js` must be in the same directory (it is on jsDelivr and unpkg), the phone needs network access, and the bundled copy stays in your app either way. Always pin a version.
|
|
160
|
-
|
|
161
|
-
## Platform notes
|
|
162
|
-
|
|
163
|
-
| platform | notes |
|
|
164
|
-
| :--- | :--- |
|
|
165
|
-
| iOS 14.5+ | WKWebView has no camera zoom API, so zoom is digital, on a 4K stream as in Safari |
|
|
166
|
-
| Android 7+ | needs an up-to-date Android System WebView; hardware zoom and the flashlight work where the device offers them |
|
|
167
|
-
| Expo Go | works as is |
|
|
168
|
-
|
|
169
|
-
- The scanner page has the address `https://kqrcode.local/`. A secure (`https`) address is what allows the camera; nothing is ever loaded from it.
|
|
170
|
-
- `superResolution="webgpu"` downloads ONNX Runtime Web from a CDN. The default, `'js'`, works offline.
|
|
171
|
-
- With iOS Lockdown Mode, WebAssembly is turned off. The scanner then falls back to jsQR, which reads regular QR codes only.
|
|
172
|
-
|
|
173
|
-
## Troubleshooting
|
|
174
|
-
|
|
175
|
-
| problem | fix |
|
|
176
|
-
| :--- | :--- |
|
|
177
|
-
| the iOS app closes when the scanner opens | `NSCameraUsageDescription` is missing: run `npx k-qr-scanner init --no-install`, or add `"plugins": ["k-qr-scanner"]` on Expo, then rebuild |
|
|
178
|
-
| `onError` with `permission-denied` | the user said no. On Android the system won't ask again after a second "no", so link to the app settings with `Linking.openSettings()` |
|
|
179
|
-
| "Unable to resolve module react-native-webview" | install it (`npx expo install react-native-webview` on Expo), then rebuild or restart Metro |
|
|
180
|
-
| a black screen and nothing happens | check `onError`, and look at the page in Safari or `chrome://inspect` in a development build |
|
|
181
|
-
| Expo: the permission doesn't apply | the plugin runs during prebuild, so run `npx expo prebuild` or a new EAS build after adding it |
|
package/docs/TESTING.md
DELETED
|
@@ -1,90 +0,0 @@
|
|
|
1
|
-
# Testing
|
|
2
|
-
|
|
3
|
-
k-qr-scanner is tested in four layers. CI runs the first on every push and pull request; run the others before a release.
|
|
4
|
-
|
|
5
|
-
| layer | what it proves | runs |
|
|
6
|
-
| :--- | :--- | :--- |
|
|
7
|
-
| [1. Unit tests](#1-unit-tests) | the engine, auto-zoom, the CLI, SSR and the React Native bridge work | in CI, ~30 s |
|
|
8
|
-
| [2. Browser end-to-end](#2-browser-end-to-end) | the real UI scans from a camera in Chrome | locally |
|
|
9
|
-
| [3. Framework apps](#3-framework-apps) | production builds of real apps scan end to end | before a release |
|
|
10
|
-
| [4. Cross-browser and devices](#4-cross-browser-and-devices) | Firefox, WebKit and real phones | before a release |
|
|
11
|
-
|
|
12
|
-
## 1. Unit tests
|
|
13
|
-
|
|
14
|
-
```bash
|
|
15
|
-
npm ci
|
|
16
|
-
npm run build # some tests use the built package
|
|
17
|
-
npm test
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
The 70 tests cover:
|
|
21
|
-
|
|
22
|
-
- **decoding**: rotation, blur, perspective, far and inverted codes, the native-resolution region path, and Micro QR and rMQR;
|
|
23
|
-
- **`formats` and module-size estimates** for every QR-family symbol;
|
|
24
|
-
- **auto-zoom** decisions;
|
|
25
|
-
- **super-resolution**: the JS kernel and the ONNX model, compared with reference output from OpenCV;
|
|
26
|
-
- **SSR**: importing and rendering the React and Vue wrappers on the server;
|
|
27
|
-
- **React Native**: the page builder and its escaping, the message bridge, `accept` round trips, the Android permission order, background handling, recovery after a WebView crash, and the Expo config plugin;
|
|
28
|
-
- **the CLI**: framework detection, generated components, React Native permission edits (once only, and nothing with `--dry-run`), and `doctor`.
|
|
29
|
-
|
|
30
|
-
## 2. Browser end-to-end
|
|
31
|
-
|
|
32
|
-
```bash
|
|
33
|
-
npx tsx scripts/e2e.mts # headless QRScanner reads a far code from the fake camera
|
|
34
|
-
npx tsx scripts/e2e.mts --ios # the same with Safari's limits: no zoom API, no OffscreenCanvas, no BarcodeDetector
|
|
35
|
-
npx tsx scripts/e2e.mts --micro # a Micro QR code instead of a regular one
|
|
36
|
-
npx tsx scripts/e2e.mts --el # the <kqr-scanner> element
|
|
37
|
-
npx tsx scripts/e2e.mts --scanqr # scanQR() resolves and removes itself
|
|
38
|
-
npx tsx scripts/e2e.mts --global # the <script> build (KQRCode global, engine loaded next to it)
|
|
39
|
-
npx tsx scripts/e2e.mts --csp # a strict CSP that blocks workers: the jsQR fallback
|
|
40
|
-
npx tsx scripts/e2e.mts --accept # accept turns the first code down with a message, then accepts it
|
|
41
|
-
npx tsx scripts/e2e.mts --rn # the React Native page at https://kqrcode.local with a stand-in bridge
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
Flags can be combined. Chrome gets a fake camera that plays a QR code video. The React Native run checks the full message flow (`ready` → `accept` → `reject` → `accept` → `scan`), that the page is a secure context, and that the camera is released in the background and reopened afterwards.
|
|
45
|
-
|
|
46
|
-
Chrome is used from its installed channel; set `CHROME_PATH` to use another binary.
|
|
47
|
-
|
|
48
|
-
## 3. Framework apps
|
|
49
|
-
|
|
50
|
-
Five small apps install the packed tarball, build for production and are then scanned in Chrome with a fake camera: React with Vite, Next.js, Nuxt, SvelteKit and Angular.
|
|
51
|
-
|
|
52
|
-
```bash
|
|
53
|
-
npm pack --pack-destination ../kqr-apps
|
|
54
|
-
node scripts/make-apps.mjs ../kqr-apps
|
|
55
|
-
# in each app: npm install && npm run build
|
|
56
|
-
npx tsx scripts/themes.mts # creates the fake-camera videos
|
|
57
|
-
npx tsx scripts/apps-e2e.mts ../kqr-apps
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
Each app must render its server HTML (for the SSR frameworks), scan the code, show the slotted content and log no console errors.
|
|
61
|
-
|
|
62
|
-
## 4. Cross-browser and devices
|
|
63
|
-
|
|
64
|
-
```bash
|
|
65
|
-
node node_modules/playwright-core/cli.js install firefox webkit
|
|
66
|
-
npx tsx scripts/xbrowser.mts # or: npx tsx scripts/xbrowser.mts firefox
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
The camera is simulated with `canvas.captureStream()` showing moving, rotating codes. For each browser the script measures the first and warm scan times, then checks photo decoding, `scanQR`, a 20-second continuous run (frame rate, wrong reads, memory) and 20 start/stop cycles, which must leave **no workers and no camera tracks** behind. Playwright's WebKit for Windows has no camera API, so on Windows only photo decoding and the "unsupported" screen are checked there.
|
|
70
|
-
|
|
71
|
-
Emulation can't cover camera hardware, so check real devices before a release:
|
|
72
|
-
|
|
73
|
-
| device | check |
|
|
74
|
-
| :--- | :--- |
|
|
75
|
-
| iPhone, Safari | opens; digital zoom reads a far code; flashlight (where available); album; rotating the phone |
|
|
76
|
-
| Android, Chrome | hardware auto-zoom on a far code; flashlight; tap to focus |
|
|
77
|
-
| Android, Samsung Internet | the same |
|
|
78
|
-
| desktop Chrome, Firefox and Safari with a webcam | opens; reads a code shown on a phone |
|
|
79
|
-
| React Native app on iOS and Android | the permission prompt; scanning; background and return; album |
|
|
80
|
-
|
|
81
|
-
Serve `demo/index.html` over HTTPS (for example `npx serve` behind a tunnel) and report results as issues, with the device, OS and browser version.
|
|
82
|
-
|
|
83
|
-
## Benchmarks
|
|
84
|
-
|
|
85
|
-
```bash
|
|
86
|
-
npm run bench # accuracy and CPU latency → bench/results.md, then updates the README table
|
|
87
|
-
npx tsx bench/browser.mts # super-resolution speed in Chrome (JS, WebAssembly, WebGPU)
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
The WeChat column needs Python with `opencv-contrib-python-headless<5` and the original model files (see `scripts/convert-sr.py`). Point `KQR_PY` at that Python; without it, the column is skipped. The method is described in [BENCHMARK.md](BENCHMARK.md).
|