章节索引 :

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, 帮助提高开发效率。

图片描述