ImagePreview 画像プレビュー - Vant 4
🖼️ ImagePreview 画像プレビュー
🎯 概要
ImagePreview コンポーネントは画像の拡大鏡のような存在です 🔍。ユーザーに没入型の画像ブラウジング体験を提供します！コンポーネント呼び出しでも関数呼び出しでも、画像をフルスクリーンモードで華麗に表示できます。ジェスチャーによる拡大縮小、スワイプによる切り替え、カスタムコンテンツなどの豊富な機能をサポートし、すべての画像が最適な表示効果を得られるようにします！
📦 導入
以下の方法でグローバルにコンポーネントを登録します。詳細な登録方法については、コンポーネントの登録を参照してください。
import { createApp } from'vue'; import { ImagePreview } from'vant'; const app = createApp(); app.use(ImagePreview);🚀 関数呼び出し
開発をより便利にするため、Vant は魔法のような補助関数のセットを提供しています！showImagePreview 関数を使用すると、まるで魔法の杖を振るように、瞬時にフルスクリーンの画像プレビューコンポーネントを呼び出すことができます。
たとえば、showImagePreview 関数を使用すると、呼び出し後にページに対応する画像プレビューコンポーネントが直接レンダリングされます。
import { showImagePreview } from'vant'; showImagePreview(['https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg']);🎯 コードの例
🔧 基本的な使い方
showImagePreview を呼び出すときに、直接画像の配列を渡すだけで、画像プレビューを表示できます。まるで美しいアルバムを開くように、各画像が完璧に表示されます！
import { showImagePreview } from'vant'; showImagePreview([ 'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg', 'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg', ]);📍 初期位置の指定
特定の画像から閲覧を開始したいですか？showImagePreview は設定オブジェクトの受け渡しをサポートしており、startPosition オプションで画像の初期位置（インデックス値）を指定できます。まるでしおりのように正確に位置を特定できます！
import { showImagePreview } from'vant'; showImagePreview({ images: [ 'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg', 'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg', ], startPosition: 1, });✨ 閉じるボタンの表示
closeable オプションを有効にすると、ポップアップの右上隅に閉じるアイコンが表示され、ユーザーに親切な退出ボタンが提供されます！さらに、close-icon 属性でアイコンのスタイルをカスタマイズしたり、close-icon-position 属性でアイコンの位置を調整したりすることで、インターフェースをデザイン理念に合わせることができます。
import { showImagePreview } from'vant'; showImagePreview({ images: [ 'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg', 'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg', ], closeable: true, });👂 閉じるイベントの監視
onClose オプションで画像プレビューの閉じるイベントを監視すると、アプリに鋭い「耳」を装着したように、ユーザーの操作に即座に反応できます！
import { showToast, showImagePreview } from'vant'; showImagePreview({ images: [ 'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg', 'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg', ], onClose() { showToast('閉じます'); }, });⏰ 非同期での閉じる
beforeClose 属性でコールバック関数を渡すと、画像プレビューが閉じる前に特定の操作を実行できます。これは閉じる操作に「セキュリティゲート」を追加するようなもので、閉じるタイミングを完全に制御できます！
import { showImagePreview } from'vant'; const instance = showImagePreview({ images: [ 'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg', 'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg', ], beforeClose: () =>false, }); setTimeout(() => { // インスタンスの close メソッドを呼び出して手動で画像プレビューを閉じる instance.close(); }, 2000);🎨 ImagePreview コンポーネントの使用
ImagePreview にコンポーネントやその他のカスタムコンテンツを埋め込む必要がある場合は、ImagePreview コンポーネントを直接使用し、index スロットを使用してカスタマイズできます。これは画像プレビューにカスタムの「衣装」を着せるようなもので、機能をより多彩にすることができます！使用前に app.use などの方法でコンポーネントを登録する必要があります。
import { ref } from'vue'; exportdefault { setup() { const show = ref(false); const index = ref(0); const images = [ 'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg', 'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg', ]; constonChange = (newIndex) => { index.value = newIndex; }; return { show, index, images, onChange, }; }, };🎬 image スロットの使用
コンポーネント呼び出しの方法で ImagePreview を使用する場合は、image スロットを通じてカスタムコンテンツを挿入できます。例えば、ビデオコンテンツを表示することができます。これはプレビューアに「トランスフォーマー」の能力を装備するようなもので、画像だけでなくビデオも再生できるようになります！この例では、close-on-click-image 属性を false に設定すると、ビデオをクリックしたときに誤ってプレビューが閉じることを防ぐことができます。
import { ref } from'vue'; exportdefault { setup() { const show = ref(false); const images = [ 'https://www.w3school.com.cn/i/movie.ogg', 'https://www.w3school.com.cn/i/movie.ogg', 'https://www.w3school.com.cn/i/movie.ogg', ]; return { show, images, }; }, };image スロットを使用して画像をカスタマイズする場合、スロットのパラメータを使用して style スタイルと onLoad コールバック関数をバインドできます。これにより、\<img> タグが画像の拡大縮小をサポートできるようになります。まるで画像にスマートな「脳」を装着したかのように、様々な表示ニーズに適応できるようになります！
API
メソッド
Vant では以下の ImagePreview に関する補助関数がエクスポートされています：
| メソッド名 | 説明 | パラメータ | 戻り値 |
|---|---|---|---|
| showImagePreview | フルスクリーンの画像プレビューコンポーネントを表示する | string[] | ImagePreviewOptions | ImagePreview インスタンス |
ImagePreviewOptions
showImagePreview メソッドを呼び出すときに、以下のオプションを渡すことができます：
| パラメータ名 | 説明 | 型 | デフォルト値 |
|---|---|---|---|
| images | プレビューする画像の URL 配列 | string[] | [] |
| startPosition | 画像プレビューの開始位置のインデックス | number | string | 0 |
| swipeDuration | アニメーションの期間（単位：ms） | number | string | 300 |
| showIndex | ページ番号を表示するかどうか | boolean | true |
| showIndicators | スライドインジケータを表示するかどうか | boolean | false |
| loop | ループ再生を有効にするかどうか | boolean | true |
doubleScale v4.7.2 | ダブルタップによる拡大縮小を有効にするかどうか。無効にすると、クリック時に即座に画像プレビューが閉じます | boolean | true |
| onClose | 閉じるときのコールバック関数 | Function | - |
| onChange | 画像を切り替えるときのコールバック関数。コールバックパラメータは現在のインデックス | Function | - |
| onScale | 画像を拡大縮小するときのコールバック関数。コールバックパラメータは現在のインデックスと現在の拡大縮小値からなるオブジェクト | Function | - |
| beforeClose | 閉じる前のコールバック関数。false を返すと閉じるのを阻止できます。Promise の返却もサポート | (active: number) => boolean | Promise<boolean> | - |
| closeOnPopstate | ページが戻るときに自動的に閉じるかどうか | boolean | true |
closeOnClickImage v4.8.3 | 画像をクリックした後に画像プレビューを閉じるかどうか | boolean | true |
closeOnClickOverlay v4.6.4 | マスクレイヤーをクリックした後に画像プレビューを閉じるかどうか | boolean | true |
vertical v4.8.6 | 縦方向のジェスチャースワイプを有効にするかどうか | boolean | false |
| className | カスタムクラス名 (画像プレビューのポップアップに適用) | string | Array | object | - |
| maxZoom | ジェスチャーによる拡大縮小の最大倍率 | number | string | 3 |
| minZoom | ジェスチャーによる拡大縮小の最小倍率 | number | string | 1/3 |
| closeable | 閉じるアイコンを表示するかどうか | boolean | false |
| closeIcon | 閉じるアイコンの名前または画像リンク | string | clear |
| closeIconPosition | 閉じるアイコンの位置。top-left、bottom-left、bottom-right から選択可能 | string | top-right |
| transition | アニメーションのクラス名。transition の name 属性と同等 | string | van-fade |
| overlayClass | カスタムマスクレイヤークラス名 | string | Array | object | - | | overlayStyle | カスタムマスクレイヤースタイル | object | - | | teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | - |
Props
コンポーネント呼び出しで ImagePreview を使用する場合、以下の Props がサポートされます：
| パラメータ | 説明 | 型 | デフォルト値 |
|---|---|---|---|
| v-model:show | 画像プレビューを表示するかどうか | boolean | false |
| images | プレビューする画像の URL 配列 | string[] | [] |
| start-position | 画像プレビューの開始位置のインデックス | number | string | 0 |
| swipe-duration | アニメーションの期間（単位：ms） | number | string | 300 |
| show-index | ページ番号を表示するかどうか | boolean | true |
| show-indicators | スライドインジケータを表示するかどうか | boolean | false |
| loop | ループ再生を有効にするかどうか | boolean | true |
double-scale v4.7.2 | ダブルタップによる拡大縮小を有効にするかどうか。無効にすると、クリック時に即座に画像プレビューが閉じます | boolean | true |
| before-close | 閉じる前のコールバック関数。false を返すと閉じるのを阻止できます。Promise の返却もサポート | (active: number) => boolean | Promise<boolean> | - |
| close-on-popstate | ページが戻るときに自動的に閉じるかどうか | boolean | true |
close-on-click-image v4.8.3 | 画像をクリックした後に画像プレビューを閉じるかどうか | boolean | true |
close-on-click-overlay v4.6.4 | マスクレイヤーをクリックした後に画像プレビューを閉じるかどうか | boolean | true |
vertical v4.8.6 | 縦方向のジェスチャースワイプを有効にするかどうか | boolean | false |
| class-name | カスタムクラス名 | string | Array | object | - |
| max-zoom | ジェスチャーによる拡大縮小の最大倍率 | number | string | 3 |
| min-zoom | ジェスチャーによる拡大縮小の最小倍率 | number | string | 1/3 |
| closeable | 閉じるアイコンを表示するかどうか | boolean | false |
| close-icon | 閉じるアイコンの名前または画像リンク | string | clear |
| close-icon-position | 閉じるアイコンの位置。top-left、bottom-left、bottom-right から選択可能 | string | top-right |
| transition | アニメーションのクラス名。transition の name 属性と同等 | string | van-fade |
| overlay-class | カスタムマスクレイヤークラス名 | string | Array | object | - | | overlay-style | カスタムマスクレイヤースタイル | object | - | | teleport | 指定挂载的节点，等同于 Teleport 组件的 to 属性 | string | Element | - |
Events
コンポーネント呼び出しで ImagePreview を使用する場合、以下のイベントがサポートされます：
| イベント名 | 説明 | コールバックパラメータ |
|---|---|---|
| close | 閉じるときにトリガーされます | { index: number, url: string } |
| closed | 閉じてアニメーションが終了した後にトリガーされます | - |
| change | 現在の画像を切り替えるときにトリガーされます | index: number |
| scale | 現在の画像を拡大縮小するときにトリガーされます | { index: number, scale: number } |
| long-press | 現在の画像を長押ししたときにトリガーされます | { index: number } |
メソッド
コンポーネント呼び出しで ImagePreview を使用する場合、ref を使用して ImagePreview インスタンスを取得し、インスタンスメソッドを呼び出すことができます。詳細については、コンポーネントインスタンスメソッドを参照してください。
| メソッド名 | 説明 | パラメータ | 戻り値 |
|---|---|---|---|
resetScale 4.7.4 | 現在の画像の拡大縮小率をリセットします | - | - |
| swipeTo | 指定位置に切り替えます | index: number, options?: SwipeToOptions | - |
型定義
コンポーネントは以下の型定義をエクスポートしています：
importtype { ImagePreviewProps, ImagePreviewOptions, ImagePreviewInstance, ImagePreviewScaleEventParams, } from'vant';ImagePreviewInstance はコンポーネントインスタンスの型で、次のように使用します：
import { ref } from'vue'; importtype { ImagePreviewInstance } from'vant'; const imagePreviewRef = ref<ImagePreviewInstance>(); imagePreviewRef.value?.swipeTo(1);Slots
コンポーネント呼び出しで ImagePreview を使用する場合、以下のスロットがサポートされます：
| 名前 | 説明 | パラメータ |
|---|---|---|
| index | ページ番号のカスタムコンテンツ | { index: 現在の画像のインデックス } |
| cover | 画像プレビューの上にカバーするカスタムコンテンツ | - |
| image | カスタム画像コンテンツ | { src: 現在のリソースアドレス, onLoad: 画像読み込み関数, style: 現在の画像スタイル } |
onClose コールバックパラメータ
| パラメータ名 | 説明 | 型 |
|---|---|---|
| url | 現在の画像 URL | string |
| index | 現在の画像のインデックス値 | number |
onScale コールバックパラメータ
| パラメータ名 | 説明 | 型 |
|---|---|---|
| index | 現在の画像のインデックス値 | number |
| scale | 現在の画像の拡大縮小値 | number |
テーマカスタマイズ
スタイル変数
コンポーネントは、カスタムスタイルに使用できる以下の CSS 変数を提供しています。使用方法については、ConfigProvider コンポーネントを参照してください。
| 名前 | デフォルト値 | 説明 |
|---|---|---|
| --van-image-preview-index-text-color | var(--van-white) | - |
| --van-image-preview-index-font-size | var(--van-font-size-md) | - |
| --van-image-preview-index-line-height | var(--van-line-height-md) | - |
| --van-image-preview-index-text-shadow | 0 1px 1px var(--van-gray-8) | - |
| --van-image-preview-overlay-background | rgba(0, 0, 0, 0.9) | - |
| --van-image-preview-close-icon-size | 22px | - |
| --van-image-preview-close-icon-color | var(--van-gray-5) | - |
| --van-image-preview-close-icon-margin | var(--van-padding-md) | - |
| --van-image-preview-close-icon-z-index | 1 | - |
よくある質問
デスクトップでコンポーネントを操作できませんか？
デスクトップ対応を参照してください。
showImagePreview を参照するとコンパイルエラーが発生しますか？
showImagePreview メソッドを参照すると次のエラーが発生する場合、プロジェクトで babel-plugin-import プラグインが使用されているため、コードが誤ってコンパイルされています。
These dependencies were not found: * vant/es/show-image-preview in ./src/xxx.js * vant/es/show-image-preview/style in ./src/xxx.jsVant は 4.0 バージョンから babel-plugin-import プラグインをサポートしなくなりました。移行ガイドを参照して、このプラグインを削除してください。
📚 関連文書
🖼️ メディアコンポーネント
- Image 画像 - 画像コンポーネント、画像プレビューとの完璧な組み合わせ
- Swipe スライダー - スライダーコンポーネント、画像切り替えの中核機能を提供
🎨 インタラクティブコンポーネント
- Popup ポップアップ - ポップアップコンポーネント、画像プレビューの基本的なコンテナ
- Overlay マスク - マスクコンポーネント、没入型体験を提供
🎯 フィードバックコンポーネント
- Toast トースト - トーストコンポーネント、画像プレビューと組み合わせて使用
- Loading ローディング - ローディングコンポーネント、画像読み込み時のフレンドリーな通知
🛠️ 開発ガイド
- Advanced Usage 高度な使い方 - 高度な使い方ガイド
- ConfigProvider グローバル設定 - グローバル設定コンポーネント
- Theme テーマカスタマイズ - テーマカスタマイズガイド
📱 モバイル対応
- Migrate from v3 移行ガイド - バージョン移行ガイド