形狀
在 Univer Sheets 中，形狀（Shapes）可用於建立流程圖、註解標示、提示框，以及在工作表上建立視覺化說明。
插件模式
安裝
Shell
pnpm add @univerjs-pro/engine-formula @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-uiShell
npm install @univerjs-pro/engine-formula @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-uiShell
yarn add @univerjs-pro/engine-formula @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-uiShell
bun add @univerjs-pro/engine-formula @univerjs/drawing @univerjs/drawing-ui @univerjs/sheets-drawing @univerjs/sheets-drawing-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-ui形狀還依賴 @univerjs-pro/engine-formula 中的 UniverProFormulaEnginePlugin。請將基礎初始化程式碼中原有的 UniverFormulaEnginePlugin 匯入與註冊替換為此插件。不要同時註冊兩種公式引擎，否則插入形狀時可能出現相依項目未註冊的錯誤。
形狀插件依賴繪圖插件，註冊形狀插件前必須先註冊 UniverDrawingPlugin、UniverSheetsDrawingPlugin、UniverDrawingUIPlugin 和 UniverSheetsDrawingUIPlugin。
使用
TypeScript
import { UniverProFormulaEnginePlugin } from '@univerjs-pro/engine-formula'import { UniverSheetsShapePlugin } from '@univerjs-pro/sheets-shape'import { UniverSheetsShapeUIPlugin } from '@univerjs-pro/sheets-shape-ui'import SheetsShapeUIZhTW from '@univerjs-pro/sheets-shape-ui/locale/zh-TW'import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { UniverDrawingPlugin } from '@univerjs/drawing'import { UniverDrawingUIPlugin } from '@univerjs/drawing-ui'import DrawingUIZhTW from '@univerjs/drawing-ui/locale/zh-TW'import { UniverSheetsDrawingPlugin } from '@univerjs/sheets-drawing'import { UniverSheetsDrawingUIPlugin } from '@univerjs/sheets-drawing-ui'import SheetsDrawingUIZhTW from '@univerjs/sheets-drawing-ui/locale/zh-TW'import '@univerjs-pro/sheets-shape/facade'import '@univerjs/drawing-ui/lib/index.css'import '@univerjs/sheets-drawing-ui/lib/index.css'import '@univerjs-pro/sheets-shape-ui/lib/index.css'const univer = new Univer({ locale: LocaleType.ZH_TW, locales: { [LocaleType.ZH_TW]: mergeLocales( DrawingUIZhTW, SheetsDrawingUIZhTW, SheetsShapeUIZhTW, ), },})univer.registerPlugin(UniverProFormulaEnginePlugin)univer.registerPlugin(UniverDrawingPlugin)univer.registerPlugin(UniverDrawingUIPlugin)univer.registerPlugin(UniverSheetsDrawingPlugin)univer.registerPlugin(UniverSheetsDrawingUIPlugin)univer.registerPlugin(UniverSheetsShapePlugin)univer.registerPlugin(UniverSheetsShapeUIPlugin)如果你持有 Univer 商業授權，請參考 在客戶端使用 License 進行設定。
行動裝置支援
先設定行動版編輯器。在本頁外掛模式的初始化程式碼中，將下列桌面版註冊替換為同一套件匯出的行動版外掛，並在開啟文件前完成。保留模型外掛、樣式、語言套件與 Facade 匯入，請勿同時註冊兩個版本。
| 套件 | 桌面版註冊 | 行動版註冊 |
|---|---|---|
@univerjs/drawing-ui | UniverDrawingUIPlugin | UniverDrawingMobileUIPlugin |
@univerjs/sheets-drawing-ui | UniverSheetsDrawingUIPlugin | UniverSheetsDrawingMobileUIPlugin |
@univerjs-pro/sheets-shape-ui | UniverSheetsShapeUIPlugin | UniverSheetsShapeMobileUIPlugin |
預設模式
形狀功能已包含在 @univerjs/preset-sheets-advanced 預設中。此預設已註冊 UniverProFormulaEnginePlugin，無需手動替換公式引擎。
安裝
@univerjs/preset-sheets-advanced 的 UniverSheetsAdvancedPreset 在執行時依賴 UniverSheetsDrawingPreset，請先安裝 @univerjs/preset-sheets-drawing。
Shell
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedShell
npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedShell
yarn add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedShell
bun add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced使用
TypeScript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'import UniverPresetSheetsAdvancedZhTW from '@univerjs/preset-sheets-advanced/locales/zh-TW'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhTW from '@univerjs/preset-sheets-core/locales/zh-TW'import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'import UniverPresetSheetsDrawingZhTW from '@univerjs/preset-sheets-drawing/locales/zh-TW'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-drawing/lib/index.css'import '@univerjs/preset-sheets-advanced/lib/index.css'const { univerAPI } = createUniver({ locale: LocaleType.ZH_TW, locales: { [LocaleType.ZH_TW]: mergeLocales( UniverPresetSheetsCoreZhTW, UniverPresetSheetsDrawingZhTW, UniverPresetSheetsAdvancedZhTW, ), }, presets: [ UniverSheetsCorePreset(), UniverSheetsDrawingPreset(), UniverSheetsAdvancedPreset(), ],})如果你持有 Univer 商業授權，請參考 在客戶端使用 License 進行設定。
Facade API
完整 Facade API 類型定義，請查看 FacadeAPI。
導入
插件模式說明
僅插件模式需要手動匯入 Facade 套件。預設模式已內建對應 Facade，無需額外匯入。
TypeScript
import '@univerjs-pro/sheets-shape/facade'插入基礎形狀
向 FWorksheet.insertShape 傳入通用形狀建立資料，它會回傳可直接操作的 Facade 實例。
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const rectShape = fWorksheet.insertShape({ shapeType: univerAPI.Enum.ShapeTypeEnum.Rect, transform: { left: 120, top: 80, width: 240, height: 120 }, shapeData: { fill: { fillType: univerAPI.Enum.ShapeFillEnum.SolidFill, color: '#e6f4ff', }, stroke: { lineStrokeType: univerAPI.Enum.ShapeLineTypeEnum.SolidLine, color: '#1677ff', width: 2, }, },})if (!rectShape) throw new Error('Shape could not be inserted.')編輯形狀文字
使用下方或前面範例中 insertShape() 回傳的形狀物件。getText() 回傳即時的 FShapeText 物件，可透過 getPlainText() 讀取純文字、setText() 取代全部文字，並設定字型、顏色與對齊方式。
TypeScript
if (!rectShape) throw new Error('Shape is not available')const shapeText = rectShape.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()；僅修改建構器不會自動寫回。更多選項請參閱文字樣式與文字方塊內距和版面配置。
TypeScript
const richText = univerAPI.newRichText() .text('Quarterly ') .bold('review')shapeText.setRichText(richText)插入並連接連接線形狀
透過 FWorksheet.insertShape 插入連接線，再使用回傳的 FConnectorShape Facade 綁定兩端。
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const leftShape = fWorksheet.insertShape({ shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect, transform: { left: 80, top: 80, width: 180, height: 100 },})const rightShape = fWorksheet.insertShape({ shapeType: univerAPI.Enum.ShapeTypeEnum.Ellipse, transform: { left: 420, top: 200, width: 180, height: 100 },})const connectorShape = fWorksheet.insertShape({ shapeType: univerAPI.Enum.ShapeTypeEnum.BentConnector3, transform: { left: 240, top: 130, width: 240, height: 120 },})if (!leftShape || !rightShape || !connectorShape) { throw new Error('Shapes could not be inserted.')}const startSite = leftShape.getConnectionSites()[0]const rightSites = rightShape.getConnectionSites()const endSite = rightSites[2] ?? rightSites[0]if (!startSite || !endSite) throw new Error('Connection site not found.')connectorShape .bindStart(leftShape.getId(), startSite.index) .bindEnd(rightShape.getId(), endSite.index) .setEndArrow(univerAPI.Enum.ShapeArrowTypeEnum.Arrow)更新與刪除形狀
直接透過形狀的 Facade 實例更新或刪除形狀。
TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const firstShape = fWorksheet.getShapes().find(shape => !shape.isConnectorShape())if (firstShape) { firstShape .setStrokeColor('#ff4d4f') .setStrokeWidth(3) .setSolidFill('#fff1f0') // 如有需要，可在更新後刪除該形狀 const removed = firstShape.remove() console.log(removed)}圖案格式刷
選取來源圖案，啟用格式刷，再選取目標。格式刷複製填滿、外框、效果與支援的文字格式，保留目標識別、幾何、文字內容及公式繫結。清除格式會還原插入時的預設樣式。SmartArt 不適用；對應的圖案 UI 外掛會自動註冊此行為。
你覺得這篇文檔如何？