# パノラマタグを追加する — Dnalogel

型付きのテキストホットスポットを読み込み、クリックに応答し、終了時に削除します。

Canonical: https://developer.realsee.ai/ja/docs/dnalogel/panorama-tags
Source: https://developer.realsee.ai/ja/docs/dnalogel/panorama-tags.md
Language: ja

# パノラマタグを追加する

撮影した空間内の地点を名前付きで示すにはテキストホットスポットを使います。例では [クイックスタート](https://developer.realsee.ai/ja/docs/dnalogel/quickstart) の `PanoTagPlugin` を使います。

<span id="supply-a-position-in-the-current-scene" class="docs-anchor-alias" aria-hidden="true"></span>

## 現在のシーンの座標を渡す

タグの `position` は画面のピクセルではなく 3 つの数値による空間座標です。現在の Work やシーン編集工程から取得してください。別シーンの任意の座標を流用し、見えないことを読み込み失敗と判断しないでください。

`Tag<'Text', '2DPoint'>` が内容と配置形状を定めます。テキストは `title` と `description` を使い、古い `text` は非推奨です。

```ts title="examples/sdk-guides/src/dnalogel/tags.ts"
import type { PanoTagPlugin, Tag } from '@realsee/dnalogel'

type TagsController = ReturnType<typeof PanoTagPlugin>

export async function addTextHotspot(tags: TagsController, position: [number, number, number]) {
  const tag: Tag<'Text', '2DPoint'> = {
    id: 'welcome', contentType: 'Text', stickType: '2DPoint', position,
    data: { title: 'Welcome', description: 'Explore this captured space.' }
  }
  await tags.load({ tagList: [tag] })
  tags.enable()
  await tags.show()
  const stop = tags.hooks.on('click', ({ tag: clicked }) => {
    if (clicked.id === 'welcome') tags.changeUnfoldedById('welcome', true)
  })
  return () => { stop(); tags.destroyTagById('welcome') }
}
```

準備済みコントローラーと座標で関数を呼び、返された cleanup を保持します。`load({ tagList })` は既存データを置き換えます。追加する場合は `addTag()` を使います。

<span id="change-or-remove-a-hotspot" class="docs-anchor-alias" aria-hidden="true"></span>

## ホットスポットを変更・削除する

`changeDataById`、`changePositionById`、`changeEnabledById`、`changeUnfoldedById`、`destroyTagById` を使えます。安定した ID を保持して対象を指定します。クリックの購読は **`tags.hooks.on('click', ...)`** であり、`tags.on(...)` ではありません。

cleanup はクリック購読を解除し、タグを削除します。Five の所有側はアンマウント時にクイックスタートの `dispose()` も呼びます。

<span id="verify" class="docs-anchor-alias" aria-hidden="true"></span>

## 確認する

適切な視点からタグが見え、クリックで開き、cleanup 後に消えることを確認します。別方向を向いて戻る操作も試してください。load の成功だけでは座標が可視範囲にあると証明できません。

[公開コントローラー](https://unpkg.com/@realsee/dnalogel@3.81.10/libs/PanoTagPlugin/controller/index.d.ts) · [タグのスキーマ](https://unpkg.com/@realsee/dnalogel@3.81.10/libs/PanoTagPlugin/typings/tag/Tag.d.ts)