崇高文本
by Jimmy Zhang
吉米·张(Jimmy Zhang)
崇高文本片段指南 (A Guide to Sublime Text Snippets)
I recently switched jobs, which involves a lot of acclimation: new coworkers to befriend, new terms to learn, a new development environment to internalize. But most of all, the switch came with a change in programming languages, away from the tidy aesthetic of Python, and straight into the angled and curly world of JavaScript.
我最近换了工作,这需要很多的适应:新的同事成为朋友,新的学习条件,新的开发环境内部化。 但最重要的是,这种转换带来了编程语言的变化,它脱离了整洁的Python美学,而直接进入了JavaScript的弯弯曲曲的世界。
As I continued to misplace brackets and omit parenthesis, I searched for something that would help me navigate the unfamiliar territory. Luckily, I found Sublime Text Snippets.
当我继续放错括号并省略括号时,我在寻找可以帮助我导航陌生领域的内容。 幸运的是,我找到了Sublime Text片段。
I love Sublime Text Snippets because they reduce cumbersome definitions to a few keystrokes, like this:
我喜欢Sublime Text Snippets,因为它们将繁琐的定义减少为几次击键,如下所示:
总览 (Overview)
Sublime Text Snippets expedite the act of writing code by providing a quick way to insert blocks of text that show up repeatedly in a project. They are both easy to understand and straightforward to write, making them a great tool for saving time and eliminating errors while developing.
Sublime Text Snippets通过提供一种快速的方式来插入重复出现在项目中的文本块,从而加快了编写代码的过程。 它们既易于理解又易于编写,使其成为节省时间并消除开发过程中错误的理想工具。
A snippet maps a trigger word to a pre-defined block of text, both of which you define. To invoke the snippet, type the trigger word and press tab
. This simple action expands the trigger word into the mapped block of text — replete with as many brackets, parentheses, and semi-colons as necessary, always matching and in the correct order.
摘要将触发词映射到预定义的文本块,您都可以定义它们。 要调用代码段,请输入触发词,然后按tab
。 这个简单的操作将触发词扩展到映射的文本块中,并根据需要添加足够多的括号,括号和分号,并且始终保持匹配并以正确的顺序进行。
Note: The examples given below apply mostly to JavaScript and React, but the information about snippets can be applied to any programming language or framework.
注意:下面给出的示例主要适用于JavaScript和React,但是有关代码片段的信息可以应用于任何编程语言或框架。
创建片段 (Creating Snippets)
To create a new snippet in Sublime Text 3, go to:
要在Sublime Text 3中创建新的代码段,请转到:
Tools -> Developer -> New Snippet...
This opens a new window containing a new snippet template, which looks like this:
这会打开一个包含新代码段模板的新窗口,如下所示:
There are four parts to a snippet. Although only one part is required, defining all four is recommended.
片段有四个部分。 尽管只需要一部分,但是建议定义全部四个部分。
1)内容(第3行):必填 (1) The Content (Line 3): Required)
<content><![CDATA[ Hello, ${1:this} is a ${2:snippet}.]]></content>
Define the block of text to be expanded by the snippet by editing the line(s) between the <![CDA
TA[ and
]]> tags. (From now on, the block of text that is expanded after the snippet is invoked will be referred to as the snippet’s content).
通过编辑<![CDA
TA [ nd
]]>标记之间的行,定义要由代码段扩展的文本块。 (从现在开始,在所述段被调用后扩展的文本的块将被称为上帐篷剪断宠物的c)中 。
You’ll notice the presence of words surrounded by a dollar sign, braces, numbers, and prefixed by a number. This optional markup specifies a Field Marker, which controls the cursor position after the snippet is invoked.
您会注意到存在用美元符号,花括号,数字和数字开头的单词。 此可选标记指定一个Field Marker ,该标记控制代码段调用后的光标位置。
After content is expanded, the cursor moves automatically to the first field marker (${1:this}
above). Pressing tab again moves the cursor to the next numbered field marker, or to the end of the snippet’s content if there are no fields left (see pro tip below).
扩展内容后,光标会自动移动到第一个字段标记(上面的${1:this}
)。 再次按Tab键可将光标移动到下一个编号的字段标记,如果没有剩余字段,则将光标移动到代码段内容的末尾(请参见下面的提示 )。
Text after the colon in a field marker is optional. If specified, it is automatically selected as part of the cursor movement, meaning it can be deleted in one swift stroke. This makes text after the colon great for “placeholder” values that provide guidance of what should be filled in, or for optional default values, such as the isRequired
field in the example below.
字段标记中冒号后面的文本是可选的。 如果指定,它将自动选择为光标移动的一部分,这意味着可以快速删除它。 这使冒号后的文本非常适合提供占位符的“占位符”值,这些值提供了应填写的内容的指导,也适合于可选的默认值,例如下例中的isRequired
字段。
Pro tipUse the $0
field marker (the exit marker) to explicitly define where the cursor will exit after all field markers have been cycled through. This is useful if you want to rebind the tab
key to auto-completion after the snippet is invoked. To do so, place the exit marker immediately after the first field marker, like this:${1:example}$0
提示使用$0
字段标记(退出标记)来明确定义在所有字段标记循环之后光标将离开的位置。 如果要在调用代码段后将tab
键重新绑定到自动完成功能,这将很有用。 这样做,请将出口标记紧接在第一个字段标记之后,如下所示: ${1:example}$0
2:触发字(第6行):可选 (2: The Trigger Word (Line 6): Optional)
<tabTrigger>hello</tabTrigger>
Short and mnemonic trigger words work best. For example, the Babel React Snippet package maps cwm
to componentWillMount
and cwr
to componentWillReceiveProps
.
简短的助记词最有效。 例如, Babel React Snippet软件包将cwm
映射到componentWillMount
并将cwr
到componentWillReceiveProps
。
Trigger words are optional because there is an alternative way to invoke snippets, which we will cover in the Advanced Usage section.
触发字是可选的,因为还有另一种调用代码段的方法,我们将在“高级用法”部分中介绍。
3:范围(第8行):可选 (3: A Scope (Line 8): Optional)
<scope> source: python </scope>
Scopes limit where your snippet can be invoked, improving precision and preventing collisions. For example, with scopes, the same trigger word can have different meanings for different programming languages.
范围限制了可以调用代码段的位置,从而提高了准确性并防止了冲突。 例如,对于范围,对于不同的编程语言,相同的触发字可能具有不同的含义。
This gist lists how to define scopes for a long list of programming languages, but scopes are capable of much more. We will cover scopes in more detail in the Advanced Usage section.
本要点列出了如何为一长串编程语言定义范围,但是范围还可以提供更多功能。 我们将在“高级用法”部分中详细介绍范围。
4:说明(第10行):可选 (4: A Description (Line 10): Optional)
<description> demo description </description>
For some reason, the description tag doesn’t show up in the create snippet template. However, providing one will come in handy.
由于某些原因,描述标签未显示在创建代码段模板中。 但是,提供一个将派上用场。
Snippets show up in Sublime Text’s auto-complete menu, along with a descriptive phrase. Without a description, this phrase defaults to the snippet’s filename, which isn’t guaranteed to have enough context when multiple snippets share the same prefix.
片段以及描述性短语会显示在Sublime Text的自动完成菜单中。 如果没有描述,则该短语默认为代码段的文件名,当多个代码段共享同一前缀时,不能保证该上下文具有足够的上下文。
Pro tipCreate a keyboard shortcut to quickly create a new snippet. Go to Preferences -> Keybindi
ngs and add the following line to the “User” configuration file (of course, replace cmd+al
t+n with whatever combination suits you best):
专家提示创建键盘快捷方式以快速创建新代码段。 转到Preferences -> Keybindi
绑定”,然后Preferences -> Keybindi
下行添加到“用户”配置文件中(当然,以最适合的组合替换ce cmd+al
t + n):
{ "keys": ["cmd+alt+n"], "command": "new_snippet" }
保存片段 (Saving Snippets)
After creating your snippet, make sure to save it in a file ending in sublime-snippet
. On Mac, user created snippets are saved at:
创建代码段后,请确保将其保存在以sublime-snippet
结尾的文件中。 在Mac上,用户创建的代码段保存在:
~/Library/Application Support/Sublime Text 3/Packages/User
Creating a new snippet through the menu item or keyboard shortcut automatically prompts this location on save.
通过菜单项或键盘快捷键创建新的代码段会在保存时自动提示此位置。
高级用法 (Advanced Usage)
环境变量 (Environment Variables)
We’ve covered the four aspects of creating a static snippet. However, it is possible to create dynamic snippets through the use of environment variables, which contain references to the context in which a snippet was invoked.
我们已经介绍了创建静态代码段的四个方面。 但是,可以通过使用环境变量来创建动态摘录,这些环境变量包含对在其中调用摘录的上下文的引用。
Context is a vague term, so see the Sublime Text Snippet Documentation for a table of environment variables and their exact meanings.
上下文是一个模糊的术语,因此请参阅Sublime Text Snippet文档以获取有关环境变量及其确切含义的表格。
For an example of how environment variables can be used, my team follows a convention where a component’s stylesheet is saved under the same file name as the component, and given a .scss
extension.
关于如何使用环境变量的示例,我的团队遵循一个约定,其中将组件的样式表保存在与组件相同的文件名下,并具有.scss
扩展名。
The component file can then leverage this convention with a snippet using the $TM_FILENAME
environment variable.
然后,组件文件可以使用$TM_FILENAME
环境变量通过代码片段利用此约定。
<content><![CDATA[ import styles from './$TM_FILENAME${1:}scss']]></content>
The $TM_SELECTED_TEXT
or $SELECTION
environment variable serves a more general purpose. Remember how I mentioned there was an alternative way of invoking snippets? Instead of keying the trigger word and hitting tab
, you can also invoke snippets through the Command Palette.
$TM_SELECTED_TEXT
或$SELECTION
环境变量用于更一般的用途。 还记得我曾经提到过调用片段的另一种方法吗? 除了键入触发字并单击tab
,您还可以通过Command Palette调用代码段。
On Mac, hit cmd+shift+p
to bring up the Palette, type ‘Snippet’ and select the desired snippet from the drop-down. This roundabout approach has one major benefit — it is possible to invoke a snippet with a block of text selected, and for that text to be included as part of a snippet’s content. This allows you to create “wrapping” snippets, which wrap selected text with an if clause, for example.
在Mac上,按cmd+shift+p
出调色板,键入“片段”,然后从下拉列表中选择所需的片段。 这种回旋方式有一个主要好处-可以调用选中了一段文本的代码段,并将该文本作为代码段内容的一部分包含在内。 这使您可以创建“包装”片段,例如,这些片段使用if子句包装所选文本。
Pro tip Expand selection shortcuts are great for quickly selecting text to wrap with snippets like the one above.
专业提示 扩展选择快捷方式非常适合快速选择要用上面的代码片段环绕的文本。
高级范围 (Advanced Scopes)
We’ve talked about limiting snippets to certain source code files, but snippets often have more granular contexts in which they are valid. As an example, a method such as componentWillUpdate
typically only makes sense within a component (class) definition, which the following snippet definition makes explicit:
我们已经讨论过将代码段限制为某些源代码文件,但是代码段通常在更有效的上下文中具有更细的上下文。 例如,诸如componentWillUpdate
之类的方法通常仅在组件(类)定义内有意义,以下代码段定义对此进行了明确说明:
The inclusion of meta.class.js
on line 8 means that the snippet is only valid in situations where the source code file being edited is a JavaScript file, and the cursor is “within” a class definition. If you tried to invoke the snippet in a blank JavaScript file, nothing would happen.
在第8行中包含meta.class.js
意味着该代码段仅在以下情况下有效:正在编辑的源代码文件是JavaScript文件, 并且光标在类定义之内。 如果您尝试在空白JavaScript文件中调用该代码段,则不会发生任何事情。
To fully leverage the power of scopes, you need to have a little understanding of syntax, scopes and scope selectors. These are nuanced topics worthy of their own post, so I’ll explain them at a very high level, with links to the documentation to fill in the gaps:
要充分利用范围的功能,您需要对语法,范围和范围选择器有所了解。 这些都是微不足道的主题,值得在其自己的文章中发表,因此,我将在较高层次上对它们进行解释,并提供文档链接以填补空白:
a language syntax defines how source code is divided into scopes.
语言语法定义了如何将源代码划分为范围。
scopes are labeled regions of text that correspond to the “units” of a programming language, such as class or function definitions. Every position within a source code file has an associated scope. Meta scopes are most relevant to snippets.
范围是与程序语言(例如类或函数定义)的“单元”相对应的标记文本区域。 源代码文件中的每个位置都有一个关联的范围。 元范围与摘要最相关。
scope selectors “query” scopes. Scopes selectors are bound to actions (such as snippets, or keyboard shortcuts), and are used to determine if the action is appropriate given the current scope.
范围选择器 “查询”范围。 范围选择器绑定到操作(如代码片段或键盘快捷键),用于确定给定当前范围的操作是否合适。
Pro tipThe best way to learn about scopes is play around with them. Move your cursor to different positions within a file, and use the cmd+shift+p
keyboard shortcut to bring up a pop-up menu displaying the associated scope:
专家提示学习示波器的最好方法是与它们一起玩。 将光标移到文件中的其他位置,然后使用cmd+shift+p
键盘快捷键调出弹出菜单,显示相关的范围:
Snippets take mere seconds to create. Yet they save much more in effort, and not just by saving how much you have to type. By providing a quick, reproducible way to expand content, snippets reduce errors. They also abstract away hard-to-remember details, such as method names and their signatures. All of this frees your fingers — and your brain — to focus on what they want to do most: write great code.
片段只需几秒钟即可创建。 但是,它们可以节省更多的精力,而不仅仅是节省您必须键入的内容。 通过提供一种快速,可复制的方式来扩展内容,代码片段减少了错误。 它们还抽象出难以记住的细节,例如方法名称及其签名。 所有这些都释放了您的手指和大脑的精力,使您可以专注于他们最想做的事情:编写出色的代码。
崇高文本