# WPS 重要API(表格部分)
## 开始
### 简介
> 本文中所有的测试都是在Python 3.8.5的环境中进行实现的，IDE为Pycharm
>
> 引用的库主要是Pywin32，通过该库直接调用WPS提供的开发API，因此必须在计算机上安装WPS，迁移时记得在目标主机上安装需要的依赖库（当然也可以直接打包成exe）
>
> 由于这种方式直接就是操纵WPS，因此完全可以用一样的方式去调用Excel，但需要根据Office官方提供的二次开发库做一小部分修改（迁移幅度应该不大，因为这其间具有一整套API标准）
### 快速测试
#### 导入库
~~~
# 必须引入client，直接引入win32com可能报错
import win32com.client
~~~
#### 声明application（加载wps的表格）
~~~
# 实际上测试excel时也可以直接这样做
application = win32com.client.Dispatch('Excel.Application')
~~~
#### 打开WPS文件
~~~
# Path指的是本地表格文件的路径，比如:
# Path = r"c:\Users\Aine\Desktop\a.xlsx"
# 通过Win32的方式并不限制xls和xlsx（因为操作是wps在做）
workbook = application.Workbooks.Open(Path)
~~~
#### 读取表格文件中的表
~~~
# Sheet指的就是表名（注意不是文件名）
worksheet = workbook.Worksheets(Sheet)
~~~
#### 修改单元格的内容
~~~
worksheet.Cells(1, 1).Value = 'Hello World'
~~~
#### 修改表名称
~~~
worksheet.Name = 'MySheet'
~~~
#### 保存并退出
~~~
# Path是指要将文件保存到哪一个位置
worksheet.SaveAs(Path)
~~~
#### 操作完成后退出表格文件
~~~
# 注意，此处退出的是文件，而不是WPS程序
# 相当于在WPS中关闭了文件
# 如果操作完表格不关闭文件，极有可能会造成文件无法打开
workbook.Close()
~~~
#### 最后一定要记得退出ET(表格)
~~~
application.Quit()
~~~
### 流程概况
> 1. 加载Application
>
> 2. 通过Application获取Workbook
>
> 3. 通过Workbook的Worksheets获取Worksheet
>
> 4. 根据获取到的表对数据进行操作
>
> 5. 保存修改/另存为
>
> 6. 关闭Workbook（文件）
>
> 7. 关闭Application（ET）
>
## 重要API
#### Application
> 参考 [WPS开放文档](https://open.wps.cn/docs/office)
>
> Application相当于WPS中表格的主程序（也称为et），在Python + Pywin32中，首先要通过Dispatch加载程序
##### 重要方法
###### FindFile和GetOpenFilename（打开文件对话框）
> [参考信息（FindFile）](https://qn.cache.wpscdn.cn/encs/doc/office_v11/index.htm?page=WPS%20%E5%8A%A0%E8%BD%BD%E9%A1%B9%E5%BC%80%E5%8F%91/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Application/%E6%96%B9%E6%B3%95/FindFile%20%E6%96%B9%E6%B3%95.htm)
>
> [参考信息（GetOpenFilename）](https://qn.cache.wpscdn.cn/encs/doc/office_v11/index.htm?page=WPS%20%E5%8A%A0%E8%BD%BD%E9%A1%B9%E5%BC%80%E5%8F%91/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Application/%E6%96%B9%E6%B3%95/GetOpenFilename%20%E6%96%B9%E6%B3%95.htm)
~~~
# FindFile方法
# 该方法属于Application对象的方法，调用后会前台显示WPS界面，并弹出打开文件对话框。
# 注意，该对话框不会返回打开文件的路径，但会返回是否打开成功
# 当选择了一个文件，会在前台打开该文件
Application.FindFile()
# GetOpenFilename方法
# 和FindFile方法不同，这个方法并不会前台打开文件，而是弹出一个打开文件对话框
# 该方法返回的值是文件的全路径
# 通常有需要的情况下是使用GetOpenFilename方法
Application.GetOpenFilename()
~~~
###### GetSaveAsFilename（弹出另存为对话框）
> [参考信息](https://qn.cache.wpscdn.cn/encs/doc/office_v11/index.htm?page=WPS%20%E5%8A%A0%E8%BD%BD%E9%A1%B9%E5%BC%80%E5%8F%91/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Application/%E6%96%B9%E6%B3%95/GetSaveAsFilename%20%E6%96%B9%E6%B3%95.htm)
~~~
# GetSaveAsFilename方法
# 该方法和GetOpenFilename类似，都不会真正的进行另存为操作，而是返回用户选择的全路径
Application.GetSaveAsFilename()
~~~
###### InputBox（弹出一个接受用户输入的对话框）
> [参考信息](https://qn.cache.wpscdn.cn/encs/doc/office_v11/index.htm?page=WPS%20%E5%8A%A0%E8%BD%BD%E9%A1%B9%E5%BC%80%E5%8F%91/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Application/%E6%96%B9%E6%B3%95/InputBox%20%E6%96%B9%E6%B3%95.htm)
~~~
# 该方法会弹出一个包含一个文本框的对话框，并返回用户的输入
# 该文本框可以接受多种数值，也可以指定其标题、初始值、位置以及返回值类型
# 具体参数参考官方文档 ↑↑↑
Application.InputBox("请输入密码","警告","123456")
~~~
###### Run和Wait
> [参考消息（Run）](https://qn.cache.wpscdn.cn/encs/doc/office_v11/index.htm?page=WPS%20%E5%8A%A0%E8%BD%BD%E9%A1%B9%E5%BC%80%E5%8F%91/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Application/%E6%96%B9%E6%B3%95/Run%20%E6%96%B9%E6%B3%95.htm)
>
> [参考消息（Wait）](https://qn.cache.wpscdn.cn/encs/doc/office_v11/index.htm?page=WPS%20%E5%8A%A0%E8%BD%BD%E9%A1%B9%E5%BC%80%E5%8F%91/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Application/%E6%96%B9%E6%B3%95/Wait%20%E6%96%B9%E6%B3%95.htm)
~~~
# Run方法用于运行一个宏或调用一个VB程序
# 注意，个人版一般是不支持宏调用的
# Wait方法用于暂停运行宏
Application.Run(要运行的宏)
# Wait会暂停ET的一切操作，当然不会暂停打印和重新计算
# 传入的值是必须的，含义是下一次继续运行的时间，比如Wait("12:20:00")
Application.Wait(继续运行的时间)
~~~
当然也可以暂停运行指定的时间，比如十分钟（官方例程）
~~~
let now = new Date()
let seconds = now.getTime()
now.setTime(seconds + 1000 * 10)
Application.Wait(now.toLocaleString())
~~~
###### Quit
> [参考信息](https://qn.cache.wpscdn.cn/encs/doc/office_v11/index.htm?page=WPS%20%E5%8A%A0%E8%BD%BD%E9%A1%B9%E5%BC%80%E5%8F%91/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Application/%E6%96%B9%E6%B3%95/Quit%20%E6%96%B9%E6%B3%95.htm)
~~~
# Quit几乎是最需要但最容易忘记的方法，它负责退出ET程序，注意，该方法要在退出表格文件之后执行
# 另外，如果有未保存的Workbook，ET会弹出对话框询问用户是否关闭，可以通过将Application中的DisplayAlerts设置为False（不显示信息，会直接不保存退出）
Application.Quit()
~~~
##### 重要属性
###### ActivePrinter（获取/设置打印机）
~~~
# String类型
Application.ActivePrinter
~~~
###### Build（获取ET内部版本号）
~~~
Application.Build
~~~
###### DisplayFullScreen（是否全屏）
~~~
# 指示ET当前是否为全屏状态，可读写（True 全屏； FaLse 非全屏）
Application.DisplayFullScreen
~~~
###### EnableSound（是否允许发声）
~~~
# 该属性指示ET是否可以发出声音，Boolean，可读写
Application.EnableSound
~~~
###### HighQualityModeForGraphics（高质量打印图形）
~~~
# Boolean
Application.HighQualityModeForGraphics
~~~
###### Hinstance（获取ET的句柄）
~~~
# 只读
Application.Hinstance
~~~
###### OperatingSystem（获取操作系统版本）
~~~
# 只读
Application.OperatingSystem
~~~
###### Path（获取WPS所在目录）
~~~
# 只读
Application.Path
~~~
###### PrintCommunication（测试打印机可达性）
~~~
Application.PrintCommunication
~~~
###### Ready（ET是否就绪）
~~~
# 判断ET是否准备就绪
Application.Ready
~~~
###### ScreenUpdating（屏幕更新）
~~~
# 一般设置为True，如果需要加快宏（包括Py脚本）运行，可以暂时设置为False
Application.ScreenUpdating
~~~
###### StatusBar（设置状态栏文字）
~~~
# 可以获取和设置ET下方状态栏的文本
Application.StatusBar
~~~
###### UserControl （判断窗口是否由用户打开）
~~~
# 如果用户创建或者ET可见，该值为True，如果以代码方式打开切应用程序隐藏，该值为False
Application.UserControl
~~~
###### UserName （获取系统用户名）
~~~
Application.UserName
~~~
###### Version（ET版本号）
~~~
Application.Version
~~~
###### Visible（是否可见）
~~~
# 确定ET是否可见（一般不用设置，如果设置可能造成运行时闪一下屏）
Application.Visible
~~~
###### Workbooks（打开的工作表）
~~~
# 最重要的属性之一，代表所有打开的ET文件
Application.Workbooks
# 可以通过它调取Open方法来打开ET文件
workbook = application.Workbooks.Open(Path)
~~~
###### Worksheets（Sheets集合）
~~~
# 代表Sheets集合
# 对于Application对象来说，该属性代表活动工作簿（文件）中的所有工作表（sheet）
Application.Worksheets
~~~
* * *
#### Workbook
> 参考 [WPS开放文档](https://open.wps.cn/docs/office)
>
> Workbook相当于在ET中打开的一个文件，注意是一个文件而不是文件中的表格
>
> Workbook对象一般是由打开文件产生的，当然这不唯一
##### 重要方法
###### **[PrintOut](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbook/%E6%96%B9%E6%B3%95/PrintOut%20%E6%96%B9%E6%B3%95.htm)**（打印文档）
> **[PrintOut](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbook/%E6%96%B9%E6%B3%95/PrintOut%20%E6%96%B9%E6%B3%95.htm)**可用的参数很多，并且都是可选参数，可用控制打印的起始页、终止页、份数、是否调用打印预览（默认False）、活动的打印机名、是否打印到文件、是否逐份打印、是否忽略打印区域并打印整个文档和区域语言
~~~
Workbook.PrintOut(起始页, 终止页, 份数, 打印预览, 活动的打印机, 是否打印到文件, 逐份打印, 打印到文件的位置, 是否打印整个对象, 区域语言)
~~~
###### **[Save](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbook/%E6%96%B9%E6%B3%95/Save%20%E6%96%B9%E6%B3%95.htm)**（保存文件）
> 保存对指定工作簿所做的更改
~~~
Workbook.Save()
~~~
###### **[SaveAs](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbook/%E6%96%B9%E6%B3%95/SaveAs%20%E6%96%B9%E6%B3%95.htm)**（另存为文件）
> 另存文档到指定位置
>
> 参数很多，比较常用的一般是Filename（保存到）、FileFormat（保存格式）
~~~
Workbook.SaveAs(文件路径,文件格式...)
~~~
###### **[Close](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbook/%E6%96%B9%E6%B3%95/Close%20%E6%96%B9%E6%B3%95.htm)**（关闭工作簿）
> 一定记得用完关掉，关掉工作簿之前要记得保存
>
> 虽然具有参数，但一般不需要传参
###### **[SendMail](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbook/%E6%96%B9%E6%B3%95/SendMail%20%E6%96%B9%E6%B3%95.htm)**（发送邮件）
> 这种方式当然可以使用，但如果想要直接后台发送，完全可以使用Python的yagmail库，一般的只需要两行代码就完成发送
~~~
Workbook.SendMail(收件人,主题,是否请求返回收件人,区域语言)
~~~
###### **[XmlImport](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbook/%E6%96%B9%E6%B3%95/XmlImport%20%E6%96%B9%E6%B3%95.htm)**（XML转XLS/XLSX）
> 实际上是导入Xml文件导入到工作表中，真实现转换只需要保存即可
~~~
Workbook.XmlImport(URL/UNC路径,XmlMap架构映射)
~~~
##### 重要属性
###### **[FullName](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbook/%E5%B1%9E%E6%80%A7/FullName%20%E5%B1%9E%E6%80%A7.htm)**（打开的工作簿的全路径）
> 一般用来获取当前打开文件的全路径
###### **[Password](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbook/%E5%B1%9E%E6%80%A7/Password%20%E5%B1%9E%E6%80%A7.htm)**（如果打开工作簿需要密码，在此处设置）
~~~
# 一般也用不上，但也不是不可能
Workbook.Password()
~~~
###### **[ReadOnly](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbook/%E5%B1%9E%E6%80%A7/ReadOnly%20%E5%B1%9E%E6%80%A7.htm)**（判断打开的文件是否是只读的）
> 只读状态一般是因为已经打开了
>
> 也有可能是之前通过程序打开但是没有进行关闭（.Close()方法）
###### **[Saved](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbook/%E5%B1%9E%E6%80%A7/Saved%20%E5%B1%9E%E6%80%A7.htm)** （文件是否保存）
> 可以根据此属性判断文件是否已经保存，防止数据丢失
###### **[Worksheets](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbook/%E5%B1%9E%E6%80%A7/Worksheets%20%E5%B1%9E%E6%80%A7.htm)**（工作簿中所有的工作表）
> 一般都是通过这种方式来获取Sheets对象，灰常重要
* * *
#### Workbooks
##### 重要方法
**[Add](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbooks/%E6%96%B9%E6%B3%95/Add%20%E6%96%B9%E6%B3%95.htm)** （新建工作表）
**[Open](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbooks/%E6%96%B9%E6%B3%95/Open%20%E6%96%B9%E6%B3%95.htm)**（打开工作表）
**[Close](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbooks/%E6%96%B9%E6%B3%95/Close%20%E6%96%B9%E6%B3%95.htm)** （关闭对象）
**[OpenDatabase](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbooks/%E6%96%B9%E6%B3%95/OpenDatabase%20%E6%96%B9%E6%B3%95.htm)**（打开数据库）
**[OpenText](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbooks/%E6%96%B9%E6%B3%95/OpenText%20%E6%96%B9%E6%B3%95.htm)**（打开文本文件）
**[OpenXML](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbooks/%E6%96%B9%E6%B3%95/OpenXML%20%E6%96%B9%E6%B3%95.htm)**（打开XML）
##### 重要属性
**[Count](https://qn.cache.wpscdn.cn/encs/doc/office_v11/topics/C++%20%E5%BA%94%E7%94%A8%E9%9B%86%E6%88%90%20WPS%20%E6%8C%87%E5%8D%97/%E8%A1%A8%E6%A0%BC%20API%20%E5%8F%82%E8%80%83/Workbooks/%E5%B1%9E%E6%80%A7/Count%20%E5%B1%9E%E6%80%A7.htm)**（获取工作表的数量）
