金山文档开放平台

主题

回到顶部
本页内容

区域

Range

表示一个单元格、一行、一列、一个包含单个或若干连续单元格区域的选定单元格范围

语法

表达式.Range

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1')
}

Cells

区域中的单元格，返回一个 Range 对象（可使用 Range 相关的属性、方法）

语法

表达式.Range.Cells

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:B2')

  // 单元格对象
  const cells = await range.Cells

  // 指定单元格
  const cell = await cells.Item(1)
  window.cells = cells

  // 选中第 1 个单元格
  await cell.Select()
}

Column

区域中第一列的列号

语法

表达式.Range.Column

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:B2')

  // 区域中第一列的列号
  const column = await range.Column
  console.log(column)
}

ColumnEnd

区域中最后一列的列号

语法

表达式.Range.ColumnEnd

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:B2')

  // 区域中最后一列的列号
  const columnEnd = await range.ColumnEnd
  console.log(columnEnd)
}

Columns

区域中的列，返回一个 Range 对象（可使用 Range 相关的属性、方法）

语法

表达式.Range.Columns

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:B2')

  // 列对象
  const columns = await range.Columns

  // 指定列
  const column = await columns.Item(2)

  // 选中第 2 列
  await column.Select()
}

ColumnWidth

区域宽度

语法

表达式.Range.ColumnWidth

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:B2')

  // 区域宽度
  range.ColumnWidth = 30
}

Count

区域中单元格的数量

语法

表达式.Range.Count

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:B2')

  // 区域中单元格的数量
  const count = await range.Count
  console.log(count)
}

EntireColumn

包含指定区域的整列

语法

表达式.Range.EntireColumn

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1')

  // 获取该区域的行
  const entireColumn = range.EntireColumn

  // 选择这列
  await entireColumn.Select()
}

EntireRow

包含指定区域的整行

语法

表达式.Range.EntireRow

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1')

  // 获取该区域的行
  const entireRow = range.EntireRow

  // 选择这一行
  await entireRow.Select()
}

FormatConditions

代表一个区域内所有条件格式的集合，详见 FormatConditions

语法

表达式.Range.FormatConditions

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1')

  // 条件格式对象
  const formatConditions = await range.FormatConditions
}

Formula

以 A1 样式表示法表示的对象的隐式交叉的公式

语法

表达式.Range.Formula

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A2')

  // 设置公式：A2 = A1 + B1
  range.Formula = '=A1+B1'
}

FormulaArray

返回或设置区域的数组公式

语法

表达式.Range.FormulaArray

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A2:B2')

  // 设置公式：A2 到 B2 的值为 A1 + B1 的和
  range.FormulaArray = '=Sum(A1:B1)'

  // 获取该公式
  const formulaArray = await range.FormulaArray
  console.log(formulaArray)
}

Hidden

行或者列的隐藏

语法

表达式.Range.Hidden

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1')

  // 获取整列
  const entireColumn = await range.Rows.EntireColumn
  console.log(entireColumn)

  // 隐藏该列
  entireColumn.Hidden = true
}

HorizontalAlignment

设置区域的水平对齐方式，设置的值可以是 Enum.XlHAlign 中的值。

语法

表达式.Range.HorizontalAlignment

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1')

  // 设置对齐方式：居中
  range.HorizontalAlignment = await app.Enum.XlHAlign.xlHAlignCenter

  setTimeout(async () => {
    // 获取对齐方式
    const horizontalAlignment = await range.HorizontalAlignment
    console.log(horizontalAlignment)
  }, 3000)
}

IndentLevel

JSSDK: v1.1.12+、WebOffice v2.5.1+ 支持

设置单元格缩进

语法

表达式.Range.IndentLevel

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1')

  // 写入值到单元格中
  range.IndentLevel = 10
}

Left

从列 A 的左边缘到该区域的左边缘的距离

语法

表达式.Range.Left

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('B2')

  // 左边距
  const left = await range.Left
  console.log(left)
}

MergeArea

单元格的合并区域

语法

表达式.Range.MergeArea

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:D2')

  // 合并单元格
  await range.Merge()

  // 页面加载合并后，5 秒内点击空白区域，5 秒后自动选择该区域
  setTimeout(async () => {
    // 单元格的合并区域
    const mergeArea = await range.MergeArea
    mergeArea.Select()
  }, 5000)
}

MergeCells

区域内是否存在合并的单元格

语法

表达式.Range.MergeCells

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:D2')

  // 合并单元格
  await range.Merge()

  // 区域内是否存在合并的单元格
  const mergeCells = await range.MergeCells
  console.log(mergeCells)
}

NumberFormat

获取或者设置区域的数字格式。

在获取上，如果指定区域中的所有单元格的数字格式不一致，则此属性返回 null。

在设置上，为了让用户设置更方便，我们列举了 WebOffice 上常用的值：

  • 常规：G/通用格式
  • 数值：0.00_);[红色](0.00)
  • 货币：￥#,##0.00_);[红色](￥#,##0.00)
  • 会计专用：_ ￥* #,##0.00_ ;_ ￥* -#,##0.00_ ;_ ￥* "-"??_ ;_ @_
  • 短日期：yyyy/m/d;@
  • 长日期：yyyy"年"m"月"d"日";@
  • 时间：h:mm:ss;@
  • 百分比：0.00%
  • 分数：## ?/?
  • 科学技术：0.00E+00
  • 文本：@
  • ，千位分隔样式：_ * #,##0.00_ ;_ * -#,##0.00_ ;_ * "-"??_ ;_ @_

这样在调用 API 设置数字格式的时候，可以复制上面的值进行设置，例如设置数字格式为常规：Range.NumberFormat = 'G/通用格式'。

语法

表达式.Range.NumberFormat

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1')

  // 获取区域数字格式
  const numberFormat = await range.NumberFormat
  console.log('当前区域数字格式：', numberFormat)

  // 设置区域数字格式为文本
  range.NumberFormat = '@'
}

Item()

返回一个 Range 对象，表示区域中指定的位置

语法

表达式.Range.Item({ RowIndex, ColumnIndex })

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

参数

属性数据类型默认值必填说明
RowIndex
Number
是
如果提供了第二个参数，则返回的单元格的相对行号。如果未提供第二个参数，则为要返回的子范围的索引
ColumnIndex
Number
否
要返回的单元格的相对列号

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:D2')

  // 区域子项：B2
  const item1 = await range.Item(2, 2)
  await item1.Select()
}

Row

区域中第一行的行号

语法

表达式.Range.Row

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:B2')

  // 区域中第一行的行号
  const row = await range.Row
  console.log(row)
}

RowEnd

区域中最后一行的行号

语法

表达式.Range.RowEnd

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:B2')

  // 区域中最后一行的行号
  const rowEnd = await range.RowEnd
  console.log(rowEnd)
}

RowHeight

区域高度

语法

表达式.Range.RowHeight

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:B2')

  // 区域高度
  range.RowHeight = 100
}

Rows

区域中的行，返回一个 Range 对象（可使用 Range 相关的属性、方法）

语法

表达式.Range.Rows

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:B2')

  // 行对象
  const rows = await range.Rows

  // 指定行
  const row = await rows.Item(2)

  // 选中第 2 行
  await row.Select()
}

Text

【只读】读取单元格格式化文本

语法

表达式.Range.Text

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:B2')

  // 【只读】读取单元格格式化文本
  const text = await range.Text
  console.log(text)
}

Top

从行 1 的上边缘到区域的上边缘之间的距离

语法

表达式.Range.Top

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('B2')

  // 上边距
  const top = await range.Top
  console.log(top)
}

Validation

代表工作表区域的数据有效性规则，详见 FormatConditions

语法

表达式.Range.Validation

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1')

  // 数据有效性对象
  const validation = await range.Validation
}

Value

JSSDK: v1.1.11+、WebOffice v2.5.1+ 支持

【赋值】写入值到单元格中

语法

表达式.Range.Value

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1')

  // 写入值到单元格中
  range.Value = 'WebOffice'
}

VerticalAlignment

设置区域的垂直对齐方式，设置的值可以是 Enum.XlVAlign 中的值。

语法

表达式.Range.VerticalAlignment

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1')

  // 设置对齐方式：底部对齐
  range.VerticalAlignment = await app.Enum.XlVAlign.xlVAlignBottom

  setTimeout(async () => {
    // 获取对齐方式
    const horizontalAlignment = await range.VerticalAlignment
    console.log(horizontalAlignment)
  }, 3000)
}

WrapText

获取或者设置区域自动换行

语法

表达式.Range.WrapText

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1')

  // 获取区域自动换行
  const wrapText = await range.WrapText
  console.log('区域是否自动换行：', wrapText)

  // 设置区域自动换行
  range.WrapText = true
}

Activate()

激活区域

语法

表达式.Range.Activate()

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1')

  // 激活区域 A1
  range.Activate()
}

AddComment()

添加评论

语法

表达式.Range.AddComment({ Text })

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

参数

属性数据类型默认值必填说明
Text
String
否
评论文本

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1')

  // 给 A1 区域添加评论
  range.AddComment('WebOffice')
}

Address()

获取表示使用宏语言的区域引用的 String 值

语法

表达式.Range.Address({ RowAbsolute, ColumnAbsolute, ReferenceStyle, External, RelativeTo })

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

参数

属性数据类型默认值必填说明
RowAbsolute
Boolean
否
若为 true，以绝对引用的形式返回引用的行部分。默认值为 true
ColumnAbsolute
Boolean
否
若为 true，以绝对引用的形式返回引用的列部分。默认值为 true
ReferenceStyle
Enum
否
引用样式。默认值为 xlA1，更多可看 Enum.XlReferenceStyle
External
Boolean
否
若为 true，返回外部引用。若为 false，返回本地引用。默认值为 false
RelativeTo
Range
否
如果 RowAbsolute 和 ColumnAbsolute 为 false，且 ReferenceStyle 是 xlR1C1，则必须为相对引用包含一个起点。此参数是一个定义起点的 Range 对象

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1')

  // 获取宏语言的区域引用的 String 值
  const address1 = await range.Address()
  console.log('address1：', address1)

  const address2 = await range.Address(false, false)
  console.log('address2：', address2)

  const address3 = await range.Address(true, true, -4150)
  console.log('address3：', address3)
}

AutoFill()

对指定区域中的单元格执行自动填充

语法

表达式.Range.AutoFill({ Destination, Type })

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

参数

属性数据类型默认值必填说明
Destination
Range
否
目标区域。目标区域必须包含源区域
Type
Enum
Enum.XlAutoFillType.xlFillDefault
否
填充类型，详细可见 Enum.XlAutoFillType

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:A2')

  // 要填充的单元格
  const fillRange = await app.Range('A1:A20')

  // 对指定区域中的单元格执行自动填充
  await range.AutoFill(fillRange)
}

ClearComments()

清除区域的评论

语法

表达式.Range.ClearComments()

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:B2')

  // 清除区域的评论
  await range.ClearComments()
}

ClearContents()

清除区域的内容

语法

表达式.Range.ClearContents()

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:B2')

  // 清除区域的内容
  await range.ClearContents()
}

ClearFormats()

清除区域的样式

语法

表达式.Range.ClearFormats()

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:B2')

  // 清除区域的样式
  await range.ClearFormats()
}

Contain()

判断区域是否重叠

语法

表达式.Range.Contain({ Range })

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

参数

属性数据类型默认值必填说明
Range
Range
是
Range 对象，另一块区域

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:D2')

  // 第二块区域对象
  const newRange = await app.Range('A1:B4')

  // 判断是否重叠
  const contain = await range.Contain(newRange)
  console.log(contain)
}

Delete()

单元格、行、列的删除

语法

表达式.Range.Delete()

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

示例：删除行 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('B5:D10')

  // 选择区域的所有行并删除
  await range.EntireRow.Delete()
}

示例：删除列 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('B5:D10')

  // 选择区域的所有行并删除
  await range.EntireColumn.Delete()
}

Insert()

单元格、行、列的新增

语法

表达式.Range.Insert()

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

示例：新增行 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('B5:D10')

  // 选择区域的所有行并在该范围新增
  await range.EntireRow.Insert()
}

示例：新增列 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('B5:D10')

  // 选择区域的所有行并在该范围新增
  await range.EntireColumn.Insert()
}

Merge()

合并单元格

语法

表达式.Range.Merge({ Across })

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

参数

属性数据类型默认值必填说明
Across
Boolean
false
是
如果设置为 true，则将指定区域中每一行的单元格合并为一个单独的合并单元格

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:D2')

  // 合并单元格
  await range.Merge()
}

Offset()

对指定区域进行迁移操作

语法

表达式.Range.Offset({ RowOffset, ColumnOffset })

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

参数

属性数据类型默认值必填说明
RowOffset
Number
0
否
区域偏移的行数：可以是正值、负值或零。正值表示向下偏移，负值表示向上偏移
ColumnOffset
Number
0
否
区域偏移的列数：可以是正值、负值或零。正值表示向右偏移，负值表示向左偏移

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:D2')
  await range.Select()

  // 对指定区域进行迁移操作
  const newRange = await range.Offset(2, 2)
  await newRange.Select()
}

PasteSpecial()

JSSDK: v1.1.12+、WebOffice v2.5.1+ 支持

格式刷

语法

表达式.Range.PasteSpecial()

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

参数

属性数据类型默认值必填说明
Paste
Enum.XlPasteType
否
要粘贴的区域部分 更多可看 Enum.XlPasteType
Operation
Enum.XlPasteSpecialOperation
否
粘贴操作 更多可看 Enum.XlPasteSpecialOperation
SkipBlanks
bool
false
否
如果为 True，则不将剪贴板上区域中的空白单元格粘贴到目标区域中
Transpose
bool
false
否
如果为 True，则在粘贴区域时转置行和列

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 选区
  const range = await app.Selection

  // 格式刷
  await range.PasteSpecial()
}

Select()

选择区域

语法

表达式.Range.Select()

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

参数

属性数据类型默认值必填说明
ActiveCell
Object
否
选中区域内的活动单元格 ActiveCell 格式为{row: number, col: number} row-选中区域内活动单元格的行数 col-选中区域内活动单元格的列数(超出了选中区域的范围则默认选中区域的第一个单元格)
Twinkle
Boolean
false
否
是否显示闪烁动画

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1')

  // 选择区域 A1
  range.Select()

  // 3 秒后选择区域 A1:D2
  setTimeout(async () => {
    const newRange = await app.Range('B1:D2')
    newRange.Select()
  }, 5000)
}

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1')

  // 选择区域 A1 并且设置闪烁动画
  range.Select(null, true)

  // 3 秒后选择区域 B1:D2 并设置选中区域第二行第二列为活动单元格
  setTimeout(async () => {
    const newRange = await app.Range('B1:D2')
    newRange.Select({ row: 2, col: 2 }, true)
  }, 5000)
}

ToImageDataURL()

将区域导出成图片

语法

表达式.Range.ToImageDataURL()

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

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:D2')

  // 将区域导出成图片
  const img = await range.ToImageDataURL()
  console.log(img)
}

UnMerge()

取消合并单元格

语法

表达式.Range.UnMerge({ CancelCenter })

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

参数

属性数据类型默认值必填说明
CancelCenter
Boolean
false
否
是否合并居中

示例 

//@file=base.xlsx
async function example() {
  await instance.ready()

  const app = instance.Application

  // 区域对象
  const range = await app.Range('A1:D2')

  // 合并单元格
  await range.Merge()

  setTimeout(async () => {
    // 取消合并单元格
    await range.UnMerge()
  }, 3000)
}