ENML
理解 Evernote Markup Language (ENML)
概述
ENML 是印象笔记用来表现笔记内容的标记语言。因为 ENML 是基于 XHTML 的, 所以它可以在印象笔记中方便的表示富文本。
简介
ENML 被设计成一个可以在各种客户端和平台展示的安全可移植的文档格式。它大部分是基于 XHTML 的。目前的第二版 ENML 被特意扩展了，它可以接收更多的实际的 HTML 文件从而减少了同步的失败。这意味着所有属性都被定义为 CDATA，而不是更受限的类型，并且各个 HTML 元素都可以包含其他 HTML 元素。
ENML 的正式定义在 http://xml.evernote.com/pub/enml2.dtd 中。印象笔记服务中的每个笔记的内容都必须严格遵循这个 ENML DTD。在成功调用 NoteStore.createNote 或 NoteStore.updateNote 前，服务会根据这个 DTD 来验证一个笔记的内容。
因为 ENML 基于 XHTML 并且必须严格遵循 ENML DTD，所以有几件事你需要注意。每个标签（tag）都必须配对，所以你要使用 <hr/> 而不是 <hr>。标签名必须全部小写。
注意: 尽管可以依赖印象笔记云 API 去验证笔记的 ENML，我们还是建议你下载DTD文件（在上方有链接）并且在你的应用内对笔记的 XML 进行验证。因为这样做会有以下几个好处
- 在本地对笔记进行验证会快得多。
- 笔记验证可以离线完成。
- 在本地对笔记进行验证的结果跟依赖印象笔记云 API 对ENML进行验证的结果是一样的。
增加的元素
ENML 在 XHTML 中增加了四个印象笔记的特定元素。
en-note
en-note 是所有 ENML 文档的顶级元素. 它替代了 XHTML 文档中的 HTML 和 BODY 标签。 en-note 支持下面这些可选属性:
- bgcolor - 笔记的背景色
- text - 文本的颜色
- style, title, lang, xml:lang, dir - 可选属性，他们的语义和对应的 XHTML 标准属性相同。
在一条最为简单的笔记中，一个en-note元素看起来是这样的：
en-media
en-media 用来标记笔记中的一个资源在文档中的嵌入位置。例如，它可以替代 HTML 中的 <img> 元素来标记图片资源在比集中显示的位置。en-media 支持如下属性：
- hash - 16 进制格式的资源的 MD5 校验码。这是资源的主要且唯一的标识符(必选)。请注意,这是指，该文件本身的MD5散列(二进制文件流),而不是base64编码串的散列或GUID的散列。
- type - 资源的 MIME 类型。(必选)
- align, alt, longdesc, height, width, border, hspace, vspace, usemap - 语义和对应的 'img' 属性相同的可选属性。这些被用来设置资源被显示时的格式。
- style, title, lang, xml:lang, dir - 语义和对性的 XHTML 标准属性相同的可选属性。
en-crypt
en-crypt 包含基于 Base-64 编码的加密文本。当用户在桌面客户端输入正确的密码后，这些加密文本就会显示出来。这些基于 Base-64 编码的密文被包含在元素的 CDATA 中。en-crypt 支持如下属性：
- hint - 解密时给用户的密码提示。
- cipher - 加密文本的对称加密算法名称。例如： "RC2"
- length - 对称加密算法的 key 的长度。例如： 64
en-todo
en-todo 标记笔记内容中的‘代办事项’复选框的位置。en-todo 不包含任何特别的文本；它是一个可以包含一个属性的自结尾标签：
- checked - "true" 代表待办事项已经完成，"false" 代表待办事项还未完成。如果这个属性不存在，那么默认为 "false"。
允许的元素
ENML 允许如下的标准 XHTML 元素：
- a
- abbr
- acronym
- address
- area
- b
- bdo
- big
- blockquote
- br
- caption
- center
- cite
- code
- col
- colgroup
- dd
- del
- dfn
- div
- dl
- dt
- em
- font
- h1
- h2
- h3
- h4
- h5
- h6
- hr
- i
- img
- ins
- kbd
- li
- map
- ol
- p
- pre
- q
- s
- samp
- small
- span
- strike
- strong
- sub
- sup
- table
- tbody
- td
- tfoot
- th
- thead
- title
- tr
- tt
- u
- ul
- var
- xmp
禁止的元素
ENML 被设计成允许显示静态文档。 正因为如此，在 ENML 中不允许出现类似 form 和 script 这样的“动态的” XHTML 元素。下面的 XHMTL 元素是不被允许的；试图创建包含这些元素的笔记会导致印象笔记云 API 抛出错误代码为EDAMErrorCode.ENML_VALIDATION的EDAMUserException 异常（意味着 ENML 有缺陷或不合法）：
- applet
- base
- basefont
- bgsound
- blink
- body
- button
- dir
- embed
- fieldset
- form
- frame
- frameset
- head
- html
- iframe
- ilayer
- input
- isindex
- label
- layer,
- legend
- link
- marquee
- menu
- meta
- noframes
- noscript
- object
- optgroup
- option
- param
- plaintext
- script
- select
- style
- textarea
- xml
在被支持的 XHTML 元素中，一些属性是被禁止的：
- id
- class
- onclick
- ondblclick
- on*
- accesskey
- data
- dynsrc
- tabindex
在 ENML 中使用的 URL 必须使用下面其中一种协议：
- http
- https
- file
给笔记内容添加样式
ENML 允许使用 CSS 给笔记添加样式。所有样式都必须在代码中直接使用 'style' 属性。不能引用外部的或嵌入的样式表，也不能使用 'class' 属性。
ENML 不定义或强制规定一个支持的样式集合。大多数印象笔记客户端用嵌入的浏览器控件（例如 WebView）来显示笔记内容，所以可以支持几乎所有的标准 CSS 属性。但是，因为笔记可以既显示在桌面端也可以显示在移动客户端，笔记作者在使用样式时要特别注意。在你设计你的笔记内容时，要检查在不同的平台上你的笔记的显示情况。
表示纯文本的笔记
在印象笔记中存储纯文本笔记的应用必须把换行符转换成 HTML 样式的换行。为了保证笔记在不同客户端上显示一致，我们建议你把每一段都包含在 <div> 中。对于空白行，就插入一个包含 <br> 的 <div>。例如，下面这个纯文本：
将被表示成如下的 ENML：
在通过 EDAM API 提交 HTML 内容之前，客户端应用会做如下几件事情：
1. 把文档转换成合法的 XML
2. 把所有 ENML DTD 不接受的标签都去掉
3. 转换标签到对应的 ENML 标签 (例如， BODY 被转换成 EN-NOTE)
4. 根据 ENML DTD 进行验证
5. 验证 href 和 src 的值是否是合法的 URL 和协议