# 快速開始
本指南假設您已安裝xlwings。 如果不是這樣，請轉到[安裝](installation.md).
## 1\. 腳本: 從Python與Excel進行自動化交互
建立與工作簿的連接：
~~~
>>> import xlwings as xw
>>> wb = xw.Book() # 這將創建一個新的工作簿
>>> wb = xw.Book('FileName.xlsx') # 連接到當前工作目錄中的現有文件
>>> wb = xw.Book(r'C:\path\to\file.xlsx') # 在Windows上：使用原始字符串來轉義反斜杠
~~~
如果您在兩個Excel實例中打開了相同的文件，則需要完全限定它并包含應用程序實例。 您將通過`xw.apps.keys()`找到您的應用實例密鑰（PID）：
~~~
>>> xw.apps[10559].books['FileName.xlsx']
~~~
實例化工作表對象：
~~~
>>> sht = wb.sheets['Sheet1']
~~~
在Range內讀取/寫入值非常簡單：
~~~
>>> sht.range('A1').value = 'Foo 1'
>>> sht.range('A1').value
'Foo 1'
~~~
有許多**便利功能**，例如 Range擴大：
~~~
>>> sht.range('A1').value = [['Foo 1', 'Foo 2', 'Foo 3'], [10.0, 20.0, 30.0]]
>>> sht.range('A1').expand().value
[['Foo 1', 'Foo 2', 'Foo 3'], [10.0, 20.0, 30.0]]
~~~
**功能強大的轉換器**處理大多數感興趣的數據類型，包括Numpy數組和Pandas DataFrames兩個方向：
~~~
>>> import pandas as pd
>>> df = pd.DataFrame([[1,2], [3,4]], columns=['a', 'b'])
>>> sht.range('A1').value = df
>>> sht.range('A1').options(pd.DataFrame, expand='table').value
a b
0.0 1.0 2.0
1.0 3.0 4.0
~~~
**Matplotlib**數字可以在Excel中顯示為圖片：
~~~
>>> import matplotlib.pyplot as plt
>>> fig = plt.figure()
>>> plt.plot([1, 2, 3, 4, 5])
[<matplotlib.lines.Line2D at 0x1071706a0>]
>>> sht.pictures.add(fig, name='MyPlot', update=True)
<Picture 'MyPlot' in <Sheet [Workbook4]Sheet1>>
~~~
活動工作表的**捷徑** ： `xw.Range`
如果要快速與活動工作簿中的活動工作表通信，則不需要實例化工作簿和工作表對象，可以簡單地執行：
~~~
>>> import xlwings as xw
>>> xw.Range('A1').value = 'Foo'
>>> xw.Range('A1').value
'Foo'
~~~
**注意**：在與Excel交互時，您應該只使用`xw.Range`。 在腳本中，您應該始終通過工作簿和工作表對象，如上所示。
## 2\. 宏: 從Excel調用Python
您可以使用`RunPython`函數從VBA調用Python函數：
~~~
Sub HelloWorld()
RunPython ("import hello; hello.world()")
End Sub
~~~
默認情況下，`RunPython`在Excel文件所在的目錄中需要`hello.py`。 請參閱使用`xw.Book.caller`調用Excel工作簿：
~~~
# hello.py
import numpy as np
import xlwings as xw
def world():
wb = xw.Book.caller()
wb.sheets[0].range('A1').value = 'Hello World!'
~~~
要進行此運行，您需要安裝xlwings加載項。 設置所有內容的最簡單方法是從Windows上的命令提示符或Mac上的終端使用xlwings命令行客戶端：`xlwings quickstart myproject`。
有關加載項的詳細信息，請參閱[加載項](addin.md)。
## 3\. UDFs: 用戶定義的功能（僅限Windows）
在Python中編寫UDF非常簡單：
~~~
import xlwings as xw
@xw.func
def hello(name):
return 'Hello {0}'.format(name)
~~~
轉換器也可以與UDF一起使用。 再舉個Pandas DataFrame例子：
~~~
import xlwings as xw
import pandas as pd
@xw.func
@xw.arg('x', pd.DataFrame)
def correl2(x):
# x arrives as DataFrame
return x.corr()
~~~
通過單擊xlwings加載項的導入按鈕將此函數導入Excel：有關更多詳細信息，請參閱[VBA：用戶定義函數UDFs](udfs.md)
