---
description: Google Apps Script class for Google Sheet
---

# Range

[GAS](..) ⟩ [Classes]() ⟩ Range

{% tabs %}
{% tab title="📍 屬性" %}
* Range 的位置資訊：
  * [getRow()](https://developers.google.com/apps-script/reference/spreadsheet/range#getrow) - starting row index.
  * [getColumn()](https://developers.google.com/apps-script/reference/spreadsheet/range#getcolumn) - starting column index.
  * [getNumRows()](https://developers.google.com/apps-script/reference/spreadsheet/range#getnumrows) - number of rows.
  * [getNumColumns()](https://developers.google.com/apps-script/reference/spreadsheet/range#getnumcolumns) - number of columns.
* 選取 [range](range "mention")：
  * [sheet.rangebyrect](../app/prototypes/app.sheet.prototype/sheet.rangebyrect "mention") - 簡化 Range 的選取。
  * range.[offset()](https://developers.google.com/apps-script/reference/spreadsheet/range#offsetrowoffset,-columnoffset) - 如果位移的量沒有設好，會出現類似以下錯誤：\
    ⛔ <mark style="color:red;">Exception: The starting row of the range is too small</mark>.
* 設定儲存格公式：
  * [setFormula()](https://developers.google.com/apps-script/reference/spreadsheet/range#setformulaformula)
* 合併儲存格：
  * 水平合併：[mergeAcross()](https://developers.google.com/apps-script/reference/spreadsheet/range#mergeacross) (如果有好幾列，<mark style="color:red;">**每列會分別合併**</mark>)
  * 垂直合併：[mergeVertically()](https://developers.google.com/apps-script/reference/spreadsheet/range#mergevertically)&#x20;
* 設定字體：
  * 字體顏色：[setFontColor()](https://developers.google.com/apps-script/reference/spreadsheet/range#setfontcolorcolor), [setFontColors()](https://developers.google.com/apps-script/reference/spreadsheet/range#setfontcolorscolors), [setFontColorObject()](https://developers.google.com/apps-script/reference/spreadsheet/range#setfontcolorobjectcolor), ...
  * 字體大小：[setFontSize()](https://developers.google.com/apps-script/reference/spreadsheet/range#setfontsizesize)
  * 字體粗細：[setFontWeight()](https://developers.google.com/apps-script/reference/spreadsheet/range#setfontweightfontweight)
  * 同一個儲存格內設定不同的字體： [range.setrichtextvalue](range/range.setrichtextvalue "mention") ⭐️
* 設定顏色：
  * 儲存格背景色：[setBackground()](https://developers.google.com/apps-script/reference/spreadsheet/range#setbackgroundcolor)&#x20;
* 文字對齊：
  * 水平：[setHorizontalAlignment()](https://developers.google.com/apps-script/reference/spreadsheet/range#sethorizontalalignmentalignment), [setHorizontalAlignments()](https://developers.google.com/apps-script/reference/spreadsheet/range#sethorizontalalignmentsalignments)
  * 垂直：[setVerticalAlignment()](https://developers.google.com/apps-script/reference/spreadsheet/range#setverticalalignmentalignment), [setVerticalAlignments()](https://developers.google.com/apps-script/reference/spreadsheet/range#setverticalalignmentsalignments)
{% endtab %}

{% tab title="💈範例" %}
```javascript
// column widths
sheet.setColumnWidths(startColumn, numColumns, width) 

// background color
range.setBackground('red')     // 使用顏色名稱
range.setBackground('#eeeeee') // 使用 RGB 顏色碼
range.setBackground()          // 重設背景色

// alignment
range
    .setVerticalAlignment('middle')    // 'top', 'middle', 'bottom'
    .setHorizontalAlignment('center'); // 'left', 'center', 'normal'
```
{% endtab %}

{% tab title="📗 參考" %}
* [ ] [How to Convert Column Number (e.g. 28) to Column Letter (e.g. AB) in Google Sheets](https://www.labnol.org/convert-column-a1-notation-210601/) ⭐️ - row/column number ⇄ A1 notation
{% endtab %}

{% tab title="👥 相關" %}
* [app.range.prototype](../app/prototypes/app.range.prototype "mention") - extend [range](range "mention").
* [app.sheet.prototype](../app/prototypes/app.sheet.prototype "mention") - extend [sheet](sheet "mention").
* [sheet](sheet "mention")
* [rangerect](../custom-objects/rangerect "mention") - 簡化選取 [range](range "mention")
* [sheet.rangebyrect](../app/prototypes/app.sheet.prototype/sheet.rangebyrect "mention") - 簡化選取 [range](range "mention")
* [custom-prototypes](../tips/custom-prototypes "mention") for Range objects.
* GAS ⟩ [ThemeColorType](https://developers.google.com/apps-script/reference/spreadsheet/theme-color-type?hl=en) (enum)
* [app.datarangevaluesfromsheet](../app/member/app.datarangevaluesfromsheet "mention")
{% endtab %}

{% tab title="📘 手冊" %}
* [Range](https://developers.google.com/apps-script/reference/spreadsheet/range) ⟩
  * [getA1Notation()](https://developers.google.com/apps-script/reference/spreadsheet/range#geta1notation) - 回傳類似 <mark style="color:yellow;">`"A1:E2"`</mark> 的字串。
  * [offset()](https://developers.google.com/apps-script/reference/spreadsheet/range#offsetrowoffset,-columnoffset) - another range.
  * [getSheet()](https://developers.google.com/apps-script/reference/spreadsheet/range#getsheet) - sheet ([sheet](sheet "mention")) this range belongs to.
* [RangeList](https://developers.google.com/apps-script/reference/spreadsheet/range-list#setBackground\(String\)) - collection of one or more [`Range`](https://developers.google.com/apps-script/reference/spreadsheet/range) instances <mark style="color:yellow;">**in the same sheet**</mark>.
* Sheet ⟩ [getRangeList(a1Notations)](https://developers.google.com/apps-script/reference/spreadsheet/sheet#getrangelista1notations)
* [Cells](https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/cells) - internal data structure of a cell



相關試算表指令：

* [=ADDRESS()](https://support.google.com/docs/answer/3093308?hl=en) - <mark style="color:yellow;">**row/col number**</mark> to <mark style="color:orange;">**A1/R1C1**</mark> notation.
* [=ROW()](https://support.google.com/docs/answer/3093316?hl=en\&ref_topic=3105472) - <mark style="color:yellow;">**row number**</mark> of a cell.
* [=COLUMN()](https://support.google.com/docs/answer/3093373?hl=en\&ref_topic=3105472) - <mark style="color:yellow;">**column number**</mark> of a cell.
{% endtab %}

{% tab title="🗣 討論" %}
* [In AppScript, when multiple ranges are edited at once, How is rangeList obtained?](https://stackoverflow.com/a/57622171/5409815)
{% endtab %}
{% endtabs %}
