opple-decoration-wx

OPPLE 装饰组件库 - 微信小程序预览版

概述

本仓库是 opple-decoration 的微信小程序适配版本， 在保持业务逻辑和样式不变的前提下，将 Vue 2 + Ant Design Vue 的装饰组件库转换为 微信小程序原生框架（WXML/WXSS/JS/JSON）。

一仓两用：既是完整的可运行小程序 Demo，也是可直接 npm publish 的组件库。

技术栈

| 项目 | 技术 | |------|------| | 模板 | WXML | | 样式 | WXSS（rpx 响应式单位） | | 逻辑 | JavaScript ES6（Page/Component 构造器） | | 配置 | JSON |

可用组件

| 组件 | 类型标识 | 说明 | |------|----------|------| | Banner（轮播图） | banner | 支持多张图片轮播展示，自动播放、指示器 | | NewsList（新闻列表） | newsList | 展示资讯文章列表，支持标题、日期、跳转链接 | | Anchor（锚点导航） | anchor | 页面内锚点导航，点击滚动到对应组件，支持吸顶 |

项目结构

opple-decoration-wx/
├── package.json              # npm 包配置
├── index.js                  # JS 模块导出入口
│
├── components/               # ← npm 发布
│   ├── banner/               #   轮播图组件（swiper）
│   ├── news-list/            #   新闻列表组件
│   └── anchor/               #   锚点导航组件
├── config/                   # ← npm 发布
│   ├── settings.js
│   └── componentTypes.js
├── utils/                    # ← npm 发布
│   └── index.js
├── styles/                   # ← npm 发布
│   └── theme.wxss
│
├── project.config.json       # 仅 Git 仓库
├── app.js / app.json / app.wxss   # 仅 Git 仓库（Demo 入口）
├── pages/preview/            # 仅 Git 仓库（Demo 预览页）
└── project.private.config.json    # 仅 Git 仓库

npm 发布由 package.json 的 files 字段精确控制，只有标记「← npm 发布」的内容会被推到 npm。app.*、pages/、project.*.json 仅存在于 Git 仓库中，不影响 npm 消费者。

使用方式

方式一：GitHub 克隆 → 微信开发者工具（本地 Demo）

git clone <仓库地址>

然后用微信开发者工具直接打开项目目录即可，内置示例数据开箱即用。

方式二：npm 安装（供其他小程序引用）

npm install opple-decoration-wx

在微信开发者工具中点击 工具 → 构建 npm。

引用组件

{
  "usingComponents": {
    "banner": "opple-decoration-wx/components/banner/banner",
    "news-list": "opple-decoration-wx/components/news-list/news-list",
    "anchor": "opple-decoration-wx/components/anchor/anchor"
  }
}

<banner initData="{{bannerData}}" bind:imageClick="onImageClick" />
<news-list initData="{{newsData}}" bind:newsClick="onNewsClick" />
<anchor initData="{{anchorData}}" activeIndex="{{activeIdx}}" bind:itemTap="onAnchorTap" />

引用 JS 模块

const { widgets, COMPONENT_TYPES } = require('opple-decoration-wx')

引用样式

@import 'opple-decoration-wx/styles/theme.wxss';

推送到 npm

1. 配置认证 Token

在 npmjs.com → Access Tokens → Generate New Token（Granular Access Token）， 勾选 "Disable two-factor requirement"（绕过 2FA），生成后复制 token。

npm config set //registry.npmjs.org/:_authToken=npm_xxxx你的令牌

2. 发布

cd opple-decoration-wx
npm publish

3. 后续版本更新

npm version patch   # 1.0.0 → 1.0.1（修 bug）
npm version minor   # 1.0.0 → 1.1.0（新功能）
npm publish

2FA 说明：若未使用 Granular Token，发布时会要求 2FA 验证码：npm publish --otp=6位验证码。

发布内容由 package.json 的 files 字段控制，只包含 components/、config/、utils/、styles/、index.js、README.md。app.*、pages/、project.*.json 不会发布。

组件数据格式

// Banner
{
  id: 'banner-1', type: 'banner',
  props: {
    images: [{ url: 'https://example.com/banner.jpg', link: '' }],
    autoPlay: true, interval: 3000
  },
  style: { paddingTop: 0, paddingBottom: 10, paddingLeft: 0, paddingRight: 0 }
}

// NewsList
{
  id: 'news-1', type: 'newsList',
  props: {
    title: '最新资讯',
    news: [{ id: 1, title: '新闻标题', date: '2026-05-20', link: '' }],
    showDate: true, showArrow: true
  }
}

// Anchor
{
  id: 'anchor-1', type: 'anchor',
  props: {
    items: [
      { title: '导航一', targetId: 'banner-1' },
      { title: '导航二', targetId: 'news-1' }
    ],
    sticky: true, backgroundColor: '#ffffff',
    activeColor: '#333333', textColor: '#999999'
  }
}

与原项目差异

| 功能 | opple-decoration (Vue) | opple-decoration-wx (小程序) | |------|------------------------|------------------------------| | 编辑器模式 | ✅ 三栏编辑器 | ❌ 暂不支持 | | 拖拽排序 | ✅ vuedraggable | ❌ 暂不支持 | | 属性编辑面板 | ✅ 右侧编辑器 | ❌ 暂不支持 | | 轮播图预览 | ✅ a-carousel | ✅ swiper | | 新闻列表预览 | ✅ 完整支持 | ✅ 完整支持 | | 锚点导航预览 | ✅ DOM scrollIntoView | ✅ scroll-into-view | | npm 发布 | ✅ npm publish | ✅ npm publish | | 主题色变量 | ✅ CSS var() | ⚠️ 硬编码值 |

注意事项

1. 基础库版本：建议 >= 2.9.0（支持 sticky 定位和 enhanced scroll-view）
2. npm 消费者：安装后必须在微信开发者工具中「构建 npm」
3. 外部链接：小程序无法直接打开外部网页，点击链接会复制到剪贴板
4. 样式单位：所有 px 按 1:2 比例转为 rpx
5. CSS 变量：低版本基础库不支持 var()，主题色已硬编码在各 WXSS 中
6. Demo 文件：app.*、pages/、project.*.json 仅存于 Git 仓库，npm publish 不会发布

转换记录

• 源项目：opple-decoration (Vue 2.6 + Ant Design Vue 1.7)
• 转换方式：逐组件转换，保持业务逻辑和样式不变
• 组件裁剪：Editor 模式暂不转换（依赖复杂 DOM 操作）
• 开发人员：孙文旭
• 创建日期：2026-06-05