# 數據結構教程
本教程簡要介紹了xlwings在讀取和寫入值時最常見的用例和默認行為。 有關如何使用`options`方法控制行為的深入文檔，請查看[轉換器和選項](converters.md)。
下面所有代碼示例取決于以下導入：
~~~
>>> import xlwings as xw
~~~
## 單個單元格
默認情況下，單個單元格返回為“float”，“unicode”，“None”或“datetime”對象，具體取決于單元格是否包含數字，字符串，是否為空或表示日期：
~~~
>>> import datetime as dt
>>> sht = xw.Book().sheets[0]
>>> sht.range('A1').value = 1
>>> sht.range('A1').value
1.0
>>> sht.range('A2').value = 'Hello'
>>> sht.range('A2').value
'Hello'
>>> sht.range('A3').value is None
True
>>> sht.range('A4').value = dt.datetime(2000, 1, 1)
>>> sht.range('A4').value
datetime.datetime(2000, 1, 1, 0, 0)
~~~
## 列表
* 一維列表：表示Excel中行或列的范圍作為簡單列表返回，這意味著一旦它們在Python中，您就丟失了有關方向的信息。 如果這是一個問題，下一點將向您展示如何保留此信息：
~~~
>>> sht = xw.Book().sheets[0]
>>> sht.range('A1').value = [[1],[2],[3],[4],[5]] # 列方向（嵌套列表）
>>> sht.range('A1:A5').value
[1.0, 2.0, 3.0, 4.0, 5.0]
>>> sht.range('A1').value = [1, 2, 3, 4, 5]
>>> sht.range('A1:E1').value
[1.0, 2.0, 3.0, 4.0, 5.0]
~~~
要強制單個單元格作為列表到達，請使用：
```
>>> sht.range('A1').options(ndim=1).value
[1.0]
```
>[info]注意
要以列方向向Excel寫入列表，請使用`transpose:sht.range('A1').options(transpose = True).value = [1,2,3,4]`
* 二維列表：如果必須保留行或列方向，請在Range選項中設置“ndim”。 這將返回Ranges作為嵌套列表（“二維列表”）：
~~~
>>> sht.range('A1:A5').options(ndim=2).value
[[1.0], [2.0], [3.0], [4.0], [5.0]]
>>> sht.range('A1:E1').options(ndim=2).value
[[1.0, 2.0, 3.0, 4.0, 5.0]]
~~~
* 2維Range自動作為嵌套列表返回。 將（嵌套）列表分配給Excel中的Range時，只需將左上角的單元格指定為目標地址就足夠了。 此示例還使用索引表示法將值讀回到Python中：
~~~
>>> sht.range('A10').value = [['Foo 1', 'Foo 2', 'Foo 3'], [10, 20, 30]]
>>> sht.range((10,1),(11,3)).value
[['Foo 1', 'Foo 2', 'Foo 3'], [10.0, 20.0, 30.0]]
~~~
>[info]注意
盡量減少與Excel的交互次數。 執行`sht.range('A1').value = [[1,2],[3,4]]`總是比`sht.range('A1').value = [1, 2]` 和`sht.range('A2').value = [3, 4]`更有效。
## Range expanding
您可以通過`expand`方法或`options`方法中的`expand`關鍵字動態獲取Excel范圍的維度。 雖然`expand`會返回一個擴展的Range對象，但只有在訪問Range的值時才會評估選項。 最好用一個例子來解釋差異：
~~~
>>> sht = xw.Book().sheets[0]
>>> sht.range('A1').value = [[1,2], [3,4]]
>>> rng1 = sht.range('A1').expand('table') # or just .expand()
>>> rng2 = sht.range('A1').options(expand='table')
>>> rng1.value
[[1.0, 2.0], [3.0, 4.0]]
>>> rng2.value
[[1.0, 2.0], [3.0, 4.0]]
>>> sht.range('A3').value = [5, 6]
>>> rng1.value
[[1.0, 2.0], [3.0, 4.0]]
>>> rng2.value
[[1.0, 2.0], [3.0, 4.0], [5.0, 6.0]]
~~~
`'table'`擴展為`'down'`和`'right'`，其他可用選項分別可用于列或行擴展。
>[info]注意
將`expand()`與命名Range一起作為左上角的單元格，可以在Excel中靈活地設置：您可以在表中移動并更改其大小，而無需調整代碼，例如，使用類似`sht.range('namedrange').expand().value`。
## NumPy 數組
NumPy數組的工作方式與嵌套列表類似。 但是，空單元格由`nan`而不是`None`表示。 如果要讀取Range作為數組，請在`options`方法中設置`convert = np.array`：
~~~
>>> import numpy as np
>>> sht = xw.Book().sheets[0]
>>> sht.range('A1').value = np.eye(3)
>>> sht.range('A1').options(np.array, expand='table').value
array([[ 1., 0., 0.],
[ 0., 1., 0.],
[ 0., 0., 1.]])
~~~
## Pandas DataFrames
~~~
>>> sht = xw.Book().sheets[0]
>>> df = pd.DataFrame([[1.1, 2.2], [3.3, None]], columns=['one', 'two'])
>>> df
one two
0 1.1 2.2
1 3.3 NaN
>>> sht.range('A1').value = df
>>> sht.range('A1:C3').options(pd.DataFrame).value
one two
0 1.1 2.2
1 3.3 NaN
# options: work for reading and writing
>>> sht.range('A5').options(index=False).value = df
>>> sht.range('A9').options(index=False, header=False).value = df
~~~
## Pandas系列
~~~
>>> import pandas as pd
>>> import numpy as np
>>> sht = xw.Book().sheets[0]
>>> s = pd.Series([1.1, 3.3, 5., np.nan, 6., 8.], name='myseries')
>>> s
0 1.1
1 3.3
2 5.0
3 NaN
4 6.0
5 8.0
Name: myseries, dtype: float64
>>> sht.range('A1').value = s
>>> sht.range('A1:B7').options(pd.Series).value
0 1.1
1 3.3
2 5.0
3 NaN
4 6.0
5 8.0
Name: myseries, dtype: float64
~~~
>[info]注意
在向Excel寫入列表，NumPy數組或Pandas DataFrame時，您只需要指定左上角的單元格，例如：`sht.range('A1').value = np.eye(10)`
