# 要素

- Human documentation: [https://docs.univer.ai/ja-JP/guides/boards/features/core/elements](https://docs.univer.ai/ja-JP/guides/boards/features/core/elements)

- Agent Markdown: [https://docs.univer.ai/ja-JP/guides/boards/features/core/elements.md](https://docs.univer.ai/ja-JP/guides/boards/features/core/elements.md)

- Requested language: `ja-JP`

- Content language: `ja-JP`

- Documentation version: `1.1.0`

- Source: [boards/features/core/elements.ja-JP.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/boards/features/core/elements.ja-JP.mdx)

---

要素は、テキスト、画像、図形、コネクターなど Board 上に表示されるコンテンツです。`FBoard` facade による要素の変更は通常のコマンド経路を通るため、元に戻す、やり直し、共同編集の対象になります。

## 要素を読み取る

アクティブページを読む前に、アクティブな Board を取得します。内部スナップショット全体に依存せず、安定した ID、種類、境界、順序が必要な場合はディスクリプターを使用します。

```ts
const board = univerAPI.getActiveBoard()
if (!board) throw new Error('No active board')

const elements = board.describeElements()
const shapes = board.findElements({
  elementType: univerAPI.Enum.BoardElementType.Shape,
})
```

## 図形とテキストを挿入する

低レベルの要素スナップショットを組み立てる代わりに、用途別の挿入メソッドを使用します。`insertShape` のジオメトリは `transform` に指定し、返された図形ハンドルからテキストやスタイルの API を利用できます。

```ts
const shape = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.RoundRect,
  transform: { left: 80, top: 80, width: 180, height: 100 },
  name: 'Review card',
})
if (!shape) throw new Error('Cannot insert shape')

shape.getText().setText('Review')
shape.setRotation(6)
```

独立したテキストには `insertText`、画像には `insertImage`、複数の要素を 1 つのコマンドで追加する場合は一括メソッドを使用します。

## 図形のテキストを編集する

以下または前の例で `insertShape()` が返す図形を使用します。`getText()` はライブの [FShapeText](https://docs.univer.ai/ja-JP/reference/facade/shape-text.md) オブジェクトを返します。`getPlainText()` でテキストを読み取り、`setText()` で全文を置き換え、フォント、色、配置を設定できます。

```ts
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/ja-JP/reference/facade/shape-text.md#settextstyle)と[テキストボックスの余白・レイアウト](https://docs.univer.ai/ja-JP/reference/facade/shape-text.md#settextboxoptions)も参照してください。

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

## 要素を接続する

コネクターは既存要素の ID に接続できます。後でスタイル、ラベル、端点を更新できるよう、返されたコネクターまたはその ID を保持します。

```ts
const target = board.insertShape({
  shapeType: univerAPI.Enum.ShapeTypeEnum.Rect,
  transform: { left: 360, top: 80, width: 180, height: 100 },
})
if (!target) throw new Error('Cannot insert target')

const connector = board.insertConnector({
  fromElementId: shape.getId(),
  toElementId: target.getId(),
  style: { endMarker: { type: 'filledTriangle', size: 'md' } },
})
if (!connector) throw new Error('Cannot insert connector')
```

## 要素を変形・配置する

必要なプロパティだけを変更します。重なり順、整列、分布、自動レイアウトのメソッドも要素 ID を受け取ります。

```ts
if (!board.setElementTransform(shape.getId(), { left: 120, top: 140, rotation: 12 })) {
  throw new Error('Cannot transform shape')
}

if (!board.bringElementsToFront([shape.getId()])) {
  throw new Error('Cannot bring shape to front')
}
```

## 要素を削除する

1 つの要素には `removeElement`、複数要素のアトミックな削除には `removeElements` を使用します。どちらもコマンドが成功したかを返します。

```ts
if (!board.removeElements([connector.id, target.getId()])) {
  throw new Error('Cannot remove elements')
}
```

枠付きグループとスイムレーンについては、[コンテナーとスイムレーン](https://docs.univer.ai/ja-JP/guides/boards/features/core/containers.md) に進んでください。[Boards facade リファレンス](https://docs.univer.ai/ja-JP/reference/facade/board.md)と[Board 要素のデータモデル](https://docs.univer.ai/ja-JP/guides/boards/model/board-elements.md)も参照してください。