# 在 Canvas 上繪製圖示

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.6.0`

- Source: [icons/canvas.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/icons/canvas.zh-TW.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)` 作為圖示方框，並在剩餘空間中置中。非正方形圖形會在較長的一側留下留白。
