feat: upgrade vrender to enhance image and background image

docs/assets/option/en/common/background.md

@@ -20,9 +20,21 @@ The picture configuration structure is as follows
 const type BackgroundImage = {
   image?: string | HTMLImageElement | HTMLCanvasElement;
   cornerRadius?: number | number[];
+  backgroundMode?: 'repeat' | 'repeat-x' | 'repeat-y' | 'no-repeat' | 'no-repeat-cover' | 'no-repeat-contain' | 'no-repeat-fill' | 'no-repeat-auto';
+  backgroundPosition?: 'left' | 'center' | 'right' | 'top' | 'bottom' | 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' | [number | string, number | string];
+  backgroundScale?: number;
+  backgroundOffsetX?: number;
+  backgroundOffsetY?: number;
+  backgroundClip?: boolean;
+  backgroundOpacity?: number;
 }
 ```
 
+Where:
+
+- `backgroundMode` supports `no-repeat-cover` / `no-repeat-contain` / `no-repeat-fill` / `no-repeat-auto` since version `2.0.21`, which are size shorthands for `no-repeat`
+- `backgroundPosition` is supported since version `2.0.21`, and controls the image anchor position within the background area, similar to CSS `background-position`
+
 Example usage:
 
 ```
@@ -43,7 +55,10 @@ const spec = {
     // svg
     image: svgImage,
     // url
-    image: 'https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/vchart/preview/chart-3d/area3d.png'
+    image: 'https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/vchart/preview/chart-3d/area3d.png',
+    // supported since 2.0.21
+    backgroundMode: 'no-repeat-cover',
+    backgroundPosition: 'center'
   }
 }
 

docs/assets/option/en/graphic/fill-style.md

@@ -86,6 +86,20 @@ Background fill mode, related to specific graphic elements. Optional values:
 - `'repeat-x'`: Tile horizontally
 - `'repeat-y'`: Tile vertically
 - `'no-repeat'`: No tiling
+- `'no-repeat-cover'`: Supported since version `2.0.21`. No repeat, scale proportionally and cover the whole graphic area
+- `'no-repeat-contain'`: Supported since version `2.0.21`. No repeat, scale proportionally and fit entirely inside the graphic area
+- `'no-repeat-fill'`: Supported since version `2.0.21`. No repeat, stretch to fill the graphic area
+- `'no-repeat-auto'`: Supported since version `2.0.21`. No repeat, draw with the image's intrinsic size
+
+#${prefix} backgroundPosition(string|Array<string | number>)
+
+Supported since version `2.0.21`. Background image anchor position, similar to CSS `background-position`. Only effective when the background is an image and the final mode is `no-repeat`.
+
+Supported forms:
+
+- Single keyword: `'left'`, `'center'`, `'right'`, `'top'`, `'bottom'`
+- Preset position: `'top-left'`, `'top-center'`, `'top-right'`, `'center-left'`, `'center'`, `'center-right'`, `'bottom-left'`, `'bottom-center'`, `'bottom-right'`
+- Tuple: `[x, y]`, where `x` / `y` can be a number, keyword, or percentage string, for example `['25%', '75%']`
 
 #${prefix} backgroundFit(boolean)
 

docs/assets/option/en/graphic/image.md

@@ -28,10 +28,41 @@ The repeat mode for the image in the y direction.
 - `'repeat'`
 - `'stretch'`
 
+#${prefix} imageMode(string)
+
+Supported since version `2.0.21`. Image drawing mode. Only effective when `repeatX` and `repeatY` both resolve to `no-repeat`.
+
+Optional values:
+- `'cover'`: Scale proportionally and crop to cover the whole graphic area
+- `'contain'`: Scale proportionally and fit entirely inside the graphic area
+- `'fill'`: Stretch to fill the graphic area
+- `'auto'`: Draw with the image's intrinsic size
+
+#${prefix} imagePosition(string|Array<string | number>)
+
+Supported since version `2.0.21`. Image anchor position, similar to CSS `background-position`.
+
+Supported forms:
+- Single keyword: `'left'`, `'center'`, `'right'`, `'top'`, `'bottom'`
+- Preset position: `'top-left'`, `'top-center'`, `'top-right'`, `'center-left'`, `'center'`, `'center-right'`, `'bottom-left'`, `'bottom-center'`, `'bottom-right'`
+- Tuple: `[x, y]`, where `x` / `y` can be a number, keyword, or percentage string, for example `['25%', '75%']`
+
+#${prefix} imageScale(number)
+
+Supported since version `2.0.21`. Additional image scale ratio. Only effective when the image is not repeated.
+
+#${prefix} imageOffsetX(number)
+
+Supported since version `2.0.21`. Additional x offset of the image. Only effective when the image is not repeated.
+
+#${prefix} imageOffsetY(number)
+
+Supported since version `2.0.21`. Additional y offset of the image. Only effective when the image is not repeated.
+
 #${prefix} image(string | Object)
 
 Image resource, can be a url, HTMLImageElement, or HTMLCanvasElement.
 
 {{ use: graphic-attribute(
   prefix = ${prefix},
-) }}
+) }}

docs/assets/option/zh/common/background.md

@@ -16,9 +16,21 @@
 const type BackgroundImage = {
   image?: string | HTMLImageElement | HTMLCanvasElement;
   cornerRadius?: number | number[];
+  backgroundMode?: 'repeat' | 'repeat-x' | 'repeat-y' | 'no-repeat' | 'no-repeat-cover' | 'no-repeat-contain' | 'no-repeat-fill' | 'no-repeat-auto';
+  backgroundPosition?: 'left' | 'center' | 'right' | 'top' | 'bottom' | 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' | [number | string, number | string];
+  backgroundScale?: number;
+  backgroundOffsetX?: number;
+  backgroundOffsetY?: number;
+  backgroundClip?: boolean;
+  backgroundOpacity?: number;
 }
 ```
 
+其中：
+
+- `backgroundMode` 自 `2.0.21` 版本开始支持 `no-repeat-cover` / `no-repeat-contain` / `no-repeat-fill` / `no-repeat-auto` 这些 `no-repeat` 下的尺寸简写
+- `backgroundPosition` 自 `2.0.21` 版本开始支持，用于控制图片在背景区域中的锚定位置，语义类似 CSS `background-position`
+
 使用示例:
 
 ```
@@ -39,7 +51,10 @@ const spec = {
     // svg
     image: svgImage,
     // url
-    image: 'https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/vchart/preview/chart-3d/area3d.png'
+    image: 'https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/vchart/preview/chart-3d/area3d.png',
+    // 自 2.0.21 版本开始支持
+    backgroundMode: 'no-repeat-cover',
+    backgroundPosition: 'center'
   }
 }
 

docs/assets/option/zh/graphic/fill-style.md

@@ -86,6 +86,20 @@ const spec = {
 - `'repeat-x'`: 水平方向平铺
 - `'repeat-y'`: 垂直方向平铺
 - `'no-repeat'`: 不平铺
+- `'no-repeat-cover'`: 自 `2.0.21` 版本开始支持，不平铺，等比缩放并覆盖整个图元区域
+- `'no-repeat-contain'`: 自 `2.0.21` 版本开始支持，不平铺，等比缩放并完整包含在图元区域内
+- `'no-repeat-fill'`: 自 `2.0.21` 版本开始支持，不平铺，拉伸填满图元区域
+- `'no-repeat-auto'`: 自 `2.0.21` 版本开始支持，不平铺，按图片原始尺寸绘制
+
+#${prefix} backgroundPosition(string|Array<string | number>)
+
+自 `2.0.21` 版本开始支持。背景图锚定位置，语义类似 CSS `background-position`，仅在图片背景且最终为 `no-repeat` 时生效。
+
+支持以下写法：
+
+- 单关键字：`'left'`、`'center'`、`'right'`、`'top'`、`'bottom'`
+- 预设位置：`'top-left'`、`'top-center'`、`'top-right'`、`'center-left'`、`'center'`、`'center-right'`、`'bottom-left'`、`'bottom-center'`、`'bottom-right'`
+- 元组：`[x, y]`，其中 `x` / `y` 支持数值、关键字或百分比字符串，例如 `['25%', '75%']`
 
 #${prefix} backgroundFit(boolean)
 

docs/assets/option/zh/graphic/image.md

@@ -28,10 +28,41 @@
 - `'repeat'` 
 - `'stretch'`
 
+#${prefix} imageMode(string)
+
+自 `2.0.21` 版本开始支持。图片绘制模式，仅在 `repeatX` 和 `repeatY` 最终都为 `no-repeat` 时生效。
+
+可选值：
+- `'cover'`: 等比缩放并裁剪，覆盖整个图元区域
+- `'contain'`: 等比缩放，完整包含在图元区域内
+- `'fill'`: 拉伸填满图元区域
+- `'auto'`: 按图片原始尺寸绘制
+
+#${prefix} imagePosition(string|Array<string | number>)
+
+自 `2.0.21` 版本开始支持。图片锚定位置，语义类似 CSS `background-position`。
+
+支持以下写法：
+- 单关键字：`'left'`、`'center'`、`'right'`、`'top'`、`'bottom'`
+- 预设位置：`'top-left'`、`'top-center'`、`'top-right'`、`'center-left'`、`'center'`、`'center-right'`、`'bottom-left'`、`'bottom-center'`、`'bottom-right'`
+- 元组：`[x, y]`，其中 `x` / `y` 支持数值、关键字或百分比字符串，例如 `['25%', '75%']`
+
+#${prefix} imageScale(number)
+
+自 `2.0.21` 版本开始支持。图片额外缩放比例，仅在不重复平铺时生效。
+
+#${prefix} imageOffsetX(number)
+
+自 `2.0.21` 版本开始支持。图片在 x 方向上的额外偏移量，仅在不重复平铺时生效。
+
+#${prefix} imageOffsetY(number)
+
+自 `2.0.21` 版本开始支持。图片在 y 方向上的额外偏移量，仅在不重复平铺时生效。
+
 #${prefix} image(string | Object)
 
 图片资源，可传入url、HTMLImageElement 或 HTMLCanvasElement。
 
 {{ use: graphic-attribute(
   prefix = ${prefix},
-) }}
+) }}

docs/package.json

@@ -19,8 +19,8 @@
     "@visactor/vchart-theme": "~1.6.6",
     "@visactor/vmind": "1.2.4-alpha.5",
     "@visactor/vutils": "~1.0.23",
-    "@visactor/vrender": "1.0.44",
-    "@visactor/vrender-kits": "1.0.44",
+    "@visactor/vrender": "1.0.45",
+    "@visactor/vrender-kits": "1.0.45",
     "@visactor/vtable": "1.19.0-alpha.0",
     "@visactor/vtable-editors": "1.19.0-alpha.0",
     "@visactor/vtable-gantt": "1.19.0-alpha.0",

packages/openinula-vchart/package.json

@@ -30,8 +30,8 @@
   "dependencies": {
     "@visactor/vchart": "workspace:2.0.20",
     "@visactor/vutils": "~1.0.23",
-    "@visactor/vrender-core": "1.0.44",
-    "@visactor/vrender-kits": "1.0.44",
+    "@visactor/vrender-core": "1.0.45",
+    "@visactor/vrender-kits": "1.0.45",
     "react-is": "^18.2.0"
   },
   "devDependencies": {

packages/react-vchart/package.json

@@ -31,8 +31,8 @@
     "@visactor/vchart": "workspace:2.0.20",
     "@visactor/vchart-extension": "workspace:2.0.20",
     "@visactor/vutils": "~1.0.23",
-    "@visactor/vrender-core": "1.0.44",
-    "@visactor/vrender-kits": "1.0.44",
+    "@visactor/vrender-core": "1.0.45",
+    "@visactor/vrender-kits": "1.0.45",
     "react-is": "^18.2.0"
   },
   "devDependencies": {
@@ -83,4 +83,4 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   }
-}
+}

packages/vchart-extension/package.json

@@ -21,10 +21,10 @@
     "start": "ts-node __tests__/runtime/browser/scripts/initVite.ts && vite serve __tests__/runtime/browser"
   },
   "dependencies": {
-    "@visactor/vrender-core": "1.0.44",
-    "@visactor/vrender-kits": "1.0.44",
-    "@visactor/vrender-components": "1.0.44",
-    "@visactor/vrender-animate": "1.0.44",
+    "@visactor/vrender-core": "1.0.45",
+    "@visactor/vrender-kits": "1.0.45",
+    "@visactor/vrender-components": "1.0.45",
+    "@visactor/vrender-animate": "1.0.45",
     "@visactor/vchart": "workspace:2.0.20",
     "@visactor/vutils": "~1.0.23",
     "@visactor/vdataset": "~1.0.23",

packages/vchart-types/types/typings/visual.d.ts

@@ -85,6 +85,38 @@ export interface ICommonSpec {
     html?: IMarkHtmlSpec;
     [key: string]: any;
 }
+/**
+ * 非平铺背景图/图片的尺寸模式。
+ * @since 2.0.21
+ */
+export type BackgroundSizing = 'cover' | 'contain' | 'fill' | 'auto';
+export type BackgroundRepeatMode = 'repeat' | 'repeat-x' | 'repeat-y' | 'no-repeat';
+/**
+ * `backgroundMode` 在 `no-repeat` 下的尺寸简写。
+ * @since 2.0.21
+ */
+export type BackgroundSizingShorthand = 'no-repeat-cover' | 'no-repeat-contain' | 'no-repeat-fill' | 'no-repeat-auto';
+export type BackgroundMode = BackgroundRepeatMode | BackgroundSizingShorthand;
+export type BackgroundPositionHorizontalKeyword = 'left' | 'center' | 'right';
+export type BackgroundPositionVerticalKeyword = 'top' | 'center' | 'bottom';
+export type BackgroundPositionKeyword = BackgroundPositionHorizontalKeyword | BackgroundPositionVerticalKeyword;
+export type BackgroundPositionPercent = `${number}%`;
+export type BackgroundPositionValue = number | BackgroundPositionKeyword | BackgroundPositionPercent;
+/**
+ * `backgroundPosition` / `imagePosition` 的预设定位。
+ * @since 2.0.21
+ */
+export type BackgroundPositionPreset = 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+/**
+ * 类似 CSS `background-position` 的定位写法。
+ * @since 2.0.21
+ */
+export type BackgroundPosition = BackgroundPositionKeyword | BackgroundPositionPreset | [BackgroundPositionValue, BackgroundPositionValue];
+/**
+ * image 图元在非平铺模式下的尺寸模式。
+ * @since 2.0.21
+ */
+export type ImageMode = BackgroundSizing;
 export interface IFillMarkSpec extends ICommonSpec {
     fill?: VisualType<string> | IGradient | false | IColorKey;
     shadowBlur?: number;
@@ -93,12 +125,24 @@ export interface IFillMarkSpec extends ICommonSpec {
     shadowOffsetY?: number;
     fillOpacity?: number;
     background?: IColor | HTMLImageElement | HTMLCanvasElement | null;
-    backgroundMode?: 'repeat' | 'repeat-x' | 'repeat-y' | 'no-repeat';
+    /**
+     * 背景图绘制模式（与具体图元有关）。
+     * 原有平铺模式为：`repeat` / `repeat-x` / `repeat-y` / `no-repeat`；
+     * 自 `2.0.21` 版本开始，支持 `no-repeat-cover` / `no-repeat-contain` /
+     * `no-repeat-fill` / `no-repeat-auto` 这几个 `no-repeat` 下的尺寸简写。
+     */
+    backgroundMode?: BackgroundMode;
     backgroundFit?: boolean;
     backgroundKeepAspectRatio?: boolean;
     backgroundScale?: number;
     backgroundOffsetX?: number;
     backgroundOffsetY?: number;
+    /**
+     * 背景图锚定位置，语义类似 CSS `background-position`。
+     * 仅在图片背景且最终为 `no-repeat` 时生效。
+     * @since 2.0.21
+     */
+    backgroundPosition?: BackgroundPosition;
     backgroundClip?: boolean;
     backgroundCornerRadius?: number | number[];
     backgroundOpacity?: number;
@@ -309,6 +353,32 @@ export interface IImageMarkSpec extends IFillMarkSpec {
     height?: number;
     repeatX?: IRepeatType;
     repeatY?: IRepeatType;
+    /**
+     * 图片绘制模式。
+     * 仅在 `repeatX` 和 `repeatY` 最终都为 `no-repeat` 时生效。
+     * @since 2.0.21
+     */
+    imageMode?: ImageMode;
+    /**
+     * 图片锚定位置，语义与 `backgroundPosition` 一致。
+     * @since 2.0.21
+     */
+    imagePosition?: BackgroundPosition;
+    /**
+     * 图片额外缩放比例，仅在不重复平铺时生效。
+     * @since 2.0.21
+     */
+    imageScale?: number;
+    /**
+     * 图片 x 方向偏移，仅在不重复平铺时生效。
+     * @since 2.0.21
+     */
+    imageOffsetX?: number;
+    /**
+     * 图片 y 方向偏移，仅在不重复平铺时生效。
+     * @since 2.0.21
+     */
+    imageOffsetY?: number;
     image?: string | HTMLImageElement | HTMLCanvasElement;
 }
 export type TextAlign = TextAlignType;

packages/vchart/package.json

@@ -122,14 +122,14 @@
     "@visactor/vdataset": "~1.0.23",
     "@visactor/vscale": "~1.0.23",
     "@visactor/vlayouts": "~1.0.23",
-    "@visactor/vrender-core": "1.0.44",
-    "@visactor/vrender-kits": "1.0.44",
-    "@visactor/vrender-components": "1.0.44",
-    "@visactor/vrender-animate": "1.0.44",
+    "@visactor/vrender-core": "1.0.45",
+    "@visactor/vrender-kits": "1.0.45",
+    "@visactor/vrender-components": "1.0.45",
+    "@visactor/vrender-animate": "1.0.45",
     "@visactor/vutils-extension": "workspace:2.0.20"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   }
-}
+}