Skill asset

編輯 Skill

Skill 是完整資料夾資產；建立後可逐一加入腳本、參考文件、範本、圖片與子資料夾。

Skill 名稱

唯一代稱

簡短說明

主要分類

標籤

SKILL.md

五種工具預設適用

---
name: async-image-gallery
description: Implement resilient multi-image loading and gallery experiences with asynchronous preloading, per-image state tracking, visible progress, timeouts, retries, cache busting, responsive modal display, and accessible status messages. Use whenever a web page loads multiple product, attachment, album, or gallery images, especially when users need to distinguish loading from failure.
---

# Async Image Gallery

Use an explicit state machine for every image. Never represent loading and failure with the same UI.

## Required states

Track each image as `pending`, `loading`, `loaded`, or `failed`.

1. Fetch the image URL list asynchronously.
2. Initialize one state entry per URL.
3. Preload with `new Image()` without blocking the modal.
4. Update completed, successful, failed, and total counts after every transition.
5. Show the selected image only after its state becomes `loaded`.
6. Mark an image failed after `error` or a 30-second timeout.
7. Let users retry a failed image independently with a cache-busting query parameter.
8. Invalidate stale callbacks when the gallery closes or another product opens.

## UI requirements

- Show "getting image list" before URLs are available.
- Show "downloading image X of Y" for the selected image.
- Keep a persistent progress bar with `completed / total`.
- Report successful and failed counts separately.
- Allow navigation while remaining images load.
- Show a retry button only for the failed selected image.
- Display the full product description in the same modal.
- Use `object-fit: contain` for enlarged images.
- Assign explicit CSS grid columns to the image and navigation buttons. Do not rely on grid auto-placement.
- Preserve a usable mobile height with `dvh`.
- Add an explicit resource revision query whenever gallery CSS or JavaScript changes.

## Engineering rules

- Do not fetch image binaries through the application database.
- Keep URLs in structured data and use browser image requests.
- Do not wait for all images before showing the first successful image.
- Protect against callbacks from a previously closed gallery with a generation token.
- Keep server-side authorization on the image-list endpoint.
- Treat external image hosts as unreliable and expose honest failure states.
- Avoid infinite spinners.

Read [references/jquery-bootstrap-pattern.md](references/jquery-bootstrap-pattern.md) when implementing this pattern with jQuery and Bootstrap.

## Verification

Test these cases:

1. One image.
2. Several images with all requests succeeding.
3. One failed image among successful images.
4. Slow requests exceeding the timeout.
5. Retry success and retry failure.
6. Closing and immediately opening another gallery.
7. Desktop and mobile layouts.
8. Cached images completing before delegated handlers attach.

必須包含 YAML frontmatter 的 name 與 description。

修改說明

取消