@belia
2018-10-26T22:31:50.000000Z
字数 59833
阅读 20851
python
python第三方包
python-docx是一个用于创建和更新Microsoft Word(.docx)文件的Python库。
from docx import Document
from docx.shared import Inches
document = Document()
document.add_heading('Document Title', 0)
p = document.add_paragraph('A plain paragraph having some ')
p.add_run('bold').bold = True
p.add_run(' and some ')
p.add_run('italic.').italic = True
document.add_heading('Heading, level 1', level=1)
document.add_paragraph('Intense quote', style='Intense Quote')
document.add_paragraph(
'first item in unordered list', style='List Bullet'
)
document.add_paragraph(
'first item in ordered list', style='List Number'
)
document.add_picture('monty-truth.png', width=Inches(1.25))
records = (
(3, '101', 'Spam'),
(7, '422', 'Eggs'),
(4, '631', 'Spam, spam, eggs, and spam')
)
table = document.add_table(rows=1, cols=3)
hdr_cells = table.rows[0].cells
hdr_cells[0].text = 'Qty'
hdr_cells[1].text = 'Id'
hdr_cells[2].text = 'Desc'
for qty, id, desc in records:
row_cells = table.add_row().cells
row_cells[0].text = str(qty)
row_cells[1].text = id
row_cells[2].text = desc
document.add_page_break()
document.save('demo.docx')
注意:python-docx版本0.3.0及更高版本与先前版本API不兼容。
python-docx 托管在PyPI上,因此安装相对简单,只取决于您安装的应用程序。
1. 如果在pip工具可用的情况下你可以直接安装python-docx,如果还没有安装 可以自行搜索怎样安装。其在代码如下:
pip install python-docx
2. 当然你也可以用easy_install来安装python-docx,但是方法不如上面一 种好。其安装代码如下:
easy_install python-docx
3. 然而,如果你的pip和你的easy_install都不可用的时候,那么此时你可以手动的通过PyPI下载,然后解压包、运行setup.py.
tar xvzf python-docx-{version}.tar.gz
cd python-docx-{version}
python setup.py install
使用python-docx是非常容易的,让我们一点一点学习这些!
首先,如果你需要操作一篇文档,下面是最容易的方法:
from docx import Document
document = Document()
这是基于默认模板打开一个空白文档,这几乎是你从word打开一个新文档的内置默认值。你也可以打开并基于一个现有的文档来使用python-docx,但是我们现在想保持这么简单的做法。
段落是word结构的基础,他们用于正文,也标题和列表项目。这是添加一个段落的示例方法:
paragraph = document.add_paragraph('Lorem ipsum dolor sit amet.')
这个方法返回对一个段落的引用,在文章的结尾加上一个新段落。这种情况下,这个新段落引用将会被分配给paragraph
,但是,除非我需要这个引用,否则我会忽视掉它,在你的代码中通常不会要做任何事情在你添加了一个新段落之后。因此,保持对它的引用没有多大意义。
它还可以当作一个“光标”,用来插入一个新段落。
prior_paragraph = paragraph.insert_paragraph_before('Lorem ipsum')
这就使得我们可以在文档中间插入文档,这对于我们修改一篇而不是从零开始创建一篇文档来说重要的多。
在一些除了一些很短的文章中,正文一般分为几部分,每部分都是一个从一个标题开始,下面是如何添加一个标题的示例:
document.add_heading('The REAL meaning of the universe')
在默认情况,此代码是添加一个最高级别的标题,在word中通常显示为“标题1”,当你想要添加一个子节标题时,你可以将你需要的级别指定为一个0-9之间的整数。就像这样:
document.add_heading('The role of dolphins', level=2)
如果你指定的级别为0,则会添加一个标题段落,这可以很方便的开始一个没有单独标题的相对较短的文章。
每隔一段时间你就想要接下来的内容放到下一页面上,即使这个页面还没有满,而一个强制分页则可以完成这些操作:
document.add_page_break()
你如果发现你用的非常频繁,那么它可能就是一个你可以很好理解段落格式的一个信号。您可以设置的一个段落样式属性是在每个具有该样式的段落之前立即断开一个页面。因此,你可以合适的设置一个标题级别来确保总能开始一个新页面。更多关于样式的信息你可以在后面看到,事实证明,在Word中利用好他们是非常重要的。
一个人经常会遇到一些内容,它们与表格类似,整齐的排列在一行或者一列中。Word在这个方面做的很好,下面是如何添加一个表格的示例:
table = document.add_table(rows=2, cols=2)
表格有几种方法和属性,您可以通过他们来填充表格。通过访问一个单元格
来学习是一个很好的开始,作为基础,你可以通过列或者行的一些信息来访问他们:
cell = table.cell(0, 1)
这是我们刚刚创建的的单元格中最右边的单元格,注意他的行列起始值是0,就像通过List访问。
如果你选中了一个单元格,你可以把一些文字放入里面:
cell.text = 'parrot, possibly dead'
通常,一次访问一个表会更加容易,例如当从一个数据源填充一个可变长度的表格时,在每一个含有.cells属性的表格中我们均可以通过.rows属性来访问每一行。这个.cells可同时支持Row和Colum的索引访问,就像一个List:
row = table.rows[1]
row.cells[0].text = 'Foo bar to you.'
row.cells[1].text = 'And a hearty foo bar to you too sir!
在表格中.rows和.columns集合是可迭代的,你可以直接在for循环里面使用它们,与此相同的,.cells上行或列成序列:
for row in table.rows:
for cell in row.cells:
print(cell.text)
如果你想要得到行或列的的数目,那么你可以使用len():
row_count = len(table.rows)
col_count = len(table.columns)
你也可以以递增方式向表中添加行:
row = table.add_row()
这对于我们上面提到的可变长度表来说是十分方便的:
# 获取表格数据
items = (
(7, '1024', 'Plush kittens'),
(3, '2042', 'Furbees'),
(1, '1288', 'French Poodle Collars, Deluxe'),
)
# 添加表格
table = document.add_table(1, 3)
# 添加表头
heading_cells = table.rows[0].cells
heading_cells[0].text = 'Qty'
heading_cells[1].text = 'SKU'
heading_cells[2].text = 'Description'
# 给每项添加行数据
for item in items:
cells = table.add_row().cells
cells[0].text = str(item.qty)
cells[1].text = item.sku
cells[2].text = item.desc
同样对添加列来说也是一样的。
Word具有一组预先已经格式化好的表格样式,你可以从它的表格样式库中选择,你可以将其中一个应用于表格,如下所示:
table.style = 'LightShading-Accent1'
从表样式名称中删除所有空格可以形成样式名称,你可以通过将鼠标悬停在Word的表样式库中的缩略图上,可以找到表样式名称。
在Word中,你可以通过【插入】--> 【图像】--> 【来自文件】菜单来添加图片,而在这里,你则可以这么添加:
document.add_picture('image-filename.png')
此例子使用了从本地加载图片路径,你也可以使用一个类文件对象,本质上就像打开任何一个文件对象。如果你从网络或者数据库而不想从本地获取数据,这会很方便。
照片大小
默认情况下,添加的的图片大小等于您本地图片大小,但这通常会比您想象的更大。本地图片大小的计算方法是像素/dpi(每英寸像素点数),因此,一个300dpi的300x300像素的图片通常大小是1英寸,但是问题是现在大多数图片的默认72dpi,这实际上使得同样的图片在这样的情况下会在一半的页面上一边显示大小为4.167英寸。
在这里,要获得你想要的图像大小,你可以指定其高度和宽度,如inches或cm:
from docx.shared import Inches
document.add_picture('image-filename.png', width=Inches(1.0))
你可以自由的指定高度和宽度,但是你通常情况下不想要这样。如果你指想要其中要给参数,python-docx通常可以帮你计算出另外一个参数,这样可以保持你照片的长宽比,使他看上去不是被拉伸的。
你可以使用英寸或者厘米这两个方便的单位来指定你的测量单位。在python-docx内部,我们默认使用英国公制单位,914400英寸(这里没查到,只查到914400um=1码),因此你如果忘记了而只是指定了宽度为2的话你就得到一个很小的图像。此时你需要导入docx.shared
子包,你可以就像一个整数一样的在算术中使用它们,当然,他们事实上也是,因此,像一个表达式width = Inches(3) /thing_count就被利用的很好。
如果你不知道Word的段落格式,你应该检查下它。基本上,它允许你能一次性应用一整套样式,如果你了解CSS的话,它和CSS非常类似。
你可以在创建段落时应用段落样式:
document.add_paragraph('Lorem ipsum dolor sit amet.', style='ListBullet')
这种特殊的样式会使得段落以一个符号的样式出现,一个非常方便的东西。之后你依然还可以应用样式,这下面的两行相当于上面的一行:
paragraph = document.add_paragraph('Lorem ipsum dolor sit amet.')
paragraph.style = 'List Bullet'
这个样式被指定用他的样式名,如上所示的List Bullet
。通常,样式名出现在Word的用户界面中,但是,请注意,如果您使用的是本地化版本的Word,则样式ID可能来自英语样式名称,并且可能不会完全对应于其在Word UI中的样式名称。
为了能够理解黑体和斜体是怎么回事,你需要理解一点段落内部的事情,简短来说就是这样:
1. 一个段落包含所有块级格式,例如缩进、行高、Tab等等。
2. 字符级别的格式,例如黑体和斜体,都是被应用于run级别的。所有段落里面的内容都必须在一个run里面但是也不仅仅一个更新。因此一个含有粗体的段落可能会需要三个run,一个是普通的,一个是包括了粗体的,以及后面另外一个普通的。
当你利用.add_paragraph()
方法向一个段落中添加一段文字的时候,它被放入一个单独的run中,你可以使用.add_run()
在段落中添加更多的内容:
paragraph = document.add_paragraph('Lorem ipsum ')
paragraph.add_run('dolor sit amet.')
这样产生一个像一个单独字符串产生的段落。除非你看xml,否则你不会看不来这些内容是分开的。注意第一个字符串末尾的尾随空格,你需要明确说明空格在开头和结尾之间出现的位置,他们不会自动的在runs之间插入。你总能遇到你几次这个问题。
Run
这个对象有.bold
和.italic
两个属性值供你去设置:
paragraph = document.add_paragraph('Lorem ipsum ')
run = paragraph.add_run('dolor')
run.bold = True
paragraph.add_run(' sit amet.')
上述例子的结果像这样: ‘Lorem ipsum dolor sit amet.’
如果你不需要其它的设置你也可以直接对.add_run()
的.bold
和italic
值结果设置为True
:
paragraph.add_run('dolor').bold = True
# 它同时也等于:
run = paragraph.add_run('dolor')
run.bold = True
# 你不需要'run'之后再次设置引用
利用.add_paragraph
构建内容不是必须的,如果你是从runs中构建内容的话这会使你的代码变得更加简单:
paragraph = document.add_paragraph()
paragraph.add_run('Lorem ipsum ')
paragraph.add_run('dolor').bold = True
paragraph.add_run(' sit amet.')
除了指定一组段落级别的段落样式外,Word还可以指定一组run级别的字符样式,通常你可以认为这些字符样式包括字符、字体、字号、颜色、粗体、斜体等等。
和段落样式一样,字符样式必须定义在你已经用Document()打开的文档中。(见理解样式)。
字符样式可以在添加一个run中定义:
paragraph = document.add_paragraph('Normal text, ')
paragraph.add_run('text with emphasis.', 'Emphasis')
你也可以在字符已经创建好了之后再去应用样式,这段代码与撒谎上面的代码效果相同:
paragraph = document.add_paragraph('Normal text, ')
run = paragraph.add_run('text with emphasis.')
run.style = 'Emphasis'
如同段落样式一样,这些样式名称可以再Word界面内看见。
python-docx允许你创建一个新文件或者在一个已经存在的文件上做些修改。事实上,它只允许你从一个已经存在的文档上进行修改。如果你需要从一篇没有任何内容的文档开始,你会感觉从头开始一篇文档一样。
这个特点是强大的。决定许多文档看上去怎么样子的部分是你删除所有内容后留下的。这些样式如页眉、也叫是与你的主要内容无关的,因此,你可以从文档的开头就放置这些个性化的内容而之后他们会在文档中出现。
让我们逐步的创建一个文档示例,并开始做两件事:打开并保存它。
最简单的入门方法是打开一个新文档,而不是指定一个文档打开:
from docx import Document
document = Document()
document.save('test.docx')
这个示例是基于内置的默认模板创建一个文档并把它保存成一个没有改变的文件名:test.docx。这个默认模板实质上是一个没有任何内容的新文档,保存在你已经安装好的python-docx包里。选择Word Doucument模板与你在Word中选择【文件】-【新模板】菜单选项选择的Word Document(Word文件选项里面好像没有这个选项( ̄▽ ̄)",感觉应该是文件-->新建里面选择的模板)大致相同。
如果说你想要更多的改变最终文档,或者说更改已经存在的一个文档,这个时候你则需要打开一个存在着文件名的一个文档:
document = Document('存在的文档.docx')
document.save('重命名的文档.docx')
注意事项:
- 你可以用这个方法打开任何Word 2007及以后的版本(Word 2003及更早期的.doc文件我们无法使用)。虽然也许你不能很好的编辑内容,但是你可以很好的加载和保存。它现在还在完善中,因此你现在还不能进行添加或者改变标题或者脚注之类的东西,但是Python-docx会很“客气的”把这些内容单独放在一边并足够聪明的保存它们不用实际理解他们到底是什么。
- 如果你在打开文件和保存文件的时候使用了同一个文件名,python-docx将会按照你的意思覆盖原始文件而不用其它提醒。你要确定那就是你想要的。
python-docx可以打开一个文档从要一个“类文件”对象中,当然也可以同样保存一个“类文件”对象。这当你想要从网络或者数据库中获取源或文档而不想(不允许)与本地文件系统交互的时候是非常方便的。实际上,这意味着你可以通过打开文件或者StringIO/BytesIO流中对象来打开或者保存一个文档:
f = open('foobar.docx', 'rb')
document = Document(f)
f.close()
# or
with open('foobar.docx', 'rb') as f:
source_stream = StringIO(f.read())
document = Document(source_stream)
source_stream.close()
...
target_stream = StringIO()
document.save(target_stream)
不是所有的操作系统都要求这个'rb'打开文件模式的参数,在某些操作系统里面'r'就足够了,但是在Windows或者要给Linux一些系统中是需要'b'(选择二进制模式)这个参数去允许打开zip文件格式的文件的。
好了,你已经打开了一个文档并且确信它可以稍后保存在某一个地方。下一步则是获取一些内容.....
为更有效的处理文本,理解一些块级元素比如段落和内联级别比如run是非常重要的。
段落是Word中的主要块级对象。
块级项中的文本主要包含在它左右边沿之间。当文本的内容超过了它的右边界时,这些超出的文本则就会添加到下一行。对于段落而言,边界通常是页边距,但是如果段落在列中展开的话,边界也可以是列边界,如果在在表格里面的单元格中发生的话,它也是单元格的边界
表格通常是一个块级对象。
一个内联对象通常是一个块级项内容发生的一部分,一个例子便是在Word中的一个粗体的单词和一个全部为大写的句子。而最主要的内联对象便是运行。所有块容器中的内容里面都在内联对象里面,一个段落包含一个或者多个run,他们每个都是段落文本的一部分。
块级项的属性指定其在页面上的位置,例如缩进和段前段后的空格。内联项通常指定显示内容的字体、字号、粗体、斜体等。
一个段落有许多属性,他们通常指定在容器中的位置(通常在页面中)以及将行分成不同行的方法。
通常情况下,应该将段落格式的属性集成到一个组中,然后应用到段落中,而不是每次都重复的将他们属性添加到段落中。这类似于CSS与HTML如何一起工作。这里所有的段落属性都可使用样式设置,也可直接应用于段落。
段落的格式属性是用通过ParagraphFormat对象访问的,该对象使用段落的Paragraph_Format
属性。
也称为对齐,通过使用枚举WD_PARAGRAPH_ALIGNMENT
可以将段落的水平对齐设置为左、中、右或两端对齐(在左和右对齐):
>>> from docx.enum.text import WD_ALIGN_PARAGRAPH
>>> document = Document()
>>> paragraph = document.add_paragraph()
>>> paragraph_format = paragraph.paragraph_format
>>> paragraph_format.alignment
None # indicating alignment is inherited from the style hierarchy
>>> paragraph_format.alignment = WD_ALIGN_PARAGRAPH.CENTER
>>> paragraph_format.alignment
CENTER (1)
缩进是段落于容器边缘之间的水平空间,通常我们叫做页边距。段落我们可以在左边和右边分别缩进,段落第一行也可以拥有和其他行不一样的缩进量。第一行相较于其他行缩进来说成为首行缩进,而其他行相较于首行的缩进我们则称之为悬挂缩进。
缩进使用的长度值(例如英寸、磅、厘米)指定的。负值有效但这将导致段落重叠。空值则表示缩进是直接继承的层次结构值。将None
赋值给缩进属性则会移除直接应用的缩进属性设置并且从层次结构中还原继承。
>>> from docx.shared import Inches
>>> paragraph = document.add_paragraph()
>>> paragraph_format = paragraph.paragraph_format
>>> paragraph_format.left_indent
None # indicating indentation is inherited from the style hierarchy
>>> paragraph_format.left_indent = Inches(0.5)
>>> paragraph_format.left_indent
457200
>>> paragraph_format.left_indent.inches
0.5
右边的缩进也类似:
>>> from docx.shared import Pt
>>> paragraph_format.right_indent
None
>>> paragraph_format.right_indent = Pt(24)
>>> paragraph_format.right_indent
304800
>>> paragraph_format.right_indent.pt
24.0
首行行缩进是使用first_line_indent
属性指定的,并且是相对于左缩进行来说的。负值表示悬挂缩进:
>>> paragraph_format.first_line_indent
None
>>> paragraph_format.first_line_indent = Inches(-0.25)
>>> paragraph_format.first_line_indent
-228600
>>> paragraph_format.first_line_indent.inches
-0.25
制表位停止了制表符的呈现,特别的是,他可以指定制表符后面文本开始的位置,以及将如何对齐到该位置,以及一个可选的leader字符,它将填充选项卡所跨越的水平空间。可以通过tab填满的可选主要字符。
段落或样式的制表符包含在一个TabStops
对象中,该对象使用ParagrapFormat
上的tab_stops
属性访问:
>>> tab_stops = paragraph_format.tab_stops
>>> tab_stops
<docx.text.tabstops.TabStops object at 0x106b802d8>
使用add_tab-stop()
方法添加一个新的制表位:
>>> tab_stop = tab_stops.add_tab_stop(Inches(1.5))
>>> tab_stop.position
1371600
>>> tab_stop.position.inches
1.5
默认是左对齐,但是可以通过提供WD_TAB_ALIGNMENT
枚举成员来指定。 前导符默认是空格,但我们可以通过提供WD_TAB_LEADER
来指定:
>>> from docx.enum.text import WD_TAB_ALIGNMENT, WD_TAB_LEADER
>>> tab_stop = tab_stops.add_tab_stop(Inches(1.5), WD_TAB_ALIGNMENT.RIGHT, WD_TAB_LEADER.DOTS)
>>> print(tab_stop.alignment)
RIGHT (2)
>>> print(tab_stop.leader)
DOTS (1)
使用TabStops上的序列语义访问现有的制表符:
>>> tab_stops[0]
<docx.text.tabstops.TabStop object at 0x1105427e8>
更多信息请见TabStops
和TabStop
API 文档
space_before
和space_after
属性控制着段间距,控制着段前段后的距离。
段间距在页面布局内被折叠,这意味着两段之间的间距是第一段的空格后和第二段空格前的最大值。段间距被指定为一个长度值,通常使用Pt
:
>>> paragraph_format.space_before, paragraph_format.space_after
(None, None) # inherited by default
>>> paragraph_format.space_before = Pt(18)
>>> paragraph_format.space_before.pt
18.0
>>> paragraph_format.space_after = Pt(12)
>>> paragraph_format.space_after.pt
12.0
行间距是指段落中行基线之间的距离。行间距可以指定为绝对距离,也可以指定相对于行高度(基本上是所用字体的点大小)。一个典型的绝对衡量标准是18磅。一个典型的相对测量值将是两个空格(2.0倍行距)。默认的行距是一个空格(1.0倍行距).
行距是由line_spacing
和line_spacing_rule
属性的相互作用控制。line_spacing
是一个Length
,是(小数)float
,或者是零。Length
表示绝对距离。浮点数表示多个float
。None表示继承了行距。line_space_Rule
是wd_line_space
枚举或者None
的成员:
>>> from docx.shared import Length
>>> paragraph_format.line_spacing
None
>>> paragraph_format.line_spacing_rule
None
>>> paragraph_format.line_spacing = Pt(18)
>>> isinstance(paragraph_format.line_spacing, Length)
True
>>> paragraph_format.line_spacing.pt
18.0
>>> paragraph_format.line_spacing_rule
EXACTLY (4)
>>> paragraph_format.line_spacing = 1.75
>>> paragraph_format.line_spacing
1.75
>>> paragraph_format.line_spacing_rule
MULTIPLE (5)
四个段落属性kepp_together
,keep_with_next
、page_break_before
、widow_control
控制着段落在页面附近的显示。kepp_together
会导致整个断过出现在同一个页面上,如果不这么做的就会在段落之前存在分页符。
keep_with_next
会使后面的段落与当前段落出现在同一张页面内。举例来说,这将会被用在使节标题和小节内的段落保持在同一个页面。
page_break_before
使得一个段落可以放置在一个新页面的顶部。这将会使得章节标题总是会从新页面开头出现。
widow_control
会断开一个页面,以避免将段落的第一行或最后一行放在与段落其余部分分开的页面上。
所有的这四种属性都是有三种状态的,即他们可以取值True
、False
或者None
.None
表示这些属性值将会继承层次结构,True
表示打开,Flase
表示关闭:
>>> paragraph_format.keep_together
None # all four inherit by default
>>> paragraph_format.keep_with_next = True
>>> paragraph_format.keep_with_next
True
>>> paragraph_format.page_break_before = False
>>> paragraph_format.page_break_before
False
字符格式通常被应用在Run
级,举例来说它通常包含字号、字体、粗体、斜体、下划线。
Run对象的只读Font
属性提供对font
对象的访问。run的Font
对象提供了获取和设置该运行的字符格式的属性。
这里提供了几个例子,有关可用属性的完整集合,请参阅Font API文档。
run中的font可通过如下方式访问:
>>> from docx import Document
>>> document = Document()
>>> run = document.add_paragraph().add_run()
>>> font = run.font
字体和字号通常像这样设置:
>>> from docx.shared import Pt
>>> font.name = 'Calibri'
>>> font.size = Pt(12)
许多字体属性是三态的,即也可以取值True
,False
以及None
.True
意味着属性是可以用,而False
则与之相反。而None
从概念上讲则意味着"继承”。运行存在于继承层次结构的样式中,默认情况下从该层次结构继承其字符格式。使用Font
对象直接应用的任何字符格式都会覆盖继承的值。
加粗和斜体是三态属性,全大写、删除线、上标等等也是。有关完整列表,请参阅Font
API文档:
>>> font.bold, font.italic
(None, None)
>>> font.italic = True
>>> font.italic
True
>>> font.italic = False
>>> font.italic
False
>>> font.italic = None
>>> font.italic
None
Underline是一个特例。它是三态属性和枚举值属性的混合。True
表示单下划线,这是目前最常见的。False
表示不需要下划线,但通常情况下,如果s属性值为None
,则也代表不需要下划线。其他形式的下划线,如双划线或虚线,都是由WD_UNDERLINE枚举成员指定的:
>>> font.underline
None
>>> font.underline = True
>>> # or perhaps
>>> font.underline = WD_UNDERLINE.DOT_DASH
每个Font
对象都有一个ColorFormat
对象,该对象提供对其颜色的访问,可通过其只读color
属性访问。
给字体指定一个RGB颜色:
>>> from docx.shared import RGBColor
>>> font.color.rgb = RGBColor(0x42, 0x24, 0xE9)
字体的颜色可以恢复到它的默认值(继承),通过分配None
给rgb
或theme_color
属性的ColorFormat
:
>>> font.color.rgb = None
确定字体的颜色首先要确定字体的颜色类型:
>>> font.color.type
RGB (1)
颜色类型属性的值可以是MSO_COLOR_TYPE
枚举的成员或None
。MSO_COLOR_TYPE.RGB表示它是RGB颜色
。MSO_COLOR_TYPE.THEME
表示主题颜色.MSO_COLOR_TYPE.AUTO
表示其值由应用程序自动确定,通常设置为黑色。(这个值比较罕见).None
表示没有应用颜色,颜色是从样式层次结构继承而来的;这是最常见的情况。
当颜色类型是MSO_COLOR_TYPE.RGB
时,rgb
属性为RGBColor
值,表示RGB颜色:
>>> font.color.rgb
RGBColor(0x42, 0x24, 0xe9)
当颜色类型为MSO_COLOR_TYPE.THEME
,theme_color
属性将是MSO_THEME_COLOR_INDEX
的成员,表示主题颜色:
>>> font.color.theme_color
ACCENT_1 (5)
Word支持section的概念,section是文档中具有相同页面布局设置(如页边距和页面方向)的部分。例如,这就是文档如何在纵向布局中包含一些页面,在横向布局中包含一些页面的方法。
大多数Word文档只有默认出现的一个部分,而且大多数文档没有理由更改默认的页边距或其他页面布局。但是,当您确实需要更改页面布局时,您需要了解各个部分才能完成。
对文档部分的访问由Document
对象上的sections
属性提供:
>>> document = Document()
>>> sections = document.sections
>>> sections
<docx.parts.document.Sections object at 0x1deadbeef>
>>> len(sections)
3
>>> section = sections[0]
>>> section
<docx.section.Section object at 0x1deadbeef>
>>> for section in sections:
... print(section.start_type)
...
NEW_PAGE (2)
EVEN_PAGE (3)
ODD_PAGE (4)
从理论上讲,文档没有标明sections
是可能的,尽管我还没有看到这种情况在发生。如果您正在访问不可预知的.docx文件,您可能希望使用len()
检查或try
语句来避免未捕获的IndexError
异常阻止您的程序。
sectionsadd_section()
方法允许在文档末尾添加一个新的section。调用此方法后添加的段落和表将出现在新的section中:
>>> current_section = document.sections[-1] # last section in document
>>> current_section.start_type
NEW_PAGE (2)
>>> new_section = document.add_section(WD_SECTION.ODD_PAGE)
>>> new_section.start_type
ODD_PAGE (4)
Section
对象有允许发现和指定页面布局设置的11个属性。
Section.start_type
描述的是section
之前的隔断类型:
>>> section.start_type
NEW_PAGE (2)
>>> section.start_type = WD_SECTION.ODD_PAGE
>>> section.start_type
ODD_PAGE (4)
start_type
值是枚举变量WD_SECTION_START
的成员
Section中的三个属性描述了页面的尺寸和方向。这些可以一起使用,例如,将Section的方向由纵向到横向:
>>> section.orientation, section.page_width, section.page_height
(PORTRAIT (0), 7772400, 10058400) # (Inches(8.5), Inches(11))
>>> new_width, new_height = section.page_height, section.page_width
>>> section.orientation = WD_ORIENT.LANDSCAPE
>>> section.page_width = new_width
>>> section.page_height = new_height
>>> section.orientation, section.page_width, section.page_height
(LANDSCAPE (1), 10058400, 7772400)
Section的7个属性一起指定了决定文本出现在页面上的不同页边距:
>>> from docx.shared import Inches
>>> section.left_margin, section.right_margin
(1143000, 1143000) # (Inches(1.25), Inches(1.25))
>>> section.top_margin, section.bottom_margin
(914400, 914400) # (Inches(1), Inches(1))
>>> section.gutter
0
>>> section.header_distance, section.footer_distance
(457200, 457200) # (Inches(0.5), Inches(0.5))
>>> section.left_margin = Inches(1.5)
>>> section.right_margin = Inches(1)
>>> section.left_margin, section.right_margin
(1371600, 914400)
python-docx的API旨在使简单的事情变得简单,同时允许通过适度和增强的理解来实现更复杂的结果。
仅使用一个对象docx.api.Document
就可以创建基本文档是可能的,即打开文件时返回文档对象。docx.api.Document
上的方法,文档允许将块级对象添加到文档末尾。块级对象包括段落、内联图片和表。标题、项目符号和编号列表只是应用了特定样式的段落。
通过这种方式,我们可以从上到下“写”出一篇文章,几乎像一个人如果他们知道他们想要什么会说这个的基本用例,在内容总是添加到文档的最后,预计可能会占80%的实际使用情况下,这是一个优先的前提下尽可能地让它尽可能简单的力量整个API。
docx.api.Document
上的每个块级方法。例如add_paragraph()
,返回创建的块级对象,通常不需要引用;但是,当必须单独创建内联对象时,您需要使用块引用来完成。
...还有更多的示例...
Grasshopper:
“师傅,为什么我的段落不符合我指定的风格?”
师傅:
“那是因为你还需要把这篇文章阅读下去,Grasshopper”
当文档的的元素格式一致的时候,处理文档就会变得很容易。为了达到这种效果,文档专业设计者开发了样式表,样式表定义了文档元素类型以及指定了每种元素的格式。例如,段落主题被设置为:字号9pt,字体:Times Roman,行间距为11pt,左端对齐,加粗。当这些指定的内容被添加到每个文档的元素上面时,一个整体美观的外观是可以实现的。
Word中的样式是一组可以一次性应用于文档的规范。Word有段落样式、字符样式、表格样式和数字定义。他们被应用于段落、文本、表格、列表等等。
有经验的程序员会将样式定位为间接Level,关于它的好处其中之一便是允许你定义一次,利用多次,这样定义节省了很多相同的工作,但更重要的是它允许你改变定义并将改变反应在你应用的所有位置上面。
这其中可能发生的事情可能会相当多直到我可以添加一些更高级的功能来解决它,这里先放一些。
1. 当你使用Word的时候,所有这些样式都可以被应用于文中,好看的可以变得更加好看,而且你不需要为自己再重新做,大多数自己的并不会比内置的更漂亮。
2. 虽然这些样式显示在你的UI里面,但它并不在你创建的文档里面,至少在你第一次使用他们之前。这种事非常好的,他们会占用相当大的空间,而且很多。如果文件包含所有你可以使用但没有使用的样式,这会
3. 如果你使用了python-docx未在文件中使用的样式来应用样式(如果你好奇的话,可以到styles.xml去查看),Word就会忽视它。他不会抱怨,但是他同样改变不了文件的格式。我确定那是个好理由,但如果你不能理解Word的话,那你则可以把它当做一个谜题了。
4.你如你应用了样式,Word就会把样式保存在文件中,一旦在文件中了,它就会一直在那儿。应该有办法将它删掉,但是你得努力。如果你使用了样式,删除了样式,但是当你保存文件时,它还是在那儿。
添加这些就是希望注意: 如果你使用python-docx要在创建的文档中使用样式,则以文档的开头就必须包含样式定义。否则就不会工作,它不会引发异常, 它只是不起作用。
如果你使用 "默认" 模板文档, 它包含下面列出的样式, 大多数你可能是你想要的,如果你不设计自己的。如果您使用的是自己的起始文档, 则需要在其中至少使用一次所需的样式。您不必保留内容, 但您需要在保存文档之前至少将该样式应用于某种方式。写上一个字或一个词语, 连续应用五种样式,然后删除段落这样工作就可以了。这就是我如何把下面的那些放入默认模板:)。
样式定义
文档样式部分中的元素<w:style>
,它显式地定义了样式的属性。
定义样式
文档
已经在文档中明确定义的文档隐藏样式相区别。
内置样式
Word中含有276个预设风格的预设样式在Word中,例如像“Heading 1”。内置样式可以是显式的也可以是隐式的。而尚未定义的样式称为隐式样式。但是不管显式定义还是隐式定义的都可以在Word的样式面板或者样式选项中出现。
自定义格式
可以被称为用户样式,即所有不是预设样式的样式,注意下自定义样式不能为隐藏样式。
隐式样式
在特定文档中没有定义的内置样式称为该文档中的隐式样式。根据文档中的LatentStyles
对象中的设置,隐式样式可以作为UI中的选项出现。
推荐列表样式
从样式列表下拉框中选择【推荐】时,样式工具箱或面板中出现的样式列表。
样式库
The selection of example styles that appear in the ribbon of the Word UI and which may be applied by clicking on one of them.
出现在Word UI中的示例样式的选择,可以通过单击其中之一来应用。
一个样式有三个识别属性,name
,style_id
和type
。
每个样式的name
属性都是稳定的,是用于访问的唯一标识符。
样式的style_id
在内部用于将内容对象(如段落)设为其样式。然而,这个值是由Word自动生成的,不能保证在整个保存过程中都是稳定的。通常,样式id只是通过从本地化样式名称中删除空格形成的,但是也有例外。python-docx的用户通常应该避免使用样式id,除非他们对所涉及的内部内容有信心。
样式的type
是在创建时设置的,不能更改。
Word有近300种所谓的内置样式,比如Normal、Heading 1和List Bullet。样式定义存储在styles.xml
是docx包的一部分,但是内置的样式定义存储在Word应用程序本身中,不写入styles.xml
。直到真正使用xml。这是一种明智的策略,因为它们占用了大量空间,否则将在每个.docx文件中产生大量冗余和无用的开销。
内置样式直到使用后才写入python.docx包,这一事实引起了对隐式样式的需求。
除了收集一组格式化属性外,样式还有五个属性指定其behavior
。这种行为相对简单,基本上等同于样式出现在Word或LibreOffice UI中的时间和位置。
理解样式行为的关键概念是推荐列表。在Word中的“样式”窗格中,用户可以选择要查看的样式列表。其中一个被命名为“推荐列表”,称为“推荐列表”。所有五种行为属性都会影响样式在这个列表和样式库中的外观的某些方面。
简而言之,如果一个样式的隐藏属性为False(默认),那么它就会出现在推荐列表中。如果一个样式没有隐藏,并且它的quick_style
属性为True
,那么它也会出现在样式库中。如果隐藏样式的unhide_when_used
属性为True
,那么它的隐藏属性在第一次使用时就设置为False
。样式列表和样式库中的样式按照优先级排序,然后按照字母顺序排序相同优先级的样式。如果样式的locked
属性为True,并且文档的格式限制被打开,那么样式将不会出现在任何列表或样式库中,并且不能应用于内容。
需要指定没有在style.sxml
中定义的内置样式的UI行为。就需要隐式样式定义。隐式样式定义基本上是根样式定义,除了样式名称之外,它最多有五个行为属性。通过为每个行为属性定义默认值来节省额外的空间,因此只需要定义那些与默认值不同的属性,并且匹配所有默认值的样式不需要隐式的样式定义。
潜在的样式定义使用w:latentStyles
和w:lsdException
元素指定,这些元素出现在styles.xml中。
内建样式只需要隐式样式定义,因为只有内建样式可以出现在UI中,而不需要在styles.xml中定义样式。
样式可以从另一种样式继承属性,有点类似于级联样式表(CSS)的工作方式。使用base_style属性指定继承。通过将一种样式建立在另一种样式的基础上,就可以形成任意深度的继承层次结构。没有基本样式的样式从默认文档继承属性。
本页使用了前一小节的概念,如果不熟悉,请参阅前一节了解样式
样式可以通过使用Document.styles
属性访问:
>>> document = Document()
>>> styles = document.styles
>>> styles
<docx.styles.styles.Styles object at 0x10a7c4f50>
style
对象提供了对通过名称定义的样式的字典式访问:
>>> styles['Normal']
<docx.styles.style._ParagraphStyle object at <0x10a7c4f6b>
注意 |
---|
内置样式使用英文名称(如“Heading 1”)存储在WordprocessingML文件中,但是 使用本地化版本的Word的用户还是会在UI中看到本地语言名称(如“Kop1”)。因为python-docx操作WordprocessingML文件,样式查找必须使用英文名。这个外部站点上的文档允许您在本地语言名称和英语样式名称之间创建映射: http://www.thedoctools.com/index.php?show=mt_create_style_name_list 用户定义的样式(也称为自定义样式)不是本地化的,它们是通过与Word中的UI中的相同的名字来访问的。 |
Styles
对象也是可以迭代的,通过使用BaseStyle
上的标识属性,可以生成定义样式的各种子集。例如,这段代码将生成一个定义的段落样式列表:
>>> from docx.enum.style import WD_STYLE_TYPE
>>> styles = document.styles
>>> paragraph_styles = [
... s for s in styles if s.type == WD_STYLE_TYPE.PARAGRAPH
... ]
>>> for style in paragraph_styles:
... print(style.name)
...
Normal
Body Text
List Bullet
Paragraph
、Run
和Table
对象每个都有Styles
属性,为这些属性分配一个样式对象将应用该样式:
>>> document = Document()
>>> paragraph = document.add_paragraph()
>>> paragraph.style
<docx.styles.style._ParagraphStyle object at <0x11a7c4c50>
>>> paragraph.style.name
'Normal'
>>> paragraph.style = document.styles['Heading 1']
>>> paragraph.style.name
'Heading 1'
样式名也可以直接指定,在这种情况下,python-docx将为您执行查找
>>> paragraph.style = 'List Bullet'
>>> paragraph.style
<docx.styles.style._ParagraphStyle object at <0x10a7c4f84>
>>> paragraph.style.name
'List Bullet'
样式还可以在创建时使用样式对象或其名称:
>>> paragraph = document.add_paragraph(style='Body Text')
>>> paragraph.style.name
'Body Text'
>>> body_text_style = document.styles['Body Text']
>>> paragraph = document.add_paragraph(style=body_text_style)
>>> paragraph.style.name
'Body Text'
一个新样式可以通过指定一个唯一的名字和类型来添加到文档中:
>>> from docx.enum.style import WD_STYLE_TYPE
>>> styles = document.styles
>>> style = styles.add_style('Citation', WD_STYLE_TYPE.PARAGRAPH)
>>> style.name
'Citation'
>>> style.type
PARAGRAPH (1)
使用base_style
属性指定新样式应该从以下位置继承格式设置:
>>> style.base_style
None
>>> style.base_style = styles['Normal']
>>> style.base_style
<docx.styles.style._ParagraphStyle object at 0x10a7a9550>
>>> style.base_style.name
'Normal'
一个样式可以通过使用一个简单的delete()
方法来删除:
>>> styles = document.styles
>>> len(styles)
10
>>> styles['Citation'].delete()
>>> len(styles)
9
注意 |
---|
从文档中删除Style.delete()方法。它不会影响应用该样式的文档中的内容。具有文档中未定义的样式的内容是使用该内容对象的默认样式呈现的,例如段落中的“Normal” |
字符、段落和表样式都可以指定要应用于具有该样式的内容的字符格式。可以直接应用于文本的所有字符格式都可以用样式指定。示例包括字体字体和大小、粗体、斜体和下划线。
这三种样式类型中的每一种都有一个font
属性,提供对Font
对象的访问。样式的字体对象提供了获取和设置该样式的字符格式的属性。
这里提供了几个例子,要想了解更详细的信息,请参阅:Font API参考手册。
Font样式可以通过这样访问:
>>> from docx import Document
>>> document = Document()
>>> style = document.styles['Normal']
>>> font = style.font
字体和字号可以通过这样访问:
>>> from docx.shared import Pt
>>> font.name = 'Calibri'
>>> font.size = Pt(12)
许多字体属性都是三态的,意味着,意味着他们可以有:True
,False
和None
。True
意味着属性是“打开”,False
意味着“关闭”,从概念上说,None
意味着“继承”。因为样式存在于继承层次结构中,所以有能力在层次结构中的正确位置指定属性是很重要的,通常是在层次结构中越高越好。例如,如果所有标题都应该使用Arial字体,那么在标题1样式上设置这个属性,让标题2从标题1继承就更有意义了。
粗体和斜体是三态属性,全大写、删除线、上标等等也是三态属性。有关完整列表,请参阅Font
API文档:
>>> font.bold, font.italic
(None, None)
>>> font.italic = True
>>> font.italic
True
>>> font.italic = False
>>> font.italic
False
>>> font.italic = None
>>> font.italic
None
下划线是一种特殊的情况,它是三态属性和枚举值属性的混合。True
表示单下划线,这是目前最常见的。False
表示不需要下划线,但如果不需要下划线,通常都不是正确的选择,因为很少从基本样式继承下划线。其他形式的下划线,如双划线或虚线,都是由WD_UNDERLINE
枚举成员指定的:
>>> font.underline
None
>>> font.underline = True
>>> # or perhaps
>>> font.underline = WD_UNDERLINE.DOT_DASH
段落样式和表格样式都允许指定段落格式。这些样式都提供了对ParagraphFormat
对象的paragraph_format
属性的访问方法。
段落格式包括布局,如对齐、缩进、前后空格、前分页和孤行控制。有关可用属性的完整列表,请参阅ParagraphFormat
的API文档。
这是一个例子,告诉你如何创建一个段落样式,悬挂缩进1/4字符,12pint的间距,和孤行控制:
>>> from docx.enum.style import WD_STYLE_TYPE
>>> from docx.shared import Inches, Pt
>>> document = Document()
>>> style = document.styles.add_style('Indent', WD_STYLE_TYPE.PARAGRAPH)
>>> paragraph_format = style.paragraph_format
>>> paragraph_format.left_indent = Inches(0.25)
>>> paragraph_format.first_line_indent = Inches(-0.25)
>>> paragraph_format.space_before = Pt(12)
>>> paragraph_format.widow_control = True
段落样式具有next_paragraph_style
属性,该属性指定将应用于在该样式的段落之后插入的新段落的样式。当样式通常只在序列中出现一次(如标题)时,这是非常有用的。在这种情况下,段落样式可以在完成标题后自动恢复为主体样式。
在大多数的情况下(正文段落),后续段落应采用与当前段落相同的风格。如果没有指定下一段的样式,默认的样式可以通过应用相同的样式很好地处理这种情况。
这里是一个如果在一个主体文本里改变下一段标题1样式的的例子:
>>> from docx import Document
>>> document = Document()
>>> styles = document.styles
>>> styles['Heading 1'].next_paragraph_style = styles['Body Text']
这种默认可以通过设置其为None
或样式本身来恢复:
>>> heading_1_style = styles['Heading 1']
>>> heading_1_style.next_paragraph_style.name
'Body Text'
>>> heading_1_style.next_paragraph_style = heading_1_style
>>> heading_1_style.next_paragraph_style.name
'Heading 1'
>>> heading_1_style.next_paragraph_style = None
>>> heading_1_style.next_paragraph_style.name
'Heading 1'
样式的属性分为两类,行为属性和格式属性。它的行为属性控制样式在UI中出现的时间和位置。它的格式属性决定了应用样式的内容的格式,比如字体的大小和段落缩进。
这是5中样式的行为属性;
有关这些行为属性如何交互的描述,请参阅“了解样式”中的“样式行为”部分,以确定样式在UI中出现的时间和位置。
优先级属性接受一个整数值。其他四个样式行为属性是三态属性,这意味着它们可以取值True(打开)、False(关闭)或None(继承)。
以下代码将使“正文文本”段落样式首先出现在样式库中:
>>> from docx import Document
>>> document = Document()
>>> style = document.styles['Body Text']
>>> style.hidden = False
>>> style.quick_style = True
>>> style.priorty = 1
他的代码将从样式库中删除“普通”段落样式,但允许它保留在推荐列表中:
>>> style = document.styles['Normal']
>>> style.hidden = False
>>> style.quick_style = False
请参阅“了解样式”中的“内置样式”和“隐式样式”部分,以了解隐式样式如何定义尚未在样式中定义的内建样式的行为属性在python.docx文件的styles.xml 部分。
>>> document = Document()
>>> latent_styles = document.styles.latent_styles
LatentStyles
对象支持len()方法,迭代、和通过样式名进行字典式访问:
>>> len(latent_styles)
161
>>> latent_style_names = [ls.name for ls in latent_styles]
>>> latent_style_names
['Normal', 'Heading 1', 'Heading 2', ... 'TOC Heading']
>>> latent_quote = latent_styles['Quote']
>>> latent_quote
<docx.styles.latent.LatentStyle object at 0x10a7c4f50>
>>> latent_quote.priority
29
LatentStyles对象还提供对当前文档中内置样式的默认行为属性的访问。这些默认值为_LatentStyle定义的任何未定义属性以及没有显式潜式定义的内置样式的所有行为属性提供值。有关LatentStyles对象的完整可用属性集,请参阅API文档:
>>> latent_styles.default_to_locked
False
>>> latent_styles.default_to_locked = True
>>> latent_styles.default_to_locked
True
在LatentStyles
中可以通过使用一个·add_latent_style()
方法 来添加一个隐式样式。
>>> latent_style = latent_styles['List Bullet']
KeyError: no latent style with name 'List Bullet'
>>> latent_style = latent_styles.add_latent_style('List Bullet')
>>> latent_style.hidden = False
>>> latent_style.priority = 2
>>> latent_style.quick_style = True
一个隐式样式删除可以通过 delete() 方法。
>>> latent_styles['Light Grid']
<docx.styles.latent.LatentStyle object at 0x10a7c4f50>
>>> latent_styles['Light Grid'].delete()
>>> latent_styles['Light Grid']
KeyError: no latent style with name 'Light Grid'
从概念上讲,Word文档有两个层,一个文本层和一个绘图层。在文本层中,文本对象从左到右、从上到下流动,当先前的页面被填充时,就开始一个新的页面。在绘图层中,绘制对象(称为形状)被放置在任意位置。这些形状有时被称为浮动形状。
图片是可以出现在文本或绘图层中的形状。当它出现在文本层时,它被称为内联形状,或者更具体地说,内联图片。
内联形状被视为一个大文本字符(字符符号)。线的高度增加,以适应形状,形状被包装成一条线,它将适合宽度,就像文本。在它前面插入文本会使它向右移动。通常,一幅画是单独放在一段中,但这不是必需的。它可以在放置它的段落前后有文本。
在编写本文时,python-docx只支持内联图片。可以添加浮动图片。如果您有一个案例,请在问题跟踪器上提交一个特性请求。add_picture()
方法将一个指定的图片添加到文档末尾的一个段落中。然而,通过深入挖掘API,您可以在图片的任意一侧放置文本,或者两者都放置。
主要文档及相关对象
返回从docx加载的文档对象,其中docx可以是.docx文件(字符串)的路径,也可以是类文件对象。如果docx缺少或没有,则加载内置的默认文档“模板”
WordprocessingML(WML)文档。不打算直接构造。使用docx.Document()打开或创建一个文档。
sections
对象提供对本文档中每个节的访问。Styles
对象,提供对该文档中的样式的访问。<w:ins>
或<w:del>
,也不会出现在列表中每个Document对象都提供了通过core_properties
属性来提供对其CorePropertiesvV1
来对其CoreProperties
对象的访问。CoreProperties
象为文档提供对所谓的核心属性的读写访问。核心属性包括作者、类别、注释、content_status、已创建、标识符、关键字、语言、last_modified_by、last_print、modified、revision、主题、标题和版本等。
每个属性都是三种类型之一,str和datetime以及int。字符串属性的长度限制为255个字符,如果没有设置,则返回一个空字符串(")。没有时区的datetime对象,即UTC格式。任何时区转换都是客户端的责任。如果未设置日期属性,则返回None。
python-docx不会自动设置任何文档核心属性,除非将核心属性部分添加到没有核心属性的表示中(非常少见)。如果python-docx添加了一个核心属性部分,那么它包含标题、last_modified_by、修订和修改属性的默认值。如果需要,客户端代码应该更新诸如修订和last_modified_by之类的属性。
提供对文档级别设置的访问。使用 Document.settingsf
访问。设置属性。
style用于在单个名称下收集一组格式化属性,并一次性将这些属性应用于内容对象。这促进了整个文档和相关文档的格式一致性,并允许通过以适当的样式更改定义来全局地进行格式更改。
提供对文档中定义的样式的访问的集合。使用Document.Style
属性访问。通过样式名称支持len()、迭代和字典样式访问。
style
对象,类型为style_type,并通过名称进行标识。内建样式可以通过为可选的内建参数传递True来定义。LatentStyles
对象提供对隐式样式的默认行为和_LatentStyle
对象集合的访问,这些对象定义了特定的隐式样式的默认覆盖。用于各种类型的样式对象、段落、字符、表和编号的基类。所有样式对象都继承这些属性和方法。
Ture
,False
就说明这个是自定义(用户样式)。注意,这个值是基于XML中存在的customStyle属性,而不是基于关于哪些样式构建到Word中的特定知识。True
。否则为False
。为了在样式库中显示,这个值必须为False
, quick_style
必须为True
。True
,一个被锁住状态的样式不能再在样式面板中显示出来或者说不能被文档内容应用。只有在打开文档的格式保护时(通过Developer菜单),该行为才会激活。None
表示没有定义任何设置,导致Word使用默认值0。样式名用作二级排序键,用于解析具有相同优先级值的样式的排序。True
,如果该样式在隐藏时应该显示在样式库中,则为False
。读/写布尔值。True
。否则False
。请注意,当将python-docx应用于内容时,它不会自动地为该属性打开具有True
的样式。基础: docx.styles.style.BaseStyle
字符样式。字符样式应用于Run
对象,主要通过字体属性中的Font对象提供字符级格式。
Ture
,False
就说明这个是自定义(用户样式)。注意,这个值是基于XML中存在的customStyle属性,而不是基于关于哪些样式构建到Word中的特定知识。Font
对象提供对这种样式的字符格式属性(如字体名称和大小)的访问。True
。否则为False
。为了在样式库中显示,这个值必须为False
以及 quick_style
必须为True
。True
,一个被锁住状态的样式不能再在样式面板中显示出来或者说不能被文档内容应用。只有在打开文档的格式保护时(通过Developer菜单),该行为才会激活。None
表示没有定义任何设置,导致Word使用默认值0。样式名用作二级排序键,用于解析具有相同优先级值的样式的排序。True
,如果该样式在隐藏时应该显示在样式库中,则为False
。读/写布尔值。True
。否则False
。请注意,当将python-docx应用于内容时,它不会自动地为该属性打开具有True
的样式。Ture
,False
就说明这个是自定义(用户样式)。注意,这个值是基于XML中存在的customStyle属性,而不是基于关于哪些样式构建到Word中的特定知识。Font
对象提供对这种样式的字符格式属性(如字体名称和大小)的访问。True
。否则为False
。为了在样式库中显示,这个值必须为False
以及 quick_style
必须为True
。True
,一个被锁住状态的样式不能再在样式面板中显示出来或者说不能被文档内容应用。只有在打开文档的格式保护时(通过Developer菜单),该行为才会激活。None
表示没有定义任何设置,导致Word使用默认值0。样式名用作二级排序键,用于解析具有相同优先级值的样式的排序。True
,如果该样式在隐藏时应该显示在样式库中,则为False
。读/写布尔值。True
。否则False
。请注意,当将python-docx应用于内容时,它不会自动地为该属性打开具有True
的样式。Ture
,False
就说明这个是自定义(用户样式)。注意,这个值是基于XML中存在的customStyle属性,而不是基于关于哪些样式构建到Word中的特定知识。Font
对象提供对这种样式的字符格式属性(如字体名称和大小)的访问。True
。否则为False
。为了在样式库中显示,这个值必须为False
以及 quick_style
必须为True
。True
,一个被锁住状态的样式不能再在样式面板中显示出来或者说不能被文档内容应用。只有在打开文档的格式保护时(通过Developer菜单),该行为才会激活。None
表示没有定义任何设置,导致Word使用默认值0。样式名用作二级排序键,用于解析具有相同优先级值的样式的排序。True
,如果该样式在隐藏时应该显示在样式库中,则为False
。读/写布尔值。True
。否则False
。请注意,当将python-docx应用于内容时,它不会自动地为该属性打开具有True
的样式。提供对本文档中隐式样式的默认行为和_LatentStyle对象集合的访问,这些对象为特定的指定隐式样式定义这些缺省值的覆盖。
_LatentStyle
对象,以覆盖这个潜在样式对象中为具有名称的内置样式定义的继承默认值。None
,这将导致Word使用默认值99。LatentStyles
对象中指定的默认值的内置样式的数量。如果XML中没有设置(非常少见),则没有设置。默认的Word 2011模板将该值设置为276,这是Word 2010中的内置样式。w:lsdException
元素的代理,当样式中尚未存储该样式的定义时,该元素指定内置样式的显示行为。style.xml的一部分。这个元素中的值覆盖了父w:latentStyles
元素中指定的默认值。
LatentStyles
对象中定义的默认值为其每个属性提供有效值。在调用此方法后试图访问此对象上的任何属性将引发AttributeError
。<w:latentstyles>
None
表示有效值应该继承自其父LatentStyles对象指定的默认值。代理对象包装元素
提供对段落格式的访问,如对齐、缩进、行间距、前后缩进以孤行控制。
None
第一行缩进是从样式层次结构继承的。True
。None
它的有效值是从样式层次结构继承的。True
。例如,此属性可用于将一个章节标题保持在与第一段相同的页面上。None
它的有效值是从样式层次结构继承的。None
个表示左缩进值是从样式层次结构继承的。使用英寸值对象作为以英寸为单位应用缩进的方便方法。float
或Length
,指定段落连续行中基线之间的空间。None
值表示从样式层次结构继承行间距。浮动值,例如2.0或1.75,表示行距为线高的倍数。Lenght
如Pt(12)表示间距是固定高度。Pt值类是在点的单位中应用行间距的一种方便方法。分配None
会重置从样式层次结构继承的行间距。line_space
的值。将任何WD_LINE_SPACING成员赋值为SINGLE
、DOUBLE
或ONE_POINT_FIVE
都会导致line_space
的值被更新,以产生相应的行间距。True
。None
指出它的有效值是从样式层次结构继承的。Length
,指定段落右侧和右侧之间的空间。None
表示右缩进值是从样式层次结构继承的。使用Cm
值对象作为一种方便的方法来应用以厘米为单位的缩进。None
表示这个值是从样式层次结构继承的。长度对象提供了方便的属性,例如pt和inch,允许轻松转换到各种长度单位。None
表示这个值是从样式层次结构继承的。Length对象提供了方便的属性,例如pt和cm,可以方便地转换到各种长度单位。TabStops
对象提供对为这种段落格式定义的选项卡停止的访问。True
。None
它的有效值是从样式层次结构继承的。代理对象包装元素。运行中的一些属性接受三态值,True
、False
或None
。True
与False
分别对应开关。False
表示属性没有在运行中直接指定,它的有效值是从样式层次结构中获取的。
WD_BREAK.LINE
,WD_BREAK.PAGE
,WD_BREAK.COLUMN
在docx.enum.text中导入WD_BREAK时。break_type默认为WD_BREAK.LINE。image_path_or_stream
可以是路径(字符串)或包含二进制图像的类文件对象。如果既没有指定宽度也没有指定高度,则图像将以其实际大小显示。如果只指定了一个,则使用它来计算一个缩放因子,然后应用于未指定的维数,以保持图像的长宽比。图的本机大小使用图像文件中指定的点每英寸(dpi)值计算,如果没有指定值,默认为72 dpi,yiban情况下是这样的。Run.text
相比这一方法可能更加友好。_CharacterStyle
对象,表示应用于此运行的字符样式。如果运行没有直接应用的字符样式,则返回文档的默认字符样式(通常是默认字符字体)。将此属性设置为None会删除任何直接应用的字符样式。Run
的下划线样式,可以是一个为None、True、False或WD_UNDERLINE的值。None
值表示运行没有直接应用的下划线样式,因此将继承包含段落的下划线值。将None
赋给此属性会删除任何直接应用的下划线值。False
值表示没有下划线的直接应用的设置,覆盖任何继承值。True
值表示单下划线。WD_UNDERLINE
的值用来指定其他的轮廓样式,比如`double、wavy和点星型。代理对象封装元素的父元素,并提供对字符属性(如字体名称、字体大小、粗体和下标)的访问。
ColorFormat
对象,提供了一种获取和设置该字体文本颜色的方法。True
时,将使运行中的复杂脚本字符以粗体显示。True
时,将使运行中的复杂脚本字符以斜体显示。True
时,将使运行中的文本以双删除线贯穿显示。True
时,将使运行中的文本显示为凸起的页面。True
时,将导致run中的文本隐藏不显示,除非应用程序设置强制显示隐藏文本。None
表示有效值是从样式层次结构继承的。None
表示字体是从样式层次结构继承的。True
时,指定在扫描文档以查找拼写和语法时,此运行的内容不应报告任何错误。True
使运行中的文本显示为每个字符都有阴影时。None
,以英文单位(EMU)表示字体高度。None
表字体大小应该从样式层次结构继承。Length是int的子类,具有方便转换为点或其他长度单位的属性。docx.shared.Pt
类允许方便的点值规范:
>> font.size = Pt(24)
>> font.size
304800
>> font.size.pt
24.0
True
时,运行中的小写字符显示为大写字母,比为运行指定的字体大小小两个点。FdocGrid
元素中定义的每行设置中使用文档网格字符。subscript
:布尔值,指示此字体中的字符是否显示为下标。None
下标/下标值是从样式层次结构继承的。
None
表示下标/上标值是从样式层次结构继承的。None
、True
、False
或WD_UNDERLINE
的值之一。没有指示字体从样式层次结构继承下划线值。False
表示没有下划线。True
表示单下划线。WD_UNDERLINE
的值用来指定其他的轮廓样式,比如double、wavy和dotted。一个单独的标签停止应用于一个段落或样式。使用包含制表位对象的列表语义进行访问。
WD_TAB_ALIGNMENT
成员。读/写。WD_TAB_LEADER中
的一个成员,指定作为“leader”使用的重复字符,填充此选项卡所跨越的空间。分配None会产生与分配wd_tab_leader . space相同的结果。读/写。position
: 一个长度对象,表示这个制表符从段落内边缘的距离。可能是积极的,也可能是消极的。读/写。
一组taosptop卡对象,提供对段落或段落样式的选项卡停止的访问。支持迭代、索引访问、del和len()。采用分段格式的tab_stops属性;它不打算直接建造。
WD_TAB_ALIGNMENT
枚举的成员作为对齐方式传递来指定。可以通过将WD_TAB_LEADER
枚举的成员作为leader传递来指定可选的leader字符。一个WordprocessingML elemen的代理类。
_Column
对象,新添加到最右边的表。WD_TABLE_ALIGNMENT
或为None
,指定该表在页边距之间的位置。如果没有指定设置,则会导致从样式层次结构继承有效值。True
。如果表布局是固定的,则为False
。如果总列宽度超过页面宽度,则在两种情况下都会调整列宽。读/写布尔。_TableStyle
对象。如果表没有直接应用的样式,则返回文档的默认表样式(通常是普通表)。将None赋给此属性会删除任何直接应用的表样式,导致它继承文档的默认表样式。注意,表样式的样式名称与用户界面中显示的样式略有不同;连字符,如果出现,必须删除。WD_TABLE_DIRECTION
中的一个成员,指示表单元格排列的方向,例如WD_TABLE_DIRECTION.LTR
。没有一个表示值是从样式层次结构继承的。表格里的单元格
InvalidSpanError
。None
。 width
在EMU中设置此单元格的宽度,如果没有设置显式宽度,则为None。
表格的行
_Cell
实例序列。Length
对象,如果没有设置显式高度,则返回None
。WD_ROW_HEIGHT_RULE
枚举的成员返回该单元格的高度规则,如果没有设置显式的height_rule
,则返回None
。表格的列
_Cell
实例序列。None
。与表中的行对应的_Row对象序列。支持len()、迭代、索引访问和切片。
Table
对象Table
对象。提供对部分属性(如页边距和页面方向)的访问。
文档部分,提供对部分和页面设置设置的访问。
Length
对象,表示本节中所有页的底部空白,单位为英文公制单位。Length
对象,表示从页面底部边缘到页脚底部边缘的距离。如果XML中没有设置,则为None。Length
对象,表示本节中所有页的页槽大小(以英文公制单位表示)。页边距是在内页边距上增加的额外间距,以确保页边距均匀。Length
对象,表示从页面顶部边缘到页眉顶部边缘的距离。如果XML中没有设置,则为None
。Length
对象,表示本节中所有页的左边空白处,单位为英文公制单位。WD_ORIENTATION
成员,是WD_ORIENT.PORTRAIT
或WD_ORIENT.LANDSCAPE
。Length
对象,表示本节中所有页的右边距,单位为英文公制单位。WD_SECTION_START
枚举的成员对应于此部分的初始中断行为,例如WD_SECTION
。如果部分应该从下一个奇数页开始,则为奇数页。Length
对象,表示本节中所有页的顶部空白,单位为英文公制单位。InlineShape
的width
和height
属性提供了一个length对象,它是length的实例。这些实例的行为像int,但也有内置单元转换属性,例如:
>>> inline_shape.height
914400
>>> inline_shape.height.inches
1.0
一个元素的代理,表示一个内联图形对象的容器
docx.enum.shape.WD_INLINE_SHAP
枚举的成员,例如LINKED_PICTURE
,只读。低级的绘图元素,如出现在各种文档上下文中的颜色。
提供对颜色设置的访问,例如RGB颜色、主题颜色和亮度调整。
None
。 type
为MSO_COLOR_TYPE.RGB时,这个属性的值总是一个RGBColor值。如果type
是MSO_COLOR_TYPE.THEME
,它也可能是RGBColor
值。就像Word在指定主题颜色时写入当前值一样。在这种情况下,RGB值应该被解释为仅仅是一个好的猜测,因为主题颜色在呈现时优先。当type
为None
或MSO_COLOR_TYPE.AUTO
时,其值为None
。 RGBColor
值yiji将使type
变为MSO_COLOR_TYPE.RGB
。分配`None``会导致没有任何颜色,从而从样式层次结构继承有效颜色。MSO_THEME_COLOR_INDEX
的成员,如果没有指定主题颜色,则为None
。当type
为MSO_COLOR_TYPE.THEME
时。这个属性的值总是MSO_THEME_COLOR_INDEX的成员。当类型有任何其他值时,此属性的值为None。 MSO_THEME_COLOR_INDEX
的成员会使type
变成MSO_COLOR_TYPE.THEME。任何现有的RGB值都被保留,但被Word忽略。分配None会导致删除所有颜色规范,从而从样式层次结构继承有效的颜色。None
,这将导致有效颜色从样式层次结构继承。python-docx中的长度值表示为标准长度值对象。Length是int的子类,具有int的所有行为。
>>> inline_shape.height
914400
>>> inline_shape.height.inches
1.0
长度构造函数类的基类:英寸、厘米、毫米、Px和Emu。作为英制公制单位的int计数,914,400到英寸,36,000到毫米。以只读属性的形式提供方便的单位转换方法。不可变的。
width = Inches(0.5)
。height = Cm(12)
width = Mm(240.5)
。width = Twips(42)
。twip是0.20,635 EMU。width = Emu(457200)
。定义特定RGB颜色的不可变值对象。、
r、g和b都是0-255范围内的整数。使用h十六进制表示法(例如0x42)可以增强可读性,在使用十六进制RGB值时:
>>> lavender = RGBColor(0xff, 0x99, 0xcc)
类方法:from_string(rgb_hex_str)
从RGB颜色十六进制字符串返回一个新实例,比如'3C2F80'
在这里可以找到用于python-docx属性设置的各种枚举文档:
指定颜色规格方案
例子:
from docx.enum.dml import MSO_COLOR_TYPE
assert font.color.type == MSO_COLOR_TYPE.THEME
表示Office主题颜色,即格式色带上的颜色画廊中显示的颜色之一。
别名:MSO_THEME_COLOR
实例:
from docx.enum.dml import MSO_THEME_COLOR
font.color.theme_color = MSO_THEME_COLOR.ACCENT_1
别名:WD_ALIGN_PARAGRAPH
指定段落对齐类型。
例子:
from docx.enum.text import WD_ALIGN_PARAGRAPH
paragraph = document.add_paragraph()
paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER
alias: WD_STYLE
指定内置的Microsoft Word样式。
例子:
from docx import Document
from docx.enum.style import WD_STYLE
document = Document()
styles = document.styles
style = styles[WD_STYLE.BODY_TEXT]
别名:WD_ALIGN_VERTICAL
指定表的一个或多个单元格中文本的垂直对齐方式。
实例:
from docx.enum.table import WD_ALIGN_VERTICAL
table = document.add_table(3, 3)
table.cell(0, 0).vertical_alignment = WD_ALIGN_VERTICAL.BOTTOM
别名:WD_COLOR
指定要应用的标准预设颜色。用于字体高亮显示和其他应用程序。
指定要应用于段落的行间距格式。
实例:
from docx.enum.text import WD_LINE_SPACING
paragraph = document.add_paragraph()
paragraph.line_spacing_rule = WD_LINE_SPACING.EXACTLY
别名: WD_ORIENT
指定页面方向:
实例:
from docx.enum.section import WD_ORIENT
section = document.sections[-1]
section.orientation = WD_ORIENT.LANDSCAPE
指定表对齐类型
实例:
from docx.enum.table import WD_TABLE_ALIGNMENT
table = document.add_table(3, 3)
table.alignment = WD_TABLE_ALIGNMENT.CENTER
from docx.enum.table import WD_ROW_HEIGHT_RULE
table = document.add_table(3, 3)
table.rows[0].height_rule = WD_ROW_HEIGHT_RULE.EXACTLY
AUTO
: 调整行高度以适应行的最高值。
AT_LEAST
: 行高度至少是指定的最小值。
EXACTLY
: 行高度是一个精确的值。
别名:WD_SECTION指定段中断的开始类型。
实例:
from docx.enum.section import WD_SECTION
section = document.sections[0]
section.start_type = WD_SECTION.NEW_PAG
指定四种样式类型之一:段落、字符、列表或表。
实例:
from docx import Document
from docx.enum.style import WD_STYLE_TYPE
styles = Document().styles
assert styles[0].type == WD_STYLE_TYPE.PARAGRAPH
指定要用作带格式化选项卡的标题的字符。
指定应用程序在指定表或行中对单元格进行排序的方向。
实例:
from docx.enum.table import WD_TABLE_DIRECTION
table = document.add_table(3, 3)
table.direction = WD_TABLE_DIRECTION.RTL
指定应用于一系列字符的下划线的样式
None
不一样。None
是一个有效的赋值,但会导致运行继承其下划线值。分配WD_UNDERLINE。没有人会无条件地关闭下划线。True
(而不是WD_UNDERLINE.SINGLE)。
# encoding: utf-8
"""
|Document| and closely related objects
"""
from __future__ import (
absolute_import, division, print_function, unicode_literals
)
from .blkcntnr import BlockItemContainer
from .enum.section import WD_SECTION
from .enum.text import WD_BREAK
from .section import Section, Sections
from .shared import ElementProxy, Emu
[docs]
class Document(ElementProxy):
"""
WordprocessingML (WML) document. Not intended to be constructed directly.
Use :func:`docx.Document` to open or create a document.
"""
__slots__ = ('_part', '__body')
def __init__(self, element, part):
super(Document, self).__init__(element)
self._part = part
self.__body = None
[docs]
def add_heading(self, text='', level=1):
"""
Return a heading paragraph newly added to the end of the document,
containing *text* and having its paragraph style determined by
*level*. If *level* is 0, the style is set to `Title`. If *level* is
1 (or omitted), `Heading 1` is used. Otherwise the style is set to
`Heading {level}`. Raises |ValueError| if *level* is outside the
range 0-9.
"""
if not 0 <= level <= 9:
raise ValueError("level must be in range 0-9, got %d" % level)
style = 'Title' if level == 0 else 'Heading %d' % level
return self.add_paragraph(text, style)
[docs]
def add_page_break(self):
"""
Return a paragraph newly added to the end of the document and
containing only a page break.
"""
paragraph = self.add_paragraph()
paragraph.add_run().add_break(WD_BREAK.PAGE)
return paragraph
[docs]
def add_paragraph(self, text='', style=None):
"""
Return a paragraph newly added to the end of the document, populated
with *text* and having paragraph style *style*. *text* can contain
tab (``\\t``) characters, which are converted to the appropriate XML
form for a tab. *text* can also include newline (``\\n``) or carriage
return (``\\r``) characters, each of which is converted to a line
break.
"""
return self._body.add_paragraph(text, style)
[docs]
def add_picture(self, image_path_or_stream, width=None, height=None):
"""
Return a new picture shape added in its own paragraph at the end of
the document. The picture contains the image at
*image_path_or_stream*, scaled based on *width* and *height*. If
neither width nor height is specified, the picture appears at its
native size. If only one is specified, it is used to compute
a scaling factor that is then applied to the unspecified dimension,
preserving the aspect ratio of the image. The native size of the
picture is calculated using the dots-per-inch (dpi) value specified
in the image file, defaulting to 72 dpi if no value is specified, as
is often the case.
"""
run = self.add_paragraph().add_run()
return run.add_picture(image_path_or_stream, width, height)
[docs]
def add_section(self, start_type=WD_SECTION.NEW_PAGE):
"""
Return a |Section| object representing a new section added at the end
of the document. The optional *start_type* argument must be a member
of the :ref:`WdSectionStart` enumeration, and defaults to
``WD_SECTION.NEW_PAGE`` if not provided.
"""
new_sectPr = self._element.body.add_section_break()
new_sectPr.start_type = start_type
return Section(new_sectPr)
[docs]
def add_table(self, rows, cols, style=None):
"""
Add a table having row and column counts of *rows* and *cols*
respectively and table style of *style*. *style* may be a paragraph
style object or a paragraph style name. If *style* is |None|, the
table inherits the default table style of the document.
"""
table = self._body.add_table(rows, cols, self._block_width)
table.style = style
return table
@property
def core_properties(self):
"""
A |CoreProperties| object providing read/write access to the core
properties of this document.
"""
return self._part.core_properties
@property
def inline_shapes(self):
"""
An |InlineShapes| object providing access to the inline shapes in
this document. An inline shape is a graphical object, such as
a picture, contained in a run of text and behaving like a character
glyph, being flowed like other text in a paragraph.
"""
return self._part.inline_shapes
@property
def paragraphs(self):
"""
A list of |Paragraph| instances corresponding to the paragraphs in
the document, in document order. Note that paragraphs within revision
marks such as ``<w:ins>`` or ``<w:del>`` do not appear in this list.
"""
return self._body.paragraphs
@property
def part(self):
"""
The |DocumentPart| object of this document.
"""
return self._part
[docs]
def save(self, path_or_stream):
"""
Save this document to *path_or_stream*, which can be either a path to
a filesystem location (a string) or a file-like object.
"""
self._part.save(path_or_stream)
@property
def sections(self):
"""
A |Sections| object providing access to each section in this
document.
"""
return Sections(self._element)
@property
def settings(self):
"""
A |Settings| object providing access to the document-level settings
for this document.
"""
return self._part.settings
@property
def styles(self):
"""
A |Styles| object providing access to the styles in this document.
"""
return self._part.styles
@property
def tables(self):
"""
A list of |Table| instances corresponding to the tables in the
document, in document order. Note that only tables appearing at the
top level of the document appear in this list; a table nested inside
a table cell does not appear. A table within revision marks such as
``<w:ins>`` or ``<w:del>`` will also not appear in the list.
"""
return self._body.tables
@property
def _block_width(self):
"""
Return a |Length| object specifying the width of available "writing"
space between the margins of the last section of this document.
"""
section = self.sections[-1]
return Emu(
section.page_width - section.left_margin - section.right_margin
)
@property
def _body(self):
"""
The |_Body| instance containing the content for this document.
"""
if self.__body is None:
self.__body = _Body(self._element.body, self)
return self.__body
class _Body(BlockItemContainer):
"""
Proxy for ``<w:body>`` element in this document, having primarily a
container role.
"""
def __init__(self, body_elm, parent):
super(_Body, self).__init__(body_elm, parent)
self._body = body_elm
def clear_content(self):
"""
Return this |_Body| instance after clearing it of all content.
Section properties for the main document story, if present, are
preserved.
"""
self._body.clear_content()
return self