首页 / 开发手册 / 标签语法

标签语法

先看这一篇:两类标签、属性规则、条件判断,以及模板里绝对不能做的事。

这一篇是标签手册的入口。后面的章节一篇讲一件事(公共标签、导航、列表、详情、分页……), 每篇开头都写着「适用范围」。语法只有下面这几条,看完就能读懂后面所有篇。

两类标签

类型写法用途
单标签{naicha:site name="title"}取一个值,直接输出
块标签{naicha:list}…{/naicha:list}循环输出一段 HTML

单标签不压作用域:写在页面的任何位置都行 —— 循环里、循环外、属性值里, 甚至同一行属性中间(见「容易踩的坑」那一篇)。 块标签成对出现,中间那段会按标签的规则重复(或按条件显示); 循环体里取值用固定的作用域前缀:{naicha:list} 里写 {list.title}, {naicha:shop} 里写 {shop.title} —— 前缀写错就是空串(不报错)。

标签只在哪里生效

只有模板文件里写的标签才会被执行。所谓模板文件,就是主题目录下那些 .html (templates/你的主题/)。

访客能提交的任何地方都不执行标签 —— 内容正文、评论、留言、表单、自定义字段、页面片段, 统统只当**文字**看待:谁在里面写 {naicha:list},页面上就原样显示这串字符, 既不会去取内容,也读不到别的东西。

为什么可以放心:引擎运行时只有一条渲染入口,它收的是"主题目录里的文件名", 不是任意字符串;正文/评论走的是另一条"取值"通道,默认转义, 只有你自己显式写 html="1" 才按 HTML 原样输出 —— 而原样输出 ≠ 执行。
一句话:标签是模板的语言,不是内容的语言。

不是所有标签在哪儿都能用

标签本身写在哪个模板里都行(引擎不会拒绝),但能不能取到数据,取决于上下文:

  • 作用域前缀:{list.title} 必须写在 {naicha:list} 里, {detail.*} 写在 {naicha:detail} 里,{comment.*} 写在评论行循环里 —— 前缀对不上就是空串
  • 页面上下文:{naicha:page}(分页条)要有"正在分页的那份列表"; {detail.*} 要有"当前这一篇"
  • 数据本身:这一篇没有图集,{detail.gallery} 就是空数组

取不到时输出空串、不报错 —— 这是刻意的:模板里少一个字段,不该让整页 500。

⚠️ 反过来说也要记住:放错地方不会报错,只会静默变空。 所以每一篇开头都写了「适用范围」,照着它用;页面开着却"那一段什么都没有", 第一个该对照的就是那一行。

属性写法

name="news"        双引号字符串
num="10"           数字
flag="1"           布尔
title="{naicha:param name="cid"}"   属性值里可以嵌套标签
⚠️ 属性里的引号要错开:外层用双引号时,里面那一层写单引号 ({naicha:param name='cid'})。写成一样的一对会把标签截断, 而截断之后只是取值变空 —— 不报错,很不容易发现。

变量取值与修饰符

循环里用 标签名.字段名,后面可以跟修饰符:

{list.title}              标题(自动 HTML 转义)
{list.content html="1"}    正文(按 HTML 原样输出)
{list.summary excerpt="60"}  截取 60 字并去掉标签
{list.publish_time format="Y年m月d日"}
{list.title urlencode="1"}   用于拼 URL
html="1"按 HTML 原样输出(只对你自己写的富文本用)
excerpt="60"截取前 N 字,并去掉 HTML 标签
format="Y-m-d"时间格式化,语法与 PHP 的 date() 一致
urlencode="1"做 URL 编码,拼 /tag/ 这类地址时必须加
highlight="关键词"把命中的词包成 <mark class="nc-hl">(先转义、再插标签,安全)
默认就是安全的:不写 html="1" 时,输出内容一律做 HTML 转义。 只有当字段内容确实是你自己写的富文本时,才加 html="1"。

条件判断

{naicha:if var="list.top" eq="1"}
  <span class="badge">置顶</span>
{naicha:else}
  <span>普通</span>
{/naicha:if}

可用比较:eq、neq、gt、lt、gte、lte、 in、empty、notempty。 判断变量不存在或为空时,条件一律不成立,不会报错。详见「什么时候显示、什么时候不显示(if)」那一篇。

在 JavaScript 里用变量

<script> 内部只识别 {naicha:...} 形式的标签,其余花括号原样保留 —— 这样 JS 里的对象、函数体、CSS 规则块都不会被误当成模板变量。

<script>
fetch('{naicha:url type="api"}/upload', { method: 'POST' })   // ✔ 正常编译
var obj = { a: 1 };                                        // ✔ 原样保留
</script>

需要在脚本里取宿主变量时,用少数几个已放行的名字, 其余裸变量请改用 {naicha:param name="x"} 明确取值。

HTML 注释里的标签不生效

模板里的 <!-- … --> 是纯文本:写在注释内部的 {naicha:…} 不会被当成标签编译,会原样输出到页面源码里(浏览器不显示,用户看不到)。

这条规则是刻意做的。在注释里写一句「这里用的是某个标签」是最自然的写法, 但如果注释文本也参与编译,块标签就会去找闭合 —— 要么跨过注释把中间一大段正文吞掉 (页面看着「少了一块」),要么配对失败整页 500, 而报错信息只会说 unexpected end of file,完全指不到注释那一行。

想在模板里留标签示例,用 &#123; 转义。 &#123;naicha:list} 会显示成 {naicha:list} 而不是被当成真标签执行 —— 本手册所有示例都是这么写的。

模板里做不到的事

  • 不能写 SQL。模板只能调用受控的取数标签,语法上就没有拼接 SQL 的口子。
  • 不能调任意 PHP 函数。能用的只有修饰符(excerpt、format 等)和标签。
  • 不能取没在控制器里传入的变量,取不到输出空串,不会泄露其它数据。
没找到答案? 可以在 联系我们 留言说明使用场景,我们会补充进文档。