API

Image

nsh 匯出 Image，這是用來顯示圖片的 <Image> 元素。同一個 Image 也可以向原生圖片載入器查詢圖片資訊而不顯示圖片：包括圖片尺寸，以及在顯示之前先行載入。

import { Image, type PixelSize } from "nsh";

Image 是一個帶有兩個函式的元件：<Image src=…> 負責轉譯原生圖片檢視（編譯器會就地產生它，就像處理 <View> 一樣），而 Image.getSize / Image.prefetch 則直接在它上面呼叫。

const Image: ((props: ImageProps) => JSX.Element) & {
  getSize(src: string | ImageAsset): Promise<PixelSize>;
  prefetch(src: string | ImageAsset): Promise<void>;
};

指南請參閱圖片與資源。

#Image.getSize

getSize(src: string | ImageAsset): Promise<PixelSize>;

interface PixelSize {
  width: number;   // pixels (an SVG's: points)
  height: number;
}

載入圖片，並以其像素尺寸完成 Promise（為來源圖片的尺寸，而非降低取樣後的副本；SVG 則為其固有尺寸，單位為 point，在網頁上則依瀏覽器的測量結果）。若匯入的圖片具有像素密度變體，會載入各檢視在此螢幕上所載入的變體，並以匯入檔案的尺寸完成，無論實際載入的是哪個變體（顯示該圖片的 <Image> 會在 onLoad 中回報所載入變體的像素）。載入的位元組會保留在記憶體中，因此接著顯示該圖片的 <Image> 不會再次下載。若圖片無法載入，Promise 會被拒絕。

import { Image, signal } from "nsh";

const url = "https://picsum.photos/seed/nsh/1200/800";
const ratio = signal(1);

Image.getSize(url).then(({ width, height }) => ratio.set(width / height));

<Image src={url} style={{ width: "100%", aspectRatio: ratio() }} />;

#Image.prefetch

prefetch(src: string | ImageAsset): Promise<void>;

在顯示圖片之前預先載入。當圖片的位元組進入記憶體後完成，若圖片無法載入，則以該錯誤拒絕。對於具有像素密度變體的匯入圖片，會載入各檢視在此螢幕上所載入的變體。可用於圖庫的下一頁，或點擊後才會顯示的圖片。

const next = photos.slice(index + 1, index + 4);
next.forEach((p) => Image.prefetch(p.url).catch(() => {})); // the <Image> reports its own error later

#相關內容

<Image>：src、placeholder、objectFit 樣式、onLoad、onProgress、onError 以及其他屬性。
匯入圖片檔（import logo from "./logo.png"）會得到一個 ImageAsset（{ url, size, scales? }，以 point 為單位的尺寸），可供 <Image src> 與 canvas 的 drawImage 接受。