PyCharm 的文件模板

上一個小節我們完成了對PyCharm 的編輯器基本功能學習，這也標志著用PyCharm編寫程序前需要了解的一些概念及功能等準備工作都完成了。從這一節開始，我們就進入編寫程序的階段，第一步我們要開始創建文件。

在 PyCharm 中，用戶可以根據文件模板創建多種類型的文件，在前面 使用 PyCharm 填充項目 這一小節已經詳細講解了創建文件過程，本節將不再贅述。文件模板是創建文件的第一步，本節將幫助大家了解什么是文件模板？為什么要用文件模板？如何創建文件模板等等。

1. 什么是文件模板？

文件模板是創建新文件時要生成的默認內容的規范。根據要創建的文件類型，模板提供預期位于該類型的所有文件中的初始代碼和格式（根據行業標準、公司內部的編碼規范等）。

如下所示，以下是一個 Python文件的模板文件， 每創建新的Python文件時，IDE都會自動按照模板內容生成下面的信息，并填充到新文件的頭中，無需手動輸入。

#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""Module documentation goes here
   and here
   and ...
"""

2. 為什么要用文件模板？

代碼規范是非常重要的，創建的文件模板可以在團隊成員之間共享，正確執行的模板文件或一系列模板文件有利于灌輸標準化。同時，使用模板有助于節省時間，提高工作效率。

3. 文件模板配置

在 PyCharm 主頁菜單依次點擊 Preferences/File -> Settings -> Editor -> File and Code Templates 來到文件模板配置頁面：

默認情況下，模板列表僅包含 PyCharm 提供的預定義模板。其中一些是內部的，這意味著它們無法刪除或重命名(通常“-”按鈕是灰色的)。修改的模板以及手動創建的自定義模板以藍色顯示。

• Files：包含可用于創建新文件的文件模板；
• Includes：可重復使用內容的模板，這些模板可以插入到文件模板，下面會詳細介紹。
• code：包含 PyCharm 用于生成各種構造的代碼片段的內部模板。可以編輯此選項卡上的可用代碼段，但不能創建新代碼段。自定義代碼片段，需要用 Live Template, 本節后面會介紹。

4. 文件模板語法

文件模板以 Velocity Template Language（VTL） 編寫，一個文件模板主要包括以下部分：

• 固定文本， 比如標記、代碼、注釋等；
• 變量，格式如 ${DATE}， 將會被當前實際日期替換；
• 各種指令，比如 #set、#if 等。

通常我們會為不同類型文件創建頭，標明作者及創建時間等消息，下面列出一些常用的變量：

• ${PROJECT_NAME}：當前的項目名；
• ${NAME}：在文件創建過程中，新文件對話框的命名；
• ${USER}：當前的登錄用戶；
• ${DATE}：現在的系統日期；
• ${TIME}：現在的系統時間；
• ${YEAR}：當前年份；
• ${MONTH}：當前月份；
• ${DAY}：當前月份中的第幾日；
• ${HOUR}：現在的小時；
• ${MINUTE}：現在的分鐘；
• ${PRODUCT_NAME}：IDE創建文件的名稱；
• ${MONTH_NAME_SHORT}：月份的前三個字母縮寫；
• ${MONTH_NAME_FULL}：完整的月份名。

關于更多變量定義及更詳細的VTL用法，請參考VelocityTemplate Language 。

5. 文件模板相關操作

5.1 編輯預定義的文件模板

默認情況下， Python Script 文件模板內容是空的?？梢栽谟覀仍黾酉旅娴膬热?，為文件增加頭， 顯示時間，作者及功能描述信息。

點擊 OK , 回到編輯頁面，創建新的 Python 文件。

輸入文件名 test_template, 打開文件，文件會自動顯示模板中定義的內容。

5.2 創建新的文件模板

方法一：

step1：主頁菜單依次點擊 Preferences/File -> Settings -> Editor -> File and Code Templates。

step2：在 File 選項卡上，單擊 + 按鈕并指定模板的名稱 mytemplate、文件擴展名和正文。應用更改并關閉對話框。

step3：回到編輯器， 創建新的文件， 會看到新的模板選項。

方法二：

在 File 選項卡上，單擊 復制模板 按鈕并根據需要修改模板的名稱、文件擴展名和正文。應用更改并關閉對話框即可，步驟與增加新的模板基本是一致的。

方法三：

step1：打開編輯器中的文件。

step2：選擇菜單 Tools -> Save File as Template。

step3：在打開的"Save Files as Template"對話框中，指定新的模板名稱并編輯正文（如有必要）。

Tips：修改的預定義文件模板與自定義模板，被保存在 PyCharm 應用程序配置目錄下，而不是當前項目下。下圖顯示了 Mac 環境下的路徑 ~/Library/Application Support/JetBrains/PyCharm2020.1：

5.3 模板中的可重用內容

Includes Templates 可定義重復使用內容的模板，這些模板可以插入到文件模板( File Templates)。

step1：主頁菜單依次點擊 Preferences/File -> Settings -> Editor -> File and Code Templates。

step2：在 include 選項卡上，單擊 + 按鈕并指定模板的名稱、文件擴展名和正文。選擇應用。

step3：切換到 File 選項卡， 選擇其中一個模板， 通過 #parse 指令填加上面創建的 includes template。同一個 includes template 能被多個 File templates 應用的。

6. 活動模板(Live Templates)

活動模板通常是一段通用的語句片段，可能是一段純文本的注釋；也可能是一段代碼；例如循環、條件、各種聲明或打印語句。

6.1 創建活動模板

step1：主頁菜單依次點擊 Preferences/File -> Settings -> Editor -> Live Templates。

step2：單擊 + 按鈕并選擇 Live Template。事先可選擇已存在的模板組，如果未選擇模板組，則將自動生成 user 組，并且將模板加到 user。 當然，也可以創建一個新的模板組通過 Template Group...

step3：在 Template text 字段中，使用變量指定模板的正文。然后點擊 Edit Variable 按鈕編輯變量。

Tips: 若要在模板中聲明變量，請使用以下格式：$VAR$。

step4：設定范圍后，點擊應用并關閉窗口。

Tips：新創建模板是以template group 為單位保存的， 同File Templates 一樣，保存在IDE應用程序配置目錄下。

step5：在編輯器打開文件，輸入我們設定的縮寫 cd, 然后按 tab 鍵，定義的內容就會顯示。

關于創建 Live Template, 可以在編輯器中選擇要從中創建實時模板的文本片段，點擊對應菜單項創建。

7. 共享模板

前面已經提到新創建模板文件是保存在 IDE 的配置路徑下的，如何把這些模板文件共享呢？
選擇 File -> Manage IDE Settings -> Export Settings 從菜單。

在"Export Setting"對話框中，確保選中 Live templates 復選框，并指定存檔的路徑和名稱。

單擊"OK"基于Live Templates 配置文件生成?？梢耘c團隊成員共享此文件，也可以在另一個 PyCharm 安裝中導入該文件。導入過程是上述過程的逆過程，不再詳述。

8. 小結

這節我們主要講述的文件模板作用，以及如何創建等相關內容。通常軟件公司都有自己的編碼規范，也會定義一套模板文件，以保證代碼可讀性與可維護性。即使對于個人，也應養成好的編程習慣，通過創建模板文件編寫統一規范的注釋信息及代碼。同時也建議有意識的使用 PyCharm 自帶的一些 Live Templates, 幫助提高開發效率。