# 内容控件

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

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

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0`

- Source: [docs/features/content-controls.zh-CN.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/features/content-controls.zh-CN.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-CN'
import { LocaleType } from '@univerjs/core'

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

univerAPI.loadLocales(LocaleType.ZH_CN, 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-CN/reference/packages/plugins/univerjs-pro/docs-sdt.md)和 [UI API](https://docs.univer.ai/zh-CN/reference/packages/plugins/univerjs-pro/docs-sdt-ui.md)。DOCX 转换由 [Exchange](https://docs.univer.ai/zh-CN/guides/docs/features/import-export.md) 提供；编辑器支持不代表所有 Word 属性和自定义 XML 绑定均可无损转换。