开发文档

开启模板开发者模式

开始设计一个新模板，请首先打开 config/config_global.php 文件，在文件结尾添加以下代码开启模板开发者模式。

$_config['plugindeveloper'] = 1;

模板套系与风格区别

模板套系：统一的一类模板，集中放置并打包的系列。
模板风格：使用某个模板套系代码，仅改变其中变量设置的一个方案。
（默认一个模板套系下就一个风格方案，通过“复制”功能，可以复制出不同的风格，进行不同的设置，比如改变logo设置）

模板创建（基于最新版的教程）

首先进入后台 - 模板 - 设计新模板
填写模板名称(name)，例如设置为“我的模板”
填写版权信息(copyright)，根据自己的情况填写版权信息
填写惟一标识符(identifier)，惟一标识符用于生成模板目录和后续提交模板到应用中心，不可与现有模板重复，命名规则限制与 PHP 变量命名相同，建议一次性将此配置设置好，否则可能涉及到很多代码方面的变更，增加编码的麻烦。请注意：惟一标识符请不要设置的过短，或使用有可能与其他模板重复的命名。会自动创建模板目录：template/标识符/。
初始化模板设置，使用已经存在的模板设置初始化本模板，或创建空白设置的模板
其他细节参考下边老教程的说明

模板创建（老版本dz的教程）

创建模板套系

首先进入后台 - 界面 - 模板管理，扩展制作模板时需要创建一个专属套系用来后期修改
- 基于“模板套系”可以扩展针对 ./template/default/ 目录中对的模板文件
- 创建套系的原则是不破坏原有模板基础上进行全新的扩展模板设计

实例

在站点根目录 ./template/中创建新的目录如" ./template/mytest"
在 mytest 目录中创建必要子目录与文件如：

./template/mytest/common/
./template/mytext/common/extend_common.css
./template/mytext/common/extend_module.css

其中common目录为公共模板目录，其内部新建的extend_common.css、extend_module.css为扩展型CSS文件，它们可以在./template/default/common/common.css的和module.css的基础上进行CSS代码的覆盖性扩展
如果需要替换论坛首页模板，可以新建 ./template/mytext/forum/discuz，或复制 ./template/default 中的对应文件放在 mytext 对应目录，以在缓存生成时覆盖原有模板缓存，达到修改模板而不破坏原生模板的目的

后台风格管理

进入后台 - 界面 - 风格管理
- “风格管理”可以对已有风格进行风格变量的编辑，也可以基于前面创建的“模板套系”来全新开辟新的风格

新建风格

后台风格管理中，可以通过新增和复制原有风格进行新建风格的操作
新建风格之后，需要编辑它，调整里面的“匹配模板”为上面创建的新套系即可

风格管理编辑页面中重点风格常量介绍

匹配模板：对应的模板套系
扩展配色：此风格基础上可用于用户切换配色方案的扩展，它对应 ./template/mytest/style/ 目录中的样式文件。全新创建时应在./template/mytest/style/目录中建立如t1/style.css之后方能生效
默认配色：指定站点访问时，用户首先看到的配色方案
默认表情分类：对应后台 - 界面 - 表情管理中所启用的表情
界面基础图片目录：可用于更改模板图片目录，在CSS文件中使用{IMGDIR}的常量进行输出，在Discuz! X2版本之后的模板中需要使用$_G['style']['imgdir']
扩展图片目录：用来更改扩展图片目录，在CSS文件中使用{STYLEIMGDIR}的常量进行输出，在Discuz! X2版本之后的模板中需要使用$_G['style']['styleimgdir']
其他风格常量：以上没有提到风格常量，均可以在后台取得以花括号框选的常量用以在CSS文件中使用（X2以后的模板中均需要$_G['style']中对应的数组键值），涉及到CSS样式的动态变更，可以在修改对应设置如：正常字体大小 {FONTSIZE}:12px/1.5，则直接修改程序运行中CSS缓存中的值
自定义模板变量 - 新增：可以根据扩展需求，针对个性化的CSS进行全局的定义

PHP中使用template()函数显示已存在模板

在Discuz!程序执行中可以通过 include template('模板文件夹/模板名称无后缀');的方式进行解析，前提是您使用的Discuz!程序已经包含了 ./source/function/function_core.php 的函数库

PHP格式的模板

[X2.5新增内容]

从 Discuz! X2.5 开始，模板文件支持 PHP 扩展名的格式，你可以创建例如 ./template/mytext/common/forum/discuz.php 文件，PHP 的模板文件中你只需在原有 HTM 的模板文件开头添加一行代码即可，如：

<?php exit;?>

<?php echo '你不能看此模板的内容';exit;?>

PHP 的模板文件的模板数据内容将从文件的第二行开始解析。PHP 和 HTM 模板文件同时存在时，会优先解析 PHP 模板文件

模板语法

变量输出

输出一个变量的值，等同于php的 <?php echo $my_var;?>，花括号可以省略但不建议去掉。

{$my_var}

条件判断

通过if判断流程分支
- 如果写在HTML表单元素中，可以省去使代码更清晰易读，如{if $my_var}xxx{/if}

<!--{if $my_var}-->
 任意html语句
<!--{/if}-->

带有多条件的if写法，可使用PHP常规判断中的按位运算符等

<!--{if $my_var && ($my_var2 & 1 || $my_var3 == 3)}-->
 任意html语句
<!--{/if}-->

带有分支条件的if写法

<!--{if $my_var == 1}-->
 变量为1
<!--{elseif $my_var == 2}-->
 变量为2
<!--{else}-->
 其他情况
<!--{/if}-->

循环输出

带有数组键的循环写法

<!--{loop $my_arr $key $val}-->
 循环输出的HTML语句
<!--{/loop}-->

没有数组键的循环写法

<!--{loop $my_arr $val}-->

模板嵌套

将被嵌套模板内容解析为PHP语句并合并入本模板中的写法
- common/header 对应某个模板套系中的common目录的header模板文件

<!--{subtemplate common/header}-->

程序运行时include嵌套模板内容

<!--{template common/header}-->

插件钩子

在模板中设立插件钩子插件模板和语言包的设计
- hook为关键词，意为将index_top定义为钩子

<!--{hook/index_top}-->

变量数组嵌套使用

条件判断或变量输出时用到

<!--{if $my_arr[$my_var]}-->
<!--{if $my_arr[0]}-->
<!--{if $my_arr[$my_arr2[$my_var]]}-->

PHP解析

在模板中使用PHP语句可以通过{eval}进行

<!--{eval $my_var = 1;}-->
<!--{eval echo $my_var;}-->
<!--{eval $my_arr = array(1, 2, 3);}-->
<!--{eval print_r($my_arr);}-->
<!--{eval output();}-->
<!--{eval exit();}-->

多行PHP解析(Discuz! X3 新增)

<!--{eval}-->
...PHP语句...
<!--{/eval}-->

语言包使用

在模板中可以通过下面的代码来使用语言包中的某个值

{lang index_yesterday}

其中语言包在 ./source/language/目录下，以PHP数组形式存放

插件模板和语言包的设计

请参见：插件模板和语言包的设计

综合示例

综合示例题目1：php程序中创建一个数组并在模板中循环，并且根据模板显示奇数行输出不同的CSS样式

PHP端代码：

此PHP代码省略了包含 class_core.php 以及初始化$_G变量，详细请查看：

<?php
 /*此处省略include class_core.php*/
 $my_arr = array('one', 'two', 'three', 'four');
 include template('forum/mytest'); //使用自定义模板套系中的forum目录的mytest
?>

模板代码：

<!--{loop $my_arr $key $val}-->
  <div {if $key % 2 == 1}style="background: #ccc;"{/if}>
   这里是value值：{$val}
  </div>
 <!--{/loop}-->

综合示例题目2：结合风格常量与javascript，动态改变模板页面的字体大小,并引用默认模板的header和footer
- 默认风格中，小号字体大小 {SMFONTSIZE}为0.83em，主题列表字体大小 {THREADTITLEFONTSIZE}为14px，在Disucz!X2中使用时，需要使用$_G['style']['SMFONTSIZE']和$_G['style']['THREADTITLEFONTSIZE']。
- $('test1')此写法是因为header中已经加载了common.js全局javascript脚本文件，可以通过简写来达到document.getElementById('test1')的效果
- ./template/mytest/forum/mytest模板代码如下

<!--{subtemplate common/header}-->
<div id="test1" style="font-size:{$_G['style']['FONTSIZE']};">
 这是一个改变字体的实例
</div>
<span onclick="changefontsize('{$_G['style']['SMFONTSIZE']}');">改变小号字</span><span onclick="changefontsize('{$_G['style']['THREADTITLEFONTSIZE']}');">改变为大号字</span>
<script type="text/javascript">
function changefontsize(size) {
 $('test1').style.fontSize = size;
}
</script>
<!--{subtemplate common/footer}-->

模板缓存与CSS缓存

模板缓存

模板缓存存放：所有的模板缓存均被解析成php文件存放在 ./data/template 中，以 “数字_模板标示符组合.tpl.php”形式保存
页面缓存刷新原理：当开发者编辑过模板文件之后，Discuz! 模板解析器会匹配模板htm文件与缓存php文件的最后修改时间，如过模板html文件较新或无缓存文件，则更新或生成缓存，不新，则不采取任何动作
手动删除此目录的缓存不会影响Discuz!系统的整体运行，Discuz! 模板缓存仍然会进行自动生成

CSS缓存

CSS缓存存放：./data/cache/目录中，以 “style_风格自增编号_应用入口关键字_所在页面的mod值.css”形式保存
自建新套系模板文件可以通过创建 ./template/mytest/common/extend_common.css 或 extend_module.css 进行CSS扩展
- 其中这两个文件的CSS样式脚本会通过 Discuz! 模板解析将风格常量统一赋值进去并合将CSS脚本复制出来放入 ./template/default/common/common.css 和 module.css 所对应的缓存中去，方便站点运行时引用
extend_module.css 系统解析与缓存存放：
- 其中可以使用下面的书写方法：

/** forum::index,forum::forumdisplay **/
 .mycss {font: {FONTSIZE} {FONT};}
/** end **/

上面的写法含义是：针对 forum 的 index 和 forumdisplay 追加一个自定义的CSS样式 "mycss" ，Discuz! 模板解析将会根据 forum::index 的关键词将 mycss 分别追加在“./data/cache/style_2_forum_index.css”和“./data/cache/style_2_forum_forumdisplay.css”中(里面的数字2，根据新增的风格编号而定)
这样的写法好处就是，不变更默认模板的情况下有效的扩展CSS，并可以很好的进行多站点移植

CSS 继承规范

Discuz! X系列产品中 CSS 文件会在缓存时按照以下顺序进行合并：

template/default/*.css 文件
当默认模版是非默认模版时，template/模版目录/extend_*.css 文件或 template/模版目录/*.css
当某插件启用时，source/plugin/插件目录/template/extend_*.css 文件

因此非默认模版目录中的 CSS 属性将继承默认模版中的 CSS 属性，插件目录中的 CSS 文件将继承前二者的 CSS 属性
CSS 自身的集成顺序为：当 CSS 属性名称相同是，CSS 文件中，写在后面的替换前面的代码

CSS缓存

CSS多IE下兼容HACK写法

所有 IE浏览器适用：  .ie_all .foo { ... }
IE6 专用：    .ie6 .foo { ... }
IE7 专用：    .ie7 .foo { ... }
IE8 专用：    .ie8 .foo { ... }

CSS书写规范

属性写在一行内，属性之间、属性名和值之间以及属性与“{}”之间须有空格，例如：.class { width: 400px; height: 300px; }
属性的书写顺序：
1. 针对特殊浏览器的属性，应写在标准属性之前，例如：-webkit-box-shadow:; -moz-box-shadow:; box-shaow:;
2. 按照元素模型由外及内，由整体到细节书写，大致分为五组：
  1. 位置：position,left,right,float
  2. 盒模型属性：display,margin,padding,width,height
  3. 边框与背景：border,background
  4. 段落与文本：line-height,text-indent,font,color,text-decoration,...
  5. 其他属性：overflow,cursor,visibility,...
谨慎添加新的选择符规则，尤其不可滥用 id，尽可能继承和复用已有样式
选择符、属性、值均用小写（格式的颜色值除外），缩写的选择符名称须说明缩写前的全称，例如 .cl -> Clearfix
勿使用冗余低效的 CSS 写法，例如：ul li a span { ... }
慎用 !important
建议使用在 class/id 名称中的词语
1. 表示状态：a->active
2. 表示结构：h->header,c->content,f->footer
3. 表示区域：mn->main,sd->side,nv-navigation,mu->menu
4. 表示样式：l-list,tab,p_pop

常用CSS

左浮动、右浮动

.z { float: left; }
.y { float: right; }

因为左右浮动造成的父级浮动溢出，及使用方法

.cl:after { content: "."; display: block; height: 0; clear: both; visibility: hidden; } .cl { zoom: 1; }

<div class="cl">
 <div class="z"></div>
</div>

大标题字体

.wx, .ph { font-family: "Microsoft YaHei", "Hiragino Sans GB", STHeiti, Tahoma, SimHei, sans-serif; font-weight: 100; }

行内分割竖线

.pipe { margin: 0 5px; color: #CCC; }

.xs0 { font-family: {SMFONT}; font-size: {SMFONTSIZE}; -webkit-text-size-adjust: none; }
.xs1 { font-size: 12px !important; }
.xs2 { font-size: 14px !important; }
.xs3 { font-size: 16px !important; }

灰色文字

.xg1, .xg1 a { color: {LIGHTTEXT} !important; }
.xg1 .xi2 { color: {HIGHLIGHTLINK} !important; }
.xg2 { color: {MIDTEXT}; }

高亮文字，1为橙色，2为蓝色

.xi1, .onerror { color: {NOTICETEXT}; }
.xi2, .xi2 a, .xi3 a { color: {HIGHLIGHTLINK} ; }

文字粗体

.xw0 { font-weight: 400; }
.xw1 { font-weight: 700; }

层下边线

.bbda { border-bottom: 1px dashed {COMMONBORDER}; }
.bbs { border-bottom: 1px solid {COMMONBORDER} !important; }

去除边框

.bw0 { border: none !important; }
.bw0_all, .bw0_all th, .bw0_all td { border: none !important; }

去除背景

.bg0_c { background-color: transparent !important; }
.bg0_i { background-image: none !important; }
.bg0_all { background: none !important; }

外边距样式

.mtn { margin-top: 5px !important; }
.mbn { margin-bottom: 5px !important; }
.mtm { margin-top: 10px !important; }
.mbm { margin-bottom: 10px !important; }
.mtw { margin-top: 20px !important; }
.mbw { margin-bottom: 20px !important; }

内边距样式

.ptn { padding-top: 5px !important; }
.pbn { padding-bottom: 5px !important; }
.ptm { padding-top: 10px !important; }
.pbm { padding-bottom: 10px !important; }
.ptw { padding-top: 20px !important; }
.pbw { padding-bottom: 20px !important; }

更新时间：2013-9-4

开发文档

为你整合最有用的Discuz!X 开发文档

目录

开启模板开发者模式

模板套系与风格区别

模板创建（基于最新版的教程）

模板创建（老版本dz的教程）

创建模板套系

实例

后台风格管理

新建风格

风格管理编辑页面中重点风格常量介绍

PHP中使用template()函数显示已存在模板

PHP格式的模板

模板语法

变量输出

条件判断

循环输出

模板嵌套

插件钩子

变量数组嵌套使用

PHP解析

语言包使用

插件模板和语言包的设计

综合示例

模板缓存与CSS缓存

模板缓存

CSS缓存

CSS 继承规范

CSS缓存

CSS多IE下兼容HACK写法

CSS书写规范

常用CSS

产品服务

使用教程

服务支持

联系我们