标签语法
先看这一篇:两类标签、属性规则、条件判断,以及模板里绝对不能做的事。
这一篇是标签手册的入口。后面的章节一篇讲一件事(公共标签、导航、列表、详情、分页……), 每篇开头都写着「适用范围」。语法只有下面这几条,看完就能读懂后面所有篇。
两类标签
| 类型 | 写法 | 用途 |
|---|---|---|
| 单标签 | {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,完全指不到注释那一行。
{ 转义。
{naicha:list} 会显示成 {naicha:list}
而不是被当成真标签执行 —— 本手册所有示例都是这么写的。
模板里做不到的事
- 不能写 SQL。模板只能调用受控的取数标签,语法上就没有拼接 SQL 的口子。
- 不能调任意 PHP 函数。能用的只有修饰符(
excerpt、format等)和标签。 - 不能取没在控制器里传入的变量,取不到输出空串,不会泄露其它数据。
