织梦function如何使用？

在织梦里，"function" 通常指两种情况：

1. 系统内置函数：织梦本身提供的、可以直接在模板或PHP代码中调用的函数。
2. 自定义函数：开发者自己编写，并集成到织梦系统中,以便在模板里像调用系统函数一样方便地使用的函数。

这篇教程将重点讲解第二种情况，即如何创建和使用你自己的函数,这是扩展织梦功能最核心的技能之一。

为什么需要自定义函数？

当你发现织梦默认的标签无法满足你的需求时,就需要自定义函数。

• 复杂的数据处理：你需要将文章内容里的所有 <img> 标签提取出来,并生成缩略图列表。
• 特殊的数据格式化：你需要将一个Unix时间戳格式化为 "X天前" 这样的相对时间。
• 调用外部API：在模板中调用天气API,并显示当前天气。
• 封装复杂的逻辑：将一段重复使用的PHP代码封装成一个函数,让模板调用更简洁。

创建和使用自定义函数的完整流程

整个过程分为三步：

1. 编写PHP函数代码：创建一个 .php 文件,并编写你的函数。
2. 引入/加载函数文件：让织梦系统知道你的函数文件在哪里。
3. 在模板中调用函数：使用织梦的 function} 标签语法来调用你的函数。

编写PHP函数代码

你需要创建一个PHP文件,并在其中定义你的函数。

函数命名规范：

• 函数名必须以 __ 开头和结尾，__my_function()。
• 这是织梦识别自定义函数的约定,不能省略。

函数文件存放位置：

• 为了方便管理，建议将自定义函数文件放在 /include/helpers/ 目录下,这个目录就是专门用来存放辅助函数的。
• 我们创建一个新文件：/include/helpers/my_helper.php

示例：创建一个“截取字符串并添加省略号”的函数

打开 /include/helpers/my_helper.php 文件,写入以下代码：

<?php
if (!defined('DEDEINC')) exit('dedecms');
/**
 * 截取字符串并添加省略号
 * @param string $str 需要处理的字符串
 * @param int $length 截取长度
 * @return string 处理后的字符串
 */
function __cutstr_with_ellipsis($str, $length = 100)
{
    // 如果字符串为空，直接返回
    if (empty($str)) {
        return '';
    }
    // 使用织梦自带的 CutStr 函数进行截取
    $result = CutStr($str, $length, false);
    // 如果原始字符串长度大于截取长度，则添加省略号
    if (strlen($str) > $length) {
        $result .= '...';
    }
    return $result;
}

代码解释：

• if (!defined('DEDEINC')) exit('dedecms');：这是织梦文件的标准开头，用于安全检查,防止直接访问。
• function __cutstr_with_ellipsis(...)：我们定义了一个符合规范的函数名。
• CutStr(...)：我们在函数内部调用了织梦自带的 CutStr 函数,这说明自定义函数可以和系统函数完美结合。
• 函数返回处理后的字符串。

引入/加载函数文件

织梦默认不会加载 /include/helpers/ 目录下的所有文件，你需要手动告诉织梦去加载你的 my_helper.php 文件。

有几种方法可以实现：

在需要调用的PHP文件中引入（推荐用于特定页面）

如果你只想在某个特定页面（比如首页 index.php）使用这个函数,可以直接在该PHP文件的开头引入。

在 /index.php 文件中，找到 require_once(dirname(__FILE__)."/include/common.inc.php"); 这一行，在它后面添加：

// 引入自定义函数文件
require_once(DEDEINC."/helpers/my_helper.php");

优点：不会影响其他页面，性能开销小。 缺点：需要在每个需要使用该函数的PHP文件中都手动引入一次。

通过全局配置文件引入（推荐用于通用函数）

如果你的函数在很多页面都需要使用,可以通过修改织梦的核心配置文件来全局引入。

1. 打开 /include/common.inc.php 文件。

2. 找到类似这样的代码段（可能在文件末尾）：

   //加载常用函数库
   //require_once(DEDEINC.'/helpers/arrayhelper.class.php');
   //require_once(DEDEINC.'/helpers/stringhelper.class.php');

3. 在这里添加你的引入语句：

   //加载常用函数库
   //require_once(DEDEINC.'/helpers/arrayhelper.class.php');
   //require_once(DEDEINC.'/helpers/stringhelper.class.php');
   // 引入自定义函数文件
   require_once(DEDEINC.'/helpers/my_helper.php');

优点：一劳永逸，所有页面都可以调用，无需再手动引入。 缺点：会增加一点点全局的初始化时间,但对于通用函数来说可以忽略不计。

在模板中调用函数

最关键的一步来了，在织梦的模板文件（.htm 文件）中，你可以使用 语法来调用你刚刚创建的函数。

基本语法：

{ function 函数名(参数1, '参数2', ...)}

示例：在首页文章列表中使用我们的函数

打开你的首页模板文件 index.htm，找到文章列表循环标签 arclist 或 list,在需要显示摘要的地方使用你的函数。

假设你的文章摘要字段是 description,你可以这样写：

{dede:arclist row='5' titlelen='40'}
    <li>
        <a href="[field:arcurl/]">[field:title/]</a>
        <span>
            <!-- 调用我们自定义的函数，截取摘要长度为80 -->
            [field:description function='__cutstr_with_ellipsis(@me, 80)'/]
        </span>
    </li>
{/dede:arclist}

语法解析：

• [field:description function='...'/]：这是调用函数的标准格式。
• function='...'：固定写法,表示这里要执行一个函数。
• __cutstr_with_ellipsis：我们定义的函数名。
• @me：这是一个非常重要的特殊变量，它代表当前字段的原始值。@me 就等于 [field:description] 的原始内容。
• , 80：这是传递给函数的第二个参数，我们的函数定义是 __cutstr_with_ellipsis($str, $length = 100)，所以这里将 80 传递给了 $length 参数。

其他调用示例：

如果你的函数没有参数,调用方式更简单：

{ my_global_function() }

如果你的函数需要多个参数：

[field:pubdate function='MyDateFunction(@me, "Y-m-d H:i", "yes")'/]

这里调用了 MyDateFunction 函数，并传递了三个参数：@me（原始时间）、"Y-m-d H:i"（格式化字符串）和 "yes"（一个标志）。

总结与最佳实践

1. 函数命名：务必使用 __yourFunctionName() 的格式。
2. 文件位置：将自定义函数放在 /include/helpers/ 目录下,便于管理。
3. 加载方式：
   • 通用函数 -> 修改 common.inc.php 全局引入。
   • 特定页面函数 -> 在对应PHP文件中 require_once 引入。
4. 模板调用：使用 [field:xxx function='__myFunc(@me, param)'/] 语法，@me 是当前字段的值。
5. 安全第一：在自定义函数中处理外部传入的数据时（@me），做好数据校验和过滤,防止XSS等安全问题。

通过掌握自定义函数，你就能极大地扩展织梦CMS的灵活性,让它更好地服务于你的项目。