xlwings.Range 簡易リファレンス

# はじめに

これは xlwings 0.11.5 [本家xlwings.Range](http://docs.xlwings.org/en/stable/api.html#range) [本家xlwings.RangeRows](http://docs.xlwings.org/en/stable/api.html#rangerows) [本家xlwings.RangeColumns](http://docs.xlwings.org/en/stable/api.html#rangecolumns) の簡易日本語リファレンスである。

# xlwings.Range

Range は単一セルまたは複数のセルの範囲を管理するクラスである、範囲を指定した場合は始点終点順に関係なく英文と同順で左上が先頭セルに右下が最終セルとなる連続した範囲となる。
[VBA:Range](https://msdn.microsoft.com/ja-jp/VBA/Excel-VBA/articles/range-object-excel)

## 範囲

```python
import xlwings as xw
xw.Range('a1')               # アクティブシートの単一セル指定
xw.Range('Sheet1!a1')        # アクティブブック上のシート名付き単一セル指定
xw.Range('[Book1]Sheet1!a1') # ブック名とシート名付き単一セル指定
xw.Range((1, 1))             # 単一セル指定 VBA:Cells(1,1)
xw.Range('a:b')              # 列範囲
xw.Range('1:2')              # 行範囲
xw.Range('a1:b2')            # 矩形範囲
xw.Range((1,1), (2,2))       # 矩形範囲
xw.Range(rng1, rng2)         # xw.Range の先頭セルによる矩形範囲
xw.Range('a1,b,c3:d4')       # 不連続位置指定
xw.Range('範囲名')            #
xw.Range('_FilterDatabase')  #　フィルター
xw.Range('テーブル名')        #

rng = xw.Range(...)
rng.select()                            # 範囲を選択状態にする

rng.address                             # 範囲の絶対アドレスを返す　.get_address() と同等
rng.get_address(row, col, sheet, book)  # 範囲のアドレスを返す 絶対位置にする個所に True を指定する
rng.row                                 # 先頭セルの行数を返す
rng.column                              # 先頭セルの列数を返す

rng.count                               # 先頭範囲のセル数を返す
rng.size                                # 先頭範囲のセル数を返す
rng.shape                               # 先頭範囲の大きさをタプル (row, column) で返す

rng.sheet                               # 先頭セルのシートインスタンスを返す
rng.name = '範囲名'                      # RW 範囲名を設定する

rng.rows                     # 行範囲を返す VBA => Range(...).EntireRow, Rows(...)
rng.columns                  # 列範囲を返す VBA => Range(...).EntireColumn, Columns(...)

rng[0]                       # 範囲の先頭セルを返す
rng[-1]                      # 範囲の最終セルを返す
rng.last_cell                # 最終セルを返す

rng.resize(row, column)      # 扱う範囲を変更する

rng.offset(row, column)      # 相対位置範囲を返す
rng.end('...')               # データが連続する終端位置を返す 'up', 'down', 'left', 'right'
                             # ctrl+up, ctrl+down, ctrl+left, ctrl+right と同じ
rng.current_region           # データが連続する矩形範囲を返す
                             # ctrl+* (mac shift+ctrl+space) と同じ
rng.expand('...')            # データテーブル(DGET等の形式)として扱える範囲を返す 'table' 'right' 'down'
                             # 先頭行の空白を許すので .current_region と異なる動作である

rng.api                      # ネイティブインスタンスを返す
```

セル名の指定には Excel と同様に $ を付けても問題なく動作する。
オブジェクトを作った後に何かしらの編集で位置が変わっても正しく扱える為、新たな編集位置を求めなくともよい。

## 値・式・書式

```python
rng.value = 0                           # RW 全てのセルに数値を書き込む
rng.value = datetime(2018, 1, 1)        # RW 全てのセルに日付を書き込む
rng.value = 'abc'                       # RW 全てのセルに文字列を書き込む、確実に文字列指定するなら
                                        # '="abc"' '`abc' とする、数字,日付,式等へ自動変換が起きる
rng.value = [[0,1],[2,3]]               # RW 先頭セル位置を起点に値 0, 1 を書き込む、タプルでもよい
                                        #                         2, 3
rng.value = {'a':1,'b':2}               # RW 先頭セル位置を起点にキーと値 a, 1 を書き込む
                                        #                               b, 2
rng.formula = '=0'                      # RW 全てのセルに式 '=0' を書き込む、値を指定しても問題ない
rng.formula = [['=0','=1'],['=2','=3']] # RW セル範囲に式を書き込む、タプルでもよい
                                        # rng.value と異なり範囲外に書き込む事は無い
                                        # 式タプル要素数が一つで範囲が一つを超える場合は式で埋められる
rng.raw_value                           # 型変換や環境差吸収を行わない内部形式値を返す
rng.number_format = 'G/標準'             # RW 書式に標準を設定する
rng.color = (255, 255, 255)             # RW 背景色 RGB 0～255
rng.options(...)                        # 下記リンク先を参照
rng.add_hyperlink(adr, txt, tip)        # ハイパーリンクを設定する、下記リンク先を参照
rng.hyperlink                           # ハイパーリンクアドレスを返す

rng.clear()                             # 値と書式のクリア
rng.clear_contents()                    # 値のクリア
```
[options(...)](http://docs.xlwings.org/en/stable/api.html#xlwings.Range.options)
[add_hyperlink(...)](http://docs.xlwings.org/en/stable/api.html#xlwings.Range.add_hyperlink)

範囲が単一セルなら .value .formula .raw_value は値を一つを返し範囲が複数セルの場合はタプルで値が返される、不連続範囲の場合は先頭セルのみを返す。 他のプロパティーは先頭セルの情報のみを返すので注意。

## 高さと幅

```python
rng.top                      # 先頭行との高さ差(ポイント)を返す
rng.height                   # 範囲の高さ(ポイント)を返す
rng.width                    # 範囲の幅(ポイント)を返す

rng.row_height = 409.5       # RW 先頭セルの高さ(ピクセル)を指定する 0~409.5
rng.column_width = 255       # RW 先頭セルの幅(ピクセル)を指定する 0~255

rng.autofit()                # 高さ幅自動調整
rng.rows.autofit()           # 高さ自動調整
rng.columns.autofit()        # 幅自動調整
```
## その他

```rng.formula_array``` 恐らくリスト式だと思われるが未調査である。

# フィルター

xlwings にはフィルターを管理するクラスはないがタイトル行も含むセルを ```xw.Range('_FilterDatabase')``` で参照する事が出来る。 

# テーブル

xlwings にはテーブルを管理するクラスはないがデータセルを ```xw.Range('テーブル名')``` で参照することが出来る。 タイトル行のセルは ```xw.Range('テーブル名').rows[0].offset(-1)``` とすればよい。