更新记录

1.1.1（2026-08-17） 下载此版本

新增基础功能的封装

1.0.0（2026-08-13） 下载此版本

uniappx 基础脚手架，包含功能： 1.基础简单的登录示例代码 2.request请求封装 3.跳转 + 登录白名单/拦截 4.版本更新(多渠道，应用市场， 蒲公英分发或第三方链接等平台) 5.文件的上传下载 6.图像裁剪上传封装 7.主题的切换，包括明暗主题与自定义主题等

平台兼容性

uni-app x(5.24)

其他

base_uniappx · uni-app x 多端基础脚手架

插件 ID：yangsf-base_uniappx
类型：前端页面模板（pagetemplate-vue）
技术栈：uvue + script setup lang="uts" · 零三方依赖

基于 uni-app x 官方规范的多端起步模板。请求、登录回流、主题、更新、隐私合规、分页、媒体、二维码、系统能力等已封装，导入后改配置即可写业务。

官方文档：uvue · UTS · API

长文案确认（如版本更新说明）请用自定义页 pages/common/update；uni.showModal 不适合长内容。

插件亮点

• 开箱即用：多环境、http 封装（Token / 401 刷新 / 去重缓存 / 取消重试）、登录回流、本地存储
• 合规上架：隐私首启、协议版本再确认、登录协议勾选、注销、反馈、权限查询与申请
• 版本更新：应用商店 / 蒲公英 / 第三方下载页 / Android APK 直装
• 主题与 i18n：light / dark / 自定义主色；zh-Hans · en
• 列表基建：分页状态机 + scaffold-list-page（下拉刷新、触底、空错态、骨架、离线条）
• 账号模板：账号密码 + 短信验证码（Mock）、头像裁剪上传、设置 / 关于
• 常用能力：媒体存相册、定位、剪贴板、扫码、纯 UTS 二维码、海报、深链、表单校验
• 系统能力：拨号、系统分享、打开文档、选文件、震动、键盘高度避让
• 工程增强：Feature Flag、Logger、埋点 / 错误上报钩子、设备信息、前后台、冷启动引导、Debug 面板
• 交互组件：Navbar / Cell / Field / Popup / ActionSheet / Switch / Checkbox / SearchBar / Badge / Tag / Tabs / Loading / Confirm / ColorPicker / QRCode / DateTime 等（easycom）
• 演示完备：scaffold · list · qrcode · debug · toolkit

适用平台

面向 uni-app x，建议使用较新版本的 HBuilderX。常见目标端：

• App（Android / iOS / 鸿蒙）
• 微信小程序（及其他小程序，按业务适配）
• Web / H5（按需）

APK 安装、应用商店 scheme、系统分享等仅部分端可用；脚手架已在 utils/platform、open-link、system、update 中做端差异收敛。

快速开始

1. 导入

1. DCloud 插件市场 搜索并导入，或 HBuilderX → 新建 / 从插件市场导入
2. 打开项目，在 manifest.json 填写 appid、应用名、图标、各端权限

2. 上架前必改配置

3. 运行体验

1. 首页：环境 / 版本 / 主题 / 网络
2. 脚手架能力演示：请求、存储、更新、权限、回流、校验、Token 等
3. 能力扩展演示：防抖节流、UI 控件、媒体定位、海报深链、系统能力 / 键盘高度、合规入口
4. 分页演示 / Debug：列表空错态、环境切换、安全区、i18n
5. 登录：须勾选协议；成功后回流；个人中心可改头像
6. 设置 / 自定义主题：语言、清缓存、反馈、注销、取色持久化

目录结构

api/                 # user、update（含 Mock，可切远程）
components/          # scaffold-* 组件（easycom）
config/              # env、update、theme、privacy、features、guide
constants/           # storage-keys 等
locale/              # zh-Hans、en
pages/
  index/ login/ profile/
  demo/{scaffold,list,qrcode,debug,toolkit}
  settings/{settings,about}  theme/custom  account/deactivate
  common/{privacy,privacy-update,webview,update,guide,feedback,poster}
store/               # user、app、theme、locale
utils/               # 见下方「能力一览」
scripts/             # gen-locale-en.cjs 等
App.uvue / main.uts / pages.json / manifest.json

能力一览

配置与状态

网络与路由

合规与账号

体验基建

媒体与系统

工具与工程

组件（easycom：scaffold-*）

navbar · cell · field · empty · skeleton · list-page · offline-bar · avatar · confirm · popup · action-sheet · switch · checkbox · search-bar · badge · tag · tabs · loading · color-picker · qrcode · datetime

组件默认读 useThemeStore()：不传颜色跟主题，传入非空则覆盖。

冷启动顺序

App.onLaunch（勿随意调换）：

1. hydrate*：环境 / 语言 / 登录态 / 主题
2. 未同意隐私 → pages/common/privacy
3. 同意后：setupNetworkListener + setupKeyboardListener
4. 协议版本再确认 → 首次引导（HAS_GUIDE）
5. pending 深链落地
6. 可选自动检查更新（featureFlags ∩ update.autoCheckOnLaunch）

使用说明

版本更新

配置 config/update.uts：androidPackage / iosAppStoreId / harmonyStoreUrl / pgyerUrl / thirdPartyUrl / defaultChannel / autoCheckOnLaunch。

import { fetchUpdateInfo } from '@/api/update.uts'
import { checkAndPromptUpdate, openUpdateChannel } from '@/utils/update.uts'

const info = await fetchUpdateInfo()
await checkAndPromptUpdate(info, false)

openUpdateChannel('store')
openUpdateChannel('apk', 'https://example.com/app.apk')

远端字段建议：hasUpdate / force / versionName / versionCode / title / content / channel / apkUrl / storeUrl / pgyerUrl / downloadPageUrl。
对接真实接口：将 api/update.uts 中 fetchUpdateInfo() 改为调用远程实现。

请求

import { httpGet, httpPost, httpGetCached, httpGetRetry, abortHttp, createRequestId } from '@/utils/request.uts'

await httpGet('/users/1', true)
await httpPost('/login', { user: 'a' }, true)
await httpGetCached('/users/1', 10000, false) // GET 默认并发去重 + TTL 缓存
await httpGetRetry('/api/x', 2, false)

const id = createRequestId('list')
// options.requestId = id; options.retry = 2
// 切页：abortHttp(id)

• 相对路径拼 appConfig.baseUrl；auth 默认注入 Bearer
• 401：未重试时先 tryRefreshToken，成功重放一次；失败清登录并回流
• config/env.uts 配置 refreshTokenUrl；空则有 refreshToken 时走演示 Mock

登录回流与协议勾选

未登录跳转会写入 redirect query，并同步 LOGIN_REDIRECT 兜底。登录页须勾选同意《用户协议》《隐私政策》（链接来自 config/privacy.uts），成功后：

import { redirectAfterLogin } from '@/utils/router.uts'
redirectAfterLogin(target) // tab → switchTab；普通页 → reLaunch

401 过期会 reLaunchToLogin，尽量带回当前页。

隐私首启

未同意时进入 pages/common/privacy。同意后写本地标记，并启动网络 / 键盘监听。上架前务必改 config/privacy.uts。

权限

import { ensurePermission, getPermissionStatus, openPermissionSetting } from '@/utils/permission.uts'

const status = getPermissionStatus('camera')
const ok = await ensurePermission('camera', null)
openPermissionSetting()

Android 走系统权限申请；iOS not determined 由后续业务 API 触发弹窗；denied 可引导去设置。

上传 / 下载 / 头像

import { uploadFile, downloadFile } from '@/utils/file-transfer.uts'
import { chooseAndUploadAvatar, pickUploadImageUrl } from '@/utils/avatar.uts'

await uploadFile(localPath, '', 'file', true)
const file = await downloadFile('https://xxx/a.png', true, '')
// 或 <scaffold-avatar :src="avatar" @success="onOk" />

上传默认 appConfig.uploadUrl。头像基于 uni.chooseImage 的 crop（默认 300×300），不支持裁剪的端降级为普通选图。

分页列表

import { reactive } from 'vue'
import { createPageState, markPageLoading, applyPageResult, resetPage } from '@/utils/pagination.uts'

const page = reactive(createPageState(10))
resetPage(page)
markPageLoading(page, true)
// await 业务请求后：
applyPageResult(page, listLen, total, false)

推荐配合：

<scaffold-list-page
  :loading="page.loading"
  :refreshing="page.refreshing"
  :loaded="page.loaded"
  :empty="page.empty"
  :error="page.error"
  :footer="footerText"
  @refresh="onRefresh"
  @loadmore="onLoadMore"
>
  <!-- 列表项 -->
</scaffold-list-page>

系统能力（拨号 / 分享 / 文档 / 震动）

import {
  makePhoneCall,
  shareText,
  openDocumentFile,
  chooseLocalFiles,
  vibrateShort,
  hideSoftKeyboard
} from '@/utils/system.uts'

await makePhoneCall('10086')
await shareText('标题', 'https://example.com') // App：系统分享；其它端：复制
const files = await chooseLocalFiles(1)
await openDocumentFile(files.paths[0]) // 可选传 fileType；亦可从扩展名推断
vibrateShort('medium') // light | medium | heavy
hideSoftKeyboard()

演示：pages/demo/toolkit →「系统能力」。

键盘高度避让

隐私同意后全局监听，高度写入 appStore.keyboardHeight：

import { useAppStore } from '@/store/app.uts'
import { resetKeyboardHeight } from '@/utils/keyboard.uts'

const appStore = useAppStore()
// 模板：:style="{ paddingBottom: appStore.keyboardHeight + 'px' }"
// 离开表单页：
onUnload(() => { resetKeyboardHeight() })

二维码

纯 UTS 编码（Byte/UTF-8，版本 1–10，纠错 L/M/Q/H）+ scaffold-qrcode 网格渲染。演示：pages/demo/qrcode。

<scaffold-qrcode
  :value="content"
  :size="240"
  level="H"
  logo="/static/logo.png"
  :logoRatio="0.2"
  qrStyle="rounded"
  gradientFrom="#0a6cff"
  gradientTo="#22c1c3"
  gradientDirection="diagonal"
  background="#f7fbff"
  :frameRadius="20"
></scaffold-qrcode>

• 纠错：L(~7%) · M(~15%) · Q(~25%) · H(~30%)
• qrStyle：square / rounded / dot / soft
• 有 Logo 时纠错低于 Q 会升到 H

日期时间选择

底部弹层 + picker-view，支持 date / time / datetime。

<scaffold-datetime
  :visible="show"
  mode="datetime"
  :modelValue="value"
  @update:visible="onVisible"
  @confirm="onConfirm"
/>

import { formatDateTimeValue, parseDateTimeValue, dateTimePartsToMs } from '@/utils/datetime.uts'
// 值约定：date=YYYY-MM-DD；time=HH:mm；datetime=YYYY-MM-DD HH:mm

演示：pages/demo/toolkit → UI 分区。

深链 / 海报

import { openDeepLink, buildScaffoldDeepLink, handleScanDeepLink } from '@/utils/deeplink.uts'
import { createPosterPayload, openPosterPage } from '@/utils/poster.uts'

openDeepLink('scaffold://navigate?path=%2Fpages%2Fsettings%2Fabout', false)
openPosterPage(createPosterPayload('标题', '副标题', '/pages/index/index', false))

主题

import { toggleTheme, applyTheme, applyCustomPrimary, resetTheme, useThemeStore } from '@/store/theme.uts'

toggleTheme()
applyTheme('dark')
applyCustomPrimary('#34c759')
resetTheme()

• 模式：light / dark / custom（自定义持久化）
• 页面绑定 theme.tokens.*；导航栏 / tabBar 由 applyNavigationBarTheme / applyTabBarTheme 同步
• 不动态改 tab 文案（uni-app x 易 errCode=100）
• 自定义页：pages/theme/custom + scaffold-color-picker

i18n

import { t, toggleLocale, useLocaleStore } from '@/store/locale.uts'

const title = computed(() : string => { return t('home.demo') })
toggleLocale()

页面文案务必用 computed(() => t(key))。开发机补英文草稿：

node scripts/gen-locale-en.cjs
# 或 npm run locale:en
# 强制重生成：npm run locale:en:force

发版前搜 TODO translate 人工校对。

小程序分享

import { buildShareAppMessage, setDefaultShare } from '@/utils/share.uts'
setDefaultShare({ title: '标题', path: '/pages/index/index', imageUrl: '', summary: '' })
// #ifdef MP
onShareAppMessage(() => { return buildShareAppMessage(null) })
// #endif

短信登录倒计时

UTS 下请在页面内用 ref 驱动倒计时（经工具函数读 reactive 时 computed 可能不刷新）。辅助：canSendSmsNow / formatSmsButtonText。演示验证码固定 123456，见 pages/login/login。

防抖 / 节流（禁止传函数引用）

import { createDebounce, resetDebounce, clearDebounce, createThrottle, throttleAllow } from '@/utils/timing.uts'

const deb = createDebounce(400)
function onInput() {
  const delay = resetDebounce(deb)
  deb.timerId = setTimeout(() => { deb.timerId = -1 /* search */ }, delay)
}

const thr = createThrottle(800)
if (throttleAllow(thr)) { /* click */ }

Feature Flag / 埋点 / 错误上报

import { featureFlags } from '@/config/features.uts'
import { trackClick } from '@/utils/track.uts'
import { setErrorReportUrl, reportErrorMessage } from '@/utils/error-report.uts'

// 关闭 enableGuide / enableDebugPanel / enableTrack 等
trackClick('home_cta')
setErrorReportUrl('https://your.api/client-error') // 再改 onErrorReportStub 真正发送
reportErrorMessage('biz fail')

Logger

import { logInfo } from '@/utils/logger.uts'
logInfo('biz', 'login', { token: 'abc', mobile: '***' }) // 自动脱敏

多环境切换

import { switchAppEnv } from '@/utils/env-runtime.uts'
switchAppEnv('test') // 开发调试；正式包请固定 production

注意事项

外链打开（重要）

当前 uni-app x 内置无 uni.openURL。脚手架默认：

• http(s) → pages/common/webview
• market:// / itms-apps:// 等 → 复制到剪贴板并 Toast

若需系统浏览器 / 直接拉起商店，可安装 uts-openSchema，在 utils/open-link.uts 的 openBySchemaPlugin 中调用 openSchema(url)。

编码规范（UTS）

1. 页面唯一 <script setup lang="uts">
2. 强类型，不用 undefined（用 null）
3. 禁止把函数引用当参数传递（先 await fn() 再传结果）
4. 禁止 return Promise.reject(...)（在 new Promise 内 reject）
5. 不要给官方 API 传 null 可选字段；setStorageSync 的 data 必须非 null
6. 不要把 NavigateToOptions 当成 UTSJSONObject（会 ClassCastException）
7. 登录拦截依赖 utils/router 封装，勿对 navigateTo 挂错误类型的全局拦截器
8. 端差异收敛到 platform / open-link / system / update
9. 模块引用使用 @/ + .uts 后缀
10. 无函数提升：同文件先定义被调用函数；onLoad / onShow / onUnload 放在全部本地函数之后

对接真实后端

1. 改 config/env.uts、config/update.uts、config/privacy.uts
2. api/user.uts / api/update.uts 换真实接口；关闭或替换 Mock
3. 按各端配置：上传域名、小程序 download/upload 合法域名、Android 未知来源安装权限等
4. 正式包：固定 production，按需关闭 Debug / 引导等 Feature Flag

交流反馈

扫码加入微信开发者交流群，反馈问题、讨论 uni-app x 实践：

扫码添加好友后，请备注「base_uniappx」，便于通过并拉***聊。

Bug 或需求也可在插件市场评论区留言。

隐私、权限声明

1. 本插件需要申请的系统权限列表：

模板按官方 API 封装能力，实际权限取决于你启用的功能与各端打包配置，常见包括：

• 网络访问（请求、上传、下载）
• 相册 / 相机（头像、选图、扫码）
• 麦克风 / 定位 / 通知（按业务开启）
• 存储读写（下载缓存、打开文档）
• 电话（拨号演示 / 客服）
• Android 安装未知来源应用（APK 更新渠道，可选）

请在正式上架前，于 manifest.json 中按业务如实声明。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

插件不采集任何数据。业务请求发往你在 config/env.uts 中自行配置的后端地址。

3. 本插件是否包含广告：

无。

许可说明

本模板供学习与商业项目二次开发使用。请勿将本模板原样重新上架插件市场；基于本模板的衍生作品请保留合理署名。

脚手架保持零三方依赖。若需更强 Schema（地图 / 多商店），可自行接入插件市场 uts-openSchema，替换 utils/open-link.uts 内部实现即可。