如何在TypeScript中强制drawImage函数接收已加载的HTMLImageElement作为参数

Great question! The issue with your initial LoadedImage type comes down to two key points: first, you’ve mixed up the loading property (which controls lazy loading behavior, not the image’s loaded state) and second, TypeScript can’t automatically track changes to mutable DOM element properties like complete on its own. Let’s fix this properly.

1. First, Correct the Property Mix-Up #

The loading attribute on HTMLImageElement is a string ("eager" | "lazy" | undefined) that sets the loading strategy, not a boolean indicating if the image is done loading. The properties we actually care about for verifying a loaded image are:

• complete: A boolean that’s true when the image has finished loading (even if it failed to load properly)
• naturalWidth: A number that’s greater than 0 only if the image successfully loaded (avoids false positives from broken/corrupted images)

2. Use a Type Guard for Runtime + Compile-Time Safety #

The most robust way to enforce this constraint is with a type guard—a function that checks the image’s state at runtime and tells TypeScript to narrow the type accordingly.

First, define the type guard:

function isLoadedImage(img: HTMLImageElement): img is HTMLImageElement & { complete: true; naturalWidth: number } {
  // Check both properties to handle broken images correctly
  return img.complete && img.naturalWidth > 0;
}

Then update your drawImage function to accept the narrowed type, and use the guard before calling it:

// Now the function requires a verified loaded image
function drawImage(image: HTMLImageElement & { complete: true; naturalWidth: number }, context: CanvasRenderingContext2D) { 
  context.drawImage(image); 
}

// Usage example with full type safety
const image = new Image(); 
const context = document.getElementById("my-canvas")!.getContext("2d")!;

image.onload = () => {
  if (isLoadedImage(image)) {
    // TypeScript now recognizes image is fully loaded here
    drawImage(image, context);
  } else {
    console.error("Image loaded but appears corrupted");
  }
}; 

image.onerror = () => console.error("Failed to load image");
image.src = "path/to/your/image.png";

3. (Even Better) Encapsulate Image Loading in a Promise #

For cleaner, more maintainable usage, wrap the image loading logic in a function that returns a Promise resolving to a verified loaded image. This way, callers don’t have to handle onload manually, and TypeScript guarantees the image is ready when you use it:

function loadImage(src: string): Promise<HTMLImageElement & { complete: true; naturalWidth: number }> {
  return new Promise((resolve, reject) => {
    const img = new Image();
    
    img.onload = () => {
      if (img.complete && img.naturalWidth > 0) {
        // Assert the narrowed type since we've verified the state
        resolve(img as HTMLImageElement & { complete: true; naturalWidth: number });
      } else {
        reject(new Error("Image loaded but is corrupted"));
      }
    };

    img.onerror = () => reject(new Error(`Failed to load image from ${src}`));
    img.src = src;
  });
}

// Usage with async/await for readability
async function renderImage() {
  const context = document.getElementById("my-canvas")!.getContext("2d")!;
  try {
    const image = await loadImage("path/to/your/image.png");
    // TypeScript confirms image is loaded here
    drawImage(image, context);
  } catch (err) {
    console.error(err);
  }
}

renderImage();

Why Your Original Type Didn’t Work #

Your initial LoadedImage type had two critical issues:

• loading: false is invalid because HTMLImageElement['loading'] is not a boolean—it’s a string for controlling loading strategy
• Even if you fixed that, TypeScript can’t automatically infer that an HTMLImageElement’s complete property changes from false to true after onload fires. You need explicit type narrowing (via a guard or assertion) to tell TypeScript about the state change.

内容的提问来源于stack exchange，提问作者Klaasvaak