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 配置文件生成。可以与团队成员共享此文件，也可以在另一个 PyCharm 安装中导入该文件。导入过程是上述过程的逆过程，不再详述。

8. 小结

这节我们主要讲述的文件模板作用，以及如何创建等相关内容。通常软件公司都有自己的编码规范，也会定义一套模板文件，以保证代码可读性与可维护性。即使对于个人，也应养成好的编程习惯，通过创建模板文件编写统一规范的注释信息及代码。同时也建议有意识的使用 PyCharm 自带的一些 Live Templates, 帮助提高开发效率。