qianxun-vue3-uniapp

一个面向 Vue 3 + uni-app 的源码直发 UI 插件库。

当前版本提供 qx-button、qx-input 等基础组件，目标是先打通：

• 组件目录结构
• 统一安装入口
• SCSS 主题变量与组件样式分层
• TypeScript 类型声明
• npm 安装后直接供移动端脚手架使用

工程化约束

• 公共主题变量统一放在 theme-chalk/src/common
• 每个组件的样式文件单独放在 theme-chalk/src
• 公共方法、hooks、tokens、类型定义从包入口统一抛出
• npm 包只发布源码、样式、类型、公共方法和最小化 uni_modules 兼容目录
• 组件实现优先兼容 uni-app 与微信小程序等端能力，避免引入浏览器专属 API

目录结构

qianxun-vue3-uniapp
├── components
│   ├── qx-button
│   │   ├── index.ts
│   │   └── src/qx-button.vue
│   ├── qx-input
│   │   ├── index.ts
│   │   └── src/qx-input.vue
│   └── index.ts
├── constants
├── hooks
├── theme-chalk
│   ├── index.scss
│   └── src
│       ├── common/var.scss
│       ├── qx-button.scss
│       └── qx-input.scss
├── tokens
├── typings
├── utils
├── global.d.ts
├── index.ts
├── package.json
├── tsconfig.json

安装依赖

pnpm install

本地检查

pnpm typecheck
pnpm lint

这个包不是以预构建产物为核心，而是以源码插件形式发布，安装到 uni-app 移动端脚手架后由宿主工程统一编译。

使用方式

import { createSSRApp } from 'vue'
import QianxunUI from 'qianxun-vue3-uniapp'
import 'qianxun-vue3-uniapp/styles'

const app = createSSRApp(App)
app.use(QianxunUI)

如果希望在 app.use 里显式控制注册组件，同时只引入对应样式入口，可以改成按需模式：

import { createSSRApp } from 'vue'
import QianxunUI from 'qianxun-vue3-uniapp'
import 'qianxun-vue3-uniapp/styles/qx-button'
import 'qianxun-vue3-uniapp/styles/qx-input'
import 'qianxun-vue3-uniapp/styles/qx-qrcode'

const app = createSSRApp(App)

app.use(QianxunUI, {
  components: ['QxButton', 'QxInput', 'QxQrCode']
})

app.use 参数只控制组件注册范围。微信小程序最终样式体积由宿主工程在构建期 import 了哪些样式入口决定，因此按需减包需要和样式子入口配套使用。

在本地联调 qianxun-vue3-mp 时，建议通过宿主项目自己的样式桥接文件先覆盖变量，再引入组件库样式。

// qianxun-vue3-mp/src/assets/styles/qianxun-ui.scss
@import './qianxun-ui.variables.scss';
@import '../../../../qianxun-vue3-uniapp/theme-chalk/index.scss';

// qianxun-vue3-mp/src/assets/styles/qianxun-ui.variables.scss
$qx-color-primary: #37a954;
$qx-button-shadow-primary: 0 18rpx 36rpx rgba(55, 169, 84, 0.22);

<template>
  <view class="demo-stack">
    <qx-button type="primary" block>开始使用</qx-button>
    <qx-input v-model="keyword" clearable placeholder="请输入关键字" />
    <qx-qrcode value="https://qianxun.example.com" background-color="#f8fafc" />
  </view>
</template>

SCSS 主题变量

@use 'qianxun-vue3-uniapp/theme-chalk/var' as *;

导出内容

• 默认导出：整包安装插件
• 命名导出：QxButton
• 命名导出：QxInput
• 公共方法：withInstall、makeInstaller
• hooks：useNamespace
• tokens：qxColors、qxRadius、qxButtonTokens、qxInputTokens
• 类型：QxButtonProps、QxButtonType、QxButtonEmits、QxInputProps、QxInputType、QxInputEmits

发布到 npm

发布前请先确认：

• 已在本地创建 .npm-publish.local，或已经 npm login
• 推荐使用 NPM_TOKEN 作为一键发布凭证
• 你对包名 qianxun-vue3-uniapp 有发布权限
• 已按需更新 package.json 中的 version
• 本地如果配置了淘宝或 npmmirror 镜像，脚本会自动切到 npm 官方发布源

.npm-publish.local 示例：

NPM_TOKEN=your_npm_token
# 如果账号发布时要求 OTP，再临时补这一项
# NPM_OTP=123456

方式一：分步执行

pnpm install
npm run lint
npm run typecheck
npm run check:pack
npm publish --access public

方式二：脚本执行

npm run release:auth
sh ./scripts/release-npm.sh --dry-run
sh ./scripts/release-npm.sh

脚本会执行：

• 读取本地 .npm-publish.local 或环境变量中的 npm 凭证
• 认证检查：优先使用 NPM_TOKEN，否则校验当前 npm login 状态
• npm run lint
• npm run typecheck
• npm pack --dry-run
• 最终 npm publish --access public

项目发布脚本只支持 NPM_TOKEN。如果发布动作本身要求 OTP，可在发布前临时设置 NPM_OTP。

如果未登录且未提供本地 token 或 NPM_TOKEN，脚本会直接给出认证提示并终止，不再输出原始的 ENEEDAUTH 报错。

发布到 npm 的包内容已经排除了 scripts 目录，因此本地发布脚本不会随包一起上传。

其中：

• npm run release:auth 只校验认证是否可用
• sh ./scripts/release-npm.sh --dry-run 会执行认证、lint、typecheck 和 pack 检查，但不会真正发布