# 在 Canvas 上绘制图标

- Human documentation: [https://docs.univer.ai/zh-CN/guides/icons/canvas](https://docs.univer.ai/zh-CN/guides/icons/canvas)

- Agent Markdown: [https://docs.univer.ai/zh-CN/guides/icons/canvas.md](https://docs.univer.ai/zh-CN/guides/icons/canvas.md)

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.6.0`

- Source: [icons/canvas.zh-CN.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/icons/canvas.zh-CN.mdx)

---

从 `@univerjs/icons-svg` 1.48.0 或更高版本导入 `drawCanvasIcon`，即可在 Canvas 2D 上下文中同步绘制内置图标。

```package-install
npm install @univerjs/icons-svg
```

## 绘制筛选图标

在页面中添加画布，等元素创建后运行下面的代码。

```html
<canvas id="toolbar-icons" width="48" height="24"></canvas>
```

```ts
import { drawCanvasIcon } from '@univerjs/icons-svg'

const canvas = document.querySelector<HTMLCanvasElement>('#toolbar-icons')
const ctx = canvas?.getContext('2d')

if (ctx) {
  drawCanvasIcon(ctx, 'filter-applied-icon', 4, 4, 16, '#2563eb')
}
```

前两个数字是绘制区域左上角的坐标，第三个是正方形区域的边长，单位为画布坐标单位。图标保持原始宽高比，在区域内居中。

## 选择图标和颜色

导出的 `CanvasIconName` 类型提供受支持名称的自动补全。名称取自去掉 `.svg` 的文件名，例如 `filter-applied-icon`。图标目录中只有部分 SVG 支持 Canvas。

省略最后一个参数会保留 SVG 原色。传入单一颜色会同时替换主色和强调色。要单独替换某种颜色，可传入以 SVG 原色为键的映射。下面的示例把半星的填充部分改为金色。

```ts
if (ctx) {
  drawCanvasIcon(ctx, 'star-incomplete-double-icon', 28, 4, 16, { black: '#d97706' })
}
```

## 在 Univer 场景中绘制图标

`@univerjs/engine-render` 导出 `CanvasIconShape`，用于把 Canvas 图标绘制为场景图形。构造函数为 `(key, icon, props)`：`key` 标识图形，`icon` 是 `CanvasIconName`，`props` 是 `IShapeProps`。通过 `scene.addObject(shape)` 把图形添加到场景。

```ts
import { CanvasIconShape, IRenderManagerService } from '@univerjs/engine-render'

// 要绘制图标的单元。
const unitId = 'your-unit-id'
const render = univer.__getInjector().get(IRenderManagerService).getRenderUnitById(unitId)

if (render) {
  const shape = new CanvasIconShape('filter-icon', 'filter-applied-icon', {
    left: 24,
    top: 16,
    width: 16,
    height: 16,
    fill: '#2563eb',
  })

  render.scene.addObject(shape)
}
```

图形以 `Math.min(width, height)` 作为图标方框，并在剩余空间中居中。非正方形图形会在较长的一侧留出额外空间。
