语言与引用注入

添加临时语言注入

1. 将插入符号置于要注入语言的字符串字面量、标签或属性内，然后按下 Alt+Enter （或使用 意图操作 图标 ）。

2. 选择 注入语言或引用 ，然后选择要注入的语言。

   

添加持久性语言注入

使用语言注入注释（注解）来添加持久的注入语言片段。

• 在目标字符串字面量之前添加一个空行，然后输入以下注释：

  # language=<language_ID>

  

  请使用添加注释的文件的注释语法来编写注释，而不是使用要注入的语言的注释语法。 语言 ID 可能不同于 PyCharm 显示的语言名称，例如，在可注入语言列表中。

  要查找语言 ID，请将文本光标放在注释中的 language= 后面，然后按 Ctrl+Space。 补全列表会显示所有可注入语言的 ID，并在圆括号中显示语言名称。

  您也可以在设置中了解语言 ID。 按下 Ctrl+Alt+S 以打开设置，然后选择 编辑器 | 语言注入。 双击某种语言的注入规则；该语言 ID 在 ID 字段中指定。

• （可选）在注释中包含前缀或后缀。

  # language=<language_ID> prefix=<prefix> suffix=<suffix>

  在以下情况下需要：

  • 该字符串是不完整/部分的 SQL 语句

  • 该字符串未直接用于我们支持的调用之一（例如 select /where)

打开片段编辑器

1. 将插入符号置于已注入的代码片段内，然后按下 Alt+Enter （或使用 意图操作 图标 ）。

2. 请选择 编辑 <语言 ID> 片段。

   PyCharm 将打开一个专用的编辑器部分，用于编辑已注入语言的代码。 此编辑器提供完整的编码辅助，包括代码补全、检查、意图操作 以及代码样式操作。

   

添加临时引用注入

1. 将插入符号置于要注入引用的字符串字面量内，然后按下 Alt+Enter （或使用 意图操作 图标 ）。

2. 选择 注入语言或引用 ，然后选择一个选项。 例如， 文件引用 会添加指向指定文件的链接。

   根据您安装的插件，可能会有其他引用选项可用。

   

添加持久性引用注入

使用注释添加持久性引用注入。

在目标字符串字面量之前添加一个空行，并输入带有所需值的 # language= 注释。

例如， # language=file-reference 会添加对文件的引用：

取消持久语言注入

要取消语言注入，请删除用于引入它的注释（注解）。

取消临时语言注入

1. 将插入符号置于该代码片段处，然后按下 Alt+Enter （或使用 意图操作 图标 ）。

2. 请选择 取消语言或引用注入。

禁用意图操作灯泡图标

要在编辑器中隐藏意图操作图标 ，请执行以下操作：

1. 按下 Ctrl+Alt+S 以打开设置，然后选择 编辑器 | 常规 | 外观。

2. 清除 显示意图灯泡 复选框。

3. 应用更改并关闭对话框。

配置自定义注入规则

1. 请执行下列任一操作：

   • 要创建新规则，请点击工具栏上的 并选择要应用规则的上下文，例如，用于 Python 字符串文字的 通用 Python。

   • 要编辑现有规则，请选择它，然后点击工具栏上的 。

   • 要基于现有规则创建规则，请选择基础规则，点击工具栏上的 创建副本 ，选择副本，然后点击工具栏上的 编辑。

   语言注入设置 对话框将打开。 对话框中的控件取决于所选的注入类型。

2. 指定要注入的语言的 ID 或名称。

   可选择指定前缀和后缀，即要在注入前后添加的字符序列。 可能需要用它来包装不完整的片段。 假设有以下代码段：

   condition = "WHERE id = ?"

   要将 SQL 注入此字符串，请指定 SELECT * FROM users 后跟一个空格作为前缀，以便注入的片段成为完整的 SQL 语句。 或者，如果选择 JSON 作为注入语言，可以指定 { 作为前缀，指定 } 作为后缀。

3. 在 位置模式 或 模板标记 字段中，根据规则类型，输入用于定义上下文的规则，以便 PyCharm 在该上下文中将字面量识别为注入。 这些规则可能以函数实参、变量初始值设定项等为目标。

   除了 psiElement() 和 string() 等平台模式外，还可以使用以下 Python 特定模式：

   • pyLiteralExpression() ：匹配文字表达式，例如字符串文字。

   • pyStringLiteralMatches("regexp") ：匹配其值包含指定正则表达式匹配项的字符串文字。 匹配不区分大小写，并且 . 也会匹配换行符。 文档字符串和长度为 10,000 个字符或以上的字符串文字不会被匹配。

   • pyArgument("function_name", index) ：匹配对具有指定名称的函数或方法的调用中的实参。 index 是该实参从零开始的位置。 PyCharm 会将函数名称与调用中的名称进行比较，而不会解析该函数。

   • pyModuleFunctionArgument("function_name", index, "module_name") ：匹配对指定模块顶层定义的函数进行调用时的实参。 module_name 是不带扩展名的模块文件名称，而不是模块的限定名称。 例如，对于 mypkg/db_utils.py ，请指定 db_utils。

   • pyMethodArgument("method_name", index, "class_qualified_name") ：匹配对在具有指定限定名称的类中定义的方法进行调用时的实参。 对于继承的方法，请指定定义该方法的类。 PyCharm 会根据对象的推断类型解析调用，因此不会匹配未知类型对象上的调用。

   pyArgument()、 pyModuleFunctionArgument() 和 pyMethodArgument() 模式不匹配关键字实参，例如 execute(sql="...")。

   要组合条件，请使用 .and()。

   示例：

   将一种语言注入到以 SELECT 开头的字符串文字中：

   pyStringLiteralMatches("^\\s*SELECT\\s")

   将一种语言注入到对名为 execute 的函数或方法进行的任意调用的第一个实参中：

   pyLiteralExpression().and(pyArgument("execute", 0))

   将一种语言注入 run_query() 函数的第一个实参中，该函数定义于 db_utils.py ：

   pyModuleFunctionArgument("run_query", 0, "db_utils")

   将一种语言注入 仓库 类的 query() 方法的第一个实参中，该类定义于 myapp/db.py ：

   pyMethodArgument("query", 0, "myapp.db.Repository")

   这些规则基于 程序结构接口模式 ，实际上是内部 PyCharm 语言的方法的链式调用。 程序结构接口 显示文件在 PyCharm 中的结构。

   如果正在编辑预定义的注入规则，模式已预先指定。 这些规则可确保高效性和易用性。 建议使用这些配置，而不是创建新的配置。

4. 可选：

   在 高级 区域中，指定其他设置以缩小注入规则适用的上下文，从而对注入过程进行更细粒度的控制。

   • 在 值模式 字段中，输入用于确定要将语言注入到哪个上下文中的正则表达式。 通过使用模式的第一个捕获组作为注入目标，您可以将过程配置为仅将语言注入到匹配特定模式的值中，或注入到匹配该模式的多个部分中。

     例如， ^javascript:(.*) 匹配可在超链接 href 中用于执行 JavaScript 代码的 javascript 协议。

   • 单个文件 - 如果此选项关闭，与值模式匹配的片段将被单独处理，视为不同的“文件”——例如，从片段编辑器的视角来看。

     如果该选项开启，相应片段将合并为一个整体或"文件"。

     给定的值模式

     xxx (.+) yyy (.+) zzz

     以及片段

     xxx select * yyy from family zzz，

     select * 和 from family 在选项关闭时将被视为两个独立的片段（或"文件"）。 如果该选项开启， select * from family 将被视为一个整体或"文件"。

5. 对于 XML 标记 和 XML 特性 注入规则，请参阅 语言注入设置对话框：XML 标签注入 和 语言注入设置对话框： XML 属性注入。

   对于 通用 Python 注入规则和 Python 专用位置模式，请参阅 语言注入设置对话框：通用 Python。