README.md

@vue/component-compiler-utils

英文原版

用来编译 Vue 单文件组件的底层实用工具

这个包包含了底层的实用工具，对于将 Vue 单文件组件编译为 JavaScript 的打包器或模块系统来说，为其撰写插件或转换规则是用得到这些实用工具的。

表层 API 设计被刻意最小化，目的是在尽可能灵活的同时保持可复用。

为什么 vue-template-compiler 不是一个 peerDependency？

因为这个包更多地作为一个底层实用工具被使用，在实际的 Vue 工程中常常是一个可传递的依赖。这也是顶层包 (例如 vue-loader) 在调用 parse 和 compileTemplate 方法时将 vue-template-compiler 通过选项注入的原因。

没有将其列为同级依赖 (peer dependency) 也使得工具作者可以将 vue-template-compiler 换为一个非默认的模板编译器，而不需要仅仅为了填补同级依赖而引入它。

API

parse(ParseOptions): SFCDescriptor

将单文件组件的源码解析为一个带有 source map 的描述器。实际的编译器 (vue-template-compiler) 必须通过 compiler 选项被传入，这样具体的版本号就可以被最终用户指定。

interface ParseOptions {
  source: string
  filename?: string
  compiler: VueTemplateCompiler
  // https://github.com/vuejs/vue/tree/dev/packages/vue-template-compiler#compilerparsecomponentfile-options
  // default: { pad: 'line' }
  compilerParseOptions?: VueTemplateCompilerParseOptions
  sourceRoot?: string
  needMap?: boolean
}

interface SFCDescriptor {
  template: SFCBlock | null
  script: SFCBlock | null
  styles: SFCBlock[]
  customBlocks: SFCCustomBlock[]
}

interface SFCCustomBlock {
  type: string
  content: string
  attrs: { [key: string]: string | true }
  start: number
  end: number
  map?: RawSourceMap
}

interface SFCBlock extends SFCCustomBlock {
  lang?: string
  src?: string
  scoped?: boolean
  module?: string | boolean
}

compileTemplate(TemplateCompileOptions): TemplateCompileResults

将模板的源码编译为 JavaScript 代码。实际的编译器 (vue-template-compiler) 必须通过 compiler 选项被传入，这样具体的版本号就可以被最终用户指定。

它也可以通过 consolidate 可选地为任何模板引擎进行预处理。

interface TemplateCompileOptions {
  source: string
  filename: string

  compiler: VueTemplateCompiler
  https://github.com/vuejs/vue/tree/dev/packages/vue-template-compiler#compilercompiletemplate-options
  // default: {}
  compilerOptions?: VueTemplateCompilerOptions

  // Template preprocessor
  preprocessLang?: string
  preprocessOptions?: any

  // 将模板里找到的资源 URL 转换为 `require()` 调用
  // 这个选项默认是关闭的。如果设置为 true，则默认值为：
  // {
  //   video: ['src', 'poster'],
  //   source: 'src',
  //   img: 'src',
  //   image: 'xlink:href'
  //   use: 'xlink:href'
  // }
  transformAssetUrls?: AssetURLOptions | boolean

  // 为 vue-template-es2015-compiler，即一个 Buble 的 fork，指定的选项
  transpileOptions?: any

  isProduction?: boolean  // default: false
  isFunctional?: boolean  // default: false
  optimizeSSR?: boolean   // default: false

  // 是否美化编译后的渲染函数 (只在开发环境下有效)
  // 默认值：true
  prettify?: boolean
}

interface TemplateCompileResult {
  code: string
  source: string
  tips: string[]
  errors: string[]
}

interface AssetURLOptions {
  [name: string]: string | string[]
}

处理输出

处理得到的 JavaScript 代码形如；

var render = function (h) { /* ... */}
var staticRenderFns = [function (h) { /* ... */}, function (h) { /* ... */}]

它不会假定任何模块系统。你要在必要的时候负责处理导出。

compileStyle(StyleCompileOptions)

将输入的原始 CSS 进行 scoped CSS 转换。它不会处理预处理器。如果组件没有使用 scoped CSS 那么这一步会被跳过。

interface StyleCompileOptions {
  source: string
  filename: string
  id: string
  map?: any
  scoped?: boolean
  trim?: boolean
  preprocessLang?: string
  preprocessOptions?: any
  postcssOptions?: any
  postcssPlugins?: any[]
}

interface StyleCompileResults {
  code: string
  map: any | void
  rawResult: LazyResult | void // 来自 PostCSS 的懒处理原始结果
  errors: string[]
}

compileStyleAsync(StyleCompileOptions)

和 compileStyle(StyleCompileOptions) 相同，但是返回一个解析 StyleCompileResults 的 Promise 对象。可用于异步的 PostCSS 插件。