> For the complete documentation index, see [llms.txt](https://lochiwei.gitbook.io/web/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lochiwei.gitbook.io/web/appendix/gas/classes/range.md).

# Range

[GAS](/web/appendix/gas.md) ⟩ [Classes](/web/appendix/gas/classes.md) ⟩ 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](/web/appendix/gas/classes/range.md)：
  * [💾 sheet.rangeByRect()](/web/appendix/gas/app/prototypes/app.sheet.prototype/sheet.rangebyrect.md) - 簡化 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()](/web/appendix/gas/classes/range/range.setrichtextvalue.md) ⭐️
* 設定顏色：
  * 儲存格背景色：[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](/web/appendix/gas/app/prototypes/app.range.prototype.md) - extend [Range](/web/appendix/gas/classes/range.md).
* [app.sheet.prototype](/web/appendix/gas/app/prototypes/app.sheet.prototype.md) - extend [Sheet](/web/appendix/gas/classes/sheet.md).
* [Sheet](/web/appendix/gas/classes/sheet.md)
* [RangeRect](/web/appendix/gas/custom-objects/rangerect.md) - 簡化選取 [Range](/web/appendix/gas/classes/range.md)
* [💾 sheet.rangeByRect()](/web/appendix/gas/app/prototypes/app.sheet.prototype/sheet.rangebyrect.md) - 簡化選取 [Range](/web/appendix/gas/classes/range.md)
* [💡 custom prototypes](/web/appendix/gas/tips/custom-prototypes.md) for Range objects.
* GAS ⟩ [ThemeColorType](https://developers.google.com/apps-script/reference/spreadsheet/theme-color-type?hl=en) (enum)
* [app.dataRangeValuesFromSheet()](/web/appendix/gas/app/member/app.datarangevaluesfromsheet.md)
  {% 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](/web/appendix/gas/classes/sheet.md)) 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 %}