QRコードコンポーネントに画像ロゴとコーナーカラー設定を追加

Web Awesome の <wa-qr-code> が中心画像と個別コーナーカラーを指定できるようになり、ブランドロゴやデザインアクセントを直接 QR に組み込めるようになった。これにより、単色 QR に比べて視覚的訴求力が向上する。

背景

従来の <wa-qr-code> は色指定が color と background-color のみで、ロゴ埋め込みやコーナー色の分離が不可能だった。デザイン要件が多様化する中で、同一コンポーネントでブランドロゴを表示したいケースが増えていた。PR #2139 はそのギャップを埋め、画像とコーナーカラーのオプションを提供することを目的としている。結果として、利用者は QR コードを他の UI コンポーネントと同等のカスタマイズ性で扱えるようになる。

技術的な変更

依存ライブラリの刷新 が最初のステップとなり、qr-creator から @konnorr/qr-creator へ切り替えられた。これにより画像描画用の API が利用可能になり、QR の中心にロゴを配置できるようになった。\n\njson:packages/webawesome/package.json\n@@ -82,14 +82,14 @@\n "dependencies": {\n "@ctrl/tinycolor": "4.1.0",\n "@floating-ui/dom": "^1.6.13",\n+ "@konnorr/qr-creator": "^1.0.1",\n "@lit/react": "^1.0.8",\n@@ -88,7 +88,6 @@\n- "qr-creator": "^1.0.0"\n },\n\n\n*コンポーネント API の拡張* では image, image-background, image-coverage, image-padding の four プロパティが新たに導入された。これらはすべて属性として設定でき、null がデフォルト値となる。属性の追加に伴い、updated() ライフサイクルで generate() を再呼び出し、画像パラメータを QR 生成ロジックに渡す処理が実装された。\n\nts:packages/webawesome/src/components/qr-code/qr-code.ts\n@@ -18,6 +18,10 @@\n @property() value = '';\n @property({ attribute: 'error-correction' }) errorCorrection: 'L' | 'M' | 'Q' | 'H' = 'H';\n+ @property() image: string | null = null;\n+ @property({ attribute: 'image-background' }) imageBackground: string | null = null;\n+ @property({ attribute: 'image-coverage', type: Number }) imageCoverage: number | null = null;\n+ @property({ attribute: 'image-padding', type: Number }) imagePadding: number | null = null;\n\n\n*スタイルの調整* では、コーナー色を別途カスタマイズできるよう --corner-color カスタムプロパティが利用可能になった。qr-code.styles.ts に span 要素の瞬時トランジションを追加し、色変更時の CSS アニメーションが確実に検知できるようにした。\n\nts:packages/webawesome/src/components/qr-code/qr-code.styles.ts\n@@ -14,4 +14,9 @@\n transition: color 1ms;\n }\n+\n+ span {\n+ /* We force a near-instant transition so we can listen for transitionend when the color changes */\n+ transition: color 1ms;\n+ }\n\n\n*ドキュメントとテストの充実* でも変更は網羅的に行われた。qr-code.md に画像属性使用例と --corner-color の解説が追加され、利用者がすぐに実装を試せるようになった。qr-code.test.ts には画像関連プロパティの受け渡しとデフォルト値の検証テストが新規追加され、回帰防止が強化された。\n\nts:packages/webawesome/src/components/qr-code/qr-code.test.ts\n@@ -76,6 +76,44 @@\n describe('image', () => {\n it('should accept an image attribute', async () => {\n const el = await fixture<WaQrCode>(\n html`<wa-qr-code value="test" image="https://example.com/logo.png"></wa-qr-code>`,\n );\n expect(el.image).to.equal('https://example.com/logo.png');\n });\n\n it('should have correct default image property values', async () => {\n const el = await fixture<WaQrCode>(html`<wa-qr-code value="test"></wa-qr-code>`);\n expect(el.image).to.be.null;\n expect(el.imageCoverage).to.be.null;\n expect(el.imagePadding).to.be.null;\n expect(el.imageBackground).to.be.null;\n });\n /* additional attribute tests omitted for brevity */\n });\n\n\n## 設計判断

機能追加は既存コンポーネントの拡張で行う 方針が採用された。新しい属性を @property デコレータで宣言し、既存の generate() フローにシームレスに組み込むことで、破壊的変更を回避した。\n\n*ライブラリ選択の切り替え* は画像描画の実装コストを最小化するために行われ、@konnorr/qr-creator が提供する画像レイヤー機能を直接利用できる点が評価された。依存増加は最小限に抑えられ、既存の QR 生成ロジックへの影響は限定的である。\n\n*スタイル面の拡張* では CSS カスタムプロパティ --corner-color を公開し、デザイナーがコーナー色を独自に設定できるようにした。span 要素のトランジション強化は、色変化を検知して内部状態を更新するための実装上の必要条件であり、パフォーマンスへの影響はほぼ無視できる。\n\n## まとめ

今回の PR は、<wa-qr-code> に画像ロゴとコーナーカラーという二つのビジュアルカスタマイズ手段を追加し、ブランド表現の幅を大きく広げた。依存ライブラリの入れ替えと属性ベースの拡張という設計選択により、既存コードへの破壊的影響は最小限に抑えつつ、開発者とデザイナーの両方に使いやすい API が提供された。