項(xiàng)目官方文檔

項(xiàng)目官方git

docxtpl 軟件包使用兩個(gè)主要軟件包：

• python docx，用于讀取、寫(xiě)入和創(chuàng)建子文檔
• jinja2用于管理插入到模板docx中的標(biāo)記。jinja官網(wǎng),?jinja中文網(wǎng)站

簡(jiǎn)單示例

from docxtpl import DocxTemplatetpl = DocxTemplate('test.docx')context = {'template': '123' }tpl.render(context) tpl.save('test1.docx')

安裝

pip install docxtpl

---

導(dǎo)言

python-docx-template被開(kāi)發(fā)出來(lái)，是因?yàn)閜ython-docx的強(qiáng)大在于創(chuàng)建文檔，而不是修改它們。

這個(gè)想法是開(kāi)始于創(chuàng)建一個(gè)需要用MicrosoftWord生成的文檔的示例，它可以像我們想要的那樣復(fù)雜：如圖片、索引表、頁(yè)腳、頁(yè)眉、變量，以及我們可以用Word做的任何事情。然后，當(dāng)我們使用MicrosoftWord編輯文檔時(shí)，直接在文檔中插入類似于Jinja 2的標(biāo)記。將文檔保存為.docx文件(XML格式)：它將是.docx模板文件。

現(xiàn)在，我們可以使用python-docx-template從這個(gè).docx模板和將關(guān)聯(lián)的上下文變量生成您想要的多個(gè)Word文檔。

注意：python-docx-template是測(cè)試的是MS Word 97格式，它可能不適用于其他版本.

Jinja 2類語(yǔ)法

因Jinja 2包被使用，可以使用Word文檔中的所有Jinja 2標(biāo)記和過(guò)濾器。然而，要使它在Word文檔中工作，進(jìn)行了些限制和擴(kuò)展：

限制

通常的Jinja 2標(biāo)簽，只能在同一個(gè)段落的同一個(gè)‘’run’中使用，它不能跨幾個(gè)段落使用，表行、‘run’。如果您想要管理段落、表行和整個(gè)‘run’的樣式，您必須使用特殊的標(biāo)記語(yǔ)法，如下一章所述。

注意：MicrosoftWord的“Run”是一個(gè)具有相同風(fēng)格的字符序列。例如，如果您創(chuàng)建一個(gè)具有相同風(fēng)格的所有字符的段落：Word將在內(nèi)部創(chuàng)建一個(gè)段落中的“Run”。現(xiàn)在，如果你在這段中間加了一個(gè)粗體，單詞會(huì)把前面的“Run”轉(zhuǎn)換成3‘Run’(普通-粗體-正常)。

擴(kuò)展

為了管理段落、表行、表列、run，必須使用特殊的語(yǔ)法。（區(qū)別于jinja2）

{%p jinja2_tag %} for paragraphs
{%tr jinja2_tag %} for table rows
{%tc jinja2_tag %} for table columns
{%r jinja2_tag %} for runs

通過(guò)使用這些標(biāo)記，python-docx-template將真正的Jinja 2標(biāo)記放入文檔的XML源代碼中的正確位置。此外，這些標(biāo)記還告訴python-docx-template移除位于開(kāi)始和結(jié)束標(biāo)記的位置的段落、表行、表列或run，只注意中間的位置。

重要*不要使用2次{%p, {%tr、`{%tc‘、{%r在同一段落、行、列或run中。例子：

不要用這個(gè)

{%p if display_paragraph %}Here is my paragraph {%p endif %}

而是使用

{%p if display_paragraph %}
Here is my paragraph
{%p endif %}

這種語(yǔ)法是可能是因?yàn)镸icrosoft word將每一行都看作是一個(gè)新的段落，{%p標(biāo)簽不在同一段中

顯示變量

作為Jinja 2的一部分，可以使用雙括弧：{{ <var> }}。但如果 <var> 是RichText對(duì)象，必須指定要更改實(shí)際的“Run”。{{r <var> }}注意’r緊跟左括弧。

重要*不要使用?r?變量出現(xiàn)在模板中，因?yàn)閧{r}} 可以解釋為 {{r 沒(méi)有指定變量。不過(guò)，您可以使用以‘r’開(kāi)頭的更大的變量名。例如{{render_color}}將被解釋為{{ render_color }}不像{{r ender_color}}.

重要*不要使用2次 {{r 在同一run上。使用RichText.add()方法在python端連接多個(gè)字符串和樣式，并且只有一個(gè)字符串和樣式 {{r 在模板邊。

單元格顏色

當(dāng)您想要更改表格單元格的背景色時(shí)，有一種特殊情況，您必須在單元格的開(kāi)頭放置以下標(biāo)記

{% cellbg <var> %}

<var>必須包含顏色的十六進(jìn)制代碼無(wú)散列符號(hào)

列跨越

如果您想在多個(gè)列上動(dòng)態(tài)地跨越一個(gè)表單元格(當(dāng)您有一個(gè)具有動(dòng)態(tài)列計(jì)數(shù)的表時(shí)，這是很有用的)，您必須在單元格的最開(kāi)始處放置下面的標(biāo)記來(lái)跨越

{% colspan <var> %}

<var>必須包含要跨越的列數(shù)的整數(shù)。有關(guān)示例，請(qǐng)參見(jiàn)下一篇示例操作

Escaping

為了展示{%, %}, {{或}}，你可以用

{%, %}, {{ or }}

RichText

當(dāng)你使用{{ <var> }}標(biāo)記，它將被包含在 var 變量的字符串替換。但它將保持目前的格式。如果要添加動(dòng)態(tài)變化的樣式，則必須同時(shí)使用以下兩種方式：{{r <var> }}標(biāo)簽一個(gè) RichText對(duì)象在 var 變量。您可以更改顏色、粗體、斜體、大小等，但最好的方法是使用microsoft word來(lái)定義自己的字符樣式（主頁(yè)選項(xiàng)卡->修改樣式->管理樣式按鈕->新建樣式，在窗體中選擇“字符樣式”)，請(qǐng)參見(jiàn)tests/richtext.py，除了使用RichText()，您可以使用它的快捷方式：R()

重要*當(dāng)你使用{{r }}它從docx模板中移除當(dāng)前字符樣式，這意味著如果你沒(méi)有在RichText()設(shè)置字體樣式，樣式將返回到Microsoft Word默認(rèn)樣式。這只會(huì)影響字符樣式，而不會(huì)影響段落樣式(MSWord管理的這2種樣式)。

可以通過(guò)Richtext將超鏈接添加到文本中。

tpl=DocxTemplate(‘your_template.docx’)
rt = RichText('You can add an hyperlink, here to ')
rt.add(‘google’,url_id=tpl.build_url_id(‘http://google.com’))

將rt放在您的語(yǔ)境中，然后使用{{r rt}}在你的模板中

內(nèi)嵌圖像

您可以動(dòng)態(tài)地將一個(gè)或多個(gè)圖像添加到文檔中(使用JPEG和PNG文件進(jìn)行測(cè)試)。只要在你的模板中加上{{ <var> }}，標(biāo)記<var>是doxtpl.inlineImage的實(shí)例。

myimage=InlineImage(tpl,‘test_files/python_logo.png’,width=Mm(20))

您只需指定模板對(duì)象、圖像文件路徑和可選寬度和/或高度即可。對(duì)于高度和寬度，您必須使用毫米(毫米)，英寸(英寸)或點(diǎn)(Pt)類。有關(guān)示例，請(qǐng)參見(jiàn)test/inlineImage.py。

子文件

模板變量可以包含使用python-docxWord文檔從頭開(kāi)始構(gòu)建的復(fù)雜變量。為此，首先從模板對(duì)象獲取子文檔對(duì)象，并將其用作python-docx文檔對(duì)象，參見(jiàn)tests/subdoc.py.

轉(zhuǎn)義，換行符，新段落，列表
當(dāng)您使用{{ <var> }}，您正在修改XMLWord文檔，這意味著您不能使用所有字符，特別是<, >和&。為了使用它們，你必須轉(zhuǎn)義它們。有四種方式：

context = { ‘var’:R(‘my text’) }和在模板中{{r <var> }}(注意r),
context = { ‘var’:‘my text’}和在模板中{{ <var>|e }}
context = { ‘var’:escape(‘my text’)}和在模板中{{ <var> }}。
在調(diào)用呈現(xiàn)方法時(shí)啟用自動(dòng)轉(zhuǎn)義：tpl.render(context, autoescape=True)(默認(rèn)值autoescape=false)
RichText()或R()提供換行符和新段落功能：只需使用\n或\a在文本中，它們將作相應(yīng)的轉(zhuǎn)換。

有關(guān)更多信息，請(qǐng)參見(jiàn)tests/escape.py?。

另一個(gè)解決方案，如果要將列表包含到文檔中，即轉(zhuǎn)義文本并管理n和a，則可以使用’Listing’ class：

在python代碼中

context = { 'mylisting':Listing('the listing\nwith\nsome\nlines \a and some paragraph \a and special chars : <>&') }

在docx模板中只需使用{{ mylisting }}帶著Listing()，您將保持當(dāng)前字符的樣式(除非在一個(gè)\a之后你開(kāi)始新的一段落)。

替換docx圖片

在頁(yè)眉/頁(yè)腳中動(dòng)態(tài)添加圖像是不可能的，但您可以更改它們。這樣做的目的是在模板中放置一個(gè)虛擬圖片，像往常一樣渲染模板，然后用另一個(gè)模板替換虛擬圖片。你可以同時(shí)為所有媒體做到這一點(diǎn)。Note1：縱橫比將與替換的圖像相同 Note 2：指定用于在docx模板中插入圖像的文件名(只要其basename，而不是完整路徑)。

替換dummy_header_pic.jpg的語(yǔ)法：

tpl.replace_pic('dummy_header_pic.jpg','header_pic_i_want.jpg')

替換發(fā)生在頁(yè)眉、頁(yè)腳和整個(gè)文檔正文中。

替換docx媒體

在頁(yè)眉/頁(yè)腳中動(dòng)態(tài)添加圖片以外的其他媒體是不可能的，但您可以更改它們。這樣做的目的是在模板中放置一個(gè)虛擬媒體，像往常一樣呈現(xiàn)模板，然后用另一個(gè)模板替換虛擬媒體。你可以同時(shí)為所有媒體做到這一點(diǎn)。注意：對(duì)于圖像，高寬比將與替換的圖像注釋2相同：重要的是要有源媒體文件，因?yàn)樗鼈冃枰?jì)算它們的CRC才能在docx中找到它們。(虛擬文件名不重要)

替換dummy_header_pic.jpg的語(yǔ)法：

tpl.replace_media('dummy_header_pic.jpg','header_pic_i_want.jpg')

警告：與replace_pic() 方法不同，dummy_header_pic.jpg 必須存在模板目錄中，當(dāng)在渲染和保存生成docx時(shí)。它必須與手動(dòng)插入在docx模板的文件相同。替換可以發(fā)生在頁(yè)眉、頁(yè)腳和整個(gè)文檔正文中。

替換嵌入對(duì)象

它的工作方式類似于媒體替換，只是它適用于嵌入式docx這樣的嵌入式對(duì)象。

替換embedded_dummy.docx的語(yǔ)法：

tpl.replace_embedded('embdded_dummy.docx','embdded_docx_i_want.docx')

警告：與REPLE_PIC()方法不同，embdded_dumy.docx必須存在于模板目錄中,在渲染和保存生成的docx時(shí)。它必須與手動(dòng)插入docx模板的文件相同。替換發(fā)生在頁(yè)眉、頁(yè)腳和整個(gè)文檔正文中。

Microsoft Word 2016特例

MS Word 2016將忽略表格的 \t。這對(duì)這個(gè)版本來(lái)說(shuō)是特別的。但是LibreOffice或Wordpad沒(méi)有這個(gè)問(wèn)題。對(duì)于以jinja2標(biāo)記產(chǎn)生空格來(lái)開(kāi)頭的行，也會(huì)出現(xiàn)同樣的情況：它們將被忽略。要解決這些問(wèn)題，解決方案是使用Richtext：

tpl.render({'test_space_r' : RichText(' '),'test_tabs_r': RichText(5*'\t'), })

在模板中，使用 {r 表示法：

{{r test_space_r}} Spaces will be preserved
{{r test_tabs_r}} Tabs will be displayed

表格

可以兩種方式水平地跨表格單元格，一是利用colspan標(biāo)記(請(qǐng)參閱tests/dynamic_table.py)：

{% colspan %}

或者在for循環(huán)中(請(qǐng)參閱tests/horizontal_merge.py))：

{% hm %}

還可以在for循環(huán)中垂直合并單元格(請(qǐng)參閱 tests/vertical_merge.py)：

{% vm %}

Jinja自定義過(guò)濾器

render() 接受 jinja_env 選項(xiàng)參數(shù)：您可以傳遞一個(gè)jinja環(huán)境對(duì)象。通過(guò)這種方式，您可以添加一些定制的jinja過(guò)濾器：

from docxtpl import DocxTemplate import jinja2 def multiply_by(value, by):return value * bydoc = DocxTemplate("my_word_template.docx") context = { 'price_dollars' : 5.00 } jinja_env = jinja2.Environment() jinja_env.filters['multiply_by'] = multiply_by doc.render(context,jinja_env) doc.save("generated_doc.docx")

然后在模板中，您將能夠使用

Euros price : {{ price_dollars|multiply_by(0.88) }}

例子

查看其工作原理的最佳方法是閱讀示例，它們位于 tests/ 目錄。Docx測(cè)試模板在tests/templates/目錄。要生成最終的docx文件：

cd tests/ python runtests.py

生成的文件位于tests/output 目錄。

想要真正學(xué)會(huì)對(duì)應(yīng)包，趕緊自己下載，根據(jù)測(cè)試文件測(cè)試吧！

總結(jié)

以上是生活随笔為你收集整理的Python 第三方库之 docxtpl (处理word文档)的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。