# 快速开始
本指南假设您已安装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)
