kate522/wordpress-theme-aksrt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(widgets): FAQ structure with badges preview and doc_links

Browse Source 
Replace bare details list with produck-style summary cards, rotating
color badges, answer preview, doc links list, and help CTA; admin empty.
This commit is contained in:
kate522
2026-07-21 08:19:06 +08:00
parent 0d4d5166b4
commit fb4c047780
1 changed files with 213 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/AKSRT/Widgets/WidgetFaq.php
+213 -48
View File
@@ -1,6 +1,6 @@
<?php
/**
* FAQ accordion (zibll zib_widget_faq lite).
* FAQ accordion (zibll zib_widget_faq / produck-wid-faq structure parity).
*
* @package AKSRT
*/
@@ -11,12 +11,14 @@ defined('ABSPATH') || exit;
class WidgetFaq extends \WP_Widget {
private const BADGE_TONES = ['purple', 'pink', 'green', 'orange', 'blue'];
public function __construct() {
parent::__construct(
'aksrt_faq',
esc_html__('AKSRT 常见问题', 'aksrt'),
[
'description' => esc_html__('可折叠 FAQ 列表，支持搜索框与侧栏文档卡。', 'aksrt'),
'description' => esc_html__('FAQ 摘要卡 + 文档链接列表 + 帮助 CTA。', 'aksrt'),
'classname' => 'widget_aksrt_faq',
]
);
@@ -25,6 +27,12 @@ class WidgetFaq extends \WP_Widget {
public function widget($args, $instance): void {
$faqs = $this->normalize_faqs($instance['faqs'] ?? []);
if (!$faqs) {
if (current_user_can('manage_options')) {
echo $args['before_widget']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
echo '<div class="c-red muted-box mb20"><b>' . esc_html__('常见问题解答：', 'aksrt') . '</b>' .
esc_html__('请添加至少一条问题', 'aksrt') . '</div>';
echo $args['after_widget']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
}
return;
}
@@ -35,23 +43,60 @@ class WidgetFaq extends \WP_Widget {
}
$uid = 'aksrt-faq-' . esc_attr($this->id);
echo '<div class="aksrt-faq" id="' . $uid . '">';
echo '<section class="aksrt-faq produck-wid-faq-block" id="' . $uid . '">';
if (!empty($instance['search_s'])) {
$ph = (string) ($instance['search_placeholder'] ?? __('搜索问题…', 'aksrt'));
echo '<form class="aksrt-faq__search" method="get" action="' . esc_url(home_url('/')) . '" role="search">';
echo '<input type="search" name="s" class="aksrt-faq__search-input" placeholder="' . esc_attr($ph) . '" />';
echo '<button type="submit" class="aksrt-faq__search-btn">' . esc_html((string) ($instance['search_btn_text'] ?? __('搜索', 'aksrt'))) . '</button>';
echo '</form>';
$btn = (string) ($instance['search_btn_text'] ?? __('搜索', 'aksrt'));
echo '<header class="aksrt-faq__head produck-faq-head">';
echo '<form class="aksrt-faq__search search-form" method="get" action="' . esc_url(home_url('/')) . '" role="search">';
echo '<div class="aksrt-faq__search-wrap produck-faq-search">';
echo '<span class="aksrt-faq__search-icon" aria-hidden="true"><i class="fas fa-search"></i></span>';
echo '<input type="search" name="s" class="aksrt-faq__search-input produck-faq-search-input" placeholder="' . esc_attr($ph) . '" autocomplete="off" />';
echo '<button type="submit" class="aksrt-faq__search-btn produck-faq-search-btn"><span>' . esc_html($btn) . '</span></button>';
echo '</div></form></header>';
}
echo '<div class="aksrt-faq__list">';
$doc_title = trim((string) ($instance['doc_title'] ?? ''));
$doc_desc = trim((string) ($instance['doc_desc'] ?? ''));
$doc_icon = sanitize_text_field((string) ($instance['doc_icon'] ?? 'fas fa-book'));
$doc_links = $this->normalize_doc_links($instance['doc_links'] ?? []);
$help_title = trim((string) ($instance['help_title'] ?? ''));
$help_sub = trim((string) ($instance['help_subtitle'] ?? ''));
$help_icon = sanitize_text_field((string) ($instance['help_icon'] ?? 'fas fa-graduation-cap'));
$help_url = esc_url_raw(trim((string) ($instance['help_btn_url'] ?? '')));
$help_btn = trim((string) ($instance['help_btn_text'] ?? ''));
$has_doc = ($doc_title !== '' || $doc_desc !== '' || $doc_links);
$has_help = ($help_title !== '' || $help_sub !== '' || ($help_btn !== '' && $help_url !== ''));
$main_cls = 'aksrt-faq__main produck-faq-main';
if (!$has_doc && !$has_help) {
$main_cls .= ' is-full';
}
echo '<div class="' . esc_attr($main_cls) . '">';
echo '<div class="aksrt-faq__list produck-faq-list-col">';
$n = 0;
foreach ($faqs as $f) {
$n++;
$num = str_pad((string) $n, 2, '0', STR_PAD_LEFT);
echo '<details class="aksrt-faq__item">';
echo '<summary class="aksrt-faq__q"><span class="aksrt-faq__num">' . esc_html($num) . '</span><span class="aksrt-faq__qtext">' . esc_html($f['question']) . '</span></summary>';
$num = str_pad((string) $n, 2, '0', STR_PAD_LEFT);
$tone = self::BADGE_TONES[($n - 1) % count(self::BADGE_TONES)];
$preview = $f['answer'] !== '' ? wp_strip_all_tags($f['answer']) : '';
if ($preview !== '') {
$preview = wp_trim_words($preview, 28);
}
echo '<details class="aksrt-faq__item produck-faq-summary">';
echo '<summary class="aksrt-faq__summary">';
echo '<span class="aksrt-faq__badge produck-faq-badge tone-' . esc_attr($tone) . '">' . esc_html($num) . '</span>';
echo '<span class="aksrt-faq__qblock">';
echo '<span class="aksrt-faq__q produck-faq-q">' . esc_html($f['question']) . '</span>';
if ($preview !== '') {
echo '<span class="aksrt-faq__preview muted-2-color">' . esc_html($preview) . '</span>';
}
echo '</span>';
echo '<i class="fas fa-angle-down aksrt-faq__chevron" aria-hidden="true"></i>';
echo '</summary>';
if ($f['answer'] !== '') {
echo '<div class="aksrt-faq__a">' . wp_kses_post(wpautop($f['answer'])) . '</div>';
}
@@ -59,41 +104,78 @@ class WidgetFaq extends \WP_Widget {
}
echo '</div>';
$doc_title = trim((string) ($instance['doc_title'] ?? ''));
$doc_desc = trim((string) ($instance['doc_desc'] ?? ''));
$help_title = trim((string) ($instance['help_title'] ?? ''));
$help_url = esc_url_raw(trim((string) ($instance['help_btn_url'] ?? '')));
$help_btn = trim((string) ($instance['help_btn_text'] ?? ''));
if ($doc_title !== '' || $help_title !== '') {
echo '<div class="aksrt-faq__aside">';
if ($doc_title !== '') {
echo '<div class="aksrt-faq__doc"><strong>' . esc_html($doc_title) . '</strong>';
if ($has_doc || $has_help) {
echo '<aside class="aksrt-faq__aside produck-faq-aside">';
if ($has_doc) {
echo '<div class="aksrt-faq__doc produck-faq-doc-card zib-widget">';
echo '<div class="aksrt-faq__doc-head">';
if ($doc_icon !== '') {
echo '<span class="aksrt-faq__doc-ico"><i class="' . esc_attr($doc_icon) . '" aria-hidden="true"></i></span>';
}
echo '<div>';
if ($doc_title !== '') {
echo '<h3 class="aksrt-faq__doc-title">' . esc_html($doc_title) . '</h3>';
}
if ($doc_desc !== '') {
echo '<p>' . esc_html($doc_desc) . '</p>';
echo '<p class="aksrt-faq__doc-desc muted-2-color">' . nl2br(esc_html($doc_desc)) . '</p>';
}
echo '</div></div>';
if ($doc_links) {
echo '<ul class="aksrt-faq__doc-list produck-faq-doc-list">';
foreach ($doc_links as $dl) {
$durl = $dl['url'] !== '' ? $dl['url'] : '#';
echo '<li class="aksrt-faq__doc-li">';
echo '<a class="aksrt-faq__doc-a" href="' . esc_url($durl) . '">';
if ($dl['icon'] !== '') {
echo '<span class="aksrt-faq__doc-li-ico"><i class="' . esc_attr($dl['icon']) . '" aria-hidden="true"></i></span>';
}
echo '<span class="aksrt-faq__doc-li-mid">';
echo '<span class="aksrt-faq__doc-li-title">' . esc_html($dl['title']);
if ($dl['tag'] !== '') {
echo ' <span class="badg badg-sm c-red ml6">' . esc_html($dl['tag']) . '</span>';
}
echo '</span>';
if ($dl['desc'] !== '') {
echo '<span class="aksrt-faq__doc-li-desc muted-2-color">' . esc_html($dl['desc']) . '</span>';
}
echo '</span>';
$go = $dl['btn_text'] !== '' ? $dl['btn_text'] : __('查看教程', 'aksrt');
echo '<span class="aksrt-faq__doc-go">' . esc_html($go) . ' <i class="fas fa-angle-right" aria-hidden="true"></i></span>';
echo '</a></li>';
}
echo '</ul>';
}
echo '</div>';
}
if ($help_title !== '') {
echo '<div class="aksrt-faq__help"><strong>' . esc_html($help_title) . '</strong>';
$sub = trim((string) ($instance['help_subtitle'] ?? ''));
if ($sub !== '') {
echo '<p>' . esc_html($sub) . '</p>';
if ($has_help) {
echo '<div class="aksrt-faq__help produck-faq-help-card">';
echo '<div class="aksrt-faq__help-top">';
if ($help_icon !== '') {
echo '<span class="aksrt-faq__help-ico"><i class="' . esc_attr($help_icon) . '" aria-hidden="true"></i></span>';
}
echo '<div class="aksrt-faq__help-text">';
if ($help_title !== '') {
echo '<h3 class="aksrt-faq__help-title">' . esc_html($help_title) . '</h3>';
}
if ($help_sub !== '') {
echo '<p class="aksrt-faq__help-sub">' . nl2br(esc_html($help_sub)) . '</p>';
}
echo '</div></div>';
if ($help_btn !== '' && $help_url !== '') {
echo '<a class="aksrt-faq__help-btn" href="' . esc_url($help_url) . '">' . esc_html($help_btn) . '</a>';
echo '<a class="aksrt-faq__help-btn" href="' . esc_url($help_url) . '">' . esc_html($help_btn) . ' <i class="fas fa-arrow-right" aria-hidden="true"></i></a>';
}
echo '</div>';
}
echo '</div>';
echo '</aside>';
}
echo '</div>';
echo '</div></section>';
echo $args['after_widget']; // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
}
/**
* @param mixed $raw
* @return array<int, array{question:string,answer:string}>
* @return array<int, array{question:string,answer:string,category:string}>
*/
private function normalize_faqs($raw): array {
if (is_string($raw)) {
@@ -112,11 +194,10 @@ class WidgetFaq extends \WP_Widget {
if ($q === '') {
continue;
}
$a = (string) ($row['answer'] ?? $row['a'] ?? '');
// Allow basic HTML in answers after kses on output.
$out[] = [
'question' => $q,
'answer' => wp_kses_post($a),
'answer' => wp_kses_post((string) ($row['answer'] ?? $row['a'] ?? '')),
'category' => sanitize_key((string) ($row['category'] ?? 'all')),
];
if (count($out) >= 30) {
break;
@@ -125,39 +206,120 @@ class WidgetFaq extends \WP_Widget {
return $out;
}
/**
* @param mixed $raw
* @return array<int, array{title:string,url:string,desc:string,icon:string,tag:string,btn_text:string}>
*/
private function normalize_doc_links($raw): array {
if (is_string($raw)) {
$decoded = json_decode($raw, true);
$raw = is_array($decoded) ? $decoded : [];
}
if (!is_array($raw)) {
return [];
}
$out = [];
foreach ($raw as $row) {
if (!is_array($row)) {
continue;
}
$title = sanitize_text_field((string) ($row['title'] ?? ''));
$url = esc_url_raw(trim((string) ($row['url'] ?? $row['link'] ?? '')));
if ($title === '' && $url === '') {
continue;
}
$out[] = [
'title' => $title,
'url' => $url,
'desc' => sanitize_text_field((string) ($row['desc'] ?? '')),
'icon' => sanitize_text_field((string) ($row['icon'] ?? '')),
'tag' => sanitize_text_field((string) ($row['tag'] ?? '')),
'btn_text' => sanitize_text_field((string) ($row['btn_text'] ?? '')),
];
if (count($out) >= 12) {
break;
}
}
return $out;
}
public function form($instance): void {
$faqs = is_string($instance['faqs'] ?? null)
? (string) $instance['faqs']
: wp_json_encode($this->normalize_faqs($instance['faqs'] ?? []), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$faqs = $this->normalize_faqs($instance['faqs'] ?? []);
if (!$faqs) {
$faqs = [
['question' => '', 'answer' => '', 'category' => 'all'],
['question' => '', 'answer' => '', 'category' => 'all'],
];
}
$doc_links = $this->normalize_doc_links($instance['doc_links'] ?? []);
if (!$doc_links) {
$doc_links = [
['title' => '', 'url' => '', 'desc' => '', 'icon' => 'fas fa-file-alt', 'tag' => '', 'btn_text' => ''],
];
}
?>
<p>
<label><?php esc_html_e('标题', 'aksrt'); ?>
<input class="widefat" type="text" name="<?php echo esc_attr($this->get_field_name('title')); ?>" value="<?php echo esc_attr((string) ($instance['title'] ?? '')); ?>">
</label>
</p>
<p>
<label><?php esc_html_e('FAQ JSON', 'aksrt'); ?>
<textarea class="widefat" rows="8" name="<?php echo esc_attr($this->get_field_name('faqs')); ?>" placeholder='[{"question":"如何付费？","answer":"进入用户中心…"}]'><?php echo esc_textarea((string) $faqs); ?></textarea>
</label>
</p>
<p>
<label><input type="checkbox" name="<?php echo esc_attr($this->get_field_name('search_s')); ?>" value="1" <?php checked(!empty($instance['search_s'])); ?>> <?php esc_html_e('显示搜索框', 'aksrt'); ?></label>
</p>
<p>
<label><?php esc_html_e('文档卡标题', 'aksrt'); ?>
<label><?php esc_html_e('搜索占位', 'aksrt'); ?>
<input class="widefat" type="text" name="<?php echo esc_attr($this->get_field_name('search_placeholder')); ?>" value="<?php echo esc_attr((string) ($instance['search_placeholder'] ?? __('搜索问题…', 'aksrt'))); ?>">
</label>
</p>
<p>
<label><?php esc_html_e('搜索按钮', 'aksrt'); ?>
<input class="widefat" type="text" name="<?php echo esc_attr($this->get_field_name('search_btn_text')); ?>" value="<?php echo esc_attr((string) ($instance['search_btn_text'] ?? __('搜索', 'aksrt'))); ?>">
</label>
</p>
<p>
<label><?php esc_html_e('FAQ JSON', 'aksrt'); ?>
<textarea class="widefat" rows="6" name="<?php echo esc_attr($this->get_field_name('faqs')); ?>" placeholder='[{"question":"…","answer":"…"}]'><?php echo esc_textarea((string) wp_json_encode($faqs, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)); ?></textarea>
</label>
</p>
<hr>
<p><strong><?php esc_html_e('文档卡', 'aksrt'); ?></strong></p>
<p>
<label><?php esc_html_e('文档标题', 'aksrt'); ?>
<input class="widefat" type="text" name="<?php echo esc_attr($this->get_field_name('doc_title')); ?>" value="<?php echo esc_attr((string) ($instance['doc_title'] ?? '')); ?>">
</label>
</p>
<p>
<label><?php esc_html_e('文档卡描述', 'aksrt'); ?>
<input class="widefat" type="text" name="<?php echo esc_attr($this->get_field_name('doc_desc')); ?>" value="<?php echo esc_attr((string) ($instance['doc_desc'] ?? '')); ?>">
<label><?php esc_html_e('文档描述', 'aksrt'); ?>
<textarea class="widefat" rows="2" name="<?php echo esc_attr($this->get_field_name('doc_desc')); ?>"><?php echo esc_textarea((string) ($instance['doc_desc'] ?? '')); ?></textarea>
</label>
</p>
<p>
<label><?php esc_html_e('帮助卡标题', 'aksrt'); ?>
<label><?php esc_html_e('文档图标 class', 'aksrt'); ?>
<input class="widefat" type="text" name="<?php echo esc_attr($this->get_field_name('doc_icon')); ?>" value="<?php echo esc_attr((string) ($instance['doc_icon'] ?? 'fas fa-book')); ?>">
</label>
</p>
<p>
<label><?php esc_html_e('文档链接 JSON', 'aksrt'); ?>
<textarea class="widefat" rows="5" name="<?php echo esc_attr($this->get_field_name('doc_links')); ?>" placeholder='[{"title":"教程","url":"#","desc":"","icon":"fas fa-file","tag":"热门","btn_text":"查看教程"}]'><?php echo esc_textarea((string) wp_json_encode($doc_links, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES)); ?></textarea>
</label>
</p>
<hr>
<p><strong><?php esc_html_e('帮助卡', 'aksrt'); ?></strong></p>
<p>
<label><?php esc_html_e('帮助标题', 'aksrt'); ?>
<input class="widefat" type="text" name="<?php echo esc_attr($this->get_field_name('help_title')); ?>" value="<?php echo esc_attr((string) ($instance['help_title'] ?? '')); ?>">
</label>
</p>
<p>
<label><?php esc_html_e('帮助副标题', 'aksrt'); ?>
<textarea class="widefat" rows="2" name="<?php echo esc_attr($this->get_field_name('help_subtitle')); ?>"><?php echo esc_textarea((string) ($instance['help_subtitle'] ?? '')); ?></textarea>
</label>
</p>
<p>
<label><?php esc_html_e('帮助图标 class', 'aksrt'); ?>
<input class="widefat" type="text" name="<?php echo esc_attr($this->get_field_name('help_icon')); ?>" value="<?php echo esc_attr((string) ($instance['help_icon'] ?? 'fas fa-graduation-cap')); ?>">
</label>
</p>
<p>
<label><?php esc_html_e('帮助按钮文案', 'aksrt'); ?>
<input class="widefat" type="text" name="<?php echo esc_attr($this->get_field_name('help_btn_text')); ?>" value="<?php echo esc_attr((string) ($instance['help_btn_text'] ?? '')); ?>">
@@ -174,14 +336,17 @@ class WidgetFaq extends \WP_Widget {
public function update($new_instance, $old_instance): array {
return [
'title' => sanitize_text_field((string) ($new_instance['title'] ?? '')),
'faqs' => $this->normalize_faqs($new_instance['faqs'] ?? []),
'search_s' => !empty($new_instance['search_s']) ? 1 : 0,
'search_placeholder' => sanitize_text_field((string) ($new_instance['search_placeholder'] ?? '')),
'search_btn_text' => sanitize_text_field((string) ($new_instance['search_btn_text'] ?? '')),
'faqs' => $this->normalize_faqs($new_instance['faqs'] ?? []),
'doc_title' => sanitize_text_field((string) ($new_instance['doc_title'] ?? '')),
'doc_desc' => sanitize_text_field((string) ($new_instance['doc_desc'] ?? '')),
'doc_desc' => sanitize_textarea_field((string) ($new_instance['doc_desc'] ?? '')),
'doc_icon' => sanitize_text_field((string) ($new_instance['doc_icon'] ?? '')),
'doc_links' => $this->normalize_doc_links($new_instance['doc_links'] ?? []),
'help_title' => sanitize_text_field((string) ($new_instance['help_title'] ?? '')),
'help_subtitle' => sanitize_text_field((string) ($new_instance['help_subtitle'] ?? '')),
'help_subtitle' => sanitize_textarea_field((string) ($new_instance['help_subtitle'] ?? '')),
'help_icon' => sanitize_text_field((string) ($new_instance['help_icon'] ?? '')),
'help_btn_text' => sanitize_text_field((string) ($new_instance['help_btn_text'] ?? '')),
'help_btn_url' => esc_url_raw(trim((string) ($new_instance['help_btn_url'] ?? ''))),
];