AIYA-Framework 预置功能使用文档

此部分为 AIYA-CMS 主题核心 项目，有关 “/framework-unit” 目录下文件的说明。

这部分的代码都是一些写好的功能，分成两类：一类是文件名“method”开头的，这部分是一些制作WP主题时候的简化函数；另一类文件名是“plugin”开头的，这些都是一些WP功能插件。

---

如何使用

这里的所有文件并是通过new Class类名('Class参数')这样调用的，所以这些文件每一个都是可以单独拿出来调用的，只要确保传入的参数正确即可。

我已经在项目中提供了部分文件的功能调用：

将项目整个项目复制到主题文件夹中，在主题 functions.php 中添加：

require_once(get_template_directory() . '/framework-required/setup.php');

已经引入了本项目的话，上面这步省略，接下来继续添加组件功能：

require_once(get_template_directory() . '/framework-unit/setup.php');

然后引入组件的设置页面：

require_once(get_template_directory() . '/framework-unit/plugin-config-parent.php');

require_once(get_template_directory() . '/framework-unit/plugin-config.php');

于是你应该已经发现了，这其实就是一套完整的“WordPress优化插件”，所以对于非AIYA-CMS主题用户，也提供了：

 

AIYA-Optimize 优化插件（包含了功能列表）

 

接下来说明plugin-config.php中没有用到的组件，这部分主要是用于WP主题的方法和一些应当由WP主题作者自行决定的功能（因为需要替代WP本身的方法）。

为了方面说明，这里直接复制了AIYA-CMS主题的模板，你可以直接按照这个模板添加到自己主题的 functions.php 中：

//加载需要的组件
AYP::include_plugins('inc');
AYP::include_plugins('plugin');

//单独引用

//运行环境检查
AYP::action('EnvCheck', array(
    //PHP最低版本
    'php_last' => '8.1',
    //PHP扩展
    'php_ext' => array('session', 'curl'),
    //WP最低版本
    'wp_last' => '6.1',
    //经典编辑器插件
    'check_classic_editor' => false,
    //经典小工具插件
    'check_classic_widgets' => false,
));

//定义了一些全局变量
global $aya_post_type, $aya_tax_type;

//排队引用

//此钩子用于执行add_theme_support()
AYP::action_register('After_Setup_Theme', array(
    //将默认的帖子和评论RSS提要链接添加到
    'automatic-feed-links' => '',
    //支持标签
    'title-tag' => '',
    //支持菜单
    'menus' => '',
    //支持文章类型
    'post-formats' => array(
        //'gallery',
        //'image',
        //'audio',
        //'video',
        //'status',
    ),
    //支持缩略图
    //'post-thumbnails' => array('post', 'page'),
    //搜索表单、注释表单和注释的默认核心标记
    'html5' => array(
        'search-form',
        'comment-form',
        'comment-list',
        'gallery',
        'caption',
        'script',
        'style',
        'navigation-widgets',
    ),
    //支持自定义图标
    'custom-logo' => array(
        'height' => 240,
        'width' => 240,
        'flex-height' => true,
    ),
    //支持自定义背景图
    'custom-background' => array(
        'default-repeat' => 'repeat',
        'default-position-x' => 'left',
        'default-position-y' => 'top',
        'default-size' => 'auto',
        'default-attachment' => 'fixed'
    )
));
//注册导航菜单
AYP::action_register('Register_Menu', array(
    //'菜单ID' => '菜单名',
    'main-menu' => __('全局菜单', 'AIYA'),
    'spare-menu' => __('备用菜单', 'AIYA'),
    'header-menu' => __('顶部导航', 'AIYA'),
    'footer-menu' => __('底部导航', 'AIYA'),
    'widget-menu' => __('小工具菜单', 'AIYA'),
));
//注册小工具栏位
AYP::action_register('Register_Sidebar', array(
    //'边栏ID' => '边栏名',
    'index-sitebar' => __('首页/归档页', 'AIYA'),
    'page-sitebar' => __('页面/文章页', 'AIYA'),
));
//注册自定义文章类型
AYP::action_register('Register_Post_Type', array(
    //'文章类型' => array('name' => '文章类型名','slug' => '别名','icon' => '图标'),
    'tweet' => array(
        'name' => __('推文', 'AIYA'),
        'slug' => 'tweet',
        'icon' => 'dashicons-format-quote',
    ),
));
//注册自定义分类法
AYP::action_register('Register_Tax_Type', array(
    //'分类法' => array('name' => '分类法名','slug' => '别名','post_type' => array('此分类法适用的文章类型',)),
    'collect' => array(
        'name' => __('专题', 'AIYA'),
        'slug' => 'collect',
        'post_type' => array('post'),
    ),
));
//重新定义模板位置
AYP::action_register('Template_Redefine', false);
//注册自定义模板页面
AYP::action_register('Template_New_Page', array(
    //'模板名' => '是否静态化',
    'go' => false,
    'link' => false,
));
//注册小工具 Tips：请确保此时要注册的小工具的文件已被require_once()
AYP::action_register('Widget_Load', array(
    //'小工具Class名',
    'AYA_Widget_Menu',
    'AYA_Widget_Serach',
    'AYA_Widget_Text_Html',
    'AYA_Widget_Tag_Cloud',
    'AYA_Widget_Post_Comments',
    'AYA_Widget_Post_Views',
    'AYA_Widget_Post_Newest',
    'AYA_Widget_Post_Random',
    'AYA_Widget_Post_Custom',
    //'AYA_Widget_Comments',
    //'AYA_Widget_Author_Box',
    //'AYA_Widget_User_Welcome',
    //'AYA_Widget_Tweet_Posts',
));
//解除 WP 自带的小工具
AYP::action_register('Widget_Unload', array(
    //'需要注销的小工具Class名',
    'WP_Widget_Archives',        //年份文章归档
    'WP_Widget_Calendar',        //日历
    'WP_Widget_Categories',      //分类列表
    'WP_Widget_Links',           //链接
    'WP_Widget_Media_Audio',     //音乐
    'WP_Widget_Media_Video',     //视频
    'WP_Widget_Media_Gallery',   //相册
    'WP_Widget_Custom_HTML',     //html
    'WP_Widget_Media_Image',     //图片
    'WP_Widget_Text',            //文本
    'WP_Widget_Meta',            //默认工具链接
    'WP_Widget_Pages',           //页面
    'WP_Widget_Recent_Comments', //评论
    'WP_Widget_Recent_Posts',    //文章列表
    'WP_Widget_RSS',             //RSS订阅
    'WP_Widget_Search',          //搜索
    'WP_Widget_Tag_Cloud',       //标签云
    'WP_Nav_Menu_Widget',        //菜单
    'WP_Widget_Block',           //区块
));
//后台自定义
AYP::action_register('Admin_Custom', array(
    //禁用前台顶部工具栏
    'remove_admin_bar' => true,
    //替换后台标题格式
    'admin_title_format' => true,
    //移除后台导航栏右上角WordPress标志
    'remove_admin_bar_wp_logo' => true,
    //隐藏后台仪表盘欢迎模块和WordPress新闻
    'remove_admin_dashboard_wp_news' => true,
    //替换后台页脚信息
    'admin_footer_replace' => '感谢使用 AIYA-CMS 主题，欢迎访问 Yeraph Studio 了解更多。',
    //自定义后台导航栏菜单
    'add_admin_bar_menu' => array(),
    'admin_add_system_dashboard_widgets' => true,
));
//启用小工具缓存插件
AYP::action_register('Widget_Cache', true);
//文章浏览量计数器插件
AYP::action_register('Record_Visitors', true);
//本地化头像插件
AYP::action_register('Local_Avatars', true);

//启动
AYP::action_all();

关于这些register_方法，统一指路一下WP的官方文档：

• https://developer.wordpress.org/reference/functions/add_theme_support/
• https://developer.wordpress.org/reference/functions/register_nav_menus/
• https://developer.wordpress.org/reference/functions/register_sidebar/
• https://developer.wordpress.org/reference/functions/register_widget/
• https://developer.wordpress.org/reference/functions/unregister_widget/
• https://developer.wordpress.org/reference/functions/register_post_type/
• https://developer.wordpress.org/reference/functions/register_taxonomy/

然后再次强调一下，上面的模板中使用的实际上是这些方法的封装，封装这些方法是为了在统一位置实现最简化调用。项目内部预先定义了一些html结构和一些不需要经常被修改的参数，对于post_type和taxonomy也预先定义了路由方法。

如果你需要完全控制这些方法，则不应该使用模板的这些参数，或者预先定义的这些参数不符合你的需求，你应该在源码中修改。

关于 Template_Redefine 和 Template_New_Page 功能，这里额外补充一些：

这两个组件分别在主题中额外定位了两个目录， /template-parts 和 /template-page ，这两个位置是在项目class中定义的。

第一个功能是通过为WP的模板路由增加查询参数实现的，开启这个方法之后你的主题根目录下可以只保留 index.php 和 function.php ，其他的archive.php之类的都可以放到主题template-parts目录下，这个class中也提供了完全替代WP模板路由的方法。

第二个功能只是一个简单的自定义页面路由方法，一些主题需要的例如“文章收藏夹”、“会员功能”之类的单独功能页面，这个方法用于提供这些页面的路由。

文档：

• https://developer.wordpress.org/themes/basics/template-hierarchy/

了解WordPress模板系统：

• https://developer.wordpress.org/files/2014/10/template-hierarchy.png

 

其他组件的一些说明

Admin_Custom：顾名思义，这个类用于自定义WP后台界面的一些显示，去除仪表盘以及其他地方的一些用不到的功能。

Modify_TinyMCE：经典编辑器增强插件，这个类提供了编辑器按钮重排、增加了表格支持、和自动上传图片支持。

Widget_Cache：小工具缓存，来自 widget-output-cache 插件，但是这里重写了一下调用方法。

Record_Visitors：阅读量计数器，用于在文章meta中保存当前文章的点击量，功能和views插件一样，但是不包含调用函数，以下是AIYA-CMS主题的调用方法。

//获取文章访问量
function get_post_views($post_id = 0)
{
    if (!$post_id) {
        global $post;
        $post_id = $post->ID;
    }

    $views = get_post_meta($post_id, 'views', true);

    if ($views > 0) {
        //计算为千位
        if ($views >= 1000) {
            return round($views / 1000, 2) . 'K';
        } else {
            return $views;
        }
    } else {
        return '0';
    }
};

Local_Avatars：本地化头像组件，允许指定用户（作者及以上权限）在后台个人资料页面中上传头像来替代，调用头像需要替代主题中的get_avatar()方法，以下是AIYA-CMS主题的调用方法。

//获取本地头像
function get_local_avatar($id_or_email, $size = '96', $default = '', $alt = false)
{
    global $local_avatars;

    $avatar = $local_avatars->get_avatar('', $id_or_email, $size, $default, $alt);

    if (empty($avatar))
        $avatar = get_avatar($id_or_email, $size, $default, $alt);

    return $avatar;
}

 

注意事项 / 一些使用和增加功能的参考

以下简要说明这些功能组件的实例化方法：

$Setup = new AYA_Theme_Setup();
$Setup->action(['Class类名'] => 'Class参数');

所有的方法都是这样把参数传入class然后实例化class。换句话说，这是一个类似于插件方式的机制，但究极简化版。因为既没有回调也没有额外的安全检查。

Tips：虽然最开始设计的时候是考虑回调了的，但是WP已经有一个插件系统在拖后腿了，再额外增加一些别的检测和验证加载就更慢了，但是不做验证的话回调又没有意义，于是干脆什么都没做。（）

以及，

上面的DEMO代码中提供了两种运行方式，一种是 action() ，另一种是 action_register() 两种方法没有区别，但是 action_register() 需要在最后通过 action_all()  来触发。

这么设计的目的是为了实现统一调用，因为WP的机制是在初始化的时候先加载 function.php ，所以只需要让 action_all() 出现在 function.php 的里即可，其他的部分可以放在更容查找和易阅读的地方。

以及的以及，

上面的DEMO代码中的文件加载是通过 include_plugins() 方法自动加载项目子目录里的所有文件。

因为这种自动include方式实际上不是很安全，所以，请勿在被加载的目录下随意放置可以被直接运行的代码，除非你明确知道自己在干嘛。