ImagePaint 对象

图案填充对象, 可设置给 fill 或 stroke 属性，支持使用 svg 格式的图片。

平铺模式下超过 4096 x 2160 的 4k 图片会被优化显示。

关键属性

type: `string`

填充类型为 image。

填充类型同时支持 film 和 video ，需要安装相应的扩展插件。

url: `string`

图片 url 地址，支持 Blob url、Data url(Base64)。

我们还提供了资源库，支持原始图片对象、画布对象转 url，及预加载图片。

mode?: `ImagePaintMode`

图案填充模式, 默认为 cover。

type ImagePaintMode =
  | 'normal' // 正常
  | 'cover' // 覆盖（相当于background-size: cover）
  | 'fit' // 适应 (相当于background-size: contain)
  | 'stretch' // 拉伸，会改变图片比例
  | 'clip' // 裁剪
  | 'repeat' // 平铺 (相当于background-repeat: repeat)

format?: `'svg' | 'jpg' | 'png' | 'webp'`

补充图片格式，目前主要用于通过 url 无法识别的 svg 图片。

changeful?: `boolean`

是否频繁变化，默认为 false。

设为 true 后不再额外生成高性能 pattern，一般用于频繁变化 url 的游戏精灵、动图场景。

sync?: `boolean`

是否同步更新图片的层级缓存，默认为 false（可获得性能优化）。

开启同步后，缩放图片的过程中不会产生模糊效果，但会增加性能的开销，请合理使用。

基础属性

blendMode?: `BlendMode`

混合模式，默认为 normal。

visible?: `boolean`

是否可见，默认为 true。

opacity?: `number`

不透明度，默认为 1，暂时仅针对颜色对象和图片有效。

align: `IAlign`

背景图片对齐，类似 CSS 的 background-position 属性，clip 裁剪模式不支持此属性。

方向图

// 方位
type IAlign =
  | 'top-left'
  | 'top'
  | 'top-right'
  | 'right'
  | 'bottom-right'
  | 'bottom'
  | 'bottom-left'
  | 'left'
  | 'center'

cover 覆盖模式属性

rotation?: `number`

旋转角度, 以 90 度递增旋转。

fit 适应模式属性

rotation?: `number`

旋转角度, 以 90 度递增旋转。

padding?: `IFourNumber`

内边距，默认为 0。

repeat?: `boolean`

是否重复背景。

clip 裁剪模式属性

clipSize?: `ISizeData`

裁剪框大小，会自动拉伸裁剪内容以适应元素宽高

interface ISizeData {
  width: number // 宽度
  height: number // 高度
}

offset?: `IPointData`

偏移位置。

size?: `number` ｜ `IOptionSizeData`

图片尺寸，自动换算出 scale。

// 单独设置宽或高，另一边可自适应原始比例，同时设置宽高会拉伸
interface IOptionSizeData {
  width?: number // 宽度，当单独设置宽度时，高度自适应原始比例
  height?: number // 高度，当单独设置高度时，宽度自适应原始比例
}

scale?: `number` ｜ `IPointData`

缩放大小，优先使用 size 换算出的 scale。

rotation?: `number`

旋转角度。

repeat 平铺模式属性

offset?: `IPointData`

偏移位置。

size?: `number` ｜ `IOptionSizeData`

图片尺寸，自动换算出 scale。

// 单独设置宽或高，另一边可自适应原始比例，同时设置宽高会拉伸
interface IOptionSizeData {
  width?: number // 宽度，当单独设置宽度时，高度自适应原始比例
  height?: number // 高度，当单独设置高度时，宽度自适应原始比例
}

scale?: `number` ｜ `IPointData`

平铺图片的缩放比例，优先使用 size 换算出的 scale。

scaleFixed?: `boolean` | `'zoom-in'`

固定平铺图片的全局缩放比例，不跟随画布缩放，默认为 false。

'zoom-in' 表示仅在放大时固定比例（缩小时仍跟随缩小）。

rotation?: `number`

旋转角度, 以 90 度递增旋转。

设置 freeTransform 后可设置任意角度。

freeTransform?: `boolean`

是否进行自由变换，将忽略 rotation 的特殊旋转逻辑，方便进行手动编辑

gap?: `IGap` | `IPointGap`

平铺图片之间的间距，默认为 0。

// 设置 auto / fit 会均分剩余的空间，auto 最小值为 0，fit 允许为负数。
type IGap = number | 'auto' | 'fit'

interface IPointGap {
  x?: IGap // 单独设置 x 轴间距
  y?: IGap // 单独设置 y 轴间距
}

interlace?: `number` | `IPercentData` | `IInterlace`

平铺图片交错排列。

interface IInterlace {
  type: 'x' | 'y'
  offset: number | IPercentData
}

interface IPercentData {
  type: 'percent'
  value: number
}

// 数字
interlace: 100 // 下一行 X 轴偏移 100px

// 百分比
interlace: { type: 'percent', value: 0.5}  // 下一行 x 轴偏移 图案大小的50%

// Y 轴交错
interlace: { // 下一列 Y 轴偏移 图案大小的 50%
  type: 'y'
  offset:  { type: 'percent', value: 0.5}
}

repeat?: `IRepeat`

重复背景的方式，可设置重复 x 或 y 轴，默认同时重复两个轴。

并且支持单独设置 x 轴和 y 轴的平铺数量。

type IRepeat = boolean | 'x' | 'y' | IPointData

const repeat = { x: 10, y: 6 } // 设置 x、y 轴平铺图片的个数

子描边属性

style?: `IStrokeStyle`

当为元素设置多个描边时，可设置子描边样式 style ，用于覆盖主描边样式。

可形成蚂蚁线、模拟内中外三层描边等各种效果，了解具体设置。

图片缓存

图片缓存的全局配置，可根据需要动态调整。

import { Platform } from 'leafer-ui'

// 最大缓存等级，默认2k: 2560 * 1600 像素
Platform.image.maxCacheSize = 2560 * 1600

// 最大重复pattern缓存等级, 默认4k: 4096 * 2160 像素
Platform.image.maxPatternSize = 4096 * 2160

// 图片后缀，区分dom中image标签的缓存，否则可能会有浏览器缓存跨域问题，默认: leaf
Platform.image.suffix = 'leaf'  // image.jpg?leaf

图片跨域

图片跨域的全局配置，可根据需要动态调整。

设为 null 时可以渲染未经服务端允许的跨域图片，但不支持导出画板内容（浏览器的限制）。

import { Platform } from 'leafer-ui'

// 默认配置，未经服务端允许的跨域图片不能渲染。
Platform.image.crossOrigin = 'anonymous'

// 允许跨域图片渲染，但不支持导出画板内容（浏览器的限制）。
Platform.image.crossOrigin = null

资源库

我们还提供了资源库，可预加载图片，原始图片对象、画布对象可转为 url

引擎中的所有图片都会通过资源库有序并行加载，当图片不再使用时，会进入回收列表，到达阈值会自动销毁。

图片事件

ImageEvent

归属

UI 元素

示例

cover 覆盖模式

LeaferApp

// #图案填充 [默认 cover 覆盖模式 (Leafer)]
import { Leafer, Rect } from 'leafer-ui'

const leafer = new Leafer({ view: window })

const rect = new Rect({
    width: 100,
    height: 100,
    fill: {
        type: 'image',
        url: '/image/leafer.jpg',
        // mode: 'cover' // 默认模式，相当于 CSS 的 background-size: cover
    }
})

leafer.add(rect)

// #图案填充 [默认 cover 覆盖模式 (App)]
import { App, Rect } from 'leafer-ui'
import '@leafer-in/editor' // 导入图形编辑器插件
import '@leafer-in/viewport' // 导入视口插件 (可选)

const app = new App({ view: window, editor: {} })

const rect = new Rect({
    width: 100,
    height: 100,
    fill: {
        type: 'image',
        url: '/image/leafer.jpg',
        // mode: 'cover' // 默认模式，相当于 CSS 的 background-size: cover
    }
})

app.tree.add(rect)

cover 覆盖模式旋转 90 度

LeaferApp

// #图案填充 [cover 覆盖模式旋转 90 度 (Leafer)]
import { Leafer, Rect } from 'leafer-ui'

const leafer = new Leafer({ view: window })

const rect = new Rect({
    width: 100,
    height: 100,
    fill: {
        type: 'image',
        url: '/image/leafer.jpg',
        rotation: 90
    }
})

leafer.add(rect)

// #图案填充 [cover 覆盖模式旋转 90 度 (App)]
import { App, Rect } from 'leafer-ui'
import '@leafer-in/editor' // 导入图形编辑器插件
import '@leafer-in/viewport' // 导入视口插件 (可选)

const app = new App({ view: window, editor: {} })

const rect = new Rect({
    width: 100,
    height: 100,
    fill: {
        type: 'image',
        url: '/image/leafer.jpg',
        rotation: 90
    }
})

app.tree.add(rect)

fit 适应模式

LeaferApp

// #图案填充 [fit 适应模式 (Leafer)]
import { Leafer, Rect } from 'leafer-ui'

const leafer = new Leafer({ view: window })

const rect = new Rect({
    width: 100,
    height: 100,
    fill: {
        type: 'image',
        url: '/image/leafer.jpg',
        mode: 'fit' // 相当于 CSS 的 background-size: contain
    }
})

leafer.add(rect)

// #图案填充 [fit 适应模式 (App)]
import { App, Rect } from 'leafer-ui'
import '@leafer-in/editor' // 导入图形编辑器插件
import '@leafer-in/viewport' // 导入视口插件 (可选)

const app = new App({ view: window, editor: {} })

const rect = new Rect({
    width: 100,
    height: 100,
    fill: {
        type: 'image',
        url: '/image/leafer.jpg',
        mode: 'fit' // 相当于 CSS 的 background-size: contain
    }
})

app.tree.add(rect)

stretch 拉伸模式

LeaferApp

// #图案填充 [stretch 拉伸模式 (Leafer)]
import { Leafer, Rect } from 'leafer-ui'

const leafer = new Leafer({ view: window })

const rect = new Rect({
    width: 100,
    height: 120,
    fill: {
        type: 'image',
        url: '/image/leafer.jpg',
        mode: 'stretch'
    }
})

leafer.add(rect)

// #图案填充 [stretch 拉伸模式 (App)]
import { App, Rect } from 'leafer-ui'
import '@leafer-in/editor' // 导入图形编辑器插件
import '@leafer-in/viewport' // 导入视口插件 (可选)

const app = new App({ view: window, editor: {} })

const rect = new Rect({
    width: 100,
    height: 120,
    fill: {
        type: 'image',
        url: '/image/leafer.jpg',
        mode: 'stretch'
    }
})

app.tree.add(rect)

clip 裁剪模式

LeaferApp

// #图案填充 [clip 裁剪模式 (Leafer)]
import { Leafer, Rect } from 'leafer-ui'

const leafer = new Leafer({ view: window })

const rect = new Rect({
    width: 100,
    height: 100,
    fill: {
        type: 'image',
        url: '/image/leafer.jpg',
        mode: 'clip',
        offset: { x: -40, y: -90 },
        scale: { x: 1.1, y: 1.1 },
        rotation: 20
    }
})

leafer.add(rect)

// #图案填充 [clip 裁剪模式 (App)]
import { App, Rect } from 'leafer-ui'
import '@leafer-in/editor' // 导入图形编辑器插件
import '@leafer-in/viewport' // 导入视口插件 (可选)

const app = new App({ view: window, editor: {} })

const rect = new Rect({
    width: 100,
    height: 100,
    fill: {
        type: 'image',
        url: '/image/leafer.jpg',
        mode: 'clip',
        offset: { x: -40, y: -90 },
        scale: { x: 1.1, y: 1.1 },
        rotation: 20
    }
})

app.tree.add(rect)

repeat 平铺模式

LeaferApp

// #图案填充 [repeat 平铺模式 (Leafer)]
import { Leafer, Rect } from 'leafer-ui'

const leafer = new Leafer({ view: window })

const rect = new Rect({
    width: 100,
    height: 100,
    fill: {
        type: 'image',
        url: '/image/leafer.jpg',
        mode: 'repeat', // 相当于 CSS 的 background-repeat: repeat
        scale: 0.2
    }
})

leafer.add(rect)

// #图案填充 [repeat 平铺模式 (App)]
import { App, Rect } from 'leafer-ui'
import '@leafer-in/editor' // 导入图形编辑器插件
import '@leafer-in/viewport' // 导入视口插件 (可选)

const app = new App({ view: window, editor: {} })

const rect = new Rect({
    width: 100,
    height: 100,
    fill: {
        type: 'image',
        url: '/image/leafer.jpg',
        mode: 'repeat', // 相当于 CSS 的 background-repeat: repeat
        scale: 0.2
    }
})

app.tree.add(rect)

repeat 平铺模式旋转 90 度

LeaferApp

// #图案填充 [repeat 平铺模式旋转 90 度 (Leafer)]
import { Leafer, Rect } from 'leafer-ui'

const leafer = new Leafer({ view: window })

const rect = new Rect({
    width: 100,
    height: 100,
    fill: {
        type: 'image',
        url: '/image/leafer.jpg',
        mode: 'repeat',
        scale: 0.2,
        rotation: 90
    }
})

leafer.add(rect)

// #图案填充 [repeat 平铺模式旋转 90 度 (App)]
import { App, Rect } from 'leafer-ui'
import '@leafer-in/editor' // 导入图形编辑器插件
import '@leafer-in/viewport' // 导入视口插件 (可选)

const app = new App({ view: window, editor: {} })

const rect = new Rect({
    width: 100,
    height: 100,
    fill: {
        type: 'image',
        url: '/image/leafer.jpg',
        mode: 'repeat',
        scale: 0.2,
        rotation: 90
    }
})

app.tree.add(rect)

repeat 平铺模式不随画布缩放

// #图形编辑器 [背景为透明方格的画板]
import { App, Frame, Rect, Platform } from 'leafer-ui'
import '@leafer-in/editor' // 导入图形编辑器插件
import '@leafer-in/viewport' // 导入视口插件 (可选)

const app = new App({
    view: window,
    fill: '#333',
    editor: {},  //  配置 editor 会自动创建并添加 app.editor 实例、tree 层、sky 层
})

// 平铺的透明方格
const svg = Platform.toURL(
    `<svg width="10" height="10" xmlns="http://www.w3.org/2000/svg">
<rect x="0" y="0" width="5" height="5" fill="#FFF"/><rect x="5" y="0" width="5" height="5" fill="#CCC"/>
<rect x="0" y="5" width="5" height="5" fill="#CCC"/><rect x="5" y="5" width="5" height="5" fill="#FFF"/>
</svg>`, 'svg',)


app.tree.add(Frame.one({ // 背景为透明方格的画板
    fill: {
        type: 'image',
        url: svg,
        mode: 'repeat',
        scaleFixed: 'zoom-in' // true // 固定平铺图比例，不随画布缩放
    },
    shadow: {
        x: 0,
        y: 3,
        blur: 15,
        color: '#0009',
        scaleFixed: 'zoom-in' // 固定阴影比例，不随画布放大
    },
    children: [
        Rect.one({ editable: true, fill: '#FEB027', cornerRadius: [20, 0, 0, 20] }, 100, 100),
        Rect.one({ editable: true, fill: '#FFE04B', cornerRadius: [0, 20, 20, 0] }, 300, 100)
    ]
}, 100, 100, 500, 600))

ImagePaint 对象 ​

关键属性 ​

type: string ​

url: string ​

mode?: ImagePaintMode ​

format?: 'svg' | 'jpg' | 'png' | 'webp' ​

changeful?: boolean ​

sync?: boolean ​

基础属性 ​

blendMode?: BlendMode ​

visible?: boolean ​

opacity?: number ​

align: IAlign ​

cover 覆盖模式属性 ​

rotation?: number ​

fit 适应模式属性 ​

rotation?: number ​

padding?: IFourNumber ​

repeat?: boolean ​

clip 裁剪模式属性 ​

clipSize?: ISizeData ​

offset?: IPointData ​

size?: number ｜ IOptionSizeData ​

scale?: number ｜ IPointData ​

rotation?: number ​

repeat 平铺模式属性 ​

offset?: IPointData ​

size?: number ｜ IOptionSizeData ​

scale?: number ｜ IPointData ​

scaleFixed?: boolean | 'zoom-in' ​

rotation?: number ​

freeTransform?: boolean ​

gap?: IGap | IPointGap ​

interlace?: number | IPercentData | IInterlace ​

repeat?: IRepeat ​

子描边属性 ​

style?: IStrokeStyle ​

图片缓存 ​

图片跨域 ​

资源库 ​

图片事件 ​

ImageEvent ​

归属 ​

UI 元素 ​

示例 ​

cover 覆盖模式 ​

cover 覆盖模式旋转 90 度 ​

fit 适应模式 ​

stretch 拉伸模式 ​

clip 裁剪模式 ​

repeat 平铺模式 ​

repeat 平铺模式旋转 90 度 ​

repeat 平铺模式不随画布缩放 ​

ImagePaint 对象

关键属性

type: `string`

url: `string`

mode?: `ImagePaintMode`

format?: `'svg' | 'jpg' | 'png' | 'webp'`

changeful?: `boolean`

sync?: `boolean`

基础属性

blendMode?: `BlendMode`

visible?: `boolean`

opacity?: `number`

align: `IAlign`

cover 覆盖模式属性

rotation?: `number`

fit 适应模式属性

rotation?: `number`

padding?: `IFourNumber`

repeat?: `boolean`

clip 裁剪模式属性

clipSize?: `ISizeData`

offset?: `IPointData`

size?: `number` ｜ `IOptionSizeData`

scale?: `number` ｜ `IPointData`

rotation?: `number`

repeat 平铺模式属性

offset?: `IPointData`

size?: `number` ｜ `IOptionSizeData`

scale?: `number` ｜ `IPointData`

scaleFixed?: `boolean` | `'zoom-in'`

rotation?: `number`

freeTransform?: `boolean`

gap?: `IGap` | `IPointGap`

interlace?: `number` | `IPercentData` | `IInterlace`

repeat?: `IRepeat`

子描边属性

style?: `IStrokeStyle`

图片缓存

图片跨域

资源库

图片事件

ImageEvent

归属

UI 元素

示例

cover 覆盖模式

cover 覆盖模式旋转 90 度

fit 适应模式

stretch 拉伸模式

clip 裁剪模式

repeat 平铺模式

repeat 平铺模式旋转 90 度

repeat 平铺模式不随画布缩放