feat: enhance background image handling and opacity management

[xile611]

[中文版模板 / Chinese template]

🤔 This is a ...

• New feature
• Bug fix
• TypeScript definition update
• Bundle size optimization
• Performance optimization
• Enhancement feature
• Refactoring
• Update dependency
• Code style optimization
• Test Case
• Branch merge
• Site / documentation update
• Demo update
• Workflow
• Release
• Other (about what?)

🔗 Related issue link

🐞 Bugserver case id

💡 Background and solution

📝 Changelog

Language	Changelog
🇺🇸 English
🇨🇳 Chinese

☑️ Self-Check before Merge

⚠️ Please check all items below before requesting a reviewing. ⚠️

• Doc is updated/provided or not needed
• Demo is updated/provided or not needed
• TypeScript definition is updated/provided or not needed
• Changelog is provided or not needed

---

🚀 Summary

copilot:summary

🔍 Walkthrough

copilot:walkthrough

[Copilot]

Pull request overview

This PR extends the image primitive to support background-like layout controls (cover/contain/fill/auto + positioning/offset/scale) by reusing the background image drawing pipeline, and refactors background sizing to be expressed via backgroundMode shorthands.

Changes:

• Add imageMode / imagePosition / imageScale / imageOffsetX|Y support to image rendering and clip behavior when layout can overflow.
• Replace backgroundSizing usage with backgroundMode shorthands like no-repeat-cover across rendering contributions and browser demos.
• Improve background image sizing when resources report width/height = 0 by using intrinsic dimensions (naturalWidth/Height, videoWidth/Height) and add/adjust unit tests.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/vrender/tests/browser/src/pages/image.ts	Updates browser demo page to showcase image sizing modes and live SVG swapping.
packages/vrender/tests/browser/src/pages/background.ts	Migrates demo usage from backgroundSizing to backgroundMode sizing shorthands.
packages/vrender-core/src/render/contributions/render/image-render.ts	Implements image layout drawing via drawBackgroundImage and adds layout-based clipping logic.
packages/vrender-core/src/render/contributions/render/draw-contribution.ts	Stops forwarding backgroundSizing from stage attributes into background render params.
packages/vrender-core/src/render/contributions/render/contributions/text-contribution-render.ts	Removes backgroundSizing plumbing from text background rendering contribution.
packages/vrender-core/src/render/contributions/render/contributions/group-contribution-render.ts	Removes backgroundSizing plumbing from group background rendering contribution.
packages/vrender-core/src/render/contributions/render/contributions/base-contribution-render.ts	Introduces backgroundMode sizing shorthands resolution + intrinsic size detection for image-like resources.
packages/vrender-core/src/interface/graphic/image.ts	Adds new image layout attributes to the image attribute interface.
packages/vrender-core/src/interface/graphic.ts	Expands backgroundMode typing to include no-repeat sizing shorthands and removes backgroundSizing.
packages/vrender-core/src/graphic/image.ts	Ensures image layout attributes participate in update tagging and non-animatable attribute config.
packages/vrender-core/src/graphic/config.ts	Sets defaults for new image layout attributes and removes backgroundSizing defaults.
packages/vrender-core/tests/image/image-layout.test.ts	Adds unit tests for image layout modes and layout-driven clipping.
packages/vrender-core/tests/background/background-image-layout.test.ts	Updates background layout tests for backgroundMode shorthands and new resolver behavior.

Comments suppressed due to low confidence (1)

packages/vrender-core/src/render/contributions/render/contributions/base-contribution-render.ts:114

• IBackgroundImageDrawParams / drawBackgroundImage no longer accept or resolve backgroundSizing. If existing callers still set backgroundSizing on attributes (previously supported), the sizing choice will be dropped and behavior will change. To avoid regressions, consider reintroducing backgroundSizing?: BackgroundSizing here (deprecated) and letting resolveBackgroundDrawMode prefer it when backgroundMode is no-repeat and not one of the no-repeat-* shorthands.

export type IBackgroundImageDrawParams = {
  backgroundMode: IGraphicAttribute['backgroundMode'];
  backgroundFit: boolean;
  backgroundKeepAspectRatio: boolean;
  backgroundScale?: number;
  backgroundOffsetX?: number;
  backgroundOffsetY?: number;
  backgroundPosition?: IGraphicAttribute['backgroundPosition'];
};

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.