MorphSwift 开发者文档

概览

MorphSwift 文档中心面向站点管理员与运营人员，帮助完成行业模板选型、前台短代码放置、小工具配置，以及 SwiftCart、MorphSwift Pro、MorphKits 的协同展示。

产品生态一览

推荐阅读路径

1. 首次部署：#quick-start-setup → #ms-shortcodes → #swiftcart-shortcodes
2. 只做商城：#swiftcart-overview → #swiftcart-shortcodes → #morphkits-shop-ui
3. 升级 Pro：#pro-overview → #composer-overview → #composer-embed-publish
4. 组件选型：#morphkits-overview → #mk-preview → #ms-navbar-footer
5. 字段驱动页面：#ms-field-guide → #ms-shortcodes

角色分工建议

文档内链使用章节锚点 ID（如 #ms-shortcodes），与侧栏导航一致。

上线前验收

• 行业模板与固定页 slug 无冲突
• 商店系统页 shop / cart / checkout 可访问
• 文档 CPT 已发布避免空态
• Pro 许可有效时 Composer 入口可见

常见问题

能否只读某一章？

可以，侧栏点击或地址栏 #章节-id 直达。

与后台帮助重复吗？

前台文档聚焦访客可见配置；后台面板含更多运维项。

需要先装哪些扩展？

商城场景需 SwiftCart；组件皮肤需 MorphKits；Composer 需 Pro。

短代码放哪里？

页面区块、小工具「短代码」或 Composer 嵌入块均可。

相关链接

• 站点与页面配置
• MorphSwift 短代码
• Pro 概览
• Composer 概览

站点与页面配置

本章合并行业选型、template-types 页面映射与快照验收，帮助一次性完成站点骨架。

行业与模板包选型

切换行业包后请重新执行模板快照，避免旧 slug 与新区块残留。

固定页与短代码映射

配置步骤

1. 在 MorphSwift 行业设置中选择 template-types 包并保存
2. 执行「生成固定页 / 快照」使 slug 与模板文件对齐
3. 逐页打开古腾堡，插入本章与 #ms-shortcodes 中的短代码
4. 在 #ms-sidebars-widgets 中拖入 SwiftCart 目录小工具（可选）
5. 发布后在隐身窗口验收 shop / cart / checkout 链路

快照与回滚要点

快照会记录当前行业模板的页面清单与区块占位；回滚前请导出页面内容。大型改版建议先在 staging 域名验证 #mk-preview 组件。

常见问题

slug 已被占用怎么办？

先改名冲突页面或删除草稿，再重新执行快照。

能否混用两个行业包？

不建议；字段与侧边栏注册随行业包变化。

文档页空白？

确认文档 CPT 已 seed；空 CPT 仅显示空态。

订阅页无价格？

检查 #pro-membership-license 许可与计划配置。

template-types 目录约定

行业包页面文件位于 template-types/templates/{行业}/{变体}/ 下，文件名 page-{slug} 与 WordPress 固定页 slug 对齐。例如 ecommerce/theme/page-shop 对应 slug shop。Composer 或古腾堡正文中的短代码写在页面内容区，Hero 与侧栏结构仍由 template-types 模板片段提供。

相关链接

• 短代码索引
• SwiftCart 启用
• 侧边栏

MorphSwift 短代码

本章仅收录 MorphSwift 主题 ms_* 短代码（不含 mk_* 与 sc_*）。属性表与示例一一对应。

短代码总览

[ms_field] 自定义字段

读取后台字段模块注册的键，支持文章与分类法。

<?php echo do_shortcode('[ms_field]'); ?>

[ms_contact_form] 联系表单

渲染联系表单；结账布局下可显示 checkout 模式表单。

<?php echo do_shortcode('[ms_contact_form]'); ?>

[ms_breadcrumb] 面包屑

输出面包屑 trail。

<?php echo do_shortcode('[ms_breadcrumb]'); ?>

[ms_navbar_cart] 导航栏购物车

导航栏组件，variant 控制展示形态。

<?php echo do_shortcode('[ms_navbar_cart]'); ?>

[ms_navbar_search] 导航栏搜索

导航栏组件，variant 控制展示形态。

<?php echo do_shortcode('[ms_navbar_search]'); ?>

[ms_navbar_login] 导航栏登录

导航栏组件，variant 控制展示形态。

<?php echo do_shortcode('[ms_navbar_login]'); ?>

[ms_theme_pricing] 订阅定价表

无属性；输出订阅计划卡片，受许可与计划配置影响。

<?php echo do_shortcode('[ms_theme_pricing]'); ?>

已弃用图库短代码

[ms_case_gallery] 与 [ms_spaces_gallery] 仍可用但不再推荐，请改用古腾堡图库区块。

常见问题

短代码不渲染？

确认键名拼写与字段已保存；查看页面是否启用对应模板。

ms_field 为空？

检查 post_id/term_id 是否指向有值的对象。

导航组件不显示？

确认 header 模板已插入 ms_navbar_* 且 MorphKits 包已选。

定价表空白？

见 #pro-membership-license。

相关链接

• 字段工作流
• 页眉页脚
• 页面放置

自定义字段用法

自定义字段在后台「字段」模块注册后，可在模板与短代码中复用。本章说明 UI 工作流与 ms_field 示例。

后台工作流

1. 新建字段组并绑定文章类型或分类法
2. 在编辑页填写字段值并更新
3. 在页面插入 [ms_field key="your_key"]
4. 需要分类法字段时同时传 term_id 与 taxonomy

示例

<?php echo do_shortcode('[ms_field key="hero_title"]'); ?>

<?php echo do_shortcode('[ms_field key="cover" size="large"]'); ?>

<?php echo do_shortcode('[ms_field key="badge" term_id="12" taxonomy="product_cat" return="html"]'); ?>

完整属性说明见 #ms-shortcodes 中 [ms_field] 属性表。

常见问题

能否一次输出多个字段？

每标签一字读；列表页可多次插入或使用区块模式。

图片字段尺寸？

size 传 thumbnail|medium|large|full。

未保存就预览？

预览 URL 可能读不到草稿 meta，请先保存。

与 Composer 关系？

Composer 可嵌入含 ms_field 的 HTML 块。

字段类型与输出

字段组 location 绑定错误时，编辑页看不到输入框，前台 ms_field 也会为空。

相关链接

• 属性表
• 发布清单

小工具与侧边栏

MorphSwift 注册四个常用侧边栏，可在「外观 → 小工具」拖放模块。

拖放流程

1. 打开小工具屏幕并选择目标侧边栏
2. 将「SwiftCart 商品目录」或「自定义 HTML」拖入
3. 保存后刷新前台对应模板
4. 目录索引字段说明见 #swiftcart-catalog-widget

常见问题

侧边栏不显示？

确认模板调用了 dynamic_sidebar 且 ID 拼写正确。

首页热课位空白？

检查 learning 行业模板是否启用 ms-home-hot-courses。

能否仅移动端隐藏？

使用主题响应式类或 Composer 条件块。

页脚列数？

由 ms-footer-widgets 内小工具数量与 CSS 栅格决定。

Composer widget_area 引用

在 Composer DOM 树中，widget_area 节点 sidebar 属性填 msp-page-sidebar 等 ID，发布后会渲染该侧栏内已拖入的小工具。与古腾堡「短代码」小工具互不冲突，但同一 URL 避免重复输出。

相关链接

• 目录小工具
• 模板映射

导航栏与页脚

页眉导航通过 ms_navbar_* 短代码组合购物车、搜索、登录入口；页脚区块通常走 ms-footer-widgets。

ms_navbar_* 组合

• 在 header 模板或 Composer 页眉区插入 ms_navbar_search / cart / login
• variant 控制图标或行内布局
• 与 MorphKits 导航皮肤联用时见 #mk-preview

MorphKits 包选择

在 MorphKits 组件管理中选择 navbar 变体包（如 navbar-glass），前台会自动加载对应 CSS。预览各变体请跳转 #mk-preview。

<?php echo do_shortcode('[ms_navbar_search variant="icon"]'); ?>

<?php echo do_shortcode('[ms_navbar_cart variant="inline"]'); ?>

常见问题

登录面板不弹出？

检查是否冲突的 overlay 样式；尝试 variant="panel-row"。

购物车数量不更新？

确认 SwiftCart 已启用且脚本加载完成。

能否隐藏搜索？

不插入 ms_navbar_search 即可。

页脚版权？

使用 ms-footer-widgets 中的文本小工具。

页眉布局建议

页脚结构

页脚多列内容通过 ms-footer-widgets 维护：版权、备案、社交链接、订阅表单。若使用 MorphKits footer 变体，先在 #mk-preview 预览再启用包。

相关链接

• 组件预览
• 属性表
• 导航变体

SwiftCart 概览

SwiftCart 提供商品、购物车、结账与订单。启用后需配置 shop/cart/checkout 固定页。

启用步骤

1. 在插件列表启用 SwiftCart
2. 执行固定页创建或使用 #quick-start-setup 快照
3. 在 shop 页放置 [sc_shop]，cart/checkout 放置对应短代码
4. 可选：#swiftcart-catalog-widget 首页目录

页面片段

系统页与 URL

SwiftCart 默认创建 slug 为 shop、cart、checkout 的固定页，菜单与面包屑应指向这些 URL。

未启用 SwiftCart 时，[sc_shop] 等短代码可能显示占位或空内容。

常见问题

如何重建系统页？

SwiftCart 商店设置中的系统页修复入口。

能否改 slug？

可以，但需同步菜单、短代码所在页与 sc_get_page_url 配置。

与 MorphKits？

商店 UI 变体见 #morphkits-shop-ui。

订单邮件？

在 SwiftCart 后台通知设置中配置。

相关链接

• 属性大全
• 流程页

商店短代码

SwiftCart 前台短代码均以 sc_ 开头。下列属性表与插件注册默认值一致。

[sc_shop] 商店列表

商店主列表页核心短代码。

<?php echo do_shortcode('[sc_shop]'); ?>

[sc_products] 商品列表

任意页面商品网格。

<?php echo do_shortcode('[sc_products]'); ?>

[sc_cart] 购物车

购物车页；通常无属性。

<?php echo do_shortcode('[sc_cart]'); ?>

[sc_checkout] 结账

结账页；通常无属性。

<?php echo do_shortcode('[sc_checkout]'); ?>

[sc_product_detail] 商品详情

单品详情组合块。

<?php echo do_shortcode('[sc_product_detail]'); ?>

常见问题

sc_shop chronos 布局？

layout 与 MorphKits shop-filter 联用见 #morphkits-shop-ui。

列表为空？

检查 empty_class / empty_text 或商品是否发布。

hydrate 是什么？

控制是否加载卡片交互脚本，card 为默认。

详情 id 无效？

留空时尝试当前文关联商品。

相关链接

• 详情章节
• 商店 UI
• 结账流程

商品目录小工具

商品目录由共享 products 模板渲染。主题 template 或 Composer 代码岛通过变量键值控制输出；ms_swiftcart_catalog 小工具仅是 display_type=section 的 WordPress 封装。本章聚焦代码变量与短代码对照；侧栏放置见 #ms-sidebars-widgets。

渲染入口

1. 主题 template 或 Composer 代码岛：向 products 模板传入变量数组
2. 小工具等价：display_type=section，字段见 instance 映射表
3. 短代码等价：[sc_shop]、[sc_products …] 走同一渲染管线

display_source / display_type 总表

display_source 展示来源

display_type 输出模式

小工具 instance → 模板变量

七字段映射为 products 模板变量，仅作对照。

代码用法

section 分区目录

display_type: section
section: home_featured
display_source: shop
card_style: shop

参考：行业 template 内嵌区块。短代码：无直接等价。

shop_page 商店完整页

display_source: shop
display_type: shop_page
pagination: true

参考：page-shop。短代码：[sc_shop]

ids 指定商品

display_type: ids
product_ids: 12,34,56
count: 3
display_source: shop

参考：page-services。短代码：[sc_products ids="12,34,56" limit="3"]

categories 按分类

display_type: categories
cat_id: 5
count: 6

短代码：[sc_products category="5" limit="6"]

home 首页 starter

display_type: home
display_source: shop
count: 3

参考：index 首页。可回退为 display_type=ids。

template 展示模式

display_source: template
display_type: section
section: catalog
show_sku: false

小工具等价：取消 follow_shop_display 并调整 show_*。

products_catalog 数据来源

display_type=section 时读取行业 template 的 products_catalog 配置。

与短代码对照

常见问题

网格为空？

检查 SwiftCart、商品发布与 section limit。

条数不对？

home_featured 与 catalog 使用不同 limit。

shop_page 与 [sc_shop]？

同一渲染模式，写法不同。

小工具能否选 ids？

不能；请用短代码或 template 变量。

layout 变 shop？

旧值已迁移；需固定样式请重选变体。

show_block_preview 无效？

仅在 display_source=template 时由变量控制。

相关链接

• 短代码属性
• SwiftCart 概览

购物车与结账

购物链路依赖 shop → cart → checkout 三个 slug 页面。

slug 必须与 SwiftCart 设置一致；改名后需同步菜单链接。

<?php echo do_shortcode('[sc_cart]'); ?>

<?php echo do_shortcode('[sc_checkout]'); ?>

购物流程

1. 用户在 shop 页 [sc_shop] 加购
2. 跳转 /cart/ 渲染 [sc_cart] 修改数量
3. 点击去结账进入 /checkout/ 的 [sc_checkout]
4. 支付完成后查看订单确认页或邮件

chronos 布局下 cart 与 checkout 由 MorphKits 皮肤包裹，见 #morphkits-shop-ui。

常见问题

购物车为空？

确认会话 cookie 与 SwiftCart 前台脚本已加载。

结账页缺支付方式？

SwiftCart 支付网关设置中启用。

优惠码在哪？

cart 页 sc_cart 模板内优惠券表单。

slug 404？

重建系统页或检查固定页是否发布。

相关链接

• 固定页
• 短代码

产品详情

单品页常用 [sc_product_detail id="123"] 组合标题、图库、规格与购买区。

<?php echo do_shortcode('[sc_product_detail id="123" gallery="1" actions="1"]'); ?>

全部属性见 #swiftcart-shortcodes 中 sc_product_detail 表。

常见问题

能否只显示图库？

设置 title="0" description="0" 仅留 gallery="1"。

规格表标题？

table_title 传字符串。

与模板 single-product 关系？

可二选一或模板内再嵌短代码。

多商品对比？

使用多个 sc_product_detail 或 sc_products。

属性速查

<?php echo do_shortcode('[sc_product_detail id="42" title="1" price="1" actions="1"]'); ?>

相关链接

• 属性表

MorphKits 概览

MorphKits 管理组件包生命周期：安装、启用变体、在前台通过 mk_preview 或 SwiftCart 布局引用。

六大组件域

组件预览的权威参数见 #mk-preview。

包生命周期

1. 在 MorphKits 市场或 bundled 列表安装组件包
2. 启用目标 variant（如 navbar-glass）
3. 用 [mk_preview] 在文档或草稿页验收
4. 应用到 SwiftCart 布局或主题 header/footer
5. 升级包版本后重复预览以防样式破坏

shop-filter 与 cart-popup 变体直接影响商店交互，请在低流量时段切换。

相关链接

• 预览短代码
• 导航

mk_preview 短代码

mk_preview 是组件/变体/尺寸的唯一权威文档章节。

[mk_preview] 组件预览

七大组件示例

<?php echo do_shortcode('[mk_preview component="product-card" variant="default" size="stage"]'); ?>

<?php echo do_shortcode('[mk_preview component="navbar" variant="navbar-glass" size="stage"]'); ?>

<?php echo do_shortcode('[mk_preview component="footer" variant="default" size="stage"]'); ?>

<?php echo do_shortcode('[mk_preview component="cart-popup" variant="cart-popup-drawer" size="stage"]'); ?>

<?php echo do_shortcode('[mk_preview component="shop-filter" variant="shop-filter-chronos" size="stage"]'); ?>

<?php echo do_shortcode('[mk_preview component="cart-page" variant="default" size="stage"]'); ?>

<?php echo do_shortcode('[mk_preview component="checkout-page" variant="default" size="stage"]'); ?>

常见问题

size tile 与 stage？

tile 适合侧栏缩略；stage 适合正文宽屏。

variant 不存在？

回退 default 或 product-card。

样式未加载？

确认页面内容含 mk_preview 以触发资源入队。

与 ms_navbar 关系？

皮肤由 MorphKits 决定，短代码负责入口。

size 对照

component 非法时回退 product-card；variant 空时使用 default。

相关链接

• 导航变体
• 商店 UI

导航栏变体

常用 navbar-glass 与 navbar-centered 变体，可先用 mk_preview 选型再应用到包设置。

<?php echo do_shortcode('[mk_preview component="navbar" variant="navbar-glass" size="stage"]'); ?>

<?php echo do_shortcode('[mk_preview component="navbar" variant="navbar-centered" size="stage"]'); ?>

与 ms_navbar_* 短代码组合放置于 header。

1. MorphKits → 组件 → navbar 包 → 启用变体
2. header 模板保留 ms_navbar_* 短代码
3. 清缓存后对比 #mk-preview 与生产页眉

相关链接

• 预览
• 短代码

商店 UI 变体

cart-popup-drawer 与 shop-filter-chronos 常与 SwiftCart 商店页搭配。

<?php echo do_shortcode('[mk_preview component="cart-popup" variant="cart-popup-drawer" size="stage"]'); ?>

<?php echo do_shortcode('[mk_preview component="shop-filter" variant="shop-filter-chronos" size="stage"]'); ?>

商店页可设 [sc_shop layout="chronos"] 与 chronos 筛选条视觉一致。

chronos 组合

shop-filter-chronos 变体提供时间轴式筛选条；与 [sc_shop layout="chronos"] 同页使用时视觉一致。cart-popup-drawer 则在加购后以抽屉展示购物车摘要。

常见问题

筛选不生效？

确认 sc_shop layout 与 shop-filter 变体均已启用。

弹层被遮挡？

检查 z-index 与主题 fixed 页眉。

能否只用预览？

mk_preview 仅演示；生产需启用包。

移动端？

在真机验收 drawer 与 chronos 触控区域。

相关链接

• sc_shop
• 预览

Pro 概览

MorphSwift Pro 扩展性能、SEO 与 Composer。本章合并原性能/SEO 要点。

• 资源合并与关键 CSS 策略
• 元标签与 Open Graph 模板
• 懒加载与图片尺寸提示
• Composer 可视化多页改版

SEO 简要

• 每页可设独立 title 与 meta description
• Open Graph 图默认取特色图或主题回退
• canonical 避免 shop 分页重复收录
• 结构化数据随 Pro 模块启用

性能简要

• 合并关键 CSS 减少渲染阻塞
• 图片 lazy-load 与尺寸提示
• 第三方脚本延迟加载策略

相关链接

• 许可
• Composer

会员与授权

会员计划与许可状态影响 Pro 功能与 ms_theme_pricing 展示。

• 在 Pro 设置中绑定许可密钥
• 同步计划后刷新订阅页
• 未许可时定价区可能隐藏或显示占位

<?php echo do_shortcode('[ms_theme_pricing]'); ?>

常见问题

许可过期？

Composer 入口与 Pro 优化可能关闭。

多站点？

按产品政策一密钥一生产域。

定价不更新？

清缓存并重新保存计划。

试用？

见官网政策与后台状态面板。

subscribe 页配置

固定页 subscribe 插入 [ms_theme_pricing] 展示计划卡片；CTA 可跳转结账或外链。

相关链接

• Pro 能力
• subscribe 页

Composer 概览

Composer 提供可视化页面搭建，合并原概览与入口说明。

1. 确认 Pro 许可有效
2. 后台打开 Composer 并选择目标 URL
3. 从组件库拖入块或嵌入短代码
4. 保存草稿并在预览窗口核对

权限与入口

入口通常在 MorphSwift Pro 菜单或页面列表「用 Composer 编辑」。

相关链接

• 发布
• Pro

嵌入短代码与发布

Composer DOM 树由 section、shortcode、widget_area、custom_html 等节点构成。shortcode 节点存储字面量如 [sc_shop]；widget_area 绑定侧边栏 id；custom_html 可含 markup 与 [ms_field]。

嵌入示例

<?php echo do_shortcode('[sc_shop pagination="1"]'); ?>

<?php echo do_shortcode('[ms_field key="sidebar_note"]'); ?>

<!-- widget_area: msp-page-sidebar -->

发布清单

1. 预览 URL 在桌面与手机各打开一次
2. 所有 shortcode 节点无拼写错误，商品 ID 有效
3. widget_area 对应侧边栏已拖入小工具
4. 导航菜单含新页面链接
5. SEO title/description 已在 Pro 或页面设置填写
6. 与 template-types 同 slug 页面无冲突路由
7. 清 CDN / 对象缓存后再做最终验收

发布后若空白，先查 Pro 许可与路由绑定，再查是否误删根 section 节点。

常见问题

widget_area 注释？

Composer 识别侧栏占位符并渲染对应小工具。

短代码转义？

使用 Composer 短代码块而非纯文本。

回滚？

使用历史版本或重新导入快照。

与古腾堡共存？

同一 URL 避免双编辑器争抢。

相关链接

• 入口
• 短代码