angular-docs-cn/aio/tools/transforms/templates/api/lib/memberHelpers.html

{% import "lib/githubLinks.html" as github -%}
{% import "lib/paramList.html" as params -%}

{%- macro renderHeritage(exportDoc) -%}
  {%- if exportDoc.extendsClauses.length %} extends {% for clause in exportDoc.extendsClauses -%}
  <a class="code-anchor" href="{$ clause.doc.path $}">{$ clause.text $}</a>{% if not loop.last %}, {% endif -%}
  {% endfor %}{% endif %}
  {%- if exportDoc.implementsClauses.length %} implements {% for clause in exportDoc.implementsClauses -%}
  <a class="code-anchor" href="{$ clause.doc.path $}">{$ clause.text $}</a>{% if not loop.last %}, {% endif -%}
  {% endfor %}{% endif %}
{%- endmacro -%}

{%- macro renderMembers(doc) -%}
  {%- for member in doc.staticProperties %}{% if not member.internal %}
  <a class="code-anchor" href="{$ doc.path $}#{$ member.anchor | urlencode $}">{$ renderMemberSyntax(member, 1) $}</a>{% endif %}{% endfor -%}
  {% for member in doc.staticMethods %}{% if not member.internal %}
  <a class="code-anchor" href="{$ doc.path $}#{$ member.anchor | urlencode $}">{$ renderMemberSyntax(member, 1) $}</a>{% endif %}{% endfor -%}
  {% if doc.constructorDoc and not doc.constructorDoc.internal %}
  <a class="code-anchor" href="{$ doc.path $}#{$ doc.constructorDoc.anchor | urlencode $}">{$ renderMemberSyntax(doc.constructorDoc, 1) $}</a>{% endif -%}
  {% for member in doc.properties %}{% if not member.internal %}
  <a class="code-anchor" href="{$ doc.path $}#{$ member.anchor | urlencode $}">{$ renderMemberSyntax(member, 1) $}</a>{% endif %}{% endfor -%}
  {% for member in doc.methods %}{% if not member.internal %}
  <a class="code-anchor" href="{$ doc.path $}#{$ member.anchor | urlencode $}">{$ renderMemberSyntax(member, 1) $}</a>{% endif %}{% endfor -%}

  {%- for ancestor in doc.extendsClauses %}{% if ancestor.doc %}

  // 继承自 <a class="code-anchor" href="{$ ancestor.doc.path $}">{$ ancestor.doc.id $}</a>{$ renderMembers(ancestor.doc) $}{% endif %}{% endfor -%}
{%- endmacro -%}

{%- macro renderMemberSyntax(member, truncateLines) -%}
    {%- if member.boundTo %}<span class="property-binding">@{$ member.boundTo.type $}(
    {%- if member.boundTo.propertyName != member.boundTo.bindingName %}'{$ member.boundTo.bindingName $}'{% endif -%}
    )</span><br>{% endif -%}
    {%- if member.accessibility !== 'public' %}{$ member.accessibility $} {% endif -%}
    {%- if member.isAbstract %}abstract {% endif -%}
    {%- if member.isStatic %}static {% endif -%}
    <span class="member-name">{$ member.name $}</span>{$ member.typeParameters | escape $}{% if not member.isGetAccessor %}{$ params.paramList(member.parameters, truncateLines) | trim $}{% endif %}
    {%- if member.isOptional  %}?{% endif -%}
    {$ params.returnType(member.type) | trim | truncateCode(truncateLines) $}
{%- endmacro -%}

{%- macro renderOverloadInfo(overload, cssClass, method) -%}
<div class="overload-info">
  {% if overload.shortDescription and (overload.shortDescription != method.shortDescription) %}
  <div class="short-description">
    {$ overload.shortDescription | marked $}
  </div>{% endif %}

  <code-example language="ts" hideCopy="true" linenums="false" class="no-box api-heading">{$ renderMemberSyntax(overload) $}</code-example>

  {% if overload.deprecated !== undefined %}
  <div class="deprecated">
    {$ ('**Deprecated** ' + overload.deprecated) | marked $}
  </div>{% endif %}

  <h6 class="no-anchor">参数</h6>
  {$ params.renderParameters(overload.parameterDocs, cssClass + '-parameters', cssClass + '-parameter', true) $}

  {% if overload.type or overload.returns.type %}
  <h6 class="no-anchor">返回值</h6>
  {% marked %}`{$ (overload.type or overload.returns.type) $}`{% if overload.returns %}: {$ overload.returns.description $}{% endif %}{% endmarked %}
  {% endif %}


  {% if overload.throws.length %}
  <h6 class="no-anchor">异常</h6>
  {% for error in overload.throws %}
  {% marked %}`{$ (error.typeList or '错误') $}` {$ error.description $}{% endmarked %}
  {% endfor %}
  {% endif %}

  {% if overload.description and (overload.description != method.description) -%}
  <div class="description">
    {$ overload.description | marked $}
  </div>
  {%- endif %}
</div>
{%- endmacro -%}

{%- macro renderMethodDetail(versionInfo, method, cssClass) -%}
<a id="{$ method.anchor $}"></a>
<table class="is-full-width method-table {$ cssClass $}">
  {% if method.name !== 'constructor' %}<thead><tr><th>
    <div class="with-github-links">
    <h3>
      {% if method.isCallMember %}<i>调用签名</i>
      {% elseif method.isNewMember %}<i>构造函数签名</i>
      {% else %}{$ method.name $}()
      {% endif %}
    </h3>
    {$ github.githubLinks(method, versionInfo) $}
    </div>
  </th></tr></thead>{% endif %}
  <tbody>
    {% if method.shortDescription %}<tr>
      <td class="short-description">
        {$ method.shortDescription | marked $}
        {%- if method.see.length %}
        <p>See also:</p>
        <ul>
        {% for see in method.see %}
          <li>{$ see | marked $}</li>{% endfor %}
        </ul>
        {% endif %}
      </td>
    </tr>{% endif %}
  {% if method.overloads.length == 0 %}
    <tr>
      <td>
        {$ renderOverloadInfo(method, cssClass + '-overload', method) $}
      </td>
    </tr>
  {% elseif method.overloads.length < 3 -%}
    {% if method.isAbstract %}
      <tr>
        <td>
          {$ renderOverloadInfo(method, cssClass + '-overload', method) $}
        </td>
      </tr>
    {% endif %}
    {% for overload in method.overloads -%}
    <tr>
      <td>
        {$ renderOverloadInfo(overload, cssClass + '-overload', method) $}
      </td>
    </tr>
    {% endfor -%}
  {% else -%}
    <tr>
      <td>
        <details class="overloads">
          <summary>
            <div class="icon-action-header">
                <h4 class="no-anchor">{$ method.overloads.length $} 个重载形式...</h4>
                <a>
                  <span class="show-all">显示所有</span>
                  <span class="collapse-all">隐藏所有</span>
                  <i class="material-icons expand">expand_more</i>
                </a>
              </div>
          </summary>
          <div class="detail-contents">
            {% if method.isAbstract %}
              {$ renderOverloadInfo(method, cssClass + '-overload', method) $}
              <hr class="hr-margin fullwidth">
            {% endif %}
            {% for overload in method.overloads %}
              <h5 class="no-anchor">Overload #{$ loop.index $}</h5>
              {$ renderOverloadInfo(overload, cssClass + '-overload', method) $}
              {% if not loop.last %}<hr class="hr-margin">{% endif %}
            {% endfor %}
          </div>
        </details>
      </td>
    </tr>
  {% endif %}

  {% if method.description -%}
    <tr>
      <td class="description">
        {$ method.description | marked({ h3: 'h5' }) $}
      </td>
    </tr>
  {%- endif %}

  {% if method.usageNotes -%}
    <tr>
      <td class="usage-notes">
        <h4 id="{$ method.anchor $}-usage-notes">使用说明</h4>
        {$ method.usageNotes | marked({ h3: 'h5' }) $}
      </td>
    </tr>
  {%- endif %}
    </tbody>
</table>
{% endmacro -%}

{%- macro renderMethodDetails(versionInfo, methods, containerClass, itemClass, headingText) -%}
{% set nonInternalMethods = methods | filterByPropertyValue('internal', undefined) %}
{% if nonInternalMethods.length %}
<section class="{$ containerClass $}">
  <h2>{$ headingText $}</h2>
  {% for member in nonInternalMethods %}
    {$ renderMethodDetail(versionInfo, member, itemClass) $}
  {% endfor %}
</section>
{% endif %}
{%- endmacro -%}


{%- macro renderProperties(properties, containerClass, propertyClass, headingText, headings, headingLevel = 2) -%}
{% set nonInternalProperties = properties | filterByPropertyValue('internal', undefined) %}
{% if nonInternalProperties.length -%}
<section class="{$ containerClass $}">
  <h{$ headingLevel $}>{$ headingText $}</h{$ headingLevel $}>
  <table class="is-full-width list-table property-table">
    <thead>
      <tr>
        <th>{$ headings[0] or '属性' $}</th>
        <th>{$ headings[1] or '说明' $}</th>
      </tr>
    </thead>
    <tbody>
    {% for property in nonInternalProperties %}
      <tr class="{$ propertyClass $}">
        <td>
          <a id="{$ property.anchor $}"></a>
          <code>{$ renderMemberSyntax(property) $}</code>
        </td>
        <td>
          {%- if (property.isGetAccessor or property.isReadonly) and not property.isSetAccessor %}<span class='read-only-property'>只读</span>{% endif %}
          {%- if property.isSetAccessor and not property.isGetAccessor %}<span class='write-only-property'>Write-only.</span>{% endif %}
          {% if property.constructorParamDoc %} <span class='from-constructor'>Declared in constructor.</span>{% endif %}
          {% if property.shortDescription %}{$ property.shortDescription | marked $}{% endif %}
          {$ (property.description or property.constructorParamDoc.description) | marked $}
          {%- if property.see.length %}
          <p>参见:</p>
          <ul>
          {% for see in property.see %}
            <li>{$ see | marked $}</li>{% endfor %}
          </ul>
          {% endif %}
          </td>
    </tr>
    {% endfor %}
    </tbody>
  </table>
</section>
{%- endif -%}
{%- endmacro -%}

{% macro renderDirectiveAncestors(doc, collectionName) %}
{%- for ancestor in doc.extendsClauses %}{% if ancestor.doc %}
{% set nonInternalMembers = ancestor.doc[collectionName] | filterByPropertyValue('internal', undefined) %}
{% if nonInternalMembers.length -%}
<section class="inherited-members-list">
  <h3>继承自 <code><a class="code-anchor" href="{$ ancestor.doc.path $}">{$ ancestor.doc.name $}</a></code></h3>
  <ul>
  {% for member in nonInternalMembers %}
    <li>
        <code><a class="code-anchor" href="{$ ancestor.doc.path $}#{$ member.anchor | urlencode $}">{$ renderMemberSyntax(member) $}</a></code>
    </li>
  {% endfor %}
  </ul>
</section>
{% endif %}
{$ renderDirectiveAncestors(ancestor.doc, collectionName) $}
{% endif %}{% endfor -%}
{% endmacro %}

{% macro renderDirectiveProperties(doc, heading) %}
{$ renderProperties(doc.properties, 'instance-properties', 'instance-property', heading) $}
{$ renderDirectiveAncestors(doc, 'properties') $}
{% endmacro %}