dede源码模板标签怎么用：常见写法与示例

DedeCMS（织梦）的模板标签用于在模板中读取栏目、文章、站点配置等数据，并按指定结构输出 HTML。它们不是浏览器端的 JavaScript，也不是可以随意执行的 PHP：模板标签由 DedeCMS 在服务端解析，生成页面后再交给浏览器。

本文以常见的 DedeCMS 5.7 系列标签写法为主。不同版本、补丁、二次开发程序或模板解析器可能存在差别；实际使用时，应以当前站点的标签库、后台模板目录和生成结果为准。示例中的栏目 ID、模板文件名需要替换成站点自己的值。

一、先认识标签结构

常见标签可以分成两类。第一类是单标签，通常以 /> 结尾；第二类是容器标签，开始标签和结束标签之间放循环内容。

{dede:global.cfg_webname/}

{dede:arclist typeid='1' row='5'}
  <li><a href='[field:arcurl/]'>[field:title/]</a></li>
{/dede:arclist}

上例中，{dede:global.cfg_webname/} 是单标签，读取站点配置；{dede:arclist} 则是容器标签，会按条件取得多篇文章，并对每一篇文章执行一次内部模板。循环内的 [field:title/]、[field:arcurl/] 是当前记录的字段标签。

标签名、参数名和字段名都必须符合当前程序支持的写法。HTML 属性的引号、模板标签的括号也要完整；标签少了结束部分，常见结果是标签原样显示、模板解析失败或页面结构异常。

二、文章列表：最常用的 arclist

arclist 适合在首页、栏目页或文章页中调用一组文章，例如最新文章、推荐文章、某个栏目的内容。下面是一个基本列表：

<ul class='news-list'>
{dede:arclist typeid='1' row='10' titlelen='40' orderby='pubdate' orderway='desc'}
  <li>
    <a href='[field:arcurl/]'>[field:title/]</a>
    <time>[field:pubdate function='GetDateTime(@me)'/]</time>
  </li>
{/dede:arclist}
</ul>

这里的 typeid='1' 表示限定栏目，row='10' 表示本次调用的记录数，titlelen='40' 用于限制标题长度，orderby='pubdate' 和 orderway='desc' 指定按发布时间倒序。长度参数在不同版本或字段处理方式下可能按字符、字节或程序内部规则截取；如果多语言文本出现截断异常，应检查当前版本的截取实现，不要仅凭参数名推断精确单位。

常见的文章字段包括：

• [field:title/]：标题。
• [field:arcurl/]：文章链接。
• [field:litpic/]：缩略图路径，文章未设置缩略图时可能为空。
• [field:description/]：摘要内容。
• [field:pubdate/]：发布时间字段；可通过函数格式化。
• [field:typename/]：栏目名称。

字段是否可用、实际字段名及其返回内容，可能受内容模型和程序版本影响。需要自定义字段时，应先确认对应模型确实定义了该字段，并检查调用的标签是否能取到它。

显示缩略图，并处理没有图片的情况

缩略图字段为空时，直接输出图片标签会得到空的 src。可以在模板里用条件标签处理。DedeCMS 常见写法如下，但条件标签具体支持能力要以站点版本为准：

{dede:arclist typeid='1' row='6'}
  <article>
    <a href='[field:arcurl/]'>
      [field:array runphp='yes']
      if (@me['litpic']) {
        @me = '<img src="' . @me['litpic'] . '" alt="">';
      } else {
        @me = '';
      }
      [/field:array]
      <span>[field:title/]</span>
    </a>
  </article>
{/dede:arclist}

runphp='yes' 会让标签内容按 PHP 方式运行，因此它不是普通的文本格式化选项。上例只是展示常见的条件输出思路；不同版本的运行环境、字段数组结构和安全配置可能不同。没有必要时不要启用 PHP 执行，优先使用站点已经验证过的模板条件标签或在业务代码中预先处理数据。

限制栏目范围与筛选内容

typeid 常用于指定栏目。具体支持单个栏目、多个栏目或特定取值的方式，要以当前标签库为准；不要未经验证就把逗号分隔、范围表达式等格式当成所有版本都支持。若只要当前栏目内容，通常可以利用当前页面已有的栏目变量或在模板调用中明确传入栏目 ID，并在生成页面后检查结果。

文章列表还常用排序、推荐标记等参数。比如某些站点会用 orderby、orderway 控制排序，或用 flag 筛选推荐内容。参数名称、允许值和组合效果可能受版本及二次开发影响；应从该站的标签说明或现有可运行模板确认，不要把网上某个版本的参数表直接套用。

三、栏目页列表与分页

栏目列表页通常用 dede:list 输出当前栏目下的文章，再用 dede:pagelist 输出分页链接。它和首页常用的 arclist 不是可以随意互换的：list 通常服务于列表模板的分页数据。

<ul class='article-list'>
{dede:list pagesize='12'}
  <li>
    <a href='[field:arcurl/]'>[field:title/]</a>
    <p>[field:description/]</p>
  </li>
{/dede:list}
</ul>

<nav class='pagination'>
  {dede:pagelist listitem='info,index,end,pre,next,pageno' listsize='5'/}
</nav>

pagesize='12' 设置每页显示条数；pagelist 生成分页导航，listitem 用于选择要显示的分页项目，listsize 控制页码导航数量。它们要放在适合的列表模板中，且栏目需要有可分页的数据。若分页标签没有输出，先确认当前页面确实是列表页、列表数据超过一页，并检查是否使用了正确的模板类型。

首页上的 arclist 通常只负责取固定数量内容，不会自动替代栏目列表的分页机制。需要可翻页的栏目文章列表，应使用列表页的数据与分页标签，而不是只增加 row 参数。

四、栏目导航：channel 标签

channel 用于生成栏目链接，常见于导航栏、侧边栏和栏目树。常见写法之一是读取某个栏目的子栏目：

<ul class='channel-nav'>
{dede:channel type='son' typeid='1'}
  <li><a href='[field:typelink/]'>[field:typename/]</a></li>
{/dede:channel}
</ul>

这里的 type='son' 表示取子栏目，typeid='1' 指定父栏目。常见模板中还可能看到 type='top' 等用法。当前栏目、顶级栏目和子栏目之间的关系容易因页面上下文而混淆：在首页、栏目页、文章页使用时，当前栏目 ID 不一定相同。希望导航自动跟随当前栏目时，应先确认所用变量在该页面上下文中有值，再验证栏目层级是否符合预期。

栏目字段常见的有 [field:typename/]（栏目名称）和 [field:typelink/]（栏目链接）。若链接或名称为空，检查栏目是否存在、是否处于预期层级，以及当前模板是否调用了正确的栏目数据。

五、当前页面字段与全局配置

在文章、栏目等模板中，dede:field 常用于读取当前页面字段，例如标题或栏目名称；dede:global 常用于读取全局配置变量。

<title>{dede:field.title/} - {dede:global.cfg_webname/}</title>

<div class='breadcrumb'>
  {dede:field.position/}
</div>

cfg_webname 是常见的站点名称配置变量；具体配置项名称要与当前系统设置相符。面包屑字段是否可用以及输出格式，取决于模板和程序配置。若字段标签输出为空，不要先假设标签语法必然错误：它也可能是当前页面没有该字段，或当前标签库并未提供该字段。

模板里还会见到 {dede:field name='字段名'/} 一类形式。不同标签对属性写法的要求并不完全相同，应参照当前站点的模板示例，避免把 field、global、arclist 的参数格式相互套用。

六、模板包含：include 标签

头部、底部、侧栏等公共结构适合拆成独立模板文件，再用包含标签复用。常见格式如下：

{dede:include filename='head.htm'/}

<main>
  页面主体内容
</main>

{dede:include filename='footer.htm'/}

文件名应与站点模板目录中的实际文件一致。包含路径如何解析，可能受程序版本、模板目录和站点配置影响；不要只凭文件名相同就假定解析到了预期位置。修改公共文件后，如果页面没有变化，还要检查模板缓存、静态页面生成结果，以及当前访问的页面是否确实使用了这套模板。

七、函数与格式化：能用不等于适合

有些字段标签允许通过 function 对当前字段做处理，例如格式化发布时间：

{dede:arclist typeid='1' row='5'}
  <time>[field:pubdate function='GetDateTime(@me)'/]</time>
{/dede:arclist}

@me 在常见写法中代表当前字段值。函数名称、参数、可调用范围和结果类型要符合当前版本及标签实现，不能把它当作通用的 PHP 执行接口。函数返回值如果包含引号、尖括号等字符，还需要考虑它被放入 HTML 文本、属性还是其他上下文。

不建议为了少写几行模板而在标签中拼接复杂 PHP、SQL 或用户输入。复杂逻辑更适合放在经过审查的程序代码中处理，并清晰区分数据读取、业务判断和页面输出。

八、边界与安全：模板标签不是转义器

模板标签主要解决数据调用和页面拼装，不应被视为安全过滤机制。字段输出未必会针对 HTML 文本、HTML 属性、JavaScript 字符串等不同位置自动执行正确的上下文转义。尤其是标题、摘要、用户提交内容、外部数据，以及可能包含 HTML 的字段，必须结合数据来源和最终输出位置进行检查。

• 输出到 HTML 文本节点时，应确保内容经过适合文本上下文的转义或净化。
• 输出到属性值时，应使用引号包裹属性，并对属性内容进行适当转义；不要将不可信内容直接拼入事件属性。
• 不要把模板字段直接拼到 JavaScript 代码、SQL 语句或命令中。
• 用户提交的内容若允许部分 HTML，应采用明确的白名单净化策略，而不是仅删除几个字符。
• 不要把模板标签参数当作权限控制。隐藏链接或不输出某个按钮，并不能替代服务端的访问权限校验。

部分 DedeCMS 模板中存在可执行 PHP 的机制，部分标签也可能提供 SQL 查询能力。它们会扩大模板的执行能力和风险面，不能因为写在模板文件里就视为安全。不要让不可信人员编辑可执行模板，不要把用户输入拼进 SQL 标签；确有查询需求时，应使用受控的程序逻辑、参数化查询和必要的权限限制。具体可用标签和安全特性应以当前站点代码为准。

九、常见错误与排查顺序

1. 标签原样显示

通常先检查标签名称、花括号、斜杠、结束标签是否写全；再确认模板文件是否由 DedeCMS 模板引擎处理。如果代码被当作普通静态文本输出，标签自然不会解析。

2. 标签解析了，但没有数据

检查栏目 ID、数据状态、内容模型、筛选条件和排序字段；再确认该标签是否适用于当前模板类型。测试时可以暂时去掉筛选参数，先验证最小调用能否返回记录，然后逐项加回条件。

3. 列表能显示，链接却不对

确认使用的字段是否是当前标签返回的文章链接字段，并检查站点 URL、伪静态或静态页面配置。模板里的相对路径、绝对路径和栏目链接不能混为一谈。

4. 分页不显示或页数不对

检查是否在栏目列表模板中使用分页标签，栏目内容是否达到多页条件，以及列表模板是否设置了预期的每页条数。首页的文章调用通常不具备栏目列表分页上下文。

5. 改了模板，前台仍然没变化

区分模板文件、编译缓存和已生成的静态页面。根据站点运行方式清理或更新相应缓存，并重新生成需要更新的页面；同时确认访问地址实际对应的是哪一个模板和站点目录。

6. 页面出现乱码或截断

检查文件编码、数据库与页面编码配置，以及长度参数的截取行为。标题长度参数不等于所有语言环境下都按相同规则计数，摘要截取也可能破坏原有 HTML 结构。对于富文本内容，避免简单截断标签字符串。

十、建议的开发流程

1. 先在后台确认模板目录、栏目 ID、内容模型和当前页面使用的模板。
2. 先写最小标签，只输出标题或名称，确认数据源正确。
3. 再加入链接、排序、筛选和分页参数，每次只改一项，便于定位问题。
4. 在生成页面中检查实际 HTML，而不只看模板源码；模板标签最终输出可能与预期不同。
5. 检查空字段、特殊字符、无数据和多页等边界情况。
6. 上线前审核可执行模板逻辑和数据输出位置，确保不把模板标签当成安全过滤或权限控制。

理解 DedeCMS 标签的关键，是分清“标签调用的数据范围”和“标签输出的位置”：arclist 常用于取一组文章，list 常用于栏目分页列表，channel 常用于栏目导航，field 与 global 则读取页面字段和全局配置。掌握这些边界后，再结合当前版本的标签库验证参数，模板会更容易维护，也更不容易因版本差异或输出安全问题埋下隐患。