QR Code (QR コード) コンポーネント New

Ignite UI for Web Components QR Code は、スキャン可能な QR (Quick Response) コードをインライン SVG としてレンダリングします。コードは任意の文字列値からクライアント側で生成され、サイズ、誤り訂正、中央ロゴをカスタマイズできます。

ライブ デモ

Web Components QR Code のデモは、URL 文字列からコードをレンダリングし、モジュールの形状、サイズ、中央ロゴを切り替えることができます。

構造

Web Components QR Code は、3 つの位置検出パターンのコーナー、エンコードされたデータ モジュール、クワイエット ゾーンの余白、およびオプションの中央ロゴで構成される正方形の SVG グラフィックです。

<igc-qr-code>
└── svg[role="img"]
    ├── <title>                          // "QR code: <value>" or the aria-label value
    ├── ::part(background)               // background rect
    ├── <mask>                           // rendered when logo-src is set
    ├── <g>                              // masked when logo-src is set
    │   ├── ::part(dots)                 // data modules path
    │   ├── ::part(corner-square)        // outer finder-pattern squares (×3)
    │   └── ::part(corner-dot)           // inner finder-pattern dots (×3)
    └── <image>                          // center logo, rendered when logo-src is set

作業の開始

Web Components QR Code を使用するには、まず Ignite UI for Web Components の作業の開始 トピックに従って基本的なプロジェクトのセットアップを行い、その後、コンポーネントを登録してください。

QR Code には igniteui-webcomponents 7.3.0 以降が必要です。toBlob() および toImage() エクスポート メソッドには 7.3.2 以降が必要です。

IgcQrCodeComponent とテーマをインポートし、コンポーネントを登録します:

import { defineComponents, IgcQrCodeComponent } from 'igniteui-webcomponents';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

defineComponents(IgcQrCodeComponent);

値を指定して QR Code をレンダリングします:

<igc-qr-code value="https://www.infragistics.com"></igc-qr-code>

デフォルトでは、128×128 ピクセルの QR コードが、4 モジュールのクワイエット ゾーンの余白、誤り訂正 M、正方形のモジュールとコーナーでレンダリングされます。

使用方法

スキャン可能な QR コードをレンダリングするには、value に任意の文字列を設定します。コンポーネントは、最もコンパクトなエンコード モード (数字、英数字、またはバイト) と、値が収まる最小の QR バージョンを選択します。value をクリアすると SVG が削除されます。

誤り訂正

errorLevel を使用して、L、M (デフォルト)、Q、または H の誤り訂正レベルを選択します。レベルが高いほど、損傷したり覆われたりしたコードをより多く復元できますが、コードの密度は高くなります。予測可能なモジュール寸法が必要な場合は、version を使用して 1 から 40 までの QR バージョンを固定します。未設定のままにすると、value が収まる最小のバージョンが使用されます。

<igc-qr-code
  value="https://www.infragistics.com"
  version="4"
  error-level="H">
</igc-qr-code>

サイズ

size を使用してレンダリングされる幅と高さをピクセル単位で設定し、margin を使用してクワイエット ゾーンを QR モジュール単位で設定します。クワイエット ゾーンは size の内側に描画されるため、margin を大きくするとモジュールは小さくなります。

<igc-qr-code
  value="https://www.infragistics.com"
  size="256"
  margin="2">
</igc-qr-code>

中央ロゴ

コードの中央に画像をレンダリングするには logoSrc を設定します。コンポーネントは、その下にあるモジュールをマスクします。logoSize は、安全なロゴ領域の最大値 (H レベルでコードの 9%) に対する 0 から 1 までの比率としてロゴのサイズを設定します。logoMargin は、ロゴの周囲にピクセル単位で空白を追加します。

ロゴが現在の errorLevel で許容される範囲を超えてコードを覆うことはありません。デフォルトの M レベルでは、約 0.44 を超える logoSize の値は同じ上限サイズでレンダリングされるため、最大のロゴを表示するには errorLevel を H に設定してください。

logoSrc は、通常の URL と data:image/* URI を受け入れます。安全でないスキーム (javascript: や vbscript: など) を持つソースおよび画像以外の data: URI は拒否され、ロゴはレンダリングされません。

<igc-qr-code
  value="https://www.infragistics.com"
  error-level="H"
  logo-src="/assets/logo.png"
  logo-size="0.5"
  logo-margin="4">
</igc-qr-code>

形状

dotStyle を使用してデータ モジュールと位置検出パターンの内側のドットの形状を設定し、squareStyle を使用して位置検出パターンの外側の四角形の形状を設定します。どちらも square (デフォルト)、circle、または rounded を受け入れます。

<igc-qr-code
  value="https://www.infragistics.com"
  dot-style="rounded"
  square-style="rounded">
</igc-qr-code>

エクスポート

toImage() を呼び出して QR コードを PNG、JPEG、WebP、または SVG ファイルとしてエクスポートするか、toBlob() を呼び出して SVG の Blob として取得します。どちらのメソッドもテーマの色を解決し、ロゴをインライン化するため、エクスポート結果はレンダリングされたコードと一致します。

const qrCode = document.querySelector('igc-qr-code') as IgcQrCodeComponent;

// Downloads a 512×512 PNG from a 256px QR code.
await qrCode.toImage({ format: 'png', scale: 2, fileName: 'my-qr-code', download: true });

使用すべき場合と使用すべきでない場合

使用すべき場合: QR コードは、ページを開く、アプリをダウンロードする、リンクを検証するなどのデジタル アクションへ、印刷物や静的な画面から素早く移動する手段をユーザーに提供します。

使用すべきでない場合: スキャナーなしで読み取れる必要がある情報や、直接のボタン、リンク、短縮 URL の方がリンク先への誘導に適している場合には、QR コードの使用を避けてください。

Do	Don’t
明確なリンク先があり、周囲に十分な空白を確保できる、短く意図の明確なアクションに QR コードを使用します。	重要なコンテンツを QR コードだけで提供したり、ユーザーが簡単にスキャンできない場所に配置したりすることは避けてください。
Do	Don’t
スマートフォンのカメラが素早くスキャンできるように、前景を暗く、背景を明るく (理想的には白地に黒) 保ちます。	スキャナーが検出できない、暗い背景上の明色の QR コードや、コントラストの低いブランド カラーの色合いは避けてください。

プロパティ

Web Components QR Code は、エンコードされる値、コードの密度、サイズ設定、ロゴ、および形状のカスタマイズのためのプロパティを公開します。

メソッド

スタイル設定

Web Components QR Code の外観は、CSS 変数、CSS パーツ、およびテーマ システムによって制御されます。

スタイル設定変数

スタイル パーツ

Sass テーマ

qr-code-theme() でテーマを作成し、tokens ミックスインに渡します。

@use "igniteui-theming/sass/themes" as *;

$custom-qr-code-theme: qr-code-theme(
  $background: #ffffff,
  $dark-color: #1a1a2e,
  $corner-square-color: #c0392b,
  $corner-dot-color: #1a1a2e
);

:root {
  @include tokens($custom-qr-code-theme);
}

CSS 変数

Sass のビルド ステップなしでローカルなスタイル設定が必要な場合は、コンポーネントの CSS 変数を直接設定します。

igc-qr-code {
  --ig-qr-code-background: var(--ig-gray-50);
  --ig-qr-code-dark-color: var(--ig-primary-800);
  --ig-qr-code-corner-square-color: var(--ig-secondary-800);
}

igc-qr-code::part(corner-dot) {
  fill: var(--ig-success-500);
}

Tailwind によるスタイル設定

Tailwind ユーティリティ クラスを QR Code の CSS 変数と組み合わせます。最初に Ignite UI テーマで Tailwind をセットアップ してください:

@import "tailwindcss/theme.css";
@import "tailwindcss/utilities.css";

light-qr-code ユーティリティを適用して QR Code にテーマ変数を付与し、その後、任意のプロパティ クラスで個々の変数をオーバーライドします。! プレフィックスはユーティリティを important としてマークし、コンポーネントのデフォルト スタイルより優先されるようにします。

<igc-qr-code
  value="https://www.infragistics.com"
  class="!light-qr-code [--ig-qr-code-dark-color:#1a1a1a] [--ig-qr-code-background:#f7df1e]">
</igc-qr-code>

アクセシビリティ

Web Components QR Code は静的なグラフィックであり、スクリーン リーダーはその SVG の <title> を通じて読み上げます。

キーボード インタラクション

QR Code はフォーカス可能ではなく、キーボード入力に応答しません。

スクリーン リーダー / ARIA

レンダリングされる <svg> には role="img" と、スクリーン リーダーが読み上げる <title> があります。タイトルのデフォルトは QR code: <value> です。代わりにより意味のあるフレーズを読み上げるには、aria-label を設定してください。

<igc-qr-code
  value="https://www.infragistics.com/products"
  aria-label="Scan to visit our product page">
</igc-qr-code>

アクセシビリティ準拠

インフラジスティックスは、アクセシビリティ準拠 トピックで、Section 508 および WCAG 2.1 ガイドライン領域における Ignite UI for Web Components のアクセシビリティ サポートを文書化しています。

ユーザー側の責任:

• スキャン後に何が起こるかを晴眼のユーザーが理解できるように、QR Code に短い可視の行動喚起を併記してください。
• エンコードされた value が不透明な場合 (トークンや短い識別子など) は、読み上げられるテキストが意味を持つように aria-label を指定してください。
• CSS 変数をオーバーライドする際は、スキャナーがコードを確実に読み取れるように、モジュールの色と背景の間に十分なコントラストを維持してください。

トラブルシューティング

Web Components QR Code のトラブルシューティング ガイダンスは、一般的な統合およびレンダリングの問題について、問題 → 原因 → 解決策の形式で説明します。

QR コードがスキャンできないのはなぜですか?

モジュールと背景のコントラストが低すぎる、画面上でコードが小さすぎる、またはクワイエット ゾーンの余白が小さすぎることが原因です。確実にスキャンできるようにするには、デフォルトの white 上の black の色に戻し、size を大きくして、margin を 4 モジュール以上にしてください。

ロゴが設定した logoSize より小さいのはなぜですか?

ロゴは、現在の errorLevel の安全な領域に上限が設定されています。最大のロゴを許可するには、errorLevel を H に設定してください。

ロゴが表示されないのはなぜですか?

logoSrc が拒否されるソース (安全でないスキームまたは画像以外の data: URI) を使用しているか、画像の読み込みに失敗しています。有効な画像 URL または data:image/* URI を使用してください。その後に有効なソースを割り当てると、ロゴがレンダリングされます。

QR コードがダーク テーマに自動的に切り替わらなかったのはなぜですか?

暗い背景上の明色のコードは確実にスキャンできないため、QR Code の色はグローバルのライト/ダーク テーマに連動して反転しません。UI のダーク バリアント用に色を変更するには、--ig-qr-code-background と --ig-qr-code-dark-color を明示的に設定してください。

既知の制限

Web Components QR Code には次の制限があります。

• QR Code にはスロットやイベントはありません。

• QR Code の視覚的な構造は標準化された固定のレイアウトに従うため、右から左 (RTL) のコンテキストでは反転されません。

• CORS ヘッダーを送信しないクロスオリジンの URL から読み込まれたロゴは、エクスポートから除外されます。

API リファレンス

QR Code の完全な API サーフェスについては、次の API リファレンスを参照してください。

IgcQrCodeComponent

依存関係

Web Components QR Code は、作業の開始 で追加するテーマ スタイルシートを必要とします。その他のランタイム依存関係はありません。

その他のリソース

サポートおよび関連する Ignite UI ドキュメントについては、次のリソースを参照してください。

• Ignite UI for Web Components フォーラム (英語)
• Ignite UI for Web Components GitHub (英語)

関連コンポーネント

QR Code はスタンドアロンの表示プリミティブです。関連する視覚的コンテンツが必要な場合は、次のコンポーネントを検討してください。

• Icon - スキャン可能である必要のない、静的なシンボル画像に使用します。
• Avatar - 人物やエンティティを表すアイデンティティ画像に使用します。

FAQ