Tài liệu API

@viet-qr/core

Tài liệu dành cho gói thư viện lõi (Vanilla JS / TypeScript).

generateVietQR(options)

Hàm chính để sinh ra chuỗi payload EMVCo.

parseVietQR(qrString)

Giải mã chuỗi VietQR thành một object có cấu trúc và kiểm tra tính toàn vẹn (mã CRC, định dạng).

Utility Functions

• getBankByBin(bin: string): Trả về thông tin ngân hàng dựa vào số BIN.
• getBankByCode(code: string): Trả về thông tin ngân hàng dựa vào mã ngân hàng (VD: VCB, TCB).
• getBankByName(name: string): Trả về thông tin ngân hàng dựa vào tên ngắn (VD: Vietcombank).
• sanitizeAccountName(name: string): Xoá dấu tiếng Việt và ký tự đặc biệt, tự động viết hoa.
• removeVietnameseAccents(str: string): Xoá dấu tiếng Việt khỏi chuỗi.
• fetchBankList(url: string): Cập nhật danh sách ngân hàng từ một API hoặc CDN bất kỳ.
• setBankList(banks: Bank[]): Tự động tiêm (inject) danh sách ngân hàng vào thư viện bộ nhớ.

fetchBankList nhận vào một mảng Bank[] JSON thuần, hoặc một object có mảng .data (đúng format API của vietqr.io). Dù theo cách nào, mỗi bản ghi ngân hàng phải dùng key dạng snake_case — full_name, swift_code — khớp với API vietqr.io; thư viện sẽ tự map sang camelCase (fullName, swiftCode) khi lưu vào bộ nhớ.

@viet-qr/react

Component bọc dành cho React để tạo mã QR.

import { VietQR, VietQRButton, useVietQR } from '@viet-qr/react';

export default function App() {
  return (
    <>
      <VietQR bankId="VCB" accountNo="112233" amount={50000} />
      <VietQRButton bankId="VCB" accountNo="112233" label="Thanh toán" />
    </>
  );
}

@viet-qr/vue

Component bọc dành cho Vue để tạo mã QR.

<script setup>
import { VietQR, VietQRButton, useVietQR } from '@viet-qr/vue';
import '@viet-qr/vue/style.css'; // Cho VietQRButton
</script>

<template>
  <VietQR bankId="VCB" accountNo="112233" :amount="50000" />
  <VietQRButton bankId="VCB" accountNo="112233" label="Thanh toán" />
</template>

@viet-qr/svelte

Component bọc dành cho Svelte để tạo mã QR.

<script>
  import { VietQR, VietQRButton, useVietQR } from '@viet-qr/svelte';
</script>

<VietQR bankId="VCB" accountNo="112233" amount={50000} />
<VietQRButton bankId="VCB" accountNo="112233" label="Thanh toán" />

@viet-qr/templates

Các giao diện mã QR được thiết kế sẵn cực đẹp.

Hỗ trợ React, Vue, Svelte, và Vanilla JS (Web Components). Tất cả template đều nhận bộ props giống hệt component <VietQR /> cơ bản.

// React
import { CompactCard, PayStandee } from '@viet-qr/templates/react';

// Vue
import { CompactCard, PayStandee } from '@viet-qr/templates/vue';

// Svelte
import { CompactCard, PayStandee } from '@viet-qr/templates/svelte';

<!-- Vanilla JS / HTML -->
<script src="https://unpkg.com/@viet-qr/templates/dist/elements/index.global.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@viet-qr/templates/dist/styles.css" />

<!-- Basic QR, no card wrapper -->
<viet-qr-basic bank-id="VCB" account-no="112233"></viet-qr-basic>

<!-- Pre-built templates -->
<viet-qr-compact bank-id="VCB" account-no="112233" theme="dark"></viet-qr-compact>
<viet-qr-standee bank-id="VCB" account-no="112233" is-card="true"></viet-qr-standee>

<!-- Button Modal Web Component -->
<viet-qr-button bank-id="VCB" account-no="112233" label="Thanh toán" theme="dark"></viet-qr-button>

Attribute của bản Vanilla dùng kebab-case (bank-id, account-no, is-card, ...). is-card nhận chuỗi "true"/"false", không phải kiểu chỉ cần có mặt là true.

Khác với @viet-qr/react/vue/svelte (đã build sẵn), phần Svelte của @viet-qr/templates xuất thẳng source thô (.svelte/.ts) trong src/svelte — build tool của bạn sẽ tự biên dịch. Dự án dùng Svelte 4 cần cấu hình Vite thêm (xem "Lưu ý cho Svelte 4" ở trang Docs).

Thuộc tính UI Components

React, Vue và Svelte dùng chung một bộ props cốt lõi. Một vài thuộc tính chỉ có ở một số framework — được ghi rõ bên dưới thay vì gộp chung cho gọn.

<VietQR />

Kế thừa toàn bộ field của `VietQROptions` ở trên (`bankId`, `accountNo`, `accountName`, `amount`, `content`, `isCard`), kèm thêm:

Các thuộc tính riêng theo từng framework (không phải nơi nào cũng có):

type ImageSettings = {
  src: string;          // Đường dẫn hoặc base64 của ảnh logo
  width: number;        // Chiều rộng của logo (pixel)
  height: number;       // Chiều cao của logo (pixel)
  x?: number;          // pixels
  y?: number;          // pixels
  crossOrigin?: 'anonymous' | 'use-credentials' | ''; // canvas export / CORS
  excavate?: boolean;   // Khoét mảng trắng phía sau logo để không đè lên pattern (mặc định: false)
};

CompactCard & PayStandee

Templates React/Vue/Svelte kế thừa các prop QR ở trên. Bản Vanilla dùng bộ attributes kebab-case gọn hơn trong hướng dẫn Vanilla. Templates bổ sung:

Tên ngân hàng hiển thị (khi không có bankLogo) được tự động tra ra từ bankId qua getBankByBin/getBankByCode — không cần truyền riêng.

<VietQRButton />

Kế thừa `VietQROptions` (`bankId`, `accountNo`, `accountName`, `amount`, `content`, `isCard`) — không kế thừa các prop riêng của `<VietQR />` ở trên — kèm thêm:

Callback mở/đóng modal dùng đúng idiom riêng của từng framework, không chung một tên prop: React — prop onOpen/onClose; Vue — emit @open/@close; Svelte — dispatched event on:open/on:close.

useVietQR

Lựa chọn thay thế mang tính phản ứng (reactive) cho <VietQR /> khi bạn muốn tự dựng UI riêng. Cùng một ý tưởng ở cả 3 framework, nhưng chữ ký hàm (signature) không giống hệt nhau — đọc kỹ ví dụ đúng framework bạn dùng.

React

Nhận vào một object `VietQROptions` thuần, trả về object thuần được memo hoá bằng `useMemo`.

import { useVietQR } from '@viet-qr/react';

function MyCustomQR() {
  const { payload, isValid, error } = useVietQR({
    bankId: 'VCB',
    accountNo: '112233',
    amount: 50000,
  });

  if (!isValid) return <p>{error}</p>;
  return <MyOwnQRRenderer value={payload} />;
}

Vue

Nhận vào object thuần *hoặc* `ComputedRef<VietQROptions>`; trả về `{ payload, isValid, error }`, mỗi field là một `ComputedRef`.

<script setup>
import { useVietQR } from '@viet-qr/vue';

const { payload, isValid, error } = useVietQR({
  bankId: 'VCB',
  accountNo: '112233',
  amount: 50000,
});
</script>

<template>
  <p v-if="!isValid">{{ error }}</p>
  <MyOwnQRRenderer v-else :value="payload" />
</template>

Svelte

Chữ ký khác biệt có chủ đích: nhận vào một Svelte Readable store, không phải object thuần — cần bọc options bằng writable() trước. Trả về một Readable mà bạn subscribe bằng ký hiệu $.

<script>
  import { writable } from 'svelte/store';
  import { useVietQR } from '@viet-qr/svelte';

  const options = writable({ bankId: 'VCB', accountNo: '112233', amount: 50000 });
  const qr = useVietQR(options);
</script>

{#if !$qr.isValid}
  <p>{$qr.error}</p>
{:else}
  <MyOwnQRRenderer value={$qr.payload} />
{/if}