# React（含 Next.js、Remix）
npm install @unpic/react
 
# Vue / Nuxt
npm install @unpic/vue
 
# Svelte / SvelteKit
npm install @unpic/svelte
 
# Astro
npm install @unpic/astro
 
# Angular
npm install @unpic/angular
 
# SolidJS
npm install @unpic/solid
 
# Qwik
npm install @unpic/qwik
 
# Preact
npm install @unpic/preact
 
# Lit / Web Components
npm install @unpic/lit
 
# WebC (11ty)
npm install @unpic/webc
 
# 核心翻译器（编程式使用）
npm install unpic

import { Image } from '@unpic/react';
 
export default function App() {
  return (
    <Image
      src="https://cdn.example.com/photo.jpg"
      width={800}
      height={600}
      alt="响应式图片"
      layout="constrained"
    />
  );
}

<script setup>
import { Image } from '@unpic/vue';
</script>
 
<template>
  <Image
    src="https://cdn.example.com/photo.jpg"
    :width="800"
    :height="600"
    alt="响应式图片"
    layout="constrained"
  />
</template>

<script>
  import { Image } from '@unpic/svelte';
</script>
 
<Image
  src="https://cdn.example.com/photo.jpg"
  width={800}
  height={600}
  alt="响应式图片"
/>

---
import { Image } from '@unpic/astro';
---
 
<Image
  src="https://cdn.example.com/photo.jpg"
  width={800}
  height={600}
  alt="响应式图片"
/>

import { ImageComponent } from '@unpic/angular';
 
@Component({
  template: `
    <unpic-img
      src="https://cdn.example.com/photo.jpg"
      [width]="800"
      [height]="600"
      alt="响应式图片"
    />
  `
})
export class AppComponent {}

import { transformUrl, parseUrl } from 'unpic';
 
// 自动检测 CDN 并转换
const url = transformUrl('https://images.ctfassets.net/abc/photo.jpg', {
  width: 800,
  height: 600,
  quality: 80
});
// → https://images.ctfassets.net/abc/photo.jpg?w=800&h=600&q=80&fm=auto
 
// 解析 URL 识别 CDN
const parsed = parseUrl('https://cdn.shopify.com/xyz/product.jpg?width=400');
// → { provider: 'shopify', src: '...', operations: { width: 400 } }
 
// CDN 特有操作
const shopifyUrl = transformUrl(
  'https://cdn.shopify.com/xyz/product.jpg',
  { width: 800 },
  { shopify: { crop: 'center' } }
);

// 多来源图片统一处理
import { Image } from '@unpic/react';
 
// 以下图片来自完全不同的 CDN，但用法完全一致
export function ProductGallery({ images }) {
  return (
    <div className="grid grid-cols-2 gap-4">
      {/* Contentful */}
      <Image
        src="https://images.ctfassets.net/abc/product-1.jpg"
        width={400}
        height={400}
        alt="Product 1"
      />
      {/* Shopify */}
      <Image
        src="https://cdn.shopify.com/xyz/product-2.png"
        width={400}
        height={400}
        alt="Product 2"
      />
      {/* Cloudinary */}
      <Image
        src="https://res.cloudinary.com/demo/image/upload/hero.jpg"
        width={400}
        height={400}
        alt="Product 3"
      />
      {/* 无法识别的 URL → 指定 fallback */}
      <Image
        src="https://my-custom-cdn.com/image.jpg"
        width={400}
        height={400}
        fallback="imgix"
        alt="Product 4"
      />
    </div>
  );
}

import { Image, Source, Picture } from '@unpic/react';
 
<Picture>
  {/* 暗色模式专用图 */}
  <Source
    src="https://cdn.example.com/dark-hero.jpg"
    media="(prefers-color-scheme: dark)"
    width={1200}
    height={600}
  />
  {/* 窄屏裁剪版 */}
  <Source
    src="https://cdn.example.com/mobile-hero.jpg"
    media="(max-width: 768px)"
    width={600}
    height={400}
  />
  {/* 默认回退 */}
  <Image
    src="https://cdn.example.com/hero.jpg"
    width={1200}
    height={600}
    alt="Hero"
    layout="fullWidth"
  />
</Picture>

import { Image } from '@unpic/react';
 
// 自动模糊占位符
<Image
  src="https://cdn.example.com/photo.jpg"
  width={800}
  height={600}
  background="auto"
  alt="带占位符的图片"
/>

// @unpic/placeholder 编程式使用
import { getDominantColor, blurhashToCssGradients } from '@unpic/placeholder';
import { decodeImage } from '@unpic/pixels';
 
// 提取主色调
const pixels = await decodeImage(imageBuffer);
const color = getDominantColor(pixels);
// → [142, 98, 56] (RGB)
 
// BlurHash → CSS 渐变
const gradients = blurhashToCssGradients('LEHV6nWB2yk8pyo0adR*.7kCMdnj');
// → ['linear-gradient(...)', 'linear-gradient(...)']

# 构建时自动处理（以 Astro 为例）
# astro.config.mjs 无需特殊配置
import { defineConfig } from 'astro/config';
 
export default defineConfig({
  // Unpic 组件直接使用，无需构建时图片处理
});

// ✅ 正确：指定宽高防止 CLS
<Image src="..." width={800} height={600} alt="..." />
 
// ❌ 错误：不指定宽高导致 CLS
<Image src="..." alt="..." />

// 首屏大图使用 priority
<Image
  src="https://cdn.example.com/hero.jpg"
  layout="fullWidth"
  height={500}
  priority  // → loading="eager" + fetchpriority="high"
  alt="Hero"
/>

<Image
  src="https://cdn.shopify.com/xyz/product.jpg"
  width={400}
  height={400}
  operations={{ shopify: { crop: 'center' } }}
  alt="Product"
/>

<Image
  src="https://my-custom-cdn.com/image.jpg"
  width={800}
  height={600}
  fallback="imgix"  // 当作 Imgix URL 处理
  alt="Custom CDN image"
/>

// 错误：不指定宽高会导致 CLS
<Image src="..." alt="..." />
 
// 正确：始终指定宽高
<Image src="..." width={800} height={600} alt="..." />

// 如果 CDN 未被识别，使用 fallback
<Image
  src="https://unknown-cdn.com/image.jpg"
  width={800}
  height={600}
  fallback="imgix"  // 指定 fallback provider
  alt="..."
/>