From 3bfa4e5daa418386c82eec9709af881bd9cf52d2 Mon Sep 17 00:00:00 2001
From: Zhicheng Wang <zcwang@thoughtworks.com>
Date: Sun, 2 Sep 2018 11:11:49 +0800
Subject: [PATCH] =?UTF-8?q?docs(API):=20=E7=BF=BB=E8=AF=91=E5=AE=8C?=
 =?UTF-8?q?=E4=BA=86=20ElementRef?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 aio/content/translations/cn/api-plan.md |  2 +-
 packages/core/src/linker/element_ref.ts | 15 +++++++++++++++
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/aio/content/translations/cn/api-plan.md b/aio/content/translations/cn/api-plan.md
index a0a34755be..ef292876dc 100644
--- a/aio/content/translations/cn/api-plan.md
+++ b/aio/content/translations/cn/api-plan.md
@@ -29,7 +29,7 @@
 [x] |router/RouterModule | 2,227 | 0.69
 [x] |router/Route | 2,223 | 0.69
 [x] |common/http/HttpClientModule | 2,167 | 0.67
-[ ] |core/ElementRef | 2,163 | 0.67
+[x] |core/ElementRef | 2,163 | 0.67
 [ ] |core/OnInit | 2,136 | 0.66
 [ ] |common/UpperCasePipe | 2,078 | 0.65
 [ ] |common/NgStyle | 1,935 | 0.60
diff --git a/packages/core/src/linker/element_ref.ts b/packages/core/src/linker/element_ref.ts
index 9adc4128bd..f6488dc663 100644
--- a/packages/core/src/linker/element_ref.ts
+++ b/packages/core/src/linker/element_ref.ts
@@ -9,13 +9,18 @@
 /**
  * A wrapper around a native element inside of a View.
  *
+ * 对视图中某个原生元素的包装器。
+ *
  * An `ElementRef` is backed by a render-specific element. In the browser, this is usually a DOM
  * element.
  *
+ * `ElementRef` 的背后是一个可渲染的具体元素。在浏览器中，它通常是一个 DOM 元素。
+ *
  * @security Permitting direct access to the DOM can make your application more vulnerable to
  * XSS attacks. Carefully review any use of `ElementRef` in your code. For more detail, see the
  * [Security Guide](http://g.co/ng/security).
  *
+ * 允许直接访问 DOM 会导致你的应用在 XSS 攻击前面更加脆弱。要仔细评审对 `ElementRef` 的代码。欲知详情，参见[安全](http://g.co/ng/security)。
  *
  */
 // Note: We don't expose things like `Injector`, `ViewContainer`, ... here,
@@ -26,8 +31,11 @@ export class ElementRef<T = any> {
    * The underlying native element or `null` if direct access to native elements is not supported
    * (e.g. when the application runs in a web worker).
    *
+   * 背后的原生元素，如果不支持直接访问原生元素，则为 `null`（比如：在 Web Worker 环境下运行此应用的时候）。
+   *
    * <div class="callout is-critical">
    *   <header>Use with caution</header>
+   *   <header>当心！</header>
    *   <p>
    *    Use this API as the last resort when direct access to DOM is needed. Use templating and
    *    data-binding provided by Angular instead. Alternatively you can take a look at {@link
@@ -36,10 +44,17 @@ export class ElementRef<T = any> {
    *    supported.
    *   </p>
    *   <p>
+   *    当需要直接访问 DOM 时，请把本 API 作为最后选择。优先使用 Angular 提供的模板和数据绑定机制。或者你还可以看看 {@link
+   * Renderer2}，它提供了可安全使用的 API —— 即使环境没有提供直接访问原生元素的功能。
+   *   </p>
+   *   <p>
    *    Relying on direct DOM access creates tight coupling between your application and rendering
    *    layers which will make it impossible to separate the two and deploy your application into a
    *    web worker.
    *   </p>
+   *   <p>
+   *     如果依赖直接访问 DOM 的方式，就可能在应用和渲染层之间产生紧耦合。这将导致无法分开两者，也就无法将应用发布到 Web Worker 中。
+   *   </p>
    * </div>
    *
    */