# 內容控制項

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

內容控制項（SDT）支援豐富文字、純文字、核取方塊、日期、清單、圖片、群組、重複區段及文件組件。先設定 Docs 核心與 Pro 授權外掛，再於建立文件前註冊下列套件。將 UI 語言包合併至 `locales` 並載入樣式。Docs 進階預設未包含這些套件。

#### npm

```bash
npm install @univerjs-pro/docs-sdt @univerjs-pro/docs-sdt-ui
```

#### pnpm

```bash
pnpm add @univerjs-pro/docs-sdt @univerjs-pro/docs-sdt-ui
```

#### yarn

```bash
yarn add @univerjs-pro/docs-sdt @univerjs-pro/docs-sdt-ui
```

#### bun

```bash
bun add @univerjs-pro/docs-sdt @univerjs-pro/docs-sdt-ui
```

```ts
import { UniverDocsSdtPlugin } from '@univerjs-pro/docs-sdt'
import { UniverDocsSdtUIPlugin } from '@univerjs-pro/docs-sdt-ui'
import FeatureLocale from '@univerjs-pro/docs-sdt-ui/locale/zh-TW'
import { LocaleType } from '@univerjs/core'

import '@univerjs-pro/docs-sdt-ui/lib/index.css'

univerAPI.loadLocales(LocaleType.ZH_TW, FeatureLocale)

univer.registerPlugin(UniverDocsSdtPlugin)
univer.registerPlugin(UniverDocsSdtUIPlugin)
```

## 在選取範圍插入

命令使用目前文字選取範圍；控制項支援時會包住既有內容。重複區段項目透過父區段建立，不獨立插入。

```ts
import { InsertSdtCommand } from '@univerjs-pro/docs-sdt-ui'

await univerAPI.executeCommand(InsertSdtCommand.id, { kind: 'checkbox' })
```

## 鎖定與持久化

控制項以 `CustomRangeType.SDT` 範圍存於 `IDocumentBody.customRanges`，中繼資料位於 `ISdtCustomRange.properties`。內容鎖防止值變更，控制項鎖防止移除外層；重複區段也可禁止新增或刪除項目。透過命令變更內容、屬性及重複項目，以維持復原與重做一致。

參閱[模型命令](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs-pro/docs-sdt.md)與 [UI API](https://docs.univer.ai/zh-TW/reference/packages/plugins/univerjs-pro/docs-sdt-ui.md)。DOCX 轉換由 [Exchange](https://docs.univer.ai/zh-TW/guides/docs/features/import-export.md) 提供；編輯器支援不代表所有 Word 屬性與自訂 XML 繫結都可無損轉換。