# 内容控件(ContentControls)

文档中的内容控件对象集合

### 属性列表

|属性|说明|
|-|-|
|[Count](#count)|获取文档内容控件的数量|

### 方法列表

|方法|说明|
|-|-|
|[Add({ Type })](#add-type)|在光标处插入内容控件|
|[Item()](#item)|返回一个 ContentControl 对象，该对象代表文档中内容控件集合中的指定内容控件|
|[Item(Index).Range](#item-index-range)|内容控件的范围|
|[Item(Index).Tag](#item-index-tag)|内容控件的标签|
|[Item(Index).Title](#item-index-title)|内容控件的标题|
|[Item(Index).DropdownListEntries](#item-index-dropdownlistentries)|获取下拉列表内容控件中的所有项。只读。返回 [ContentControlListEntries](/app-integration-dev/docs-center/online-preview-edit/client/Word/ContentControlListEntries.html#contentcontrollistentries) 对象，代表下拉内容控件的下拉列表|
|[Item(Index).PlaceholderText](#item-index-placeholdertext)|获取内容控件占位符文本|
|[Item(Index).SetPlaceholderText()](#item-index-setplaceholdertext)|设置内容控件占位符文本|

## Count

获取文档内容控件的数量

### 语法

表达式：`ActiveDocument.ContentControls.Count`

表达式：文档类型应用对象

### 返回值

返回 `Number` 代表文档内容控件的数量。

### 示例

```js
//@file=base.docx
// 获取文档内容控件的数量
async function example() {
  await instance.ready()

  const app = instance.Application

  // 内容控件对象
  const contentControls = await app.ActiveDocument.ContentControls

  // 内容控件数量
  const count = await contentControls.Count
  console.log(count)
}
```

## Add({ Type })

在光标处插入内容控件

### 语法

`表达式.ActiveDocument.ContentControls.Add({ Type })`

表达式：文档类型应用对象

### 参数

> Type 属性于 JSSDK: v1.1.15+ 新增支持，支持下拉内容控件的添加

| 属性 | 数据类型 | 默认值 | 必填 | 说明                                                                                                                                   |
| ---- | -------- | ------ | ---- | -------------------------------------------------------------------------------------------------------------------------------------- |
| Type | Enum     |        | 是   | 内容控件类型，如果省略 Type，默认插入 RTF 内容控件。可以是 [WdContentControlType](/app-integration-dev/docs-center/online-preview-edit/client/Enum/Word.html#wdcontentcontroltype) 常量之一 |

### 返回值

返回新增的 ContentControl 对象

### 示例 1：添加 RTF 内容控件

```js
//@file=base.docx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 内容控件对象
  const contentControls = await app.ActiveDocument.ContentControls

  // 在光标处插入内容控件
  await contentControls.Add()
}
```

### 示例 2：添加下拉内容控件

```js
//@file=base.docx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 内容控件对象
  const contentControls = await app.ActiveDocument.ContentControls

  // 在光标处插入下拉内容控件
  await contentControls.Add({
    Type: 4
  })
}
```

## Item()

返回一个 ContentControl 对象，该对象代表文档中内容控件集合中的指定内容控件

### 语法

`表达式.ActiveDocument.ContentControls.Item(Index)`

表达式：文档类型应用对象

### 参数

| 属性  | 数据类型 | 默认值 | 必填 | 说明                |
| ----- | -------- | ------ | ---- | ------------------- |
| Index | Number   |        | 是   | 第 Index 个内容控件 |

### 返回值

返回 ContentControl 对象

### 示例

```js
//@file=base.docx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 返回第  1 个 ContentControl 对象
  const contentControl = await app.ActiveDocument.ContentControls.Item(1)
}
```

## Item(Index).Range

内容控件的范围

> 可以通过 Range.Text，来获取和设置内容控件的文本值

### 语法

`表达式.ActiveDocument.ContentControls.Item(Index).Range`

表达式：文档类型应用对象

### 示例 1：获取内容控件的范围

```js
//@file=base.docx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 内容控件对象
  const contentControls = await app.ActiveDocument.ContentControls

  // 获取第 1 个内容控件
  const contentControl = await contentControls.Item(1)

  // 获取第 1 个内容控件的范围
  const range = await contentControl.Range
  console.log(range)
}
```

### 示例 2：获取和设置内容控件的文本值

```js
//@file=base.docx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 内容控件对象
  const contentControls = await app.ActiveDocument.ContentControls

  // 获取第 1 个内容控件
  const contentControl = await contentControls.Item(1)

  // 获取第 1 个内容控件的范围
  const range = await contentControl.Range

  // 获取第 1 个内容控件的文本
  const text = range.Text
  console.log(text)

  // 设置第 1 个内容控件的文本
  range.Text = 'WebOffice'
}
```

## Item(Index).Tag

内容控件的标签

### 语法

`表达式.ActiveDocument.ContentControls.Item(Index).Tag`

表达式：文档类型应用对象

### 示例

```js
//@file=base.docx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 内容控件对象
  const contentControls = await app.ActiveDocument.ContentControls

  // 获取第 1 个内容控件
  const contentControl = await contentControls.Item(1)

  // 设置第 1 个内容控件的标签
  contentControl.Tag = 'WebOffice'

  // 获取第 1 个内容控件的标签
  const Tag = await contentControl.Tag
  console.log(Tag)
}
```

## Item(Index).Title

内容控件的标题

### 语法

`表达式.ActiveDocument.ContentControls.Item(Index).Title`

表达式：文档类型应用对象

### 示例

```js
//@file=base.docx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 内容控件对象
  const contentControls = await app.ActiveDocument.ContentControls

  // 获取第 1 个内容控件
  const contentControl = await contentControls.Item(1)

  // 设置第 1 个内容控件的标题
  contentControl.Title = 'WebOffice'

  // 获取第 1 个内容控件的标题
  const title = await contentControl.Title
  console.log(title)
}
```

## Item(Index).ID

【只读】内容控件的ID标识

### 语法

`表达式.ActiveDocument.ContentControls.Item(Index).ID`

表达式：文档类型应用对象

### 示例

```js
//@file=base.docx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 内容控件对象
  const contentControls = await app.ActiveDocument.ContentControls

  // 获取第 1 个内容控件
  const contentControl = await contentControls.Item(1)

  // 获取第 1 个内容控件的ID
  const ID = await contentControl.ID
  console.log(ID)
}
```


## Item(Index).DropdownListEntries

获取下拉列表内容控件中的所有项。只读。返回 [ContentControlListEntries](/app-integration-dev/docs-center/online-preview-edit/client/Word/ContentControlListEntries.html#contentcontrollistentries) 对象，代表下拉内容控件的下拉列表

### 语法

`表达式.ActiveDocument.ContentControls.Item(Index).DropdownListEntries`

表达式：文档类型应用对象

### 示例 1：通过新增下拉内容控件来获取下拉列表

```js
//@file=base.docx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 内容控件对象
  const ContentControls = await app.ActiveDocument.ContentControls

  // 1、新增一个下拉内容控件
  const ContentControl = await ContentControls.Add({
    Type: 4
  })

  // 2、获取该下拉内容控件的下拉列表
  const ContentControlListEntries = await ContentControl.DropdownListEntries
}
```

### 示例 2：通过指定项来获取下拉列表

```js
//@file=base.docx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 内容控件对象
  const ContentControls = await app.ActiveDocument.ContentControls

  // 1、新增一个下拉内容控件
  const ContentControl = await ContentControls.Add({
    Type: 4
  })

  // 2、获取文档中的内容控件数量（包含文本和下拉内容控件）
  // 假设这里有 2 个（打印为 2），那么新增的那个内容控件就是第 2 个
  const Count = await app.ActiveDocument.ContentControls.Count

  // 3、获取第 2 个下拉内容控件的下拉列表
  const ContentControlListEntries =
    await app.ActiveDocument.ContentControls.Item(Count).DropdownListEntries
}
```

## Item(Index).PlaceholderText

获取内容控件占位符文本

### 语法

`表达式.ActiveDocument.ContentControls.Item(Index).PlaceholderText`

表达式：文档类型应用对象

### 示例

```js
//@file=base.docx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 内容控件对象
  const contentControls = await app.ActiveDocument.ContentControls

  // 获取第 1 个内容控件
  const contentControl = await contentControls.Item(1)

  // 获取第 1 个内容控件占位符文本
  const placeholderText = await contentControl.PlaceholderText
  console.log(placeholderText)
}
```

## Item(Index).SetPlaceholderText()

设置内容控件占位符文本

### 语法

`表达式.ActiveDocument.ContentControls.Item(Index).SetPlaceholderText({ Text })`

表达式：文档类型应用对象

### 参数

| 属性 | 数据类型 | 默认值 | 必填 | 说明                      |
| ---- | -------- | ------ | ---- | ------------------------- |
| Text | String   |        | 是   | 第 Index 个内容控件的文本 |

### 示例

```js
//@file=base.docx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 内容控件对象
  const contentControls = await app.ActiveDocument.ContentControls

  // 获取第 1 个内容控件
  const contentControl = await contentControls.Item(1)

  // 设置第 1 个内容控件的文本
  await contentControl.SetPlaceholderText({ Text: 'WebOffice' })
}
```