# 形狀

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [docs/features/shape.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/features/shape.zh-TW.mdx)

---

#### Package metadata

```json
{
  "mobile": true,
  "plugins": [
    {
      "client": "@univerjs-pro/engine-formula"
    },
    {
      "client": "@univerjs-pro/docs-shape"
    },
    {
      "client": "@univerjs-pro/docs-shape-ui",
      "locale": "@univerjs-pro/docs-shape-ui/locale/zh-TW",
      "style": "@univerjs-pro/docs-shape-ui/lib/index.css"
    }
  ],
  "license": true,
  "server": false
}
```

形狀功能允許您在文件中插入和編輯形狀與繪圖，包括基本幾何形狀、箭頭和流程圖元素。

## 介紹

在 Univer Docs 中，形狀使您能夠：

* **插入幾何形狀**：新增矩形、圓形、箭頭等。
* **自訂外觀**：調整填充顏色、邊框和文字。
* **自由定位**：將形狀放置在文件中的任意位置。

## 外掛模式

### 安裝

#### npm

```bash
npm install @univerjs-pro/engine-formula @univerjs-pro/docs-shape @univerjs-pro/docs-shape-ui
```

#### pnpm

```bash
pnpm add @univerjs-pro/engine-formula @univerjs-pro/docs-shape @univerjs-pro/docs-shape-ui
```

#### yarn

```bash
yarn add @univerjs-pro/engine-formula @univerjs-pro/docs-shape @univerjs-pro/docs-shape-ui
```

#### bun

```bash
bun add @univerjs-pro/engine-formula @univerjs-pro/docs-shape @univerjs-pro/docs-shape-ui
```

> [!WARN]
> 形狀還依賴 `@univerjs-pro/engine-formula` 中的 `UniverProFormulaEnginePlugin`。請將基礎初始化程式碼中原有的 `UniverFormulaEnginePlugin` 匯入與註冊替換為此插件。不要同時註冊兩種公式引擎，否則插入形狀時可能出現相依項目未註冊的錯誤。

### 使用

```typescript
import { UniverDocsShapePlugin } from '@univerjs-pro/docs-shape' // [!code ++]
import { UniverDocsShapeUIPlugin } from '@univerjs-pro/docs-shape-ui' // [!code ++]
import DocsShapeUIZhTW from '@univerjs-pro/docs-shape-ui/locale/zh-TW' // [!code ++]
import { UniverProFormulaEnginePlugin } from '@univerjs-pro/engine-formula' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'

import '@univerjs-pro/docs-shape-ui/lib/index.css' // [!code ++]

const univer = new Univer({
  locale: LocaleType.ZH_TW,
  locales: {
    [LocaleType.ZH_TW]: mergeLocales(
      DocsShapeUIZhTW, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverProFormulaEnginePlugin) // [!code ++]
univer.registerPlugin(UniverDocsShapePlugin) // [!code ++]
univer.registerPlugin(UniverDocsShapeUIPlugin) // [!code ++]
```

如果您擁有 Univer 商業授權，請參閱[在用戶端使用授權](https://docs.univer.ai/zh-TW/server/license.md#in-plugin-mode)進行配置。

## 行動裝置支援

先設定[行動版編輯器](https://docs.univer.ai/zh-TW/guides/docs/getting-started/installation.md#mobile-support)。在本頁外掛模式的初始化程式碼中，將下列桌面版註冊替換為同一套件匯出的行動版外掛，並在**開啟文件前**完成。保留模型外掛、樣式、語言套件與 Facade 匯入，請勿同時註冊兩個版本。

| 套件                            | 桌面版註冊                     | 行動版註冊                           |
| ----------------------------- | ------------------------- | ------------------------------- |
| `@univerjs-pro/docs-shape-ui` | `UniverDocsShapeUIPlugin` | `UniverDocsShapeMobileUIPlugin` |

## 編輯形狀文字

使用下方或前面範例中 `insertShape()` 回傳的形狀物件。`getText()` 回傳即時的 [FShapeText](https://docs.univer.ai/zh-TW/reference/facade/shape-text.md) 物件，可透過 `getPlainText()` 讀取純文字、`setText()` 取代全部文字，並設定字型、顏色與對齊方式。

```ts
import '@univerjs-pro/docs-shape/facade'

const document = univerAPI.getActiveDocument()
const paragraph = document?.getParagraphs()[0]
if (!document || !paragraph) throw new Error('No active document paragraph')
const shape = document.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  placement: {
    wrappingStyle: univerAPI.Enum.TextWrappingStyle.INLINE,
    anchor: { paragraphId: paragraph.getId(), segmentId: paragraph.getSegmentId() },
  },
})
if (!shape) throw new Error('Shape is not available')
const shapeText = shape.getText()
console.log(shapeText.getPlainText())
shapeText
  .setText('Quarterly review')
  .setFontSize(18)
  .setColor('#2563eb')
  .setBold(true)
  .setHorizontalAlign(univerAPI.Enum.HorizontalAlign.CENTER)
  .setVerticalAlign(univerAPI.Enum.VerticalAlign.MIDDLE)
```

`setText()` 會取代既有文字；同一形狀需要多種文字樣式時，請使用 `setRichText()`。編輯既有豐富文字時，先呼叫 `getRichText()?.copy()`，修改建構器後再傳給 `setRichText()`；僅修改建構器不會自動寫回。更多選項請參閱[文字樣式](https://docs.univer.ai/zh-TW/reference/facade/shape-text.md#settextstyle)與[文字方塊內距和版面配置](https://docs.univer.ai/zh-TW/reference/facade/shape-text.md#settextboxoptions)。

```ts
const richText = univerAPI.newRichText()
  .text('Quarterly ')
  .bold('review')
shapeText.setRichText(richText)
```

## 圖案格式刷

選取來源圖案，啟用格式刷，再選取目標。格式刷複製填滿、外框、效果與支援的文字格式，保留目標識別、幾何、文字內容及公式繫結。清除格式會還原插入時的預設樣式。SmartArt 不適用；對應的圖案 UI 外掛會自動註冊此行為。