【翻译】Emmet(Zen Coding)官方文档 之六 自定义 Emmet

【说明】本系列博文是依据 Emmet 官方文档翻译的，原文地址为：http://docs.emmet.io/，部分内容已经在博主之前的博文中节选过，为方便已经收藏过之前博文的朋友，没有删除这些博文，仅将其完整的收录于本系列中。

自定义

Emmet 提供了大范围的微调，以使你可以用之提升自己的插件体验。几乎所有的正式开发的编辑器插件 (除了 PSPad 和基于浏览器的) 都有 扩展支持： 一个用于扩展 Emmet可以放置 json 和 js 文件的文件夹。请参考随编辑器插件发布的 README 文件，找出 Emmet 在哪儿搜索扩展。

扩展文件夹中的每个 .js 文件都在插件启动时被载入和执行。使用 js 文件建立自己的 过滤器 或 动作：可以使用 Emmet 模块并使用 JavaScript 缩写脚本与编辑器。

使用 .json 文件能够微调 Emmet 工具的不同部分：

snippets.json
添加自己的片段或升级已有的片段。

snippets.json

在扩展文件夹内创建 snippets.json 文件来添加或者覆盖片段。此文件的结构与 原始文件 相同：在最顶级定义片段所属的 语法名称 ，第二级有下面几段：

  • abbreviations 或 snippets 包含 不同类型 的片段定义。
  • filters 包含用逗号间隔的当前语法的默认 过滤器 列表。如果没有定义本属性，则默认使用 html 过滤器。
  • extends: 当前语法所继承的片段定义的语法名称。例如，sass 语法继承自 css ，不过可以为这个语法定义建立自己的或者覆盖一些 SASS 特定的片段。

走入完成后，用户的 snippets.json 与原始文件递归合并，添加或升级缩写和片段。

文本片段

在语法定义的 snippets 一节，可以创建普通的文本片段，你编辑里的一样漂亮。可以在片段中使用 tabstops ，当缩写展开时可以使用 Tab 键在它们之间跳转（前提是所用的编辑器支持 tabstops）。Emmet 采用 TextMate 编辑器的 tabstops 格式：

  • $1 或 ${1}
  • ${1:hello world} — 带有占位符的 tabstop

注意 ${0} 或 $0 tabstop 在类似于 TexeMate 或 Eclipse 等一些编辑器中有特殊含义：用作离开 “tabstops 模式”的最后一个光标位置，所以最好从 1 开始使用 tabstops 。

变量

可以在片段中使用 片段  来输出预定义数据。例如 HTML 语法的 html:5 片段是这样定义的：

<!doctype html>\n<html lang="${lang}">...</body>\n</html>

在上面的盒子中， ${lang} 用于引用定义在 snippets.json 文件的 variables 一节的 lang 变量。例如，所用的母语是俄语，可以直接使用 ru 值覆盖 lang 变量，并保持原始的片段定义。

也可以使用行内缩写属性覆盖变量值： html:5[lang=ru]。与 ID 和 CLASS 属性缩写—# 和 .—一起，可以很容易的覆盖缩写中的变量：

"for": "for (var ${class} = 0; i < ${id}.length; ${class}++) {\n\t|}"

用法示例： for#array.i.

预定义变量

片段有一些对 Emmet 有特殊意义的预定义变量名：

  • ${cursor} 或 | 是 $0 的罔，用作生成输出的当前位置。
  • ${child} 引用了一个位置，子属性和片段将被输出到此处。如果没有定义，子元素将输出到片段内容的后边。

转码 | 和 $ 字符

字符 $ 作于 tabstops 和变量，字符 | 用于指示缩写展开时的光标位置。如果想原样输出这些字符，必须使用双斜杠来对它们进行转码： \\$ 或 \\|

共享片段

如果想与其它用户共享片段，可以将它们放进以 snippets 命名的文件中，例如： snippets-foo.json、snippets_bar.json、snippetsBaz.json。Emmet 将在启动时载入它们，并将它们合并到单个片段集合中。

注意，定义在 snippets.json （译注：此处疑是 snippets-*.json）文件中的片段优先于定义在 `snippets.json` 文件中的片段

preferences.json
改变某些 Emmet 过滤器和运作的行为。

preferences.json

preferences.json 文件用于编辑 Emmet 的一些运作和解析器的行为。此文件包含 Key-value 对的简单字典。

例如在 “CSS 渐变” 上，有 css.gradient.fallback 选项描述当定义展开时能够回调 background-color 。要使它生效，直接加入如下内容到 preferences.json 文件：

{
    "css.gradient.fallback": true
}

以下是当前可用的选项列表：

bem.elementSeparator
Class 名的元素分隔符
 __
bem.modifierSeparator
Class 名的修饰符分隔符
 _
bem.shortElementPrefix
描述短的 “块元素”标记的符号。 带有这个符号前缀的Class 类名将被视为你块名称的元素名。每个符号实例在解析树的块元素中向上跳转一级。空值将禁用短标记。
 -
css.alignVendor
如果设置为 true，所有生成的 vendor 前缀属性将被赋予真实的元素名。
 false
css.autoInsertVendorPrefixes
在扩展 CSS 属性时自动生成 vendor 前缀副本。默认情况下，当缩写前放置了存折号 (例如， -bxsh)，Emmet 将仅生成 vendor 前缀属性. 该属性可用时，不需要在缩写前定义破折号： Emmet 为你生成 vendor 前缀属性。
 true
css.closeBraceIndentation
在 CSS 关闭括号前缩进。一些用户为了增强可读性而缩进 CSS 规则的关闭括号。设置这个选项将在用户新建规则添加新行（如在 CSS 文件中执行“插入格式化换行”动作）时自动在关闭前缩进。如果你恰好是这种用户，也许会想在这个选项占放一个类似于 \n\t 的值.
  
css.color.case
颜色缩写(类似于 c#0)的颜色字母的大小写。可取的值有 upper、 lower 和 keep。
 keep
css.color.short
在带有颜色的缩写展开时，将类似于 #ffffff 的颜色值简化成 #fff。
 true
css.floatUnit
浮点值的默认单位。
 em
css.fuzzySearch
是否能够模糊搜索 CSS 片段的名字。当设置为可用时，每个未知的片段将被改成接近的可用的片段名(对 CSS 值或属性无效)。最接近的匹配将被用于片段解析。例如，在此选项可用时，下面的缩写是等效的：ov:h== ov-h == o-h == oh。
 true
css.fuzzySearchMinScore
模糊匹配时搜索的最小值（取值范围为从 0 到 1）。较低的设置值能够获得更多的匹配，较高的值则匹配度更高。
 0.3
css.gradient.defaultProperty
当展开 CSS 值上下文外面的渐变时，它将生成带有相同名字的属性。
 background-image
css.gradient.fallback
当此选项可用时，CSS 渐变将为旧浏览器生成带有渐变第一个颜色的 background-color 属性。
 false
css.gradient.oldWebkit
为旧的 webkit 实现生成渐变定义。
 true
css.gradient.omitDefaultDirection
在生成的渐变中不输出默认的方向定义。
 true
css.gradient.prefixes
用逗号的 vendor 前缀列表，每个都将被生成。
 webkit, moz, o
css.intUnit
整数值的默认单位。
 px
css.keywordAliases
用逗号间隔的关键词别名列表，用在 CSS 缩写中。每个别名的定义格式如下： alias:keyword_name。
 a:auto, i:inherit, s:solid, da:dashed, do:dotted, t:transparent
css.keywords
用逗号间隔的能够用于 CSS 缩写的有效关键词列表。
 auto, inherit
css.mozProperties
可能用于 moz vendor 前缀的用逗号间隔的 CSS 属性列表。这个列表用于在展开 -property 缩写时生成前缀属性列表。空值意味着所有可用的 CSS 属性都将拥有 moz 前缀。
 animation-delay, animation-direction, animation-duration, animation-fill-mode, animation-iteration-count, animation-name, animation-play-state, animation-timing-function, appearance, backface-visibility, background-inline-policy, binding, border-bottom-colors, border-image, border-left-colors, border-right-colors, border-top-colors, box-align, box-direction, box-flex, box-ordinal-group, box-orient, box-pack, box-shadow, box-sizing, column-count, column-gap, column-rule-color, column-rule-style, column-rule-width, column-width, float-edge, font-feature-settings, font-language-override, force-broken-image-icon, hyphens, image-region, orient, outline-radius-bottomleft, outline-radius-bottomright, outline-radius-topleft, outline-radius-topright, perspective, perspective-origin, stack-sizing, tab-size, text-blink, text-decoration-color, text-decoration-line, text-decoration-style, text-size-adjust, transform, transform-origin, transform-style, transition, transition-delay, transition-duration, transition-property, transition-timing-function, user-focus, user-input, user-modify, user-select, window-shadow, background-clip, border-radius
css.mozPropertiesAddon
用于 css.mozPreperties 选项的附加 CSS 属性列表，用逗号间隔。如果想从原始集合中添加或删除几个  CSS 属性，可以用这个列表来完成。如果想添加新属性，直接写入属性名，如果想删除，就在属性名前加个连字符。例如，添加 foo 属性和删除 border-radius 属性，此选项的值将是：foo, -border-radius。
  
css.msProperties
可能用于 ms vendor 前缀的用逗号间隔的 CSS 属性列表。这个列表用于在展开 -property 缩写时生成前缀属性列表。空值意味着所有可用的 CSS 属性都将拥有 ms 前缀。
 accelerator, backface-visibility, background-position-x, background-position-y, behavior, block-progression, box-align, box-direction, box-flex, box-line-progression, box-lines, box-ordinal-group, box-orient, box-pack, content-zoom-boundary, content-zoom-boundary-max, content-zoom-boundary-min, content-zoom-chaining, content-zoom-snap, content-zoom-snap-points, content-zoom-snap-type, content-zooming, filter, flow-from, flow-into, font-feature-settings, grid-column, grid-column-align, grid-column-span, grid-columns, grid-layer, grid-row, grid-row-align, grid-row-span, grid-rows, high-contrast-adjust, hyphenate-limit-chars, hyphenate-limit-lines, hyphenate-limit-zone, hyphens, ime-mode, interpolation-mode, layout-flow, layout-grid, layout-grid-char, layout-grid-line, layout-grid-mode, layout-grid-type, line-break, overflow-style, perspective, perspective-origin, perspective-origin-x, perspective-origin-y, scroll-boundary, scroll-boundary-bottom, scroll-boundary-left, scroll-boundary-right, scroll-boundary-top, scroll-chaining, scroll-rails, scroll-snap-points-x, scroll-snap-points-y, scroll-snap-type, scroll-snap-x, scroll-snap-y, scrollbar-arrow-color, scrollbar-base-color, scrollbar-darkshadow-color, scrollbar-face-color, scrollbar-highlight-color, scrollbar-shadow-color, scrollbar-track-color, text-align-last, text-autospace, text-justify, text-kashida-space, text-overflow, text-size-adjust, text-underline-position, touch-action, transform, transform-origin, transform-origin-x, transform-origin-y, transform-origin-z, transform-style, transition, transition-delay, transition-duration, transition-property, transition-timing-function, user-select, word-break, word-wrap, wrap-flow, wrap-margin, wrap-through, writing-mode
css.msPropertiesAddon
用于 css.msPreperties 选项的附加 CSS 属性列表，用逗号间隔。如果想从原始集合中添加或删除几个  CSS 属性，可以用这个列表来完成。如果想添加新属性，直接写入属性名，如果想删除，就在属性名前加个连字符。例如，添加 foo 属性和删除 border-radius 属性，此选项的值将是：foo, -border-radius。
  
css.oProperties
可能用于 o vendor 前缀的用逗号间隔的 CSS 属性列表。这个列表用于在展开 -property 缩写时生成前缀属性列表。空值意味着所有可用的 CSS 属性都将拥有 o 前缀。
 dashboard-region, animation, animation-delay, animation-direction, animation-duration, animation-fill-mode, animation-iteration-count, animation-name, animation-play-state, animation-timing-function, border-image, link, link-source, object-fit, object-position, tab-size, table-baseline, transform, transform-origin, transition, transition-delay, transition-duration, transition-property, transition-timing-function, accesskey, input-format, input-required, marquee-dir, marquee-loop, marquee-speed, marquee-style
css.oPropertiesAddon
用于 css.oPreperties 选项的附加 CSS 属性列表，用逗号间隔。如果想从原始集合中添加或删除几个  CSS 属性，可以用这个列表来完成。如果想添加新属性，直接写入属性名，如果想删除，就在属性名前加个连字符。例如，添加 foo 属性和删除 border-radius 属性，此选项的值将是：foo, -border-radius。
  
css.propertyEnd
在展开 CSS 缩写时在每个 CSS 属性的后面放置的符号。
 ;
css.unitAliases
用逗号间隔的单位别名的列表，用于 CSS 缩写。每个别名的定义格式如下： alias:unit_value。
 e:em, p:%, x:ex, r:rem
css.unitlessProperties
必须包含单位的属性的列表。
 z-index, line-height, opacity, font-weight, zoom
css.valueSeparator
定义在展开 CSS 缩写时，在两个 CSS 属性和值之间放置的符号。
 :
css.webkitProperties
可能用于 webkit vendor 前缀的用逗号间隔的 CSS 属性列表。这个列表用于在展开 -property 缩写时生成前缀属性列表。空值意味着所有可用的 CSS 属性都将拥有 webkit 前缀。
 animation, animation-delay, animation-direction, animation-duration, animation-fill-mode, animation-iteration-count, animation-name, animation-play-state, animation-timing-function, appearance, backface-visibility, background-clip, background-composite, background-origin, background-size, border-fit, border-horizontal-spacing, border-image, border-vertical-spacing, box-align, box-direction, box-flex, box-flex-group, box-lines, box-ordinal-group, box-orient, box-pack, box-reflect, box-shadow, color-correction, column-break-after, column-break-before, column-break-inside, column-count, column-gap, column-rule-color, column-rule-style, column-rule-width, column-span, column-width, dashboard-region, font-smoothing, highlight, hyphenate-character, hyphenate-limit-after, hyphenate-limit-before, hyphens, line-box-contain, line-break, line-clamp, locale, margin-before-collapse, margin-after-collapse, marquee-direction, marquee-increment, marquee-repetition, marquee-style, mask-attachment, mask-box-image, mask-box-image-outset, mask-box-image-repeat, mask-box-image-slice, mask-box-image-source, mask-box-image-width, mask-clip, mask-composite, mask-image, mask-origin, mask-position, mask-repeat, mask-size, nbsp-mode, perspective, perspective-origin, rtl-ordering, text-combine, text-decorations-in-effect, text-emphasis-color, text-emphasis-position, text-emphasis-style, text-fill-color, text-orientation, text-security, text-stroke-color, text-stroke-width, transform, transition, transform-origin, transform-style, transition-delay, transition-duration, transition-property, transition-timing-function, user-drag, user-modify, user-select, writing-mode, svg-shadow, box-sizing, border-radius
css.webkitPropertiesAddon
用于 css.webkitPreperties 选项的附加 CSS 属性列表，用逗号间隔。如果想从原始集合中添加或删除几个  CSS 属性，可以用这个列表来完成。如果想添加新属性，直接写入属性名，如果想删除，就在属性名前加个连字符。例如，添加 foo 属性和删除 border-radius 属性，此选项的值将是：foo, -border-radius。
  
filter.commentAfter
当应用 comment 过滤器时，将被放在对应的元素后的注释内容的定义。这个定义是传递给 _.template()函数的 ERB 风格的模板。在模板上下文中，如下属性和函数是有效的：
  • attr(name, before, after) – 这个函数输出用 before and after 连接的指定的属性。如果属性不存在，将返回空字符串。
  • node – 当前节点 (AbbreviationNode 的实例)
  • name – 当前标签的名字
  • padding – 当前字符的留白，能够用于格式化
 <!-- /<%= attr("id", "#") %><%= attr("class", ".") %> -->
filter.commentBefore
当应用 comment 过滤器时，将被放在对应的元素前的注释内容的定义。更多信息，请参阅 filter.commentAfter 属性的描述。
  
filter.commentTrigger
一个属性列表，如果其中的项在缩写中存在，该缩写将被添加注释。如果希望为每个元素添加注释，可以将其设置为 *
 id, class
filter.trimRegexp
用于在 t(trim) 过滤器中检索要删除行标记 (numbers, dashes, bullets, 等)的正则表达式。这个裁切示波器用于包围缩写中从其它文档（如 Microsoft Word）中粘贴过来的列表。
 [\s|\u00a0]*[\d|#|\-|*|\u2022]+\.?\s*
format.forceIndentationForTags
定义强制其内部缩进的标签列表，用逗号间隔。
 body
format.noIndentTags
定义不其内缩进行的标签列表，用逗号间隔。
 html
sass.propertyEnd
定义展开 SASS 风格的 CSS 缩写时在每个 CSS 属性后面放置的符号。
  
stylus.propertyEnd
定义展开 Stylus 风格的 CSS 缩写时在每个 CSS 属性后面放置的符号。
  
stylus.valueSeparator
定义展开 Stylus 风格的 CSS 缩写时在两个属性和值之前放置的符号。
  
syntaxProfiles.json
定义如何生成 HTML/XML 。

syntaxProfiles.json

输出配置用于定义如何生成 HTML 内容。例如，当展开 br 属性时，Emmet 可能会生成如下标签中的一种：

  • <br> — HTML 记号
  • <br /> — XHTML 记号
  • <br/> — XML 记号

Emmet 尝试自动探测当前文档的输出配置。例如，如果文档定义成 XHTML 类型，将使用 xhtml 配置，否则使用 html 。

但有时，可能想要强制 Emmet 使用另一个特定语法的配置，或者使用带有特殊规则的自定义配置。

在这种情况下，可以在扩展文件夹创建 syntaxProfiles.json 文件并且为必备的语法指定配置。

这个文件的内容就是简单的键/值对字典，键是定义在 snippets.json 文件中的语法名，值是预定义配置（字符串）的名字或者带有配置选项（object）的字典：

{
    // force XHTML profile for HTML syntax
    "html": "xhtml",

    // create our own profile for XML
    "xml": {
        "tag_case": "upper",
        "attr_quotes": "single"
    }
}

预定义配置

  • html — 默认输出配置。
  • xhtml — 与 html 相同，但当输出空元素时，带有关闭斜杠：<br />。
  • xml — XML 和 XSL 语法的默认定义，在带有缩进的新行输出每个标签，输出空标签时带有关闭斜杠： <br/>。
  • line — 用于输出不带有任何缩进和换行的展开缩写。在某些编辑器中，默认应用于类似 JavaScript 或 Python 等编程语言上，以便生成有效的字符串。

创建自己的配置

可以指定一个带有如下键的字典来定义自己的输出配置：

  • tag_case：生成标签名的大小写，字符串类型。可取的值有：upper（大写）、lower（小写） 和 asis（原样输出）。
  • attr_case：生成标签的属性名的大小写，字符串类型。可取的值有：upper（大写）、lower（小写） 和 asis（原样输出）。
  • attr_quotes: 围住属性值的括号，字符串，可取的值有： single（单引号） 和 double（双引号）。
  • tag_nl: 在带有缩进的新行上输出每个标签。可取的值有true (每个标签占一行),false (不格式化) 和 'decide' (字符串；仅块级元素生成新行）。
  • tag_nl_leaf：当 tag_nl 设置成 true，定义叶块节点（即没有子节点的节点）里面是否格式化换行符。
  • indent：在新行上缩进标签，布尔值。
  • inline_break：达到多少行内元素需要强制换行，数值类型。默认值为 3。例如 span*2 将展开成 <span></span><span></span>，但 span*3 将生成三个 <span> 元素，每个占有一行。如果设置为 0 将不再为行内元素换行。
  • self_closing_tag：空元素是否还有关闭斜杠，如 br 和 img，布尔值。可取的值有 true、 false 和 'xhtml' (字符串；按 XHTML 风格输出关闭斜杠，例如： <br />)。
  • filters: 自动应用的 过滤器 列表。

posted on 2013-04-15 13:36  刘兴伟  阅读(4198)  评论(1)  编辑  收藏  举报

导航