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方式实际上不是很安全,所以,请勿在被加载的目录下随意放置可以被直接运行的代码,除非你明确知道自己在干嘛。

THE END
夜华子酱我知道你很急,但你先别急