xlwings はPythonからExcelを操作するための外部ライブラリです。
多機能な操作をVBAライクに記述できるので、初心者からベテランまで幅広く使われているのが特徴。このページではExcelの図形を取得、作成する方法を解説しています。
- 図形（Shape）を取得
- 図形のテキストを取得、追加、更新
- 図形を新規作成
- 図形の色などを変更
xlwingsを使ってmatplotlibで出力したグラフをExcelに挿入する方法は別の記事で解説しています。
実行環境
Microsoft Office Excel 2019
> python --version
Python 3.9.4
> pip freeze
xlwings==0.24.9
前準備
xlwings はExcelを直接操作するので、ExcelがインストールされたWindowsまたはMac OSである必要があります。
xlwings はPython 3.6以上で動作します。
また、xlwingsのインストールは、pipなら以下のコマンドを実行するだけ。
$ pip install xlwings
図形の取得
シート上の図形（Shape）は Sheet.shapes メンバから取得します。Sheet.shapesはシートの全ての図形を含むコレクションShapesです。
wb = xw.books.active
sheet = wb.sheets.active
shps = sheet.shapes
print(type(shps))
# <class 'xlwings.main.Shapes'>
if len(shps) > 0:
print(type(shps[0]))
# <class 'xlwings.main.Shape'>
ここでは以下のようなシート（四角形と楕円の図形を配置）を例にして、サンプルコードを掲載しています。
図形の属性情報
Shape オブジェクトのメンバから図形の位置・形状などの属性情報を取得可能。
for s in sheet.shapes:
print(f"-- {s.name} --")
print(f"type: {s.type}")
print(f"top: {s.top}") # 垂直位置
print(f"left: {s.left}") # 水平位置
print(f"width: {s.width}") # 幅
print(f"height: {s.height}")# 高さ
print(f"parent: {s.parent}")# 親オブジェクト
# -- Rectangle 1 --
# type: auto_shape
# top: 39.0
# left: 45.0
# width: 138.0
# height: 49.5
# parent:
# -- Oval 2 --
# type: auto_shape
# top: 106.5
# left: 109.5
# width: 107.25
# height: 66.75
# parent:
図形のテキストの取得・更新
図形のテキストの取得
すでにシートにある図形のテキストはxlwingsのAPIを経由して簡単に編集ができます。
テキストの取得は Shape.text メンバにアクセスするだけです。
なお、Shape.textは xlwings 0.21.4で導入された要素です。それ以前のバージョンでは利用できないので注意してください。
for s in sheet.shapes:
print(f"-- {s.name} --")
print(s.text)
# -- Rectangle 1 --
# 四角形１
# -- Oval 2 --
# 楕円１
図形のテキストの変更
図形のテキストを更新するにはShape.text (xlwings 0.21.4以降) の値を置き換えます。
s = sheet.shapes[0]
s.text = 'テキストを更新'
実行結果
例えば、図形の名前（Shape.nameメンバ）と組み合わせれば、テキストボックスのテキストだけを更新するという使い方も可能です。
ここでは str.replace() を使って文字列の置換を行っています。
for s in sheet.shapes:
if 'TextBox' in s.name:
print(s.text)
s.text = s.text.replace('入力', '更新')
# テキストボックスに入力されたテキスト
実行前
実行後
図形の追加
図形を新規作成（追加）するメソッドは、執筆現在、残念ながらxlwingsのPython APIで用意されていません。
そこで Sheet.api でシートが接続しているネイティブオブジェクトを取得してpywin32を直接操作し、図形を作成します。
（xlwingsは内部ではpywin32を使ったプロセス間通信でExcelを操作しています）
任意の位置に図形を作成するには、次のコードを実行します。
Sheet.api.Shapes.AddShape(Type, Left, Top, Width, Height)
| Type | 作成する図形の種類を整数で指定。値は下記のページを参照。 |
| Left | シートの左上隅から図形の左端までの距離(ポイント) |
| Top | シートの左上隅から図形の上端までの距離(ポイント) |
| Width | 図形の幅(ポイント) |
| Height | 図形の高さ(ポイント) |
Typeの値：MsoAutoShapeType 列挙 (Office) | Microsoft Docs
例えば、今回は「丸い四角形（msoShapeRoundedRectangle）」を上下50の位置で作成してみます。
また、名前にはShape.Nameメンバでアクセスできます。
s = sheet.api.Shapes.AddShape(5, 50, 50, 170, 100)
s.Name = 'New Shape 1'
print(s.Top)
# 50.0
print(s.Left)
# 50.0
print(s.Width)
# 170.0
print(s.Height)
# 100.0
実行結果
作成した図形のテキストを編集
pywin32で作成したShapeオブジェクトのテキストを編集するには、Shape.TextFrameからCharactersオブジェクトを取得してTextメンバを変更します。
改行は改行コード（Windowsでは \r\n）を挿入するなどで対応できます。
s.TextFrame.Characters().Text = 'New Shape!\r\nLine break'
実行結果
作成した図形の色を変更
Shape.Fill プロパティのForeColorやBackColorを変更することで、図形の色を変更可能です。
RGBメソッドは自前で用意します。RBGそれぞれを８ビットで表現し、それを並べて10進数にした値を渡します。ビット演算子を利用して、GreenとBlueの値をそれぞれ8ビット、16ビット分を前方シフトします。
結論としては、以下のRGB()のような関数でOKです。
def RGB(red, green, blue):
return red + (green << 8) + (blue << 16)
print(RGB(200, 100, 30))
# 1991880
s.Fill.ForeColor.RGB = RGB(200, 100, 30)
実行結果
今回参考にしたページ・資料
Python API - xlwings Documentation
Office Visual Basic for Applications (VBA) リファレンス | Microsoft Docs
