💪
先进的技术栈
Vite + Vue3 + Pinia + TypeScript ，采用业内先进的技术栈，使框架始终保持新鲜
作者其他作品
',2),wi=[Vi];function Ti(o,e){return s(),c("div",null,wi)}const Ii=y(Si,[["render",Ti],["__scopeId","data-v-d8aff6a3"]]),Ni={},Ei=o=>(G("data-v-f619d5b7"),o=o(),j(),o),Ci={class:"home-preview-block"},zi={class:"home-preview"},Ai=Ei(()=>d("h2",null,"截图预览",-1)),Hi={class:"items"},Mi={class:"item"},Bi={class:"item"},Oi={class:"item"},Fi={class:"item"},Di={class:"item"},Ui={class:"item"};function Gi(o,e){const t=ie("zoom-img");return s(),c("div",Ci,[d("div",zi,[Ai,d("div",Hi,[d("div",Mi,[g(t,{src:"/preview1.png"})]),d("div",Bi,[g(t,{src:"/preview2.png"})]),d("div",Oi,[g(t,{src:"/preview3.png"})]),d("div",Fi,[g(t,{src:"/preview4.png"})]),d("div",Di,[g(t,{src:"/preview5.png"})]),d("div",Ui,[g(t,{src:"/preview6.png"})])])])])}const ji=y(Ni,[["render",Gi],["__scopeId","data-v-f619d5b7"]]),qi={key:0},Ri=["src"],Ki=_({__name:"ZoomImg",props:{src:String},setup(o){const e=z(null);return J(()=>{e.value&&Lt(e.value,{background:"var(--vp-c-bg)"})}),(t,n)=>o.src?(s(),c("p",qi,[d("img",{ref_key:"imgRef",ref:e,src:i(ye)(o.src),loading:"lazy"},null,8,Ri)])):h("",!0)}}),Ji={...Xe,Layout(){return ve(Xe.Layout,null,{"layout-top":()=>ve(Pi),"home-features-after":()=>ve(ji),"aside-bottom":()=>ve(Ii)})},setup(){const o=pe(),e=()=>{Lt("[data-zoomable]",{background:"var(--vp-c-bg)"})};J(()=>e()),Z(()=>o.path,()=>Ue(()=>e()));const{frontmatter:t}=Yt(ot());vi({repo:"one-step-admin/one-step-admin.github.io",repoId:"R_kgDOJpKIUg",category:"Announcements",categoryId:"DIC_kwDOJpKIUs4CeSdr",mapping:"pathname",inputPosition:"top",lang:"zh-CN",lightTheme:"light",darkTheme:"transparent_dark",loading:!0},{frontmatter:t,route:o},!0)},enhanceApp({app:o}){o.component("Badge",dt),o.component("ZoomImg",Ki)}};export{Ji as R,Hs as c,w as u};
diff --git a/assets/components_action-container.md.C6ADMMHn.js b/assets/components_action-container.md.C6ADMMHn.js
new file mode 100644
index 00000000..94e435ae
--- /dev/null
+++ b/assets/components_action-container.md.C6ADMMHn.js
@@ -0,0 +1 @@
+import{_ as t,c as e,o as a,a6 as n}from"./chunks/framework.Bhh1y9_T.js";const p=JSON.parse('{"title":"ActionContainer 固定底部操作栏","description":"","frontmatter":{},"headers":[],"relativePath":"components/action-container.md","filePath":"components/action-container.md"}'),o={name:"components/action-container.md"},i=n('ActionContainer 固定底部操作栏
Slot
| name | 说明 |
|---|---|
| - | 内容区的 HTML 内容 |
| action | 操作区域的 HTML 内容 |
AuthAll 鉴权
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| value | 权限数据，如果传入为 array 时，全部匹配则鉴权通过，并显示 slot 内容 | array / string | - | - |
Slots
| name | 说明 |
|---|---|
| - | 需要鉴权的 HTML 内容 |
Auth 鉴权
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| value | 权限数据，如果传入为 array 时，匹配到其中一项则鉴权通过，并显示 slot 内容 | array / string | - | - |
Slots
| name | 说明 |
|---|---|
| - | 需要鉴权的 HTML 内容 |
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| type | 类型 | string | primary / success / warning / danger / info | - |
| closable | 是否显示关闭按钮 | boolean | - | false |
Events
| 事件名称 | 说明 | 回调参数 |
|---|---|---|
| close | 关闭按钮事件回调 | - |
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| color-from | 开始颜色 | string | - | '#843cf6' |
| color-to | 终止颜色 | string | - | '#759bff' |
| header | 头部标题 | string | - | - |
| num | 数字标记 | number | - | - |
| tip | 底行提示文字 | string | - | - |
| icon | 图标，使用 SvgIcon 组件，与该组件 name 参数相同 | string | - | - |
FileUpload 文件上传
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| action | 必选参数，上传的地址 | string | - | - |
| headers | 设置上传的请求头部 | object | - | - |
| data | 上传时附带的额外参数 | object | - | - |
| name | 上传的文件字段名 | string | - | file |
| size | 上传文件大小限制，单位为MB | number | - | 2 |
| max | 上传数量限制 | number | - | 3 |
| files | 上传的文件列表，例如：[{name: 'xxx.jpg', url: 'http://xxx.cdn.com/xxx.jpg'}] | array | - | [] |
| notip | 是否隐藏提示栏 | boolean | - | false |
| ext | 支持的文件类型 | array | - | ['zip', 'rar'] |
Slots
| name | 说明 |
|---|---|
| - | 触发下拉列表的 HTML 内容 |
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| v-model | 图标名称 | string | - | - |
| size | 选择器尺寸 | string | 'large' | 'default' |
ImagePreview 图片预览
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| src | 图片链接 | string | - | - |
| width | 展示宽度 | string | - | - |
| height | 展示高度 | string | - | - |
ImageUpload 单图上传
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| v-model | 图片地址 | string | - | - |
| action | 必选参数，上传的地址 | string | - | - |
| headers | 设置上传的请求头部 | object | - | - |
| data | 上传时附带的额外参数 | object | - | - |
| name | 上传的文件字段名 | string | - | file |
| size | 上传文件大小限制，单位为MB | number | - | 2 |
| width | 展示宽度 | number | - | 150 |
| height | 展示高度 | number | - | 150 |
| placeholder | 占位图 | string | - | - |
| notip | 是否隐藏提示栏 | boolean | - | false |
| ext | 支持的文件类型 | array | - | ['jpg', 'png', 'gif', 'bmp'] |
ImagesUpload 多图上传
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| v-model | 图片列表 | array | - | [] |
| action | 必选参数，上传的地址 | string | - | - |
| headers | 设置上传的请求头部 | object | - | - |
| data | 上传时附带的额外参数 | object | - | - |
| name | 上传的文件字段名 | string | - | file |
| max | 上传数量限制 | number | - | 3 |
| size | 上传文件大小限制，单位为MB | number | - | 2 |
| width | 展示宽度 | number | - | 150 |
| height | 展示高度 | number | - | 150 |
| placeholder | 占位图 | string | - | - |
| notip | 是否隐藏提示栏 | boolean | - | false |
| ext | 支持的文件类型 | array | - | ['jpg', 'png', 'gif', 'bmp'] |
介绍
框架提供一系列的组件方便快速开发。
基础组件
基础组件由 Element Plus 提供，其中包含按钮、文字链接、单选框、多选框、输入框、计数器、级联选择器、开关、滑块等 50+ 个组件。
阅读并学习请查看 Element Plus 官方文档。
说明
为了统一图标的使用，框架没有采用 Element Plus 官方图标的使用方式，这意味着部分 Element Plus 组件的 icon 属性将无法使用，例如 Button 按钮组件。
template
<!-- 无法使用 -->
+<el-button icon="el-icon-edit">编辑</el-button>
+
+<!-- 可以使用插槽代替 -->
+<el-button>
+ <template #icon>
+ <el-icon>
+ <svg-icon name="ep:edit" />
+ </el-icon>
+ </template>
+ 编辑
+</el-button>如果你习惯 Element Plus 官方图标的使用方式，需执行 pnpm install @element-plus/icons-vue 安装依赖，并按照官方的使用方式引入图标，点击查看详细介绍。
替换组件库
如果你不喜欢 Element Plus ，或者你想要将老项目迁移到 One-step-admin 上，但老项目里使用的组件库并不是 Element Plus ，框架也提供了组件库替换移方案：
如果你想使用的组件库不在上述方案中，可以通过参考任何一份方案，理解替换的整理思路，并自行替换，别担心会很复杂，我们已经将大部分工作做好了。
内建组件
为了实现 UI 组件库可替换，框架内建了一些组件，这些组件仅服务于框架自身，所以不建议在业务页面内使用。但如果你需要对框架进行二次开发，并保证视觉上的一致性，这时候你就会需要用到它们。
内建组件存放在 /src/layouts/ui-kit/ 目录下，并配置了使用时自动引入。
扩展组件
扩展组件为框架封装的组件，有全新开发的组件，也有在 Element Plus 组件上二次封装的组件，还有一些则是封装了第三方的插件。
组件源码完全开放，如果觉得用着不顺手，可以到 /src/components/ 目录下找到对应组件自行修改。
PageHeader 页头
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| title | 标题 | string | - | - |
| content | 内容 | string | - | - |
Slots
| name | 说明 |
|---|---|
| - | 右侧区域的 HTML 内容 |
| content | 内容区域的 HTML 内容 |
PageMain 内容块
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| title | 标题 | string | - | - |
| collaspe | 是否折叠 | boolean | - | false |
| height | 展示高度，当 collaspe 为 true 时生效 | string | - | - |
Slots
| name | 说明 |
|---|---|
| - | 内容区的 HTML 内容 |
| title | 标题区的 HTML 内容 |
PcasCascader 省市区街道联动
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| v-model | 联动数据选中项绑定值 | array | - | [] |
| type | 联动类型，pc 省市、pca 省市区、pcas 省市区街道 | string | pc / pca / pcas | pca |
| format | 绑定数据的格式化类型 | string | code / name / both | code |
| disabled | 是否禁用 | boolean | - | false |
SearchBar 搜索面板
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| fold | 是否折叠 | boolean | - | true |
| show-toggle | 是否显示切换按钮 | boolean | - | true |
| background | 是否显示背景 | boolean | - | false |
Slots
| name | 说明 |
|---|---|
| - | 内容区域的 HTML 内容，作用域参数为 { fold, toggle } |
Events
| 事件名称 | 说明 | 回调参数 |
|---|---|---|
| toggle | 切换展开/收起状态的事件回调 | 新状态的值 |
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| value | 迷你图数据，支持一维数组和对象数组，当为对象数组时，对象内参数为 {tooltip: 'xxx', value: 1} | array | - | - |
| width | 展示宽度 | number | - | 100 |
| height | 展示高度 | number | - | 30 |
| stroke-width | 折线宽度 | number | - | 3 |
| stroke-color | 折线颜色 | string | - | #dc2b33 |
| fill-color | 填充颜色 | string | - | - |
| cursor-color | 鼠标 hover 时辅助线颜色 | string | - | #dc2b33 |
| spot-color | 鼠标 hover 时辅助点颜色 | string | - | #dc2b33 |
| tooltip | 鼠标 hover 时是否显示文字提示 | boolean | - | false |
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| data | 需要储存的数据 | object / array | - | - |
| name | 数据存放的命名空间 | string | - | - |
| title | 下拉面板标题 | string | - | '储存箱' |
Slots
| name | 说明 |
|---|---|
| - | 触发下拉面板的 HTML 内容 |
Events
| 事件名称 | 说明 | 回调参数 |
|---|---|---|
| take-out | 点击下拉面板中某条记录的事件回调 | 记录的数据 |
SvgIcon SVG图标
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| name | svg 文件名 / Iconify 图标名，详细可阅读《图标》 | string | - | - |
| flip | 翻转方式，支持水平、垂直以及同时翻转 | string | horizontal / vertical / both | - |
| rotate | 旋转角度 | number | 0 - 360 | 0 |
| color | 颜色 | string | ||
| size | 尺寸 | string / number |
Trend 趋势标记
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| value | 内容 | string | - | - |
| type | 类型 | string | up / down | up |
| prefix | 前缀 | string | - | - |
| suffix | 后缀 | string | - | - |
| reverse | 颜色反转 | boolean | - | false |
常用 API
接口请求
详细可阅读《与服务端交互 - 接口请求》。
ts
import api from '@/api'
+
+api.get()
+api.post()鉴权
详细可阅读《权限 - 鉴权函数》。
ts
import useAuth from '@/utils/composables/useAuth'
+
+const { auth, authAll } = useAuth()
+
+auth()
+authAll()主导航
切换
切换主导航，index 为主导航序列数。
ts
import useMenu from '@/utils/composables/useMenu'
+
+useMenu().switchTo(index)窗口
新增窗口
ts
import useWindow from '@/utils/composables/useWindow'
+
+useWindow.add('windowName')
+
+useWindow.add({
+ title: '窗口标题',
+ name: 'windowName'
+})关闭窗口
ts
`,16),r={id:"窗口全屏切换",tabindex:"-1"},o=i("a",{class:"header-anchor",href:"#窗口全屏切换","aria-label":'Permalink to "窗口全屏切换 import useWindow from '@/utils/composables/useWindow'
+
+useWindow().remove('windowName')ts
`,1),c={id:"判断窗口是否全屏",tabindex:"-1"},g=i("a",{class:"header-anchor",href:"#判断窗口是否全屏","aria-label":'Permalink to "判断窗口是否全屏 import useWindow from '@/utils/composables/useWindow'
+
+useWindow().toggleMaximize('windowName')ts
import useWindow from '@/utils/composables/useWindow'
+
+useWindow().isMaximize('windowName') // true / false窗口刷新
ts
import useWindow from '@/utils/composables/useWindow'
+
+useWindow().reload('windowName')事件总线
基于 mitt 简单封装，使用方法请查阅官方文档。
ts
`,6),u={id:"日期",tabindex:"-1"},F=i("a",{class:"header-anchor",href:"#日期","aria-label":'Permalink to "日期 import eventBus from '@/utils/eventBus'
+
+eventBus.on()
+eventBus.emit()
+eventBus.off()基于 dayjs 简单封装，使用方法请查阅官方文档。
ts
`,2);function b(_,C,v,B,A,f){const n=h("Badge");return p(),l("div",null,[d,i("h3",r,[s("窗口全屏切换 "),t(n,{type:"pro",text:"专业版"}),s(),o]),E,i("h3",c,[s("判断窗口是否全屏 "),t(n,{type:"pro",text:"专业版"}),s(),g]),y,i("h2",u,[s("日期 "),t(n,{type:"pro",text:"专业版"}),s(),F]),m])}const w=e(k,[["render",b]]);export{D as __pageData,w as default};
diff --git a/assets/guide_api.md.UJgy_6go.lean.js b/assets/guide_api.md.UJgy_6go.lean.js
new file mode 100644
index 00000000..98fa8510
--- /dev/null
+++ b/assets/guide_api.md.UJgy_6go.lean.js
@@ -0,0 +1 @@
+import{_ as e,D as h,c as l,j as i,a as s,I as t,a6 as a,o as p}from"./chunks/framework.Bhh1y9_T.js";const D=JSON.parse('{"title":"常用 API","description":"","frontmatter":{},"headers":[],"relativePath":"guide/api.md","filePath":"guide/api.md"}'),k={name:"guide/api.md"},d=a("",16),r={id:"窗口全屏切换",tabindex:"-1"},o=i("a",{class:"header-anchor",href:"#窗口全屏切换","aria-label":'Permalink to "窗口全屏切换 import dayjs from '@/utils/dayjs'
+
+dayjs()与服务端交互
框架使用 Axios 做为异步请求工具，并进行了简单的封装。
接口请求
设置 baseURL
在根目录 .env.* 文件里的 VITE_APP_API_BASEURL 这个参数就是配置 axios 的 baseURL 。
例如项目的真实接口请求地址为：
http://api.test.com/news/listhttp://api.test.com/news/createhttp://api.test.com/shop/info
则可设置为 VITE_APP_API_BASEURL = http://api.test.com/ 。
请求调用
常用的 GET 和 POST 请求可使用以下的方法：
ts
import api from '@/api'
+
+// GET 请求
+api.get('news/list', {
+ params: {
+ page: 1,
+ size: 10,
+ },
+}).then((res) => {
+ // 后续业务代码
+})
+
+// POST 请求
+api.post('news/create', {
+ title: '新闻标题',
+ content: '新闻内容',
+}).then((res) => {
+ // 后续业务代码
+})拦截器
在 /src/api/index.ts 文件里实例化了 axios 对象，并对 request 和 response 设置了拦截器，拦截器的用处就是拦截每一次的请求和响应，然后做一些全局的处理。例如接口响应报错，可以在拦截器里用统一的报错提示来展示，方便业务开发。但因为每个公司提供的接口标准不同，所以该文件拦截器部分的代码，需要开发者根据实际情况去修改调整。
代码很简单，首先初始化 axios 对象，然后 axios.interceptors.request.use() 和 axios.interceptors.response.use() 就分别是请求和响应的拦截代码了。
参考代码里只做了简单的拦截处理，例如请求的时候会自动带上 token ，响应的时候会根据错误信息判断是登录失效还是接口报错，并做相应动作。
模块管理
如果项目里的接口很多，推荐根据模块来统一管理接口，目录为 /src/api/modules/ 。
跨域处理
生产环境的跨域需要服务端去解决，开发环境的跨域问题可在本地设置代理解决。如果本地开发环境请求接口提示跨域，可以设置 .env.development 文件里 VITE_OPEN_PROXY = true 开启代理。
ts
import api from '@/api'
+
+api.get('news/list') // http://localhost:9000/proxy/news/list
+api.post('news/add') // http://localhost:9000/proxy/news/add开启代理后，原有请求都会被指向到本地 http://localhost:9000/proxy ，因为 /proxy 匹配到了 vite.config.ts 里代理部分的设置，所以实际是请求依旧是 VITE_APP_API_BASEURL 所设置的地址。
ts
server: {
+ // vite.config.ts 中 proxy 配置，该配置即用于代理 API 请求
+ proxy: {
+ '/proxy': {
+ target: loadEnv(mode, process.cwd()).VITE_APP_API_BASEURL,
+ changeOrigin: command === 'serve' && loadEnv(mode, process.cwd()).VITE_OPEN_PROXY == 'true',
+ rewrite: path => path.replace(/\\/proxy/, ''),
+ },
+ },
+},多数据源
如果项目里需要从多个不同地址的数据源请求数据，你有两种方式可以实现。
如果只是几个接口需求从其它数据源请求，你可以使用覆盖 baseURL 的方式：
ts
import api from '@/api'
+
+api.get('/new/list', {
+ baseURL: 'http://baidu.com/', // 直接覆盖 baseURL
+})这种方式的前提是，两个数据源的 request 和 response 规则要保持一致，因为只是覆盖 baseURL ，拦截器还是用的同一套规则。
所以如果两个数据源的请求和响应是完全不同的标准，你需要给第二个数据源单独实例化一个 axios 对象。首先在 .env.* 文件里配置第二个数据源的 baseURL ：
# 命名可随意，以 VITE_APP_ 开头即可
+VITE_APP_API_BASEURL_2 = 此处填写接口地址然后把 /src/api/index.ts 文件复制一份，例如就叫 /src/api/index2.ts ，并且将代码中使用到 VITE_APP_API_BASEURL 也替换为 VITE_APP_API_BASEURL_2 ，这样你就可以在页面中通过引入不同的文件分别请求两个数据源了：
ts
import api from '@/api'
+import api2 from '@/api/index2'
+
+// 请求默认数据源
+api.get('/new/list')
+// 请求第 2 个数据源
+api2.get('/new/list')需注意，如果第二个数据源也需要开启跨域处理的话，需要在 /src/api/index2.ts 里定一个新的 proxy 路径，例如 /proxy2/ ：
ts
const api = axios.create({
+ baseURL: import.meta.env.DEV && import.meta.env.VITE_OPEN_PROXY === 'true' ? '/proxy2/' : import.meta.env.VITE_APP_API_BASEURL_2,
+ timeout: 10000,
+ responseType: 'json',
+})同时在 vite.config.ts 里增加一段新的 proxy 配置：
ts
server: {
+ // vite.config.ts 中 proxy 配置，该配置即用于代理 API 请求
+ proxy: {
+ '/proxy': {
+ target: loadEnv(mode, process.cwd()).VITE_APP_API_BASEURL,
+ changeOrigin: command === 'serve' && loadEnv(mode, process.cwd()).VITE_OPEN_PROXY == 'true',
+ rewrite: path => path.replace(/\\/proxy/, ''),
+ },
+ '/proxy2': {
+ target: loadEnv(mode, process.cwd()).VITE_APP_API_BASEURL_2,
+ changeOrigin: command === 'serve' && loadEnv(mode, process.cwd()).VITE_OPEN_PROXY == 'true',
+ rewrite: path => path.replace(/\\/proxy2/, ''),
+ },
+ },
+},Mock
Mock 数据是前端开发过程中必不可少的一环，是分离前后端开发的关键链路。通过预先跟服务器端约定好的接口，模拟请求数据甚至逻辑，能够让前端开发独立自主，不会被服务端的开发所阻塞。
开发环境 mock
mock 文件存放在 /src/mock/ 下，建议按照不同模块区分文件夹。文件新增或修改后会自动更新，不需要手动重启，可以在代码控制台查看日志信息。
以下为示例代码：
ts
import { defineFakeRoute } from 'vite-plugin-fake-server/client'
+import Mock from 'mockjs'
+
+export default defineFakeRoute([
+ {
+ url: '/mock/news/list',
+ method: 'get',
+ response: () => {
+ return {
+ error: '',
+ status: 1,
+ data: Mock.mock({
+ 'list|5-10': [
+ {
+ title: '@ctitle',
+ },
+ ],
+ }),
+ }
+ },
+ },
+])参数获取：
- GET：
({ query }) => { } - POST：
({ body }) => { }
为了让 mock 接口与真实接口共存，即项目开发中，部分请求 mock 接口，部分请求真实接口。需要在配置 mock 接口的时候，给 url 参数统一设置 /mock/ 前缀，并在调用接口的时候，使用 baseURL 强制修改此次请求的地址。
如下所示，其中 news/list 会请求本地的 mock 接口，而 news/create 依旧请求真实接口，即使开启跨域代理也不影响。
ts
import api from '@/api'
+
+api.get('news/list', {
+ baseURL: '/mock/',
+ params: {
+ page: 1,
+ size: 10,
+ },
+}).then((res) => {
+ // 后续业务代码
+})
+
+api.post('news/create', {
+ title: '新闻标题',
+ content: '新闻内容',
+}).then((res) => {
+ // 后续业务代码
+})生产环境 mock
注意
生产环境一般都是调用真实接口，如果需要使用 mock 也只适用于一些简单的示例网站及预览网站。
模板默认已经配置好生产环境 mock ，如果不想让生产环境里的请求走 mock ，可在接口调用处删除 baseURL 设置，或直接删除 mock 接口文件。
需要注意一点，如果项目中有涉及到上传功能，请彻底关闭线上环境 mock ，在环境配置里设置 VITE_BUILD_MOCK = false ，不然线上环境将会报错。
开发环境与生产环境使用 mock 差异不大，比较大的区别是生产环境里调用 mock 接口，在控制台内看不到接口请求日志。
`,52),k=[p];function l(t,e,E,d,r,g){return a(),i("div",null,k)}const y=s(h,[["render",l]]);export{o as __pageData,y as default}; diff --git a/assets/guide_axios.md.BhXyFrum.lean.js b/assets/guide_axios.md.BhXyFrum.lean.js new file mode 100644 index 00000000..19e0a2b0 --- /dev/null +++ b/assets/guide_axios.md.BhXyFrum.lean.js @@ -0,0 +1 @@ +import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.Bhh1y9_T.js";const o=JSON.parse('{"title":"与服务端交互","description":"","frontmatter":{},"headers":[],"relativePath":"guide/axios.md","filePath":"guide/axios.md"}'),h={name:"guide/axios.md"},p=n("",52),k=[p];function l(t,e,E,d,r,g){return a(),i("div",null,k)}const y=s(h,[["render",l]]);export{o as __pageData,y as default}; diff --git a/assets/guide_build.md.-GzyVqA3.js b/assets/guide_build.md.-GzyVqA3.js new file mode 100644 index 00000000..6439d0b2 --- /dev/null +++ b/assets/guide_build.md.-GzyVqA3.js @@ -0,0 +1,9 @@ +import{_ as a,c as e,o as s,a6 as n}from"./chunks/framework.Bhh1y9_T.js";const b=JSON.parse('{"title":"构建与预览","description":"","frontmatter":{},"headers":[],"relativePath":"guide/build.md","filePath":"guide/build.md"}'),p={name:"guide/build.md"},t=n(`构建与预览
构建
项目开发完成之后，可以执行 pnpm run build 命令进行构建，构建打包成功之后，会在根目录生成 dist 文件夹，里面就是构建打包好的文件。
如果是需要构建测试环境，则执行 pnpm run build:test 命令，对应会在根目录生成 dist-test 文件夹。
TIP
如果最终访问地址为域名非根节点，如 https://www.example.com/app，则需要在 vite.config.ts 中设置 base 选项为 /app/，否则会出现资源引用错误。
预览
生成好的 dist 文件夹一般需要部署至服务器才算部署发布成功，但为了保证构建出来的文件能正常运行，开发者通常希望能在本地先预览一下，可执行 pnpm run serve 或 pnpm run serve:test 命令预览不同环境构建出的文件夹。
压缩
在环境配置文件里设置 VITE_BUILD_COMPRESS 即可在构建时生成 .gz 或 .br 文件。
# 单独开启 gzip
+VITE_BUILD_COMPRESS = gzip
+
+# 单独开启 brotli ，brotli 是比 gzip 压缩率更高的算法
+VITE_BUILD_COMPRESS = brotli
+
+# 或者也可以都开启，两者可以共存
+VITE_BUILD_COMPRESS = gzip,brotli两者均需要 nginx 安装指定模块并开启后才会生效。
其它设置
在环境配置文件里除了可以设置压缩选项，还可设置：
# 是否在打包时生成 sourcemap
+VITE_BUILD_SOURCEMAP = true更新日志
只记录 feat/fix 以及破坏性更新记录。
4.7.0
🚨 Breaking Changes
🚀 Features
4.6.0
🚨 Breaking Changes
🚀 Features
🚨 Breaking Changes
- 移除
createInjectionKey函数，全局provide的generateI18nTitle函数放到useMenu()里提供 - by @hooray (ebc63) - 调整
menu.enableSubMenuCollapseButton的展示逻辑 - by @hooray (3a6d7)
🚀 Features
- 上传组件增加自定义上传 - by @hooray (dab41)
- 窗口宽度改为在配置文件全局设置，支持单独设置窗口宽度 - by @hooray (3837a)
- FileUpload 组件文件列表增加下载功能 - by @hooray (fd0ca)
🐞 Bug Fixes
4.5.0
🚨 Breaking Changes
- 配置项
menu.menuMode变更为menu.mode- by @hooray (10415)
🚀 Features
🐞 Bug Fixes
- 修复vscode失效配置 - by @hooray (e5cfa)
🚨 Breaking Changes
- 配置项
menu.menuActiveStyle变更为menu.style- by @hooray (fce08) - 配置项
menu.menuMode变更为menu.mode- by @hooray (9091d)
🚀 Features
- 增加2种导航栏模式
side-panel/head-panel- by @hooray (cab92) - 增加禁用开发者工具环境变量 - by @hooray (f2ef8)
- 新增哀悼模式和色弱模式 - by @hooray (9ebc8)
🐞 Bug Fixes
4.4.1
无重大变化
4.4.0
🚨 Breaking Changes
- 移除导航
i18n配置项，合并到title配置项内 - by @hooray (1921b)
🚀 Features
- 登录页增加扫码登录参考 - by @hooray (fc082)
🐞 Bug Fixes
4.3.0
无重大变化
🚀 Features
- 提供
$t函数,用于菜单i18n能在 VSCode I18n Ally 插件下正确显示 - by @hooray (d8039) - 工具栏部分按钮增加交互动效 - by @hooray (8f597)
- 支持 RTL 模式 - by @hooray (97483)
🐞 Bug Fixes
- 修复 mock 模板请求无响应数据 - by @hooray (6c92d)
4.2.3
无重大变化
无重大变化
4.2.2
无重大变化
无重大变化
4.2.1
无重大变化
4.2.0
🚀 Features
- 引入 unplugin-turbo-console 优化开发体验 - by @hooray (43d09)
- 增加打包后生成存档文件支持 - by @hooray (66d9e)
- 增加图片支持，整站图标改用 unocss icon 方式使用，方便在内网环境使用 - by @hooray (4bccd)
- 导航菜单收起时，无二级的一级导航增加 tooltip 展示 - by @hooray (5e61c)
- 明暗模式设置为跟随系统时，支持动态切换 - by @hooray (98792)
🐞 Bug Fixes
- Mock 数据修复 - by @hooray (fd2f6)
🚨 Breaking Changes
- 重构用户偏好模块，偏好设置可存放在 localStorage - by @hooray (7a554)
- 重构页面水印，支持动态更新 - by @hooray (7cdc8)
- 移除内置 v-waves 指令，使用第三方 v-wave 插件 - by @hooray (a7505)
🚀 Features
- 引入 unplugin-turbo-console 优化开发体验 - by @hooray (f644e)
- 增加打包后生成存档文件支持 - by @hooray (2bb50)
- SvgIcon 增加图片支持，整站图标改用 unocss icon 方式使用，方便在内网环境使用 - by @hooray (d5715)
- 导航菜单收起时，无二级的一级导航增加 tooltip 展示 - by @hooray (95cf8)
- 明暗模式设置为跟随系统时，支持动态切换 - by @hooray (c7bcb)
- 增加
v-zoomable图片预览指令 - by @hooray (3d58e)
🐞 Bug Fixes
- Mock 数据修复 - by @hooray (5c9ba)
4.1.0
🚨 Breaking Changes
🚨 Breaking Changes
- Vite-plugin-fake-server 替换 vite-plugin-mock - by @hooray (bdfa4)
- 应用配置
toolbar对象内属性调整 - by @hooray (c2915)
🚀 Features
4.0.1
4.0.0
🚨 Breaking Changes
🚀 Features
拥抱原子化 CSS ，启用 UnoCSS ，并对框架部分组件样式进行了重构
如果你正在将老版本的业务代码向新版本迁移，推荐安装 UnoCSS 这个 VSCode 插件，它能高亮显示 UnoCSS 的代码。如果你的业务页面代码中定义的 class 和 UnoCSS 的 class 重名，也可以通过这个插件快速识别到并修改。
与 Element Plus 组件库解耦，方便替换成其他第三方 UI 组件库，详细可阅读：
ESLint 配置文件格式调整，详细可阅读《代码规范 - ESLint 配置》
ESLint 提供了全新的配置方式，所有配置项将都在一个
eslint.config.js文件中实现。
基础版现在可以使用 Iconify 完整图标库，详细可阅读《图标 - Iconify 图标》
全新的主题配色方案，详细可阅读《主题 - 框架主题》
移除 Element Plus 自定义主题配置
如果你依旧需要自定义 Element Plus 的主题，可以阅读 Element Plus 官方文档《自定义主题》，或者参考下面提供的最佳实践。
在
/src/assets/styles/目录下分别新建element-plus.scss和element-plus.dark.scss并写入下面的代码：scss// element-plus.scss +@forward "element-plus/theme-chalk/src/common/var.scss" with ( + $colors: ( + "primary": ( + "base": green + ) + ) +); +@use "element-plus/theme-chalk/src/index.scss" as *; +@use "./element-plus.dark.scss" as *;scss// element-plus.dark.scss +@forward "element-plus/theme-chalk/src/dark/var.scss" with ( + $bg-color: ( + "page": #0a0a0a, + "": #141414, + "overlay": #1d1e1f, + ) +); +@use "element-plus/theme-chalk/src/dark/css-vars.scss" as *;修改
/src/main.tsts... +import ElementPlus from 'element-plus' +import 'element-plus/dist/index.css' +import 'element-plus/theme-chalk/dark/css-vars.css' +import '@/assets/styles/element-plus.scss' +...
移除应用配置中 Element Plus 默认尺寸的配置项
如果你依旧需要全局配置 Element Plus 的默认尺寸，可以参考《Config Provider 全局配置》并在
/src/App.vue中进行修改。
移除精灵图支持
原有
/src/assets/sprites/目录中的图片，现在可以移动到/src/assets/images/目录中，并修改代码中的使用方式。
ts
`,1),b=e('const globalSettings: Settings.all = {
+ menu: {
+ /**
+ * 留空默认
+ * radius 圆角
+ */
+ menuFillStyle: '',
+ // 导航栏是否圆角
+ isRounded: false,
+ },
+}3.1.3
无重大变化
无重大变化
3.1.2
无重大变化
无重大变化
3.1.1
无重大变化
无重大变化
3.1.0
无重大变化
3.0.0
🚨 Breaking Changes
- 移除
BatchActionBar组件 - by @hooray (b1f8f) - 移除
Editor组件 - by @hooray (2ea5f) - 移除 vite-plugin-html 插件 - by @hooray (9d1d3)
- 调整应用配置的配置项，并将应用配置按钮从工具栏删除 - by @hooray (ceffd)
- 重构接口请求，统一管理接口请求模块 - by @hooray (301d7)
🚀 Features
- 引入 stylelint-stylistic 插件 - by @hooray (38e3f)
🐞 Bug Fixes
- 修复 axios baseURL 配置，解决构建后 baseURL 不生效的问题 - by @hooray (87963)
🚨 Breaking Changes
- 移除
BatchActionBar组件 - by @hooray (ca569) - 移除
Editor组件 - by @hooray (6fff3) - 移除 vite-plugin-html 插件 - by @hooray (f9c4e)
- 调整应用配置的配置项，并将应用配置按钮从工具栏删除 - by @hooray (abea5)
- 重构标准模块，增加表格高度自适应功能 - by @hooray (f20ca)
- 重构接口请求，统一管理接口请求模块 - by @hooray (831ab)
🚀 Features
- 引入 stylelint-stylistic 插件 - by @hooray (f0826)
- 新增 StorageBox 组件 - by @hooray (38efb)
- 增加明暗切换过渡动效 - by @hooray (44045)
🐞 Bug Fixes
2.3.2
无重大变化
无重大变化
2.3.1
无重大变化
无重大变化
2.3.0
🚨 Breaking Changes
🚨 Breaking Changes
- Pinia store 改为 setup 写法 - by @hooray (040a5)
- UseCurrentInstance() 重命名为 useGlobalProperties() - by @hooray (39d56)
🐞 Bug Fixes
2.2.0
2.1.0
🐞 Bug Fixes
2.0.0
v1.0.0
JS 版本存档，框架下次更新将切换到 TS 版本，JS 版本将不再维护。
JS 版本存档，框架下次更新将切换到 TS 版本，JS 版本将不再维护。
代码规范
建议
请确保已阅读《准备工作 - 开发环境》，并且按照文档说明安装好相关软件及扩展。
为保证代码风格统一，请使用 Visual Studio Code 做为开发 IDE ，框架源码里已提供相关配置文件，可直接测试效果：在保存代码时，会自动对当前文件进行代码格式化操作。
IDE 配置
配置文件为 .editorconfig ，通常情况下无需做任何修改。
ESLint 配置
配置文件为 eslint.config.js ，框架使用 antfu/eslint-config 做为基础规范，如果你对默认的规则有异议，可以查阅 ESLint 官网规则并在 eslint.config.js 文件中进行覆盖。
当你对规则进行修改后，原有的代码可能会因为规则的变动导致编辑器大量提示错误，你可以通过运行 pnpm run lint:eslint 进行一次格式校验，如果规则支持自动修复，则会将不符合规则的代码自动进行格式化。
TIP
通过修改 eslint.config.js 中 ignores 配置可忽略无需做代码规范校验的目录或文件，例如在项目中导入了一些第三方的插件代码或组件代码，我们就可以将其进行忽略。
StyleLint 配置
配置文件为 .stylelintrc ，如果你对默认的规则有异议，可以查阅 Stylelint 官网规则并在 .stylelintrc 文件中进行修改。
当你对规则进行修改后，原有的代码可能会因为规则的变动导致编辑器大量提示错误，你可以通过运行 pnpm run lint:stylelint 进行一次格式校验，如果规则支持自动修复，则会将不符合规则的代码自动进行格式化。
TIP
通过修改 .stylelintignore 可忽略无需做代码规范校验的文件，例如在项目中导入了一些第三方的插件代码或组件代码，我们就可以将其进行忽略。
simple-git-hooks 和 lint-staged
由于 IDE 能做的事比较有限，只能对代码的书写规范进行格式化，对于一些无法自动修复的错误代码，如果没有改正到就被推送到 git 仓库，在多人协作开发时，可能会影响到别人的开发体验。所以框架集成了 simple-git-hooks 和 lint-staged 这两个依赖来解决这一问题。
在提交代码时， simple-git-hooks 会通过 lint-staged 对本次提交变更的文件进行分别进行 eslint 和 stylelint 检测，如果有报错，则会阻止本次代码提交，直到开发者修改完所有错误代码后，才允许提交到 git 仓库，这样可以确保 git 仓库里的代码不会有不规范的代码。
注意
请确保在安装依赖前，已经使用 git init 对项目进行过 git 环境初始化，如果你在安装依赖后再初始化了 git 环境，请在 git 环境初始化之后再执行一遍 pnpm install 安装命令。
此外，如果 git 仓库目录和框架目录并非同一个，则需要在 package.json 中修改 postinstall 脚本，切换到 git 所在目录。例如 git 目录是 project/ ，而框架目录是 project/one-step-admin/ ，则在 package.json 里找到 simple-git-hooks 配置并修改：
json
"simple-git-hooks": {
+ "pre-commit": "cd ./one-step-admin/ && pnpm lint-staged",
+ "preserveUnused": true
+}修改后重新执行一下 pnpm install 即可。
移除
如果不想在 git 提交时强制进行代码规范校验，可以在 package.json 中移除 simple-git-hooks 配置：
json
{
+ "scripts": {
+ "postinstall": "simple-git-hooks && esno scripts/prepare.js",
+ "postinstall": "esno scripts/prepare.js",
+ },
+ "simple-git-hooks": {
+ "pre-commit": "pnpm lint-staged",
+ "preserveUnused": true
+ },
+}json
{
+ "scripts": {
+ "postinstall": "simple-git-hooks",
+ },
+ "simple-git-hooks": {
+ "pre-commit": "pnpm lint-staged",
+ "preserveUnused": true
+ },
+}然后手动删除 .git/hooks/pre-commit 文件即可。
介绍
框架提供一系列的组件方便快速开发，其中基础组件为 Element Plus 原生提供的组件；而扩展组件有一部分是在 Element Plus 组件上进行了二次开发，还有一部分是封装了第三方插件。
组件源码完全开放，如果觉得用着不顺手，可以到 /src/components/ 目录下找到对应组件进行修改。
基础组件
基础组件由 Element Plus 提供，其中包含按钮、文字链接、单选框、多选框、输入框、计数器、级联选择器、开关、滑块等 50+ 个组件。
阅读并学习请查看 Element Plus 官方文档。
TIP
框架严格按照 Element Plus 推荐的使用方式进行引入，即按需自动导入，意味着你可以直接在代码里使用组件，而无需手动注册。
但也意味着 Element Plus 一些全局方法将无法使用，例如 Message 消息提示组件。
js
// 无法使用
+const { proxy } = getCurrentInstance()
+proxy.$message.success(options)
+
+// 可以使用
+ElMessage.success(options)另外因为框架没有采用 Element Plus 官方的图标使用方式，这也意味着部分组件的 icon 属性将无法使用，例如 Button 按钮组件。
template
<!-- 无法使用 -->
+<el-button icon="el-icon-edit">编辑</el-button>
+
+<!-- 可以使用插槽代替 -->
+<el-button>
+ <template #icon>
+ <el-icon>
+ <svg-icon name="ep:edit" />
+ </el-icon>
+ </template>
+ 编辑
+</el-button>扩展组件
`,8),e=[l];function p(h,k,r,E,o,g){return a(),i("div",null,e)}const y=s(t,[["render",p]]);export{c as __pageData,y as default}; diff --git a/assets/guide_components.md.DKFLed6e.lean.js b/assets/guide_components.md.DKFLed6e.lean.js new file mode 100644 index 00000000..76b5f912 --- /dev/null +++ b/assets/guide_components.md.DKFLed6e.lean.js @@ -0,0 +1 @@ +import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.Bhh1y9_T.js";const c=JSON.parse('{"title":"介绍","description":"","frontmatter":{},"headers":[],"relativePath":"guide/components.md","filePath":"guide/components.md"}'),t={name:"guide/components.md"},l=n("",8),e=[l];function p(h,k,r,E,o,g){return a(),i("div",null,e)}const y=s(t,[["render",p]]);export{c as __pageData,y as default}; diff --git a/assets/guide_configure.md.DGLgmmVa.js b/assets/guide_configure.md.DGLgmmVa.js new file mode 100644 index 00000000..3a209dad --- /dev/null +++ b/assets/guide_configure.md.DGLgmmVa.js @@ -0,0 +1,62 @@ +import{_ as s,c as a,o as i,a6 as n}from"./chunks/framework.Bhh1y9_T.js";const l="/settings.png",_=JSON.parse('{"title":"配置","description":"","frontmatter":{},"headers":[],"relativePath":"guide/configure.md","filePath":"guide/configure.md"}'),p={name:"guide/configure.md"},e=n(`配置
环境配置
默认提供三套环境配置，分别为：
yaml
# 应用配置面板
+VITE_APP_SETTING = true
+# 页面标题
+VITE_APP_TITLE = One-step-admin
+# 接口请求地址，会设置到 axios 的 baseURL 参数上
+VITE_APP_API_BASEURL = /
+# 调试工具，可设置 eruda 或 vconsole，如果不需要开启则留空
+VITE_APP_DEBUG_TOOL =
+# 是否禁用开发者工具，可防止被调试
+VITE_APP_DISABLE_DEVTOOL = false
+
+# 是否开启代理
+VITE_OPEN_PROXY = falseyaml
# 应用配置面板
+VITE_APP_SETTING = false
+# 页面标题
+VITE_APP_TITLE = One-step-admin
+# 接口请求地址，会设置到 axios 的 baseURL 参数上
+VITE_APP_API_BASEURL = /
+# 调试工具，可设置 eruda 或 vconsole，如果不需要开启则留空
+VITE_APP_DEBUG_TOOL =
+# 是否禁用开发者工具，可防止被调试
+VITE_APP_DISABLE_DEVTOOL = false
+
+# 是否在打包时启用 Mock
+VITE_BUILD_MOCK = false
+# 在构建时生成 sourcemap
+VITE_BUILD_SOURCEMAP = true
+# 在构建时开启压缩，支持 gzip 和 brotli
+VITE_BUILD_COMPRESS =
+# 是否在打包后生成存档，支持 zip 和 tar
+VITE_BUILD_ARCHIVE =yaml
# 应用配置面板
+VITE_APP_SETTING = false
+# 页面标题
+VITE_APP_TITLE = One-step-admin
+# 接口请求地址，会设置到 axios 的 baseURL 参数上
+VITE_APP_API_BASEURL = /
+# 调试工具，可设置 eruda 或 vconsole，如果不需要开启则留空
+VITE_APP_DEBUG_TOOL =
+# 是否禁用开发者工具，可防止被调试
+VITE_APP_DISABLE_DEVTOOL = false
+
+# 是否在打包时启用 Mock
+VITE_BUILD_MOCK = true
+# 在构建时生成 sourcemap
+VITE_BUILD_SOURCEMAP = false
+# 在构建时开启压缩，支持 gzip 和 brotli
+VITE_BUILD_COMPRESS = gzip,brotli
+# 是否在打包后生成存档，支持 zip 和 tar
+VITE_BUILD_ARCHIVE =其中 VITE_APP_SETTING VITE_APP_TITLE VITE_APP_API_BASEURL VITE_APP_DEBUG_TOOL VITE_APP_DISABLE_DEVTOOL 为必要配置，即不管是在开发、测试，还是生产环境都需要使用到。而其余配置则在不同环境下有不同用途，例如开发环境用于本地开发使用，测试环境和生产环境用于构建使用。
开发者可根据实际业务需求进行扩展，如果对这块不熟悉，请阅读 Vite - 环境变量和模式 章节。
注意
VITE_APP_SETTING 该变量是开启应用配置面板，目的是方便开发者在开发阶段调试，生产环境下默认关闭，也建议关闭。
如果希望提供用户一些定制化的能力，可以开启偏好设置，详细可阅读《用户偏好设置》
应用配置（框架配置）
开发者请在 /src/settings.ts 文件中设置自定义配置，而 /src/settings.default.ts 为框架的默认配置，请勿在该文件内修改。
关于配置的类型定义，可以在 /src/types/globals.d.ts 文件中查阅。
ts
// 这是基础版演示源码里的自定义配置示例
+const globalSettings: Settings.all = {
+ app: {
+ enablePermission: true,
+ },
+ menu: {
+ enableSubMenuCollapseButton: true,
+ enableHotkeys: true,
+ },
+ toolbar: {
+ enableFullscreen: true,
+ enableColorScheme: true,
+ },
+}注意
如果文档中提供的配置介绍，在你本地的开发环境中报错或者无法生效，说明你使用的版本不支持或者配置参数有变动，你可以打开 /src/settings.default.ts 查看当前版本的完整配置作为参考。并且如果你使用的是 Visual Studio Code ，鼠标悬浮到属性上时，会有属性的介绍：
版权信息
版权信息位于页面底部显示。
使用
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ copyright: {
+ enable: true,
+ },
+}网站运行日期
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ copyright: {
+ dates: '2021-2022',
+ },
+}公司名称
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ copyright: {
+ company: 'One-step-admin',
+ },
+}网站地址
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ copyright: {
+ website: 'https://one-step-admin.hurui.me',
+ },
+}如果未设置公司名称，则该设置将被忽略。
备案号
在应用配置中设置：
ts
`,19),p=[l];function e(k,d,g,r,E,c){return a(),i("div",null,p)}const F=s(n,[["render",e]]);export{y as __pageData,F as default};
diff --git a/assets/guide_copyright.md.DFx3AWRC.lean.js b/assets/guide_copyright.md.DFx3AWRC.lean.js
new file mode 100644
index 00000000..1c95edd4
--- /dev/null
+++ b/assets/guide_copyright.md.DFx3AWRC.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as h}from"./chunks/framework.Bhh1y9_T.js";const t="/copyright.png",y=JSON.parse('{"title":"版权信息","description":"","frontmatter":{},"headers":[],"relativePath":"guide/copyright.md","filePath":"guide/copyright.md"}'),n={name:"guide/copyright.md"},l=h("",19),p=[l];function e(k,d,g,r,E,c){return a(),i("div",null,p)}const F=s(n,[["render",e]]);export{y as __pageData,F as default};
diff --git a/assets/guide_error-log.md.CtmjfpdD.js b/assets/guide_error-log.md.CtmjfpdD.js
new file mode 100644
index 00000000..58c6bb85
--- /dev/null
+++ b/assets/guide_error-log.md.CtmjfpdD.js
@@ -0,0 +1,5 @@
+import{_ as i,D as t,c as n,j as a,a as s,I as l,a6 as p,o as r}from"./chunks/framework.Bhh1y9_T.js";const F=JSON.parse('{"title":"错误日志","description":"","frontmatter":{},"headers":[],"relativePath":"guide/error-log.md","filePath":"guide/error-log.md"}'),o={name:"guide/error-log.md"},h={id:"错误日志",tabindex:"-1"},d=a("a",{class:"header-anchor",href:"#错误日志","aria-label":'Permalink to "错误日志 const globalSettings: Settings.all = {
+ copyright: {
+ beian: '',
+ },
+}首先需要在应用配置里开启错误日志。
ts
const globalSettings: Settings.all = {
+ app: {
+ enableErrorLog: true,
+ },
+}然后需要到 /src/utils/error.log.ts 文件里编写业务代码，框架为方便演示，将错误日志记录在 sessionStorage 里。
开发者需要根据实际业务情况修改代码，例如将增加上报信息，记录用户账号、token等数据，并且将错误日志进行上报。
由于开启错误日志监控后，Vue 相关的错误都不会在控制台里显示，所以在开发环境下即使开启错误日志也不会被启用，如果需要在开发环境下测试，可在 /src/util/error.log.ts 里修改开启的条件判断。
需在工具栏开启，开启后用户可将常用的导航菜单添加进收藏夹，方便快速访问。
处理请求
收藏夹默认存储在浏览器本地 localStorage 里，如果需要将数据存储到服务器，可以通过 favorites.storageTo 配置项来实现，具体配置如下：
ts
const globalSettings: Settings.all = {
+ favorites: {
+ storageTo: 'server',
+ },
+}然后到 /src/api/modules/user.ts 中找到 favorites() 和 favoritesEdit() 这两个函数，并分别修改这两个函数的请求地址。
建议
为减轻后端处理，数据会直接以 JSON 字符串进行存储，建议后端可以在用户表增加相关字段，并将字段类型设为 lonetext 。
用户访问使用了自定义字体的页面时，会自动下载字体文件，字体文件有大有小，所以不建议在非英文环境中使用。
框架预设了 Digital 7 的两套字体，除此之外，你也可以通过以下方法引入你需要的自定义字体。
找字体
访问 DaFont 或其它字体下载网站，下载 .ttf 格式的字体文件。
生成字体
因为 .ttf 格式的字体文件不是浏览器支持的字体格式，所以需要通过 .ttf 生成其它格式的字体文件。
访问 Font Squirrel，上传 .ttf 文件，并按照下面设置后，点击下载。
使用
将上一步下载的压缩包解压并放入 /src/assets/fonts/ 目录下，注意按文件夹区分，随后引入文件夹中的 stylesheet.css 即可使用，以 Digital 7 字体为例：
scss
@import '../../assets/fonts/digital-7/stylesheet.css';
+.digital-7 {
+ font-family: 'digital-7regular';
+}字体的 font-family 名称在 stylesheet.css 里查看。
另外你也可以将 @import '../../assets/fonts/digital-7/stylesheet.css'; 这句代码放到全局引入，这样所有页面就都可以通过设置 font-family: 'digital-7regular'; 直接使用了。
INFO
该特性由 vue-i18n 提供技术支持。
vscode 扩展
如果使用 vscode 进行开发，推荐安装 i18n Ally 这个扩展。
安装该扩展后，代码里可以实时查看对应语言的内容。
语言选择器
在应用配置里设置后，会在顶栏里显示语言选择器。
ts
const globalSettings: Settings.all = {
+ toolbar: {
+ enableI18n: true,
+ },
+}同时还可在应用配置里设置默认语言，可选设置的值参考 /src/locales/lang/ 目录下文件名，留空则会根据浏览器语言自动判断，如果找不到对应的语言则使用 中文(简体) 兜底。
ts
const globalSettings: Settings.all = {
+ app: {
+ defaultLang: '',
+ },
+}语言包
语言包存放在 /src/locales/lang/ 目录下，因为 Element Plus 本身也有自己的语言包，所以在做国际化支持的时候，框架的语言包文件命名需要和 Element Plus 保持一致，可点击这里查看 Element Plus 的语言包文件。
假设你已经在 /src/locales/lang/ 目录下新增并配置好了一个日文语言包 ja.json ，然后你需要到 /src/locales/index.ts 文件里做以下调整。
ts
import elementLocaleZhCN from 'element-plus/lib/locale/lang/zh-cn'
+import elementLocaleZhTW from 'element-plus/lib/locale/lang/zh-tw'
+import elementLocaleEn from 'element-plus/lib/locale/lang/en'
+// 引用 Element Plus 的日文语言包
+import elementLocaleJa from 'element-plus/lib/locale/lang/ja'
+
+function getElementLocales() {
+ const locales: {
+ [key: string]: any
+ } = {}
+ for (const key in messages) {
+ locales[key] = {}
+ switch (key) {
+ case 'zh-cn':
+ Object.assign(locales[key], elementLocaleZhCN, { labelName: '中文(简体)' })
+ break
+ case 'zh-tw':
+ Object.assign(locales[key], elementLocaleZhTW, { labelName: '中文(繁體)' })
+ break
+ case 'en':
+ Object.assign(locales[key], elementLocaleEn, { labelName: 'English' })
+ break
+ // 在这里增加一个 case 选项，其中 labelName 会在语言选择器里显示
+ case 'ja':
+ Object.assign(locales[key], elementLocaleJa, { labelName: '日本語' })
+ break
+ }
+ }
+ return locales
+}修改完成后，需要重新启动项目才会生效。
导航设置
如果需要新增某个导航的国际化支持，光设置好中文(简体)的还不行，其它语言包文件里也要同步添加。当都设置好后，可在该导航里设置 title 参数，例如：
ts
title: 'menu.i18n',框架设置
以中文(简体)为例，打开 /src/locales/lang/zh-cn.json 文件可以看到框架相关的配置，在 app 对象里的就是框架部分的语言信息，如果需要对框架进行二次开发，请在这里扩展。
json
{
+ "app": {
+ "account": "用户名",
+ "captcha": "验证码",
+ "check": "确认",
+ "goLogin": "去登录",
+ "login": "登录",
+ "logout": "退出登录",
+ "newPassword": "新密码",
+ "password": "密码",
+ "profile": "个人设置",
+ "sendCaptcha": "发送验证码"
+ }
+}单页组件
如果每个页面都要做国际化支持，那语言包文件就会变得无比庞大且难以维护，推荐在每个页面组件里使用 <i18n> 自定义块进行语言维护，可访问 /src/views/feature_example/i18n.vue 查看示例。
与服务端交互
所有的请求均会在请求头里带上 Accept-Language ，后端可根据这一状态信息做动态数据国际化处理。
关闭国际化
如果不想开启国际化，可参考以下设置，该设置表示关闭语言选择器，并以中文(简体)显示。
ts
`,28);function o(c,y,F,u,C,b){const a=l("Badge");return p(),h("div",null,[i("h1",d,[s("国际化 "),t(a,{type:"pro",text:"专业版"}),s(),r]),g])}const q=n(E,[["render",o]]);export{B as __pageData,q as default};
diff --git a/assets/guide_i18n.md.DNvdKeNF.lean.js b/assets/guide_i18n.md.DNvdKeNF.lean.js
new file mode 100644
index 00000000..ee570928
--- /dev/null
+++ b/assets/guide_i18n.md.DNvdKeNF.lean.js
@@ -0,0 +1 @@
+import{_ as n,D as l,c as h,j as i,a as s,I as t,a6 as e,o as p}from"./chunks/framework.Bhh1y9_T.js";const k="/i18n-ally.png",B=JSON.parse('{"title":"国际化","description":"","frontmatter":{},"headers":[],"relativePath":"guide/i18n.md","filePath":"guide/i18n.md"}'),E={name:"guide/i18n.md"},d={id:"国际化",tabindex:"-1"},r=i("a",{class:"header-anchor",href:"#国际化","aria-label":'Permalink to "国际化 const globalSettings: Settings.all = {
+ app: {
+ defaultLang: 'zh-cn',
+ },
+ toolbar: {
+ enableI18n: false,
+ },
+}文档说明
⭐⭐⭐⭐⭐
相信你已经准备或正在使用 One-step-admin 进行开发工作了，在此之前，希望你可以去 Github 或者 Gitee(码云) 帮我点个 ⭐ ，这将是对我极大的鼓励。
顶部模式
ts
const globalSettings: Settings.all = {
+ menu: {
+ mode: 'head', // v4.5.0 之前版本为 menuMode
+ },
+}侧边栏模式（含主导航）
ts
const globalSettings: Settings.all = {
+ menu: {
+ mode: 'side', // v4.5.0 之前版本为 menuMode
+ },
+}侧边栏模式（无主导航）
ts
`,9),x={id:"侧边栏精简模式",tabindex:"-1"},B=s("a",{class:"header-anchor",href:"#侧边栏精简模式","aria-label":'Permalink to "侧边栏精简模式 const globalSettings: Settings.all = {
+ menu: {
+ mode: 'single', // v4.5.0 之前版本为 menuMode
+ },
+}ts
`,2),S={id:"顶部精简模式",tabindex:"-1"},T=s("a",{class:"header-anchor",href:"#顶部精简模式","aria-label":'Permalink to "顶部精简模式 const globalSettings: Settings.all = {
+ menu: {
+ mode: 'only-side', // v4.5.0 之前版本为 menuMode
+ },
+}ts
`,2),f={id:"侧边栏面板模式",tabindex:"-1"},V=s("a",{class:"header-anchor",href:"#侧边栏面板模式","aria-label":'Permalink to "侧边栏面板模式 const globalSettings: Settings.all = {
+ menu: {
+ mode: 'only-head', // v4.5.0 之前版本为 menuMode
+ },
+}ts
`,2),N={id:"顶部面板模式",tabindex:"-1"},q=s("a",{class:"header-anchor",href:"#顶部面板模式","aria-label":'Permalink to "顶部面板模式 const globalSettings: Settings.all = {
+ menu: {
+ mode: 'side-panel',
+ },
+}ts
const globalSettings: Settings.all = {
+ menu: {
+ mode: 'head-panel',
+ },
+}变量
布局相关的变量存放在 /src/assets/styles/globals.css 文件中（注意看注释），均为 CSS 变量。
登录
开发者通常在简单熟悉本框架后，涉及到的第一步业务开发就是修改登录功能，将其替换为自己的登录接口。
但在实践过程中，经常会遇到一些问题，比如：
- 替换真实接口后，无法正常登录
- 登录接口请求成功，但是无法跳转到后台主页
- ...
针对这些问题你需要依次检查以下几点：
- 在
.env.development里检查接口请求地址是否正确。 - 在
/src/api/index.ts里修改响应拦截器里的代码，按照实际情况进行调整。例如什么状态下是请求成功，什么状态下是请求异常，并进行错误提示。 - 在
/src/api/modules/user.ts里修改login函数，确保接口可以请求成功。 - 在
/src/store/modules/user.ts里修改isLogin计算属性，这部分需要根据实际存储的用户信息去判断是否登录。
导航
项目导航配置存放在 /src/menu/modules/ 目录下，每一个 ts 文件会被视为一个导航模块。
所有配置的导航模块均需要在 /src/menu/index.ts 文件里进行引入并放到主导航下。
基本配置
一级导航
一个导航模块包含以下结构：
ts
const menus: Menu.recordRaw = {
+ title: '演示',
+ windowName: 'Example',
+}
+
+export default menus注意事项
整个项目所有导航的 windowName 不能重复
多级导航
ts
const menus: Menu.recordRaw = {
+ title: '演示',
+ children: [
+ {
+ title: '演示页面',
+ windowName: 'Example',
+ },
+ ],
+}
+
+export default menus外链
只需要将 windowName 设置为需要跳转的 HTTP 地址即可。
ts
const menus: Menu.recordRaw = {
+ title: '官网',
+ windowName: 'https://one-step-admin.hurui.me',
+}
+
+export default menus主导航
主导航会将我们配置好的导航模块进行归类，在 /src/menu/index.ts 里进行设置。
ts
const menu = [
+ {
+ title: '演示',
+ icon: 'sidebar-default',
+ children: [
+ WindowExample,
+ ],
+ },
+]主导航只需设置 title 、icon 和 children 三个参数，其中 children 则是存放我们配置的导航模块数据。
导航配置
title
| 类型 | 是否必须 | 默认值 | 说明 |
|---|---|---|---|
| string | ✔️ | / | 导航展示的标题 |
windowName
| 类型 | 是否必须 | 默认值 | 说明 |
|---|---|---|---|
| string | ✔️ | / | 窗口组件名，确保唯一 |
| 类型 | 是否必须 | 默认值 | 说明 |
|---|---|---|---|
| string / number | ✖️ | / | 窗口宽度，设置为数字时单位为 px |
| 类型 | 是否必须 | 默认值 | 说明 |
|---|---|---|---|
| string | ✖️ | / | 标题国际化对应的 key 值 |
详细可阅读《国际化》。
',2),u={id:"notitle",tabindex:"-1"},m=s("a",{class:"header-anchor",href:"#notitle","aria-label":'Permalink to "noTitle| 类型 | 是否必须 | 默认值 | 说明 |
|---|---|---|---|
| boolean | ✖️ | false | 是否显示窗口标题栏 |
icon
| 类型 | 是否必须 | 默认值 | 说明 |
|---|---|---|---|
| string | ✖️ | / | 导航中显示的图标 |
该项配置最终会通过 <svg-icon /> 组件进行展示，意味着你可以使用自定义图标，也可使用 Iconify 提供的图标，详细可阅读《SVG 图标》。
auth
| 类型 | 是否必须 | 默认值 | 说明 |
|---|---|---|---|
| string / array | ✖️ | / | 该路由访问权限，支持多个权限叠加，只要满足一个，即可进入 |
用户在登录时，会获取用户权限，根据权限去过滤并动态注册路由。所以没有权限的路由不会被注册，也不会在侧边栏导航里显示，详细可阅读《权限 - 路由权限》。
',7),f={id:"badge",tabindex:"-1"},C=s("a",{class:"header-anchor",href:"#badge","aria-label":'Permalink to "badge| 类型 | 是否必须 | 默认值 | 说明 |
|---|---|---|---|
| boolean / number / string | ✖️ | / | 导航标记 |
设置不同的类型值，展示效果也会不同。
boolean展示形式为点，当值为 false 时隐藏number展示形式为文本，当值小于等于 0 时隐藏string展示形式为文本，当值为空时隐藏
如果标记需要动态更新，请设置为箭头函数形式，并返回外部变量，例如搭配 pinia 一起使用。
ts
badge: () => globalStore.numberparams
| 类型 | 是否必须 | 默认值 | 说明 |
|---|---|---|---|
| object | ✖️ | / | 窗口外部传入参数 |
该属性通常不在导航里直接配置，而是通过调用全局 useWindow() 提供的 API ，在打开非导航窗口时动态传入窗口所需要的参数。
后端生成
在应用配置里开启：
ts
const globalSettings: Settings.all = {
+ menu: {
+ baseOn: 'backend'
+ }
+}开启后在 /src/api/modules/app.ts 文件里找到 menuList() 这个函数，并修改这个函数的请求地址，请求返回的数据就是导航数据，你可以在 /src/mock/app.ts 里查看 mock 数据。
开启后端生成后，导航权限有两种做法，第一种是返回全部的导航数据，让框架自行处理（推荐），第二种是后端直接返回用户具备访问权限的导航数据。
`,13);function T(A,w,B,P,D,q){const e=l("Badge");return d(),h("div",null,[r,a(e,{type:"tip",text:"v4.4.0"}),t(" 开始，"),a(e,{type:"pro",text:"专业版"}),t(" 支持设置 i18n 对应的 key 值，详细可阅读《"),k,t("》。"),o,s("h3",c,[t("windowWidth "),a(e,{type:"pro",text:"专业版"}),t(),a(e,{type:"tip",text:"v4.6.0 新增"}),t(),g]),E,s("h3",y,[x,t(),a(e,{type:"pro",text:"专业版"}),t(),a(e,{type:"warning",text:"v4.4.0 移除"}),t(),b]),_,s("h3",u,[t("noTitle "),a(e,{type:"pro",text:"专业版"}),t(),m]),F,s("h3",f,[t("badge "),a(e,{type:"pro",text:"专业版"}),t(),C]),v])}const V=n(p,[["render",T]]);export{N as __pageData,V as default}; diff --git a/assets/guide_menu.md.DjhhAq8f.lean.js b/assets/guide_menu.md.DjhhAq8f.lean.js new file mode 100644 index 00000000..0b80df9d --- /dev/null +++ b/assets/guide_menu.md.DjhhAq8f.lean.js @@ -0,0 +1 @@ +import{_ as n,D as l,c as h,I as a,a as t,j as s,a6 as i,o as d}from"./chunks/framework.Bhh1y9_T.js";const N=JSON.parse('{"title":"导航","description":"","frontmatter":{},"headers":[],"relativePath":"guide/menu.md","filePath":"guide/menu.md"}'),p={name:"guide/menu.md"},r=i("",20),k=s("a",{href:"./i18n.html"},"国际化",-1),o=i("",2),c={id:"windowwidth",tabindex:"-1"},g=s("a",{class:"header-anchor",href:"#windowwidth","aria-label":'Permalink to "windowWidth权限
首先需要在应用配置里开启权限功能。
ts
const globalSettings: Settings.all = {
+ app: {
+ enablePermission: true,
+ },
+}然后在 /src/api/modules/user.ts 文件里找到 getPermissions 的方法，该方法用于登录成功后获取用户权限。在实际开发中，需要手动进行修改，框架默认通过 mock 模拟获取用户权限。
在演示源码中，默认提供了两组权限，你可以在“权限验证”导航里切换帐号查看不同权限下的效果。如果使用的不是 admin 或 test 用户名登录，则在导航栏里看不到“权限验证”导航入口。
鉴权组件
页面中某个模块，当前用户具备该权限是如何显示，不具备该权限又是如何显示，针对这样的需求，框架提供了 <Auth> 和 <AuthAll> 组件，具体使用如下：
template
<!-- 单权限验证 -->
+<Auth :value="'department.create'">
+ <p>你有该权限</p>
+ <template #no-auth>
+ <p>你没有该权限</p>
+ </template>
+</Auth>
+
+<!-- 多权限验证，用户只要具备其中任何一个权限，则验证通过 -->
+<Auth :value="['department.create', 'department.edit']">
+ <p>你有该权限</p>
+ <template #no-auth>
+ <p>你没有该权限</p>
+ </template>
+</Auth>
+
+<!-- 多权限验证，用户必须具备全部权限，才验证通过 -->
+<AuthAll :value="['department.create', 'department.edit']">
+ <p>你有该权限</p>
+ <template #no-auth>
+ <p>你没有该权限</p>
+ </template>
+</AuthAll>鉴权指令
对于单个元素，也提供了 v-auth 和 v-auth-all 鉴权指令，使用上对比鉴权组件更方便，当然它能做的事情也更简单。
template
<!-- 单权限验证 -->
+<button v-auth="'department.create'">新增部门</button>
+
+<!-- 多权限验证，用户只要具备其中任何一个权限，则验证通过 -->
+<button v-auth="['department.create', 'department.edit']">新增部门</button>
+
+<!-- 多权限验证，用户必须具备全部权限，才验证通过 -->
+<button v-auth-all="['department.create', 'department.edit']">新增部门</button>鉴权函数
鉴权组件和鉴权指令控制的是页面上的元素，而鉴权函数则更多是使用在业务流程代码里的权限判断。
ts
`,14),l=[h];function k(p,e,E,d,r,g){return a(),i("div",null,l)}const F=s(n,[["render",k]]);export{c as __pageData,F as default};
diff --git a/assets/guide_permission.md.Bi4TpiJ3.lean.js b/assets/guide_permission.md.Bi4TpiJ3.lean.js
new file mode 100644
index 00000000..7d34f69b
--- /dev/null
+++ b/assets/guide_permission.md.Bi4TpiJ3.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as t}from"./chunks/framework.Bhh1y9_T.js";const c=JSON.parse('{"title":"权限","description":"","frontmatter":{},"headers":[],"relativePath":"guide/permission.md","filePath":"guide/permission.md"}'),n={name:"guide/permission.md"},h=t("",14),l=[h];function k(p,e,E,d,r,g){return a(),i("div",null,l)}const F=s(n,[["render",k]]);export{c as __pageData,F as default};
diff --git a/assets/guide_plop-module.md.DvVVYnkY.js b/assets/guide_plop-module.md.DvVVYnkY.js
new file mode 100644
index 00000000..b5a88cb0
--- /dev/null
+++ b/assets/guide_plop-module.md.DvVVYnkY.js
@@ -0,0 +1,56 @@
+import{_ as n,D as p,c as l,j as i,a as s,I as e,a6 as t,o as h}from"./chunks/framework.Bhh1y9_T.js";const k="/module1.gif",d="/module2.gif",v=JSON.parse('{"title":"标准模块","description":"","frontmatter":{},"headers":[],"relativePath":"guide/plop-module.md","filePath":"guide/plop-module.md"}'),E={name:"guide/plop-module.md"},r={id:"标准模块",tabindex:"-1"},o=i("a",{class:"header-anchor",href:"#标准模块","aria-label":'Permalink to "标准模块 import useAuth from '@/utils/composables/useAuth'
+const { auth, authAll } = useAuth()
+
+// 单权限验证，返回 true 或 false
+auth('department.create')
+
+// 多权限验证，用户只要具备其中任何一个权限，则验证通过，返回 true 或 false
+auth(['department.create', 'department.edit'])
+
+// 多权限验证，用户必须具备全部权限，才验证通过，返回 true 或 false
+authAll(['department.create', 'department.edit'])在《代码文件自动生成 - module》里介绍了如何快速生成一个标准模块，这个标准模块是一个最基础的 CURD 模块，它包含列表页和编辑页，同时提供了搜索和删除的功能，并且同时也可以生成对应的 mock 文件，在这基础上可以更方便的进行业务扩展。
下面我就实际操作一遍，并介绍一下这个标准模块有哪些特性。
用法说明
? 请选择需要创建的模式： module - 创建标准窗口
+? 请输入窗口组件名称 test window
+? 请输入模块中文名称 默认模块
+? 是否生成 Mock Yes
+√ ++ \\src\\views\\windows\\TestWindow\\index.vue
+√ ++ \\src\\views\\windows\\TestWindow\\components\\DetailForm\\index.vue
+√ ++ \\src\\views\\windows\\TestWindow\\components\\FormMode\\index.vue
+√ ++ \\src\\mock\\test-window.js这里我已经通过命令在 /src/views/windows/ 目录下创建好了一个 TestWindow 文件夹，并且也生成了 mock 数据。接下来需要去配置下导航，这样我们才可以在导航栏里访问到。
首先在 /src/menu/modules/ 目录下新建一个 test.window.ts 文件，并在里面复制以下代码：
ts
cosnt menus: Menu.recordRaw = {
+ title: '测试模块',
+ windowName: 'TestWindow'
+}
+
+export default menus然后到 /src/router/routes.ts 文件里加上这个路由配置文件的引用。
ts
import TestWindow from './modules/test.window'
+
+const menu = [
+ ...,
+ {
+ title: '页面',
+ icon: 'ri-pages-line',
+ children: [
+ ...PagesExample,
+ TestWindow,
+ ],
+ },
+ ...
+]这时候就可以通过导航栏访问到我们的窗口了，我们的一个演示模块也就初步创建好了。
特性介绍
功能部分的介绍主要还是要看代码，先从列表页 index.vue 开始。
最先看到的是这句文件导入代码，因为几乎每个列表页都需要翻页功能，所以把翻页相关的东西都存放在 /src/utils/composables/pagination/index.ts 方便复用。
ts
import usePagination from '@/utils/composables/usePagination'
+
+const { pagination, getParams, onSizeChange, onCurrentChange, onSortChange } = usePagination()接着在 data 里存放的是标准模块提供的一些配置项和必要数据参数字段。
ts
const data = ref({
+ loading: false,
+ /**
+ * 详情展示模式
+ * dialog 对话框
+ * drawer 抽屉
+ */
+ formMode: 'dialog',
+ // 详情
+ formModeProps: {
+ visible: false,
+ id: '',
+ },
+ // 搜索
+ search: {
+ account: '',
+ name: '',
+ mobile: '',
+ sex: '',
+ },
+ searchMore: false,
+ // 批量操作
+ batch: {
+ enable: true,
+ selectionDataList: [],
+ },
+ // 列表数据
+ dataList: [],
+})标准模块提供了 2 种详情展示模式，默认是弹窗的方式，你可以修改 formMode: 'drawer' 开启抽屉模式，保存后效果如下：
再往下就是需要你修改或编写业务代码的部分，这里就不继续展开了。
详情页的代码就不多介绍了，相对比较简单，可自行阅读理解。其中表单部分单独封装成组件存放在 /src/views/windows/[模块文件夹]/components/DetailForm/index.vue 里了，同样你在 components/ 文件夹下还能看到另外一个 FormMode 的文件夹，这样的用意是让表单可以复用，可以通过弹窗或抽屉的形式打开详情页。
可能有人会有疑问，为什么不在生成文件的时候直接让我选择用哪种形式，这样生成出来就是哪种，而是在生成好的代码文件里再进行配置？
这样设计的目的主要有三点：
- 合理使用。关于表单具体使用哪种展示模式比较好，我们的建议是，当表单与当前列表页关联性较强，内容少则使用弹窗，内容多则使用抽屉；而当表单与当前列表页关联性较弱，且内容多，可以使用新建窗口的形式，让新窗口进行承载。
- 方便后期维护。考虑到需求会变，可能一开始是一个很简单的表单，后期需求一点点增加，变成了一个庞大的表单，这时候就要从弹窗改成抽屉的形式，反之也可能是从抽屉改成弹窗的形式，处理起来都很麻烦。所以方便后期维护，这部分是有意而为之，做成了 2 种形式共存，通过配置可一键切换。
- 跨窗口的组件调用。第一点里有提到，如果既不想使用弹窗，也不想使用抽屉，你还可以使用新窗口的形式进行处理，这时候由于表单部分已抽象成组件，所以即便是在新窗口里，也可以直接调用该组件，从而无需编写重复代码。
当然标准模块也只是框架提供的一个标准，你可以沿用，也可以根据自己的需求指定一套标准，毕竟最终目的都是提高开发效率，同时也确保多人协作开发的时候有个统一标准，不会出现每个人做出来的模块风格都不一样。
',26);function g(y,F,m,u,C,D){const a=p("Badge");return h(),l("div",null,[i("h1",r,[s("标准模块 "),e(a,{type:"pro",text:"专业版"}),s(),o]),c])}const A=n(E,[["render",g]]);export{v as __pageData,A as default}; diff --git a/assets/guide_plop-module.md.DvVVYnkY.lean.js b/assets/guide_plop-module.md.DvVVYnkY.lean.js new file mode 100644 index 00000000..6626f161 --- /dev/null +++ b/assets/guide_plop-module.md.DvVVYnkY.lean.js @@ -0,0 +1 @@ +import{_ as n,D as p,c as l,j as i,a as s,I as e,a6 as t,o as h}from"./chunks/framework.Bhh1y9_T.js";const k="/module1.gif",d="/module2.gif",v=JSON.parse('{"title":"标准模块","description":"","frontmatter":{},"headers":[],"relativePath":"guide/plop-module.md","filePath":"guide/plop-module.md"}'),E={name:"guide/plop-module.md"},r={id:"标准模块",tabindex:"-1"},o=i("a",{class:"header-anchor",href:"#标准模块","aria-label":'Permalink to "标准模块代码文件自动生成
INFO
该功能基于 plop 实现，在扩展新的模式前，请先详细阅读 plop 官方文档。
开发过程中，避免不了手动去频繁创建页面、组件等文件，并且还要在文件里写一些必要的代码，是不是觉得很麻烦？现在你可以用更简洁的方式来处理这一切。
框架默认提供了 5 种模式，通过 pnpm run new 指令可以自行选择。
除了框架提供的 5 种模式，你还可以自定义新的模式，其原理就是通过预设模板，按照特定规则创建文件或者文件夹。
预设模板文件存放在 /plop-templates/ 目录下，并在 /plopfile.js 文件里进行引用，你可以参考现有 5 种模式的目录结构进行创建新的模板。
page
page 模式下，只能在 /src/views/ 目录下选择指定的文件夹进行生成，生成的文件中，部分关键位置会被替换掉，例如 <page-header /> 中的 title 会按照你输入的中文名称替换，页面的 name 会根据当前文件目录和文件名自动生成，确保唯一。
component
component 模式可以选择生成的是公共组件还是局部组件，公共组件生成目录为 /src/components/ ，局部组件则在 /src/views/ 目录下选择指定的文件夹进行生成。
store
store 模式则会在 /src/store/modules/ 目录下生成一个空模板
mock
mock 模式则会在 /src/mock/ 目录下生成一个标准 CURD 的 mock 数据
如果希望将框架的部分应用配置项暴露给用户，让用户可以自行设置，那么可以使用用户偏好设置功能。
开启
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ userPreferences: {
+ enable: true,
+ },
+}定制偏好设置内容
然后打开 /src/store/modules/user.ts 文件，你可以在文件里进一步定制用户偏好设置里的内容：
ts
// 框架已将可提供给用户配置的选项提取出来，请勿新增其他选项，不需要的选项可以在这里注释掉
+const preferences = ref<Settings.all>({
+ app: {
+ colorScheme: settingsDefault.app.colorScheme,
+ theme: settingsDefault.app.theme,
+ },
+ ...
+})如果仔细对比，会发现这里的配置项并不是框架的完整应用配置，这是因为有部分配置项并不适合暴露给用户，比如 userPreferences.enable 这个配置项就是用来控制是否开启用户偏好设置的，如果开启了用户偏好设置，那么这个配置项就不应该再暴露给用户了，否则用户就可以关闭用户偏好设置了，这样就没有意义了。再比如 menu.baseOn 这个配置项是用来控制导航数据来源的，修改它会直接影响代码的调整，所以也是不能暴露给用户的。
所以请勿新增这里的配置项，你需要做的就是将不需要暴露给用户的配置项注释掉即可。
处理请求
用户偏好设置默认存储在浏览器本地 localStorage 里，如果需要将数据存储到服务器，可以通过 userPreferences.storageTo 配置项来实现，具体配置如下：
ts
const globalSettings: Settings.all = {
+ userPreferences: {
+ storageTo: 'server',
+ },
+}然后到 /src/api/modules/user.ts 中找到 preferences() 和 preferencesEdit() 这两个函数，并分别修改这两个函数的请求地址。
建议
为减轻后端处理，数据会直接以 JSON 字符串进行存储，建议后端可以在用户表增加相关字段，并将字段类型设为 lonetext 。
常见问题
安装依赖时有警告
这是一个可以无视的警告，因为依赖已经安装成功了。
如果对这个问题感兴趣，可以浏览下这个 issue ，里面有给出一个忽略警告的方案，就是在 package.json 中添加：
json
{
+ "pnpm": {
+ "peerDependencyRules": {
+ "ignoreMissing": [
+ "postcss",
+ "rollup"
+ ]
+ }
+ }
+}这样你下次再安装依赖的时候，就不会出现该警告了。
为什么本地开发环境首次载入很慢
主要是 Vite 的原因，具体可以阅读这篇文章了解《为什么有人说 vite 快，有人却说 vite 慢？》。
Vite 4.3 显著提升了开发服务器的性能，具体可以阅读这篇文章了解《Vite 4.3 is out!》，同时框架 v3.0.0 版本开始，vite 也升级到了 4.3 版本。
项目 URL 里的 # 号能不能去掉
这是因为路由默认使用的是 Hash 模式，你可以在 /src/router/index.ts 修改为 HTML5 模式，但需要注意，开启 HTML5 模式，服务器也需要做相应的配置调整，详细可阅读《Vue-router 不同的历史模式》。
构建报错，提示内存溢出
构建时失败并在错误信息里提示 Reached heap limit Allocation failed - JavaScript heap out of memory 。
你可以执行 pnpm add cross-env -D 安装 cross-env 依赖，并在 package.json 里修改构建脚本指令：
json
{
+ "scripts": {
+ "build": "vue-tsc --noEmit && cross-env NODE_OPTIONS=--max-old-space-size=8192 vite build"
+ }
+}其中 8192 表示内存空间大小。
直接修改构建产物的接口地址
如果你需要将构建产物部署到多台服务器，并且根据不同服务器配置不同的接口地址。这时候如果采用新增环境配置文件的方式，会存在一个弊端，就是不同环境需要分别进行构建。下面的方法可以让你直接修改构建产物的接口地址。
新增 /public/config.js 文件：
js
window.globalConfig = {
+ API_BASEURL: '/',
+}在 /index.html 中引入：
html
<body>
+ ...
+ <script src="/config.js"></script>
+ <script type="module" src="/src/main.ts"></script>
+</body>修改 /src/api/index.ts ，仅在生产环境时使用：
ts
const api = axios.create({
+ baseURL: (import.meta.env.DEV && import.meta.env.VITE_OPEN_PROXY === 'true') ? '/proxy/' : import.meta.env.VITE_APP_API_BASEURL,
+ baseURL: (import.meta.env.DEV && import.meta.env.VITE_OPEN_PROXY === 'true') ? '/proxy/' : (import.meta.env.DEV ? import.meta.env.VITE_APP_API_BASEURL : (window as any).globalConfig.API_BASEURL),
+ timeout: 1000 * 60,
+ responseType: 'json',
+})之后你就可以在构建产物目录下直接修改 config.js 文件内的接口地址了，此方法不仅适用于接口地址，可以自行扩展。
不会 TypeScript 怎么办
不管个人还是团队、产品或者项目，从长远考虑我们都建议你学习 TypeScript，因为它是未来的趋势，而且大部分框架、库、插件都是用 TypeScript 开发的，足以证明它是构建一款成熟稳健产品的基石。
但考虑到实际情况，会各种客观原因存在，如果必须要用传统 JavaScript 进行开发，你可以在 tsconfig.json 里将 allowJs 设置为 true 即可，框架原有的 TypeScript 代码不会受到影响，并且你也可以在项目中使用 JavaScript 编写代码。
准备工作
源码
阅读开发文档前，请确保手上已经有 One-step-admin 源码，因为文档中提及的内容，都是需要在本地项目中编写或修改代码并运行才能呈现的。如果还没有源码，可以通过下面两种方式获取：
基础版
说明
- 框架源码 不含示例代码，可直接用于实际开发
- 演示源码 同演示站，在框架源码基础上，提供了大量示例代码
到 Github Releases 页面下载最新版本的压缩包，如下图所示：
或者也可以从 Github/Gitee 上拉取源码，但需要注意的是，这种方式拉取的是最新的代码，而不是稳定版本，可能会存在一些问题，所以请谨慎使用。
sh
# 拉取框架源码
+git clone https://github.com/one-step-admin/basic.git
+# 拉取演示源码
+git clone -b example https://github.com/one-step-admin/basic.gitsh
# 拉取框架源码
+git clone https://gitee.com/one-step-admin/basic.git
+# 拉取演示源码
+git clone -b example https://gitee.com/one-step-admin/basic.git专业版
专业版用户会邀请加入到私有组织，获取源码的方式和基础版一致，只是仓库地址不同。
如果你想获取专业版源码，可以点这里去购买。
开发环境
使用本模板前，需要在本地依次安装好 Node.js, pnpm, Git 和 Visual Studio Code。
注意
Node.js 需要使用 18+ / 20+ 版本。
然后在 Visual Studio Code 里安装好以下扩展：
在 Visual Studio Code 里打开源码的文件夹，右下角会自动提示需要安装的依赖，直接点击安装即可。
建议
以上为开发时必备扩展，以下则是作者推荐安装的扩展，安装它们将在一定程度上提升开发效率。
- Chinese (Simplified) Language Pack for Visual Studio Code 中文语言包
- Color Highlight 在代码中高亮颜色
- Highlight Matching Tag 高亮显示匹配的标签
- Image preview 图片预览
- indent-rainbow 彩虹缩进提示
除此之外，还需要准备好开发使用的浏览器，推荐使用 Chrome ，并且在 Chrome 里安装好 Vue.js devtools 扩展，安装 Vue 官方提供的调试工具在一定程度上可以提升解决 bug 的效率，当然这个扩展开启后，可能在开发环境操作会有些许卡顿，建议不需要时候可以将扩展禁用。
不过由于安装 Vue.js devtools 需要访问 Chrome 应用商店，如果在大陆地区访问，需要自行准备相关可访问外网的工具。如果不具备该条件，也可访问 Vue.js devtools 官网 了解本地构建或者下载支持 Edge/Firefox 的 Vue.js devtools 。
技术栈
了解并熟悉框架使用到的技术栈，能让你使用本框架更得心应手。
',25),o=[n];function h(p,d,c,g,m,k){return t(),a("div",null,o)}const f=e(l,[["render",h]]);export{b as __pageData,f as default}; diff --git a/assets/guide_ready.md.CJkkBV7W.lean.js b/assets/guide_ready.md.CJkkBV7W.lean.js new file mode 100644 index 00000000..6f0f1af5 --- /dev/null +++ b/assets/guide_ready.md.CJkkBV7W.lean.js @@ -0,0 +1 @@ +import{_ as e,c as a,o as t,a6 as i}from"./chunks/framework.Bhh1y9_T.js";const s="/download.png",r="/vscode.png",b=JSON.parse('{"title":"准备工作","description":"","frontmatter":{},"headers":[],"relativePath":"guide/ready.md","filePath":"guide/ready.md"}'),l={name:"guide/ready.md"},n=i("",25),o=[n];function h(p,d,c,g,m,k){return t(),a("div",null,o)}const f=e(l,[["render",h]]);export{b as __pageData,f as default}; diff --git a/assets/guide_replace-to-antd.md.BaHAuChd.js b/assets/guide_replace-to-antd.md.BaHAuChd.js new file mode 100644 index 00000000..e084bf1f --- /dev/null +++ b/assets/guide_replace-to-antd.md.BaHAuChd.js @@ -0,0 +1,93 @@ +import{_ as s,c as i,o as a,a6 as n}from"./chunks/framework.Bhh1y9_T.js";const t="/ui-antd.png",y=JSON.parse('{"title":"替换为 Ant Design Vue","description":"","frontmatter":{},"headers":[],"relativePath":"guide/replace-to-antd.md","filePath":"guide/replace-to-antd.md"}'),l={name:"guide/replace-to-antd.md"},p=n(`替换为 Ant Design Vue
注意
v4.0 之前的版本不支持替换组件库，本文适用于 v4.0 及之后的版本。
由于框架默认使用的是 Element Plus 组件库，并且演示源码中大量示例也使用了 Element Plus，如果你需要使用 Ant Design Vue，请拉取框架源码分支，或者到 Github Releases 页面下载框架源码压缩包。
专业版用户也同样，请到专业版仓库下载框架源码。
安装
sh
# 安装依赖
+pnpm install
+
+# 安装 Ant Design Vue
+pnpm add ant-design-vue@4.x代码调整
基础版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import Antd from 'ant-design-vue'
+import 'ant-design-vue/dist/reset.css'
+
+function install(app: App) {
+ app.use(Antd)
+}
+
+export default { install }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import antDesignVueLocaleZhCN from 'ant-design-vue/es/locale/zh_CN'
+import { theme } from 'ant-design-vue'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+</script>
+
+<template>
+ <AConfigProvider :locale="antDesignVueLocaleZhCN" :theme="settingsStore.currentColorScheme === 'dark' ? { algorithm: [theme.darkAlgorithm] } : {}">
+ <slot />
+ </AConfigProvider>
+</template>删除相关文件
.
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader专业版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import Antd from 'ant-design-vue'
+import 'ant-design-vue/dist/reset.css'
+
+import zhCN from 'ant-design-vue/es/locale/zh_CN'
+import zhTW from 'ant-design-vue/es/locale/zh_TW'
+import en from 'ant-design-vue/es/locale/en_US'
+
+function install(app: App) {
+ app.use(Antd)
+}
+
+// 此处的对象属性和 src/locales/index.ts 中的 messages 对象属性一一对应
+const locales: { [key: string]: any } = {
+ 'zh-cn': zhCN,
+ 'zh-tw': zhTW,
+ 'en': en,
+}
+
+export default { install }
+export { locales }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { theme } from 'ant-design-vue'
+import { locales } from './index'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+</script>
+
+<template>
+ <AConfigProvider :locale="locales[settingsStore.lang]" :theme="settingsStore.currentColorScheme === 'dark' ? { algorithm: [theme.darkAlgorithm] } : {}">
+ <slot />
+ </AConfigProvider>
+</template>删除相关文件
.
+├─ plop-templates
+│ └─ module // 标准模块模板基于 Element Plus 开发，需要删除
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ IconPicker
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader修改登录页
由于登录页使用了 Element Plus 组件，并且删除会导致框架无法正常使用，所以此处需要开发者自行修改或者重新制作登录页，或者也可以参考下方示例中已经修改好的登录页。
卸载
sh
# 卸载 Element Plus
+pnpm remove element-plus完成
至此，你已经将框架中的 Element Plus 组件库替换为 Ant Design Vue 组件库，并且可以开始使用 Ant Design Vue 进行业务开发了。
示例
如果对上述的步骤还有不清楚的地方，可以访问此仓库查看示例源码，以及此链接查看示例网站。
替换为 Arco Design Vue
注意
v4.0 之前的版本不支持替换组件库，本文适用于 v4.0 及之后的版本。
由于框架默认使用的是 Element Plus 组件库，并且演示源码中大量示例也使用了 Element Plus，如果你需要使用 Arco Design Vue，请拉取框架源码分支，或者到 Github Releases 页面下载框架源码压缩包。
专业版用户也同样，请到专业版仓库下载框架源码。
安装
sh
# 安装依赖
+pnpm install
+
+# 安装 Arco Design Vue
+pnpm add @arco-design/web-vue -D代码调整
基础版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global",
+ ...
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import ArcoVue from '@arco-design/web-vue'
+import '@arco-design/web-vue/dist/arco.css'
+
+function install(app: App) {
+ app.use(ArcoVue)
+}
+
+export default { install }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import zhCN from '@arco-design/web-vue/es/locale/lang/zh-cn'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+
+const prefersColorScheme = window.matchMedia('(prefers-color-scheme: dark)')
+watch(() => settingsStore.settings.app.colorScheme, (colorScheme) => {
+ if (colorScheme === '') {
+ prefersColorScheme.addEventListener('change', updateTheme)
+ }
+ else {
+ prefersColorScheme.removeEventListener('change', updateTheme)
+ }
+ nextTick(() => {
+ updateTheme()
+ })
+}, {
+ immediate: true,
+})
+function updateTheme() {
+ switch (settingsStore.currentColorScheme) {
+ case 'light':
+ document.body.removeAttribute('arco-theme')
+ break
+ case 'dark':
+ document.body.setAttribute('arco-theme', 'dark')
+ break
+ }
+}
+</script>
+
+<template>
+ <AConfigProvider :locale="zhCN">
+ <slot />
+ </AConfigProvider>
+</template>删除相关文件
.
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader专业版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import ArcoVue from '@arco-design/web-vue'
+import '@arco-design/web-vue/dist/arco.css'
+
+import zhCN from '@arco-design/web-vue/es/locale/lang/zh-CN'
+import zhTW from '@arco-design/web-vue/es/locale/lang/zh-TW'
+import en from '@arco-design/web-vue/es/locale/lang/en-US'
+
+function install(app: App) {
+ app.use(ArcoVue)
+}
+
+// 此处的对象属性和 src/locales/index.ts 中的 messages 对象属性一一对应
+const locales: { [key: string]: any } = {
+ 'zh-cn': zhCN,
+ 'zh-tw': zhTW,
+ 'en': en,
+}
+
+export default { install }
+export { locales }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { locales } from './index'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+
+const prefersColorScheme = window.matchMedia('(prefers-color-scheme: dark)')
+watch(() => settingsStore.settings.app.colorScheme, (colorScheme) => {
+ if (colorScheme === '') {
+ prefersColorScheme.addEventListener('change', updateTheme)
+ }
+ else {
+ prefersColorScheme.removeEventListener('change', updateTheme)
+ }
+ nextTick(() => {
+ updateTheme()
+ })
+}, {
+ immediate: true,
+})
+function updateTheme() {
+ switch (settingsStore.currentColorScheme) {
+ case 'light':
+ document.body.removeAttribute('arco-theme')
+ break
+ case 'dark':
+ document.body.setAttribute('arco-theme', 'dark')
+ break
+ }
+}
+</script>
+
+<template>
+ <AConfigProvider :locale="locales[settingsStore.lang]">
+ <slot />
+ </AConfigProvider>
+</template>删除相关文件
.
+├─ plop-templates
+│ └─ module // 标准模块模板基于 Element Plus 开发，需要删除
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ IconPicker
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader修改登录页
由于登录页使用了 Element Plus 组件，并且删除会导致框架无法正常使用，所以此处需要开发者自行修改或者重新制作登录页，或者也可以参考下方示例中已经修改好的登录页。
卸载
sh
# 卸载 Element Plus
+pnpm remove element-plus完成
至此，你已经将框架中的 Element Plus 组件库替换为 Arco Design Vue 组件库，并且可以开始使用 Arco Design Vue 进行业务开发了。
示例
如果对上述的步骤还有不清楚的地方，可以访问此仓库查看示例源码，以及此链接查看示例网站。
替换为 iDux
注意
v4.0 之前的版本不支持替换组件库，本文适用于 v4.0 及之后的版本。
由于框架默认使用的是 Element Plus 组件库，并且演示源码中大量示例也使用了 Element Plus，如果你需要使用 iDux，请拉取框架源码分支，或者到 Github Releases 页面下载框架源码压缩包。
专业版用户也同样，请到专业版仓库下载框架源码。
安装
sh
# 安装依赖
+pnpm install
+
+# 安装 iDux
+pnpm add @idux/cdk @idux/components代码调整
基础版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import IduxCdk from '@idux/cdk'
+import IduxComponents from '@idux/components'
+import { IDUX_ICON_DEPENDENCIES, addIconDefinitions } from '@idux/components/icon'
+import { createGlobalConfig } from '@idux/components/config'
+import { zhCN } from '@idux/components/locales'
+import '@idux/components/index.full.css'
+
+function install(app: App) {
+ addIconDefinitions(IDUX_ICON_DEPENDENCIES)
+ app.use(IduxCdk).use(IduxComponents).use(createGlobalConfig({ locale: zhCN }))
+}
+
+export default { install }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+</script>
+
+<template>
+ <IxThemeProvider :preset-theme="settingsStore.currentColorScheme === 'dark' ? 'dark' : 'default'">
+ <IxMessageProvider>
+ <slot />
+ </IxMessageProvider>
+ </IxThemeProvider>
+</template>删除相关文件
.
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader专业版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import IduxCdk from '@idux/cdk'
+import IduxComponents from '@idux/components'
+import { IDUX_ICON_DEPENDENCIES, addIconDefinitions } from '@idux/components/icon'
+import { enUS, zhCN } from '@idux/components/locales'
+import '@idux/components/index.full.css'
+
+// 此处的对象属性和 src/locales/index.ts 中的 messages 对象属性一一对应
+const locales: { [key: string]: any } = {
+ 'zh-cn': zhCN,
+ 'zh-tw': zhCN,
+ 'en': enUS,
+}
+
+function install(app: App) {
+ addIconDefinitions(IDUX_ICON_DEPENDENCIES)
+ app.use(IduxCdk).use(IduxComponents)
+}
+
+export default { install }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { useGlobalConfig } from '@idux/components/config'
+import { locales } from './index'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+
+const [, setLocale] = useGlobalConfig('locale', locales[settingsStore.lang])
+watch(() => settingsStore.lang, val => setLocale(locales[settingsStore.lang]))
+</script>
+
+<template>
+ <IxThemeProvider :preset-theme="settingsStore.currentColorScheme === 'dark' ? 'dark' : 'default'">
+ <IxMessageProvider>
+ <slot />
+ </IxMessageProvider>
+ </IxThemeProvider>
+</template>删除相关文件
.
+├─ plop-templates
+│ └─ module // 标准模块模板基于 Element Plus 开发，需要删除
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ IconPicker
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader修改登录页
由于登录页使用了 Element Plus 组件，并且删除会导致框架无法正常使用，所以此处需要开发者自行修改或者重新制作登录页，或者也可以参考下方示例中已经修改好的登录页。
卸载
sh
# 卸载 Element Plus
+pnpm remove element-plus完成
至此，你已经将框架中的 Element Plus 组件库替换为 iDux 组件库，并且可以开始使用 iDux 进行业务开发了。
示例
如果对上述的步骤还有不清楚的地方，可以访问此仓库查看示例源码，以及此链接查看示例网站。
替换为 Naive UI
注意
v4.0 之前的版本不支持替换组件库，本文适用于 v4.0 及之后的版本。
由于框架默认使用的是 Element Plus 组件库，并且演示源码中大量示例也使用了 Element Plus，如果你需要使用 Naive UI，请拉取框架源码分支，或者到 Github Releases 页面下载框架源码压缩包。
专业版用户也同样，请到专业版仓库下载框架源码。
安装
sh
# 安装依赖
+pnpm install
+
+# 安装 Naive UI
+pnpm add naive-ui -D代码调整
基础版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ "naive-ui/volar"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import naive from 'naive-ui'
+
+function install(app: App) {
+ app.use(naive)
+}
+
+export default { install }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { darkTheme, dateZhCN, zhCN } from 'naive-ui'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+</script>
+
+<template>
+ <NConfigProvider :locale="zhCN" :date-locale="dateZhCN" :theme="settingsStore.currentColorScheme === 'dark' ? darkTheme : undefined" style="height: 100%;">
+ <NMessageProvider>
+ <slot />
+ <NGlobalStyle />
+ </NMessageProvider>
+ </NConfigProvider>
+</template>删除相关文件
.
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader专业版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ "naive-ui/volar"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import naive, { dateEnUS, dateZhCN, dateZhTW, enUS, zhCN, zhTW } from 'naive-ui'
+
+function install(app: App) {
+ app.use(naive)
+}
+
+// 此处的对象属性和 src/locales/index.ts 中的 messages 对象属性一一对应
+const locales: { [key: string]: any } = {
+ 'zh-cn': {
+ ui: zhCN,
+ date: dateZhCN,
+ },
+ 'zh-tw': {
+ ui: zhTW,
+ date: dateZhTW,
+ },
+ 'en': {
+ ui: enUS,
+ date: dateEnUS,
+ },
+}
+
+export default { install }
+export { locales }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { darkTheme } from 'naive-ui'
+import { locales } from './index'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+</script>
+
+<template>
+ <NConfigProvider :locale="locales[settingsStore.lang].ui" :date-locale="locales[settingsStore.lang].date" :theme="settingsStore.currentColorScheme === 'dark' ? darkTheme : undefined" style="height: 100%;">
+ <NMessageProvider>
+ <slot />
+ <NGlobalStyle />
+ </NMessageProvider>
+ </NConfigProvider>
+</template>修改登录页
由于登录页使用了 Element Plus 组件，并且删除会导致框架无法正常使用，所以此处需要开发者自行修改或者重新制作登录页，或者也可以参考下方示例中已经修改好的登录页。
卸载
sh
# 卸载 Element Plus
+pnpm remove element-plus完成
至此，你已经将框架中的 Element Plus 组件库替换为 Naive UI 组件库，并且可以开始使用 Naive UI 进行业务开发了。
示例
如果对上述的步骤还有不清楚的地方，可以访问此仓库查看示例源码，以及此链接查看示例网站。
替换为 TDesign
注意
v4.0 之前的版本不支持替换组件库，本文适用于 v4.0 及之后的版本。
由于框架默认使用的是 Element Plus 组件库，并且演示源码中大量示例也使用了 Element Plus，如果你需要使用 TDesign，请拉取框架源码分支，或者到 Github Releases 页面下载框架源码压缩包。
专业版用户也同样，请到专业版仓库下载框架源码。
安装
sh
# 安装依赖
+pnpm install
+
+# 安装 TDesign
+pnpm add tdesign-vue-next代码调整
基础版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ },
+ ...
+ "include": [
+ "src/**/*.ts",
+ "src/**/*.d.ts",
+ "src/**/*.tsx",
+ "src/**/*.vue"
+ "src/**/*.vue",
+ "node_modules/tdesign-vue-next/global.d.ts"
+ ]
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import TDesign from 'tdesign-vue-next'
+import 'tdesign-vue-next/es/style/index.css'
+
+function install(app: App) {
+ app.use(TDesign)
+}
+
+export default { install }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { merge } from 'lodash-es'
+import zhCN from 'tdesign-vue-next/es/locale/zh_CN'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+
+const prefersColorScheme = window.matchMedia('(prefers-color-scheme: dark)')
+watch(() => settingsStore.settings.app.colorScheme, (colorScheme) => {
+ if (colorScheme === '') {
+ prefersColorScheme.addEventListener('change', updateTheme)
+ }
+ else {
+ prefersColorScheme.removeEventListener('change', updateTheme)
+ }
+ nextTick(() => {
+ updateTheme()
+ })
+}, {
+ immediate: true,
+})
+function updateTheme() {
+ switch (settingsStore.currentColorScheme) {
+ case 'light':
+ document.documentElement.removeAttribute('theme-mode')
+ break
+ case 'dark':
+ document.documentElement.setAttribute('theme-mode', 'dark')
+ break
+ }
+}
+</script>
+
+<template>
+ <TConfigProvider :global-config="merge(zhCN)">
+ <slot />
+ </TConfigProvider>
+</template>删除相关文件
.
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader专业版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ },
+ ...
+ "include": [
+ "src/**/*.ts",
+ "src/**/*.d.ts",
+ "src/**/*.tsx",
+ "src/**/*.vue"
+ "src/**/*.vue",
+ "node_modules/tdesign-vue-next/global.d.ts"
+ ]
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import TDesign from 'tdesign-vue-next'
+import 'tdesign-vue-next/es/style/index.css'
+
+import zhCN from 'tdesign-vue-next/es/locale/zh_CN'
+import zhTW from 'tdesign-vue-next/es/locale/zh_TW'
+import en from 'tdesign-vue-next/es/locale/en_US'
+
+function install(app: App) {
+ app.use(TDesign)
+}
+
+// 此处的对象属性和 src/locales/index.ts 中的 messages 对象属性一一对应
+const locales: { [key: string]: any } = {
+ 'zh-cn': zhCN,
+ 'zh-tw': zhTW,
+ 'en': en,
+}
+
+export default { install }
+export { locales }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { merge } from 'lodash-es'
+import { locales } from './index'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+
+const prefersColorScheme = window.matchMedia('(prefers-color-scheme: dark)')
+watch(() => settingsStore.settings.app.colorScheme, (colorScheme) => {
+ if (colorScheme === '') {
+ prefersColorScheme.addEventListener('change', updateTheme)
+ }
+ else {
+ prefersColorScheme.removeEventListener('change', updateTheme)
+ }
+ nextTick(() => {
+ updateTheme()
+ })
+}, {
+ immediate: true,
+})
+function updateTheme() {
+ switch (settingsStore.currentColorScheme) {
+ case 'light':
+ document.documentElement.removeAttribute('theme-mode')
+ break
+ case 'dark':
+ document.documentElement.setAttribute('theme-mode', 'dark')
+ break
+ }
+}
+</script>
+
+<template>
+ <TConfigProvider :global-config="merge(locales[settingsStore.lang])">
+ <slot />
+ </TConfigProvider>
+</template>删除相关文件
.
+├─ plop-templates
+│ └─ module // 标准模块模板基于 Element Plus 开发，需要删除
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ IconPicker
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader修改登录页
由于登录页使用了 Element Plus 组件，并且删除会导致框架无法正常使用，所以此处需要开发者自行修改或者重新制作登录页，或者也可以参考下方示例中已经修改好的登录页。
卸载
sh
# 卸载 Element Plus
+pnpm remove element-plus完成
至此，你已经将框架中的 Element Plus 组件库替换为 TDesign 组件库，并且可以开始使用 TDesign 进行业务开发了。
示例
如果对上述的步骤还有不清楚的地方，可以访问此仓库查看示例源码，以及此链接查看示例网站。
替换为 Vexip UI
注意
v4.0 之前的版本不支持替换组件库，本文适用于 v4.0 及之后的版本。
由于框架默认使用的是 Element Plus 组件库，并且演示源码中大量示例也使用了 Element Plus，如果你需要使用 Vexip UI，请拉取框架源码分支，或者到 Github Releases 页面下载框架源码压缩包。
专业版用户也同样，请到专业版仓库下载框架源码。
安装
sh
# 安装依赖
+pnpm install
+
+# 安装 Vexip UI
+pnpm add vexip-ui代码调整
基础版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import { install as vexipInstall } from 'vexip-ui'
+import 'vexip-ui/css/index.css'
+import 'vexip-ui/css/dark/index.css'
+
+function install(app: App) {
+ app.use(vexipInstall, {
+ prefix: 'vxp',
+ })
+}
+
+export default { install }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { zhCNLocale } from 'vexip-ui'
+</script>
+
+<template>
+ <VxpConfigProvider :locale="zhCNLocale()">
+ <slot />
+ </VxpConfigProvider>
+</template>删除相关文件
.
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader专业版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import { install as vexipInstall, zhCNLocale, zhTWLocale, enUSLocale } from 'vexip-ui'
+import 'vexip-ui/css/index.css'
+import 'vexip-ui/css/dark/index.css'
+
+function install(app: App) {
+ app.use(vexipInstall, {
+ prefix: 'vxp',
+ })
+}
+
+// 此处的对象属性和 src/locales/index.ts 中的 messages 对象属性一一对应
+const locales: { [key: string]: any } = {
+ 'zh-cn': zhCNLocale(),
+ 'zh-tw': zhTWLocale(),
+ 'en': enUSLocale(),
+}
+
+export default { install }
+export { locales }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { locales } from './index'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+</script>
+
+<template>
+ <VxpConfigProvider :locale="locales[settingsStore.lang]">
+ <slot />
+ </VxpConfigProvider>
+</template>删除相关文件
.
+├─ plop-templates
+│ └─ module // 标准模块模板基于 Element Plus 开发，需要删除
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ IconPicker
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader修改登录页
由于登录页使用了 Element Plus 组件，并且删除会导致框架无法正常使用，所以此处需要开发者自行修改或者重新制作登录页，或者也可以参考下方示例中已经修改好的登录页。
卸载
sh
# 卸载 Element Plus
+pnpm remove element-plus完成
至此，你已经将框架中的 Element Plus 组件库替换为 Vexip UI 组件库，并且可以开始使用 Vexip UI 进行业务开发了。
示例
如果对上述的步骤还有不清楚的地方，可以访问此仓库查看示例源码，以及此链接查看示例网站。
资源
图片
全局公共
全局公共图片存放在 /src/assets/images/ 目录下，可自行新建文件夹分类管理。
局部私有
局部私有图片建议采用就近原则，你可以在需要的模块文件夹下建立一个 images 文件夹，专门用于存放局部私有图片。
样式
全局公共
全局公共样式存放在 /src/assets/styles/ 目录下，可自行新建文件，并在 /src/main.ts 中引入即可。
此目录下还有一个特殊目录，即 /src/assets/styles/resources/ ，这是全局 SCSS 资源目录，你可以在该目录下编写变量、函数、混合等支持 SCSS 特性的代码。
局部私有
基于单文件组件规范，局部私有样式建议直接在 .vue 文件中编写，框架集成了 UnoCSS / PostCSS / SCSS 方案，可选择自己适合的方案。更多单文件组件 CSS 功能请参考这里。
UnoCSS
vue
<template>
+ <div class="flex flex-1 flex-col select-none text-center all:transition-400">
+ <div class="ma">
+ <div class="animate-bounce-alt animate-duration-1s animate-count-infinite text-5xl fw100">
+ UnoCSS
+ </div>
+ </div>
+ </div>
+</template>PostCSS
框架内置了 postcss-nested 插件，可实现接近于 SCSS 的写法和特性。
vue
<style scoped>
+.phone {
+ &_title {
+ width: 500px;
+ @media (max-width: 500px) {
+ width: auto;
+ }
+ body.is_dark & {
+ color: white;
+ }
+ }
+ img {
+ display: block;
+ }
+}
+</style>SCSS
vue
<style lang="scss" scoped>
+$width: 500px;
+
+.phone {
+ &_title {
+ width: $width;
+ @media (max-width: $width) {
+ width: auto;
+ }
+ body.is_dark & {
+ color: white;
+ }
+ }
+ img {
+ display: block;
+ }
+}
+</style>组件
全局公共
说明
全局公共组件在使用时，无需手动引入，框架会在你使用时自动引入，该特性由 unplugin-vue-components 提供支持。
全局公共组件存放在 /src/components/ 目录下，每个组件按文件夹进行区分。
每个组件的文件夹内至少保留一个文件名为 index.vue 的组件入口（可参考 SvgIcon 组件），文件夹名称即为组件名。
推荐使用 pnpm new 指令进行组件生成，详细可查看《代码文件自动生成》。
局部私有
局部私有组件建议采用就近原则，你可以在需要的模块文件夹下建立一个 components 文件夹，专门用于存放局部私有组件。
基于设置的路由规则，新增的任何路由，都必须登录后才能访问。如果希望增加免登录的页面，也就是脱离框架本身，相对独立的页面，你可以按照下面的方式处理。
首先在 /src/router/index.ts 里 routes 配置免登录页面的路由，然后在 noLoginWhitelist 里增加一句路由完整地址。例如下面的例子，就增加了一个 /no/login/example 的免登录页面地址。
ts
`,3);function c(y,_,F,m,u,x){const a=e("Badge");return p(),t("div",null,[d,r,s("h2",E,[i("免登录页面 "),h(a,{type:"pro",text:"专业版"}),i(),o]),g])}const D=n(k,[["render",c]]);export{C as __pageData,D as default};
diff --git a/assets/guide_router.md.Ct6hq6g7.lean.js b/assets/guide_router.md.Ct6hq6g7.lean.js
new file mode 100644
index 00000000..a0202795
--- /dev/null
+++ b/assets/guide_router.md.Ct6hq6g7.lean.js
@@ -0,0 +1 @@
+import{_ as n,D as e,c as t,j as s,a as i,I as h,a6 as l,o as p}from"./chunks/framework.Bhh1y9_T.js";const C=JSON.parse('{"title":"路由","description":"","frontmatter":{},"headers":[],"relativePath":"guide/router.md","filePath":"guide/router.md"}'),k={name:"guide/router.md"},d=s("h1",{id:"路由",tabindex:"-1"},[i("路由 "),s("a",{class:"header-anchor",href:"#路由","aria-label":'Permalink to "路由"'},"")],-1),r=s("p",null,[i("由于框架采用了全新的交互方式，使得路由在本框架中并非核心功能。通过打开 "),s("code",null,"/src/router/index.ts"),i(" 可以看到，框架一共定义了两个路由地址，一个是登录地址，另一个是登录成功后的地址。")],-1),E={id:"免登录页面",tabindex:"-1"},o=s("a",{class:"header-anchor",href:"#免登录页面","aria-label":'Permalink to "免登录页面 // 固定路由
+const routes = [
+ ...,
+ {
+ path: '/no/login/example',
+ name: 'noLoginExample',
+ component: () => import('@/views/no-login-example.vue'),
+ meta: {
+ title: '免登录页面',
+ },
+ },
+]
+
+// 免登录白名单
+const noLoginWhitelist = [
+ ...,
+ '/no/login/example',
+]使用
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ app: {
+ direction: 'rtl',
+ },
+}效果如下：
开始
做好准备工作后，请在项目根目录下依次执行以下命令：
sh
# 安装依赖
+# 注意，必须使用 pnpm 安装依赖，请勿使用 npm 或 yarn 安装依赖
+pnpm install
+
+# 运行
+pnpm run dev运行成功后，会自动访问页面，默认地址为 http://localhost:9000
报错
安装依赖时提示 404 ，或者安装结束后，运行时提示「 'vite' 不是内部或外部命令，也不是可运行的程序或批处理文件 」，都些都是依赖未安装成功导致的。可以尝试执行 pnpm config set registry https://registry.npmmirror.com/ 切换为国内 npmmirror 源（也可以使用 nrm 一键切换源），然后删除根目录下 /node_modules 文件夹并重新安装依赖。
如果依旧无法运行（基本不太可能），可尝试删除根目录下 /node_modules 文件夹与 pnpm-lock.yaml 文件后，再删除 package.json 中 "preinstall": "npx only-allow pnpm" 这句脚本，最后使用 npm / yarn 进行安装依赖。但需要清楚一点，这样操作后，将无法与官方环境锁定的依赖包版本保持一致，可能会出现无法预知的问题，非必要情况下，请勿使用该方案。
由于 localStorage 和 sessionStorage 的同源策略，同一域名下的 storage 数据会共享。如果你恰好需要在同一域名下部署两套(及以上)系统，不可避免会出现 storage 数据冲突，框架提供了一个 storage 类来解决这个问题。
解决同源 storage 数据冲突的方式就是增加前缀区分，首先需要在应用配置里设置，这里需要你设置一个唯一且不重名的前缀。
ts
const globalSettings: Settings.all = {
+ app: {
+ storagePrefix: 'osa_',
+ },
+}然后在需要使用到 storage 的地方引入：
ts
import storage from '@/utils/storage'这个类封装了 setItem() ，getItem() ，removeItem() ，clear() 方法，同时还增加了一个 has() 方法用来判断对象是否存在：
ts
// localStorage
+storage.local.has(key)
+storage.local.get(key)
+storage.local.set(key, value)
+storage.local.remove(key)
+storage.local.clear()
+
+// sessionStorage
+storage.session.has(key)
+storage.session.get(key)
+storage.session.set(key, value)
+storage.session.remove(key)
+storage.session.clear()注意
由于 localStorage 有容量上限，一般为 5M ，如果一同域名下部署两套系统，意味着两套系统共享 5M 容量，所以不建议在同一域名部署太多套系统，避免出现 localStorage 不够用的情况。
全局状态管理
TIP
Pinia 已正式成为 Vue.js 官方状态库，如果你对 Pinia 还不熟悉，除了通过 Pinia 官网学习外，我还收集了一些文字/视频的介绍，可以帮助你快速上手。
全局状态文件存放在 /src/store/modules/ 目录下，请按模块进行区分。同时请保证文件名和文件内唯一ID保持一致，建议使用 pnpm new 指令进行创建。
例如新建一个 example.ts 的文件：
ts
const useExampleStore = defineStore(
+ // 唯一ID
+ 'example',
+ () => {
+ const someThing = ref(0)
+
+ return {
+ someThing,
+ }
+ },
+)
+
+export default useExampleStore使用方法：
ts
`,7),l=[t];function p(h,k,r,d,o,c){return a(),i("div",null,l)}const y=s(n,[["render",p]]);export{g as __pageData,y as default};
diff --git a/assets/guide_store.md.DBQc3j1R.lean.js b/assets/guide_store.md.DBQc3j1R.lean.js
new file mode 100644
index 00000000..62b5d63e
--- /dev/null
+++ b/assets/guide_store.md.DBQc3j1R.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as e}from"./chunks/framework.Bhh1y9_T.js";const g=JSON.parse('{"title":"全局状态管理","description":"","frontmatter":{},"headers":[],"relativePath":"guide/store.md","filePath":"guide/store.md"}'),n={name:"guide/store.md"},t=e("",7),l=[t];function p(h,k,r,d,o,c){return a(),i("div",null,l)}const y=s(n,[["render",p]]);export{g as __pageData,y as default};
diff --git a/assets/guide_svg-icon.md.Bx5n5Xsc.js b/assets/guide_svg-icon.md.Bx5n5Xsc.js
new file mode 100644
index 00000000..6ba52e80
--- /dev/null
+++ b/assets/guide_svg-icon.md.Bx5n5Xsc.js
@@ -0,0 +1,12 @@
+import{_ as t,D as n,c as e,j as s,a as i,I as l,a6 as p,o as h}from"./chunks/framework.Bhh1y9_T.js";const k="/icones1.png",o="/icones2.png",I=JSON.parse('{"title":"图标","description":"","frontmatter":{},"headers":[],"relativePath":"guide/svg-icon.md","filePath":"guide/svg-icon.md"}'),c={name:"guide/svg-icon.md"},r=p(`import useExampleStore from '@/store/modules/example'
+const exampleStore = useExampleStore()
+
+exampleStore.someThing图标
框架提供了三种使用图标的方式，你可以根据自己的使用需求自行选择。
自定义图标
你可以去阿里巴巴矢量图标库，或者其它支持下载 SVG 图标文件的网站，又或者是设计师绘制的 SVG 文件，将准备好的 SVG 图标文件放到 /src/assets/icons/ 目录下，然后在页面中就可以通过 SvgIcon 组件使用了，name 就是 svg 的文件名。
vue
<!-- /src/assets/icons/example.svg -->
+<SvgIcon name="example" />Iconify 图标
介绍
Iconify 提供 100+ 套图标集，有 100,000+ 个图标可以免费使用。
除了可以在 Iconify 官网上查找搜需要的图标，你还可以在 Icônes 网站 上查找，这是一个基于 Iconify 的在线图标搜索网站，它比 Iconify 官网的操作更直观。
Unocss 方案
说明
Unocss 方案采用了 CSS 去处理图标的展示，框架大部分核心模块里采用的是这种方式，如果你对其中的技术细节感兴趣，可以阅读这篇 Unocss 作者的《聊聊纯 CSS 图标》这篇文章。
框架已经做好了所有配置，使用方式也极为简单，你只需进入 Iconify 官网 上查找 Iconify 提供的所有图标，然后点击需要使用的图标，复制图标名称，在任意原生 HTML 标签上通过设置 class ，格式为 i-{集合名}:{图标名}，例如：
vue
<div class="i-ep:arrow-right" />
+<i class="i-ep:search" />当然你同样也可以通过 SvgIcon 使用它。
vue
<SvgIcon name="i-ep:arrow-right" />在使用 Unocss 图标时，需要注意以下两点：
图标字符串不支持拼接
vue<!-- 这样不会生效 --> +<SvgIcon :name="'i-ep' + ':search'" />图标字符串不支持异步返回
vue<!-- 这样不会生效 --> +<!-- 假设 name 是异步请求返回的数据，name 为 i-ep:search --> +<SvgIcon :name="name" />
如果确实有以上需求，你可以使用 Iconify 原生提供的方案。
Iconify 原生方案
说明
框架保留了 Iconify 官方提供的使用方式，格式为 {集合名}:{图标名} 。
vue
<script setup>
+import { Icon } from '@iconify/vue'
+</script>
+
+<template>
+ <Icon icon="ep:arrow-right" />
+</template>当然这么使用并没有很方便，依旧还是需要手动导入一个 Icon 组件。如果你也觉得麻烦的话，那么你可以使用 SvgIcon 组件来展示，框架已经帮你做好的所有处理。
vue
<SvgIcon name="ep:arrow-right" />离线/内网环境使用
说明
优先推荐使用 Unocss 方案，它不受网络环境限制，且相对于 Iconify 原生方案，它的性能更好。
如果你清楚自己需要使用 Iconify 原生方案，并且想要在离线/内网环境使用，需要做一些额外的配置。因为 Iconify 图标默认是提供在线的服务，即首次调用会触发一个外部网络请求去获取 svg 原始数据，并缓存在 localStorage 和 sessionStorage 中，这样下次再调用的时候，则直接从缓存中获取并展示。
框架提供了一份解决方案，在命令行执行 pnpm run generate:icons ，按照指引选择你需要用到的图标集（此处选择的图标集也是图标选择器里展示的图标集），并选择使用方式为离线。这样再在框架中使用这些图标，就不会触发外部网络请求了，但如果使用选择之外的图标，依旧还是会触发外部网络请求。
主题
框架主题
主题配色存放在 /themes/index.ts 文件中，基础版和专业版内容略有不同。
基础版
ts
import { hex2rgba } from '@unocss/preset-mini/utils'
+
+export const lightTheme = {
+ 'color-scheme': 'light',
+ // 内置 UI
+ '--ui-primary': hex2rgba('#0f0f0f')!.join(' '),
+ '--ui-text': hex2rgba('#fcfcfc')!.join(' '),
+ // 主体
+ '--g-app-bg': '#fff',
+ '--g-main-bg': '#f2f2f2',
+ '--g-border-color': '#f2f2f2',
+ // 头部
+ '--g-header-bg': '#fff',
+ '--g-header-color': '#0f0f0f',
+ '--g-header-menu-color': '#0f0f0f',
+ '--g-header-menu-hover-bg': '#dde1e3',
+ '--g-header-menu-hover-color': '#0f0f0f',
+ '--g-header-menu-active-bg': '#0f0f0f',
+ '--g-header-menu-active-color': '#fff',
+ // 主导航
+ '--g-main-sidebar-bg': '#f2f2f2',
+ '--g-main-sidebar-menu-color': '#0f0f0f',
+ '--g-main-sidebar-menu-hover-bg': '#dde1e3',
+ '--g-main-sidebar-menu-hover-color': '#0f0f0f',
+ '--g-main-sidebar-menu-active-bg': '#0f0f0f',
+ '--g-main-sidebar-menu-active-color': '#fff',
+ // 次导航
+ '--g-sub-sidebar-bg': '#fff',
+ '--g-sub-sidebar-logo-bg': '#0f0f0f',
+ '--g-sub-sidebar-logo-color': '#fff',
+ '--g-sub-sidebar-menu-color': '#0f0f0f',
+ '--g-sub-sidebar-menu-hover-bg': '#dde1e3',
+ '--g-sub-sidebar-menu-hover-color': '#0f0f0f',
+ '--g-sub-sidebar-menu-active-bg': '#0f0f0f',
+ '--g-sub-sidebar-menu-active-color': '#fff',
+ // 工具栏
+ '--g-toolbar-bg': '#fff',
+}
+
+export const darkTheme = {
+ 'color-scheme': 'dark',
+ // 内置 UI
+ '--ui-primary': hex2rgba('#e5e5e5')!.join(' '),
+ '--ui-text': hex2rgba('#0f0f0f')!.join(' '),
+ // 主体
+ '--g-app-bg': '#141414',
+ '--g-main-bg': '#0a0a0a',
+ '--g-border-color': '#15191e',
+ // 头部
+ '--g-header-bg': '#141414',
+ '--g-header-color': '#e5e5e5',
+ '--g-header-menu-color': '#a8a29e',
+ '--g-header-menu-hover-bg': '#141414',
+ '--g-header-menu-hover-color': '#e5e5e5',
+ '--g-header-menu-active-bg': '#e5e5e5',
+ '--g-header-menu-active-color': '#0a0a0a',
+ // 主导航
+ '--g-main-sidebar-bg': '#0a0a0a',
+ '--g-main-sidebar-menu-color': '#a8a29e',
+ '--g-main-sidebar-menu-hover-bg': '#141414',
+ '--g-main-sidebar-menu-hover-color': '#e5e5e5',
+ '--g-main-sidebar-menu-active-bg': '#e5e5e5',
+ '--g-main-sidebar-menu-active-color': '#0a0a0a',
+ // 次导航
+ '--g-sub-sidebar-bg': '#141414',
+ '--g-sub-sidebar-logo-bg': '#0f0f0f',
+ '--g-sub-sidebar-logo-color': '#e5e5e5',
+ '--g-sub-sidebar-menu-color': '#a8a29e',
+ '--g-sub-sidebar-menu-hover-bg': '#0a0a0a',
+ '--g-sub-sidebar-menu-hover-color': '#e5e5e5',
+ '--g-sub-sidebar-menu-active-bg': '#e5e5e5',
+ '--g-sub-sidebar-menu-active-color': '#0a0a0a',
+ // 工具栏
+ '--g-toolbar-bg': '#141414',
+}专业版
与基础版不同，专业版默认提供了 12 款主题，明亮和暗黑模式各 6 款，并且主题在运行时共存，可实现动态切换。
ts
import { hex2rgba } from '@unocss/preset-mini/utils'
+
+export default {
+ light: {
+ // 颜色主题
+ 'color-scheme': 'light',
+ // 内置 UI
+ '--ui-primary': hex2rgba('#0f0f0f')!.join(' '),
+ '--ui-text': hex2rgba('#fcfcfc')!.join(' '),
+ // 主体
+ '--g-app-bg': '#fff',
+ '--g-main-bg': '#f2f2f2',
+ '--g-border-color': '#f2f2f2',
+ // 头部
+ '--g-header-bg': '#fff',
+ '--g-header-color': '#0f0f0f',
+ '--g-header-menu-color': '#0f0f0f',
+ '--g-header-menu-hover-bg': '#dde1e3',
+ '--g-header-menu-hover-color': '#0f0f0f',
+ '--g-header-menu-active-bg': '#0f0f0f',
+ '--g-header-menu-active-color': '#fff',
+ // 主导航
+ '--g-main-sidebar-bg': '#f2f2f2',
+ '--g-main-sidebar-menu-color': '#0f0f0f',
+ '--g-main-sidebar-menu-hover-bg': '#dde1e3',
+ '--g-main-sidebar-menu-hover-color': '#0f0f0f',
+ '--g-main-sidebar-menu-active-bg': '#0f0f0f',
+ '--g-main-sidebar-menu-active-color': '#fff',
+ // 次导航
+ '--g-sub-sidebar-bg': '#fff',
+ '--g-sub-sidebar-logo-bg': '#0f0f0f',
+ '--g-sub-sidebar-logo-color': '#fff',
+ '--g-sub-sidebar-menu-color': '#0f0f0f',
+ '--g-sub-sidebar-menu-hover-bg': '#dde1e3',
+ '--g-sub-sidebar-menu-hover-color': '#0f0f0f',
+ '--g-sub-sidebar-menu-active-bg': '#0f0f0f',
+ '--g-sub-sidebar-menu-active-color': '#fff',
+ // 工具栏
+ '--g-toolbar-bg': '#fff',
+ },
+ ...
+ dark: {
+ // 颜色主题
+ 'color-scheme': 'dark',
+ // 内置 UI
+ '--ui-primary': hex2rgba('#e5e5e5')!.join(' '),
+ '--ui-text': hex2rgba('#0f0f0f')!.join(' '),
+ // 主体
+ '--g-app-bg': '#141414',
+ '--g-main-bg': '#0a0a0a',
+ '--g-border-color': '#15191e',
+ // 头部
+ '--g-header-bg': '#141414',
+ '--g-header-color': '#e5e5e5',
+ '--g-header-menu-color': '#a8a29e',
+ '--g-header-menu-hover-bg': '#141414',
+ '--g-header-menu-hover-color': '#e5e5e5',
+ '--g-header-menu-active-bg': '#e5e5e5',
+ '--g-header-menu-active-color': '#0a0a0a',
+ // 主导航
+ '--g-main-sidebar-bg': '#0a0a0a',
+ '--g-main-sidebar-menu-color': '#a8a29e',
+ '--g-main-sidebar-menu-hover-bg': '#141414',
+ '--g-main-sidebar-menu-hover-color': '#e5e5e5',
+ '--g-main-sidebar-menu-active-bg': '#e5e5e5',
+ '--g-main-sidebar-menu-active-color': '#0a0a0a',
+ // 次导航
+ '--g-sub-sidebar-bg': '#141414',
+ '--g-sub-sidebar-logo-bg': '#0f0f0f',
+ '--g-sub-sidebar-logo-color': '#e5e5e5',
+ '--g-sub-sidebar-menu-color': '#a8a29e',
+ '--g-sub-sidebar-menu-hover-bg': '#0a0a0a',
+ '--g-sub-sidebar-menu-hover-color': '#e5e5e5',
+ '--g-sub-sidebar-menu-active-bg': '#e5e5e5',
+ '--g-sub-sidebar-menu-active-color': '#0a0a0a',
+ // 工具栏
+ '--g-toolbar-bg': '#141414',
+ },
+ ...
+}如果框架提供的主题风格满足不了你的需求，你还可以自定义新的主题。
ts
import { hex2rgba } from '@unocss/preset-mini/utils'
+
+export default {
+ newThemeName: { // 主题名称
+ // 颜色主题
+ 'color-scheme': 'light', // 可选值 light/dark ，表示该主题在明亮或暗黑模式下的配色
+ // 内置 UI
+ '--ui-primary': hex2rgba('#409eff')!.join(' '),
+ '--ui-text': hex2rgba('#fcfcfc')!.join(' '),
+ // 主体
+ '--g-app-bg': '#fff',
+ '--g-main-bg': '#f2f2f2',
+ '--g-border-color': '#f2f2f2',
+ // 头部
+ '--g-header-bg': '#222b45',
+ '--g-header-color': '#fff',
+ '--g-header-menu-color': '#fff',
+ '--g-header-menu-hover-bg': '#334067',
+ '--g-header-menu-hover-color': '#fff',
+ '--g-header-menu-active-bg': '#334067',
+ '--g-header-menu-active-color': '#fff',
+ // 主导航
+ '--g-main-sidebar-bg': '#222b45',
+ '--g-main-sidebar-menu-color': '#fff',
+ '--g-main-sidebar-menu-hover-bg': '#334067',
+ '--g-main-sidebar-menu-hover-color': '#fff',
+ '--g-main-sidebar-menu-active-bg': '#334067',
+ '--g-main-sidebar-menu-active-color': '#fff',
+ // 次导航
+ '--g-sub-sidebar-bg': '#fff',
+ '--g-sub-sidebar-logo-bg': '#222b45',
+ '--g-sub-sidebar-logo-color': '#fff',
+ '--g-sub-sidebar-menu-color': '#0f0f0f',
+ '--g-sub-sidebar-menu-hover-bg': '#dde1e3',
+ '--g-sub-sidebar-menu-hover-color': '#0f0f0f',
+ '--g-sub-sidebar-menu-active-bg': '#409eff',
+ '--g-sub-sidebar-menu-active-color': '#fff',
+ // 工具栏
+ '--g-toolbar-bg': '#fff',
+ },
+}最后在应用配置中使用该主题：
ts
const globalSettings: Settings.all = {
+ app: {
+ // 如果主题是暗黑模式下使用的，则 darkTheme: 'newThemeName'
+ lightTheme: 'newThemeName',
+ },
+}颜色方案
在应用配置中设置：
ts
`,16),F={id:"哀悼模式",tabindex:"-1"},y=i("a",{class:"header-anchor",href:"#哀悼模式","aria-label":'Permalink to "哀悼模式 const globalSettings: Settings.all = {
+ app: {
+ /**
+ * 留空跟随系统
+ * light 明亮模式
+ * dark 暗黑模式
+ */
+ colorScheme: '',
+ },
+}在应用配置中设置：
ts
`,2),o={id:"色弱模式",tabindex:"-1"},C=i("a",{class:"header-anchor",href:"#色弱模式","aria-label":'Permalink to "色弱模式 const globalSettings: Settings.all = {
+ app: {
+ enableMournMode: true,
+ },
+}在应用配置中设置：
ts
`,2),b={id:"导航栏风格",tabindex:"-1"},f=i("a",{class:"header-anchor",href:"#导航栏风格","aria-label":'Permalink to "导航栏风格 const globalSettings: Settings.all = {
+ app: {
+ enableColorAmblyopiaMode: true,
+ },
+}风格
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ menu: {
+ /**
+ * 留空默认
+ * arrow 箭头
+ * line 线条
+ * dot 圆点
+ */
+ style: '', // v4.5.0 之前版本为 menuActiveStyle
+ },
+}圆角
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ menu: {
+ // 导航栏是否圆角
+ isRounded: true,
+ },
+}开发注意
如果只在明亮或暗黑模式中，选择其中一种模式进行业务开发，那没有什么需要注意的，你可以按照以往的开发习惯进行开发，这也是框架推荐的方式。
但如果需要让用户可以自己选择明亮或暗黑模式，或者是根据浏览器主题来判断是使用明亮还是暗黑模式。这时候开发则需要注意，业务页面里使用到的颜色将不能写成固定值（例如 color 、background-color 、border-color 、box-shadow 等有涉及到颜色的属性），因为同一个色值是无法顾及到明亮和暗黑两种模式的。
这时候我们建议使用 UnoCSS 进行样式编写，例如 text-dark dark-text-white 、bg-green dark-bg-red 。如果你不习惯使用 UnoCSS ，那也可以使用下面这种方法，在页面中去自定义一些颜色。
scss
div {
+ color: #000;
+
+ [data-theme="dark"] & {
+ color: #fff;
+ }
+}最后分享一篇关于暗黑模式的文章《教你巧用UI设计中的暗黑模式——Dark Mode》，希望帮助你更好地在暗黑模式下开发出优秀的页面。
`,14);function m(A,D,v,_,x,S){const n=l("Badge");return t(),p("div",null,[d,i("h2",F,[s("哀悼模式 "),h(n,{type:"tip",text:"v4.5.0 新增"}),s(),y]),c,i("h2",o,[s("色弱模式 "),h(n,{type:"tip",text:"v4.5.0 新增"}),s(),C]),B,i("h2",b,[s("导航栏风格 "),h(n,{type:"pro",text:"专业版"}),s(),f]),u])}const q=k(g,[["render",m]]);export{P as __pageData,q as default}; diff --git a/assets/guide_theme.md.BLSJm2vH.lean.js b/assets/guide_theme.md.BLSJm2vH.lean.js new file mode 100644 index 00000000..4f5df861 --- /dev/null +++ b/assets/guide_theme.md.BLSJm2vH.lean.js @@ -0,0 +1 @@ +import{_ as k,D as l,c as p,j as i,a as s,I as h,a6 as a,o as t}from"./chunks/framework.Bhh1y9_T.js";const e="/theme.gif",E="/menu-style.png",r="/menu-isrounded.png",P=JSON.parse('{"title":"主题","description":"","frontmatter":{},"headers":[],"relativePath":"guide/theme.md","filePath":"guide/theme.md"}'),g={name:"guide/theme.md"},d=a("",16),F={id:"哀悼模式",tabindex:"-1"},y=i("a",{class:"header-anchor",href:"#哀悼模式","aria-label":'Permalink to "哀悼模式工具栏
工具栏主要是红框处各类功能图标。
窗口预览
在应用配置中设置：
ts
`,6),r={id:"收藏夹",tabindex:"-1"},g=i("a",{class:"header-anchor",href:"#收藏夹","aria-label":'Permalink to "收藏夹 const globalSettings: Settings.all = {
+ toolbar: {
+ previewWindows: true,
+ },
+}在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ toolbar: {
+ favorites: true,
+ },
+}详细可阅读《收藏夹》。
导航搜索
在应用配置中设置：
ts
`,6),c={id:"通知中心",tabindex:"-1"},y=i("a",{class:"header-anchor",href:"#通知中心","aria-label":'Permalink to "通知中心 const globalSettings: Settings.all = {
+ toolbar: {
+ navSearch: true,
+ },
+}在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ toolbar: {
+ notification: true,
+ },
+}通知中心不涉及具体业务，需开发者自行实现，相关文件在：
/src/views/components/Tools/Notification/index.vue通知中心下拉预览面板/src/views/windows/PersonalNotification/index.vue通知中心页面
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ toolbar: {
+ i18n: true,
+ },
+}如果设置为不启用，并不代表不支持国际化切换，只是不会在工具栏显示切换语言的图标，详细可阅读《国际化》。
浏览器全屏
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ toolbar: {
+ fullscreen: true,
+ },
+}颜色主题
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ toolbar: {
+ colorScheme: true,
+ },
+}如果设置为不启用，并不代表不支持颜色主题切换，只是不会在工具栏显示切换颜色主题的图标。
`,10),u={id:"布局",tabindex:"-1"},v=i("a",{class:"header-anchor",href:"#布局","aria-label":'Permalink to "布局在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ toolbar: {
+ layout: ['previewWindows', 'favorites', '->', 'navSearch', 'notification', 'i18n', 'fullscreen', 'colorScheme'],
+ },
+}可自定义摆放位置和顺序，其中 -> 为分隔符，用于分隔左右两侧的工具栏。修改时请确保提供的所有值都存在，不可删减。
框架更新
首先明确一点，One-step-admin 无法像 npm 的插件一样更新，不仅我们的框架如此，其实大部分管理系统框架都是如此。
因为本质上这类框架其实是一个初始模板，开发者会根据自身需求去修改，然后基于业务开展业务代码编写。
所以一旦下载开始使用，基本是无法更新的，你在哪个时间点开始使用，项目就固定在什么版本了。
虽然有小部分框架选择将部分核心源码封装成 npm 依赖包，由作者全权维护，这样的处理在一定程度上有解决版本更新的问题，但弊端也很明显，开发者在二次开发上会有明显的局限，作者认为是得不偿失的。
那有没有解决办法么？其实也有，参考如下：
- 在基于 One-step-admin 做项目开发时尽量避免框架自带模块或组件的改动，或者改动地方做一个文档记录，可以清楚知道改动了哪些，这样当你需要进行新版本更新时，按照之前记录的文档可以有个大致的迁移方案，而业务代码则可以直接拷贝过去。
- 我们尽量在提交代码时标明每次提交改动的变更记录说明，这样你可以选择性的更新部分新代码到项目中，也就是局部更新。这种方案也是作者在公司内部项目经常使用的，因为大部分项目是无需全局更新到新版的，只需将必要的一些新特性或 bug 修复同步到原有项目中即可。
- 使用文件比较工具，例如 Beyond Compare，这款工具可以直接对比文件夹，可以清晰的列出文件夹内所有文件的差异，可以协助升级工作开展。
当然个人建议是，做为一个中后台系统框架，稳定是第一诉求，不到万不得已不建议频繁更新，因为更新的成本挺高的，每一次大更新，都需要一次完整的回归测试，以确保功能正常运行。
',8),n=[r];function i(s,_,d,c,l,u){return a(),t("div",null,n)}const h=e(p,[["render",i]]);export{g as __pageData,h as default}; diff --git a/assets/guide_upgrade.md.eXeFHhaS.lean.js b/assets/guide_upgrade.md.eXeFHhaS.lean.js new file mode 100644 index 00000000..8b0e8916 --- /dev/null +++ b/assets/guide_upgrade.md.eXeFHhaS.lean.js @@ -0,0 +1 @@ +import{_ as e,c as t,o as a,a6 as o}from"./chunks/framework.Bhh1y9_T.js";const g=JSON.parse('{"title":"框架更新","description":"","frontmatter":{},"headers":[],"relativePath":"guide/upgrade.md","filePath":"guide/upgrade.md"}'),p={name:"guide/upgrade.md"},r=o("",8),n=[r];function i(s,_,d,c,l,u){return a(),t("div",null,n)}const h=e(p,[["render",i]]);export{g as __pageData,h as default}; diff --git a/assets/guide_vue3-composition-api.md.D_pqF34C.js b/assets/guide_vue3-composition-api.md.D_pqF34C.js new file mode 100644 index 00000000..7cbd4b38 --- /dev/null +++ b/assets/guide_vue3-composition-api.md.D_pqF34C.js @@ -0,0 +1,19 @@ +import{_ as s,c as i,o as a,a6 as t}from"./chunks/framework.Bhh1y9_T.js";const c=JSON.parse('{"title":"使用 Composition API 开发","description":"","frontmatter":{},"headers":[],"relativePath":"guide/vue3-composition-api.md","filePath":"guide/vue3-composition-api.md"}'),n={name:"guide/vue3-composition-api.md"},p=t(`使用 Composition API 开发
TIP
Composition API 是 Vue3 全新提供的一种语法，对于从 Vue2 就在使用的开发者，如果一时半会没办法立马上手 Composition API ，你依旧可以在项目中使用 Options API 做开发。当然我们更建议你使用 Composition API 进行开发，它比 Options API 更灵活且易读。
使用
如果你还不熟悉 Composition API ，那么我们建议你阅读 Vue3 官方文档了解；如果你已经熟悉 Composition API ，那么我们建议你在开发的时候，使用 <script setup> 语法糖进行开发，它将提高很多开发上的效率。
同时得益于 unplugin-auto-import 的特性，在 <script setup> 里无需导入相关 API ，该依赖会自动导入（默认支持 vue，vue-router 和 pinia ）。
vue
<script setup lang="ts">
+// 无需手动 import 相关 API
+import { computed, ref } from 'vue'
+
+const count = ref(0)
+const doubled = computed(() => count.value * 2)
+</script>组件 name
<script setup> 可以和普通的 <script> 一起使用，所以可以这样定义组件 name：
vue
<script lang="ts">
+export default {
+ name: 'componentName',
+}
+</script>
+
+<script setup lang="ts">
+...
+</script>Vue 3.3 开始，你可以使用 defineOptions 在 <script setup> 里定义组件的 name：
vue
`,11),h=[p];function e(l,k,r,o,E,d){return a(),i("div",null,h)}const u=s(n,[["render",e]]);export{c as __pageData,u as default};
diff --git a/assets/guide_vue3-composition-api.md.D_pqF34C.lean.js b/assets/guide_vue3-composition-api.md.D_pqF34C.lean.js
new file mode 100644
index 00000000..897dd1e7
--- /dev/null
+++ b/assets/guide_vue3-composition-api.md.D_pqF34C.lean.js
@@ -0,0 +1 @@
+import{_ as s,c as i,o as a,a6 as t}from"./chunks/framework.Bhh1y9_T.js";const c=JSON.parse('{"title":"使用 Composition API 开发","description":"","frontmatter":{},"headers":[],"relativePath":"guide/vue3-composition-api.md","filePath":"guide/vue3-composition-api.md"}'),n={name:"guide/vue3-composition-api.md"},p=t("",11),h=[p];function e(l,k,r,o,E,d){return a(),i("div",null,h)}const u=s(n,[["render",e]]);export{c as __pageData,u as default};
diff --git a/assets/guide_watermark.md.Bfkh7IZ2.js b/assets/guide_watermark.md.Bfkh7IZ2.js
new file mode 100644
index 00000000..1b9bc102
--- /dev/null
+++ b/assets/guide_watermark.md.Bfkh7IZ2.js
@@ -0,0 +1,17 @@
+import{_ as t,D as n,c as e,j as a,a as s,I as p,a6 as l,o as h}from"./chunks/framework.Bhh1y9_T.js";const k="/watermark.png",b=JSON.parse('{"title":"页面水印","description":"","frontmatter":{},"headers":[],"relativePath":"guide/watermark.md","filePath":"guide/watermark.md"}'),r={name:"guide/watermark.md"},d={id:"页面水印",tabindex:"-1"},E=a("a",{class:"header-anchor",href:"#页面水印","aria-label":'Permalink to "页面水印 <script setup lang="ts">
+defineOptions({
+ name: 'ComponentName',
+})
+</script>使用
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ app: {
+ enableWatermark: true,
+ },
+}效果如下：
设置水印内容
在 /src/store/modules/watermark.ts 中可修改水印展示内容，以及其他水印相关配置。
水印同时支持动态更新，示例：
vue
`,9);function g(c,y,m,F,u,_){const i=n("Badge");return h(),e("div",null,[a("h1",d,[s("页面水印 "),p(i,{type:"pro",text:"专业版"}),s(),E]),o])}const B=t(r,[["render",g]]);export{b as __pageData,B as default};
diff --git a/assets/guide_watermark.md.Bfkh7IZ2.lean.js b/assets/guide_watermark.md.Bfkh7IZ2.lean.js
new file mode 100644
index 00000000..bd372d59
--- /dev/null
+++ b/assets/guide_watermark.md.Bfkh7IZ2.lean.js
@@ -0,0 +1 @@
+import{_ as t,D as n,c as e,j as a,a as s,I as p,a6 as l,o as h}from"./chunks/framework.Bhh1y9_T.js";const k="/watermark.png",b=JSON.parse('{"title":"页面水印","description":"","frontmatter":{},"headers":[],"relativePath":"guide/watermark.md","filePath":"guide/watermark.md"}'),r={name:"guide/watermark.md"},d={id:"页面水印",tabindex:"-1"},E=a("a",{class:"header-anchor",href:"#页面水印","aria-label":'Permalink to "页面水印 <script setup lang="ts">
+import useWatermarkStore from '@/store/modules/watermark'
+
+const watermarkStore = useWatermarkStore()
+
+watermarkStore.update({
+ text: '设置水印',
+ // 更多设置项请查看 /src/utils/watermark.ts 中 settingsType 类型定义
+})
+
+// 重置水印，恢复到默认设置
+watermarkStore.update()
+</script>高效的交互方式
摆脱传统后台框架路由跳转的交互，将每个模块以窗口的形式展示在同一个界面中，让使用人员可以做到跨模块的多线操作。
窗口最大化
窗口默认宽度为 800px ，可以在项目中进行调整，也可以通过最大化按钮将窗口最大化展示，以便展示更多信息。
快速定位操作窗口
提供的预览界面可以帮助使用人员快速定位到需要操作的窗口。
专注模式
可勾选多个窗口平均分布在页面中，专注于所勾选的窗口进行操作。
窗口排序
快速调整窗口的展示顺序。
继承自 Fantastic-admin
本框架继承了 Fantastic-admin 许多优秀的特性。例如同样提供了 5 款导航栏模式，3 款导航栏风格以及 6 款主题配色，导航也提供了各种展示形态的设置，显隐、标题、图标、徽标、外链等。
为什么不是 Fantastic-admin ?
这里的 Fantastic-admin 代表了市面上几乎所有的传统后台框架，它们的优势在于理解成本低，每个页面的功能明确，需要做什么操作就进入不同的页面。
而劣势也是因为这种优势导致的，例如要在多个模块之间进行操作，就需要频繁切换路由，而切换路由会导致之前页面上的数据丢失，进而扩展了页面缓存和标签栏的特性，但也变相增加了开发人员的开发成本。其次现在的显示器都在往高分屏/带鱼屏发展，当页面展示内容不多的时候，界面上会显示大量的留白，造成空间浪费。
基于传统后台框架的这些痛点，One-step-admin 应运而生，它探索出了一种全新的交互方式，有效提高了使用人员的操作效率，同时也减轻了开发人员的开发成本。
以上面举例的场景，在 One-step-admin 里，因为模块都以窗口的形式在同一个界面上展示，所以就不存在切换路由，也就不存在切换路由导致页面数据丢失的场景，开发人员只需关注模块内的业务实现即可。
',22),F=JSON.parse('{"title":"为什么选择我们 ?","description":"","frontmatter":{},"headers":[],"relativePath":"guide/why.md","filePath":"guide/why.md"}'),q={name:"guide/why.md"},O=Object.assign(q,{setup(x){const e="2021/11/01",n=new Date().getTime()/1e3-new Date(e).getTime()/1e3,o=parseInt(n/60/60/24);return(P,k)=>(l(),r("div",null,[u,f,g,a("p",null,[t("One-step-admin 自 "+i(e)+" 正式对外发布，截止到今天为止，已持续维护 "),a("strong",null,i(s(o)),1),t(" 天。")]),b]))}});export{F as __pageData,O as default}; diff --git a/assets/guide_why.md.DBObFHbq.lean.js b/assets/guide_why.md.DBObFHbq.lean.js new file mode 100644 index 00000000..13bb94db --- /dev/null +++ b/assets/guide_why.md.DBObFHbq.lean.js @@ -0,0 +1 @@ +import{c as r,j as a,a as t,t as i,k as s,a6 as d,o as l}from"./chunks/framework.Bhh1y9_T.js";const c="/intro-1.gif",h="/intro-2.gif",p="/intro-3.gif",m="/intro-4.gif",_="/intro-5.gif",u=a("h1",{id:"为什么选择我们",tabindex:"-1"},[t("为什么选择我们 ? "),a("a",{class:"header-anchor",href:"#为什么选择我们","aria-label":'Permalink to "为什么选择我们 ?"'},"")],-1),f=a("p",null,"如果你正在做后台框架相关的调研或选型，相信这篇介绍能帮助你快速了解 One-step-admin 的特点，以及与传统后台框架的对比。",-1),g=a("h2",{id:"长期且稳定",tabindex:"-1"},[t("长期且稳定 "),a("a",{class:"header-anchor",href:"#长期且稳定","aria-label":'Permalink to "长期且稳定"'},"")],-1),b=d("",22),F=JSON.parse('{"title":"为什么选择我们 ?","description":"","frontmatter":{},"headers":[],"relativePath":"guide/why.md","filePath":"guide/why.md"}'),q={name:"guide/why.md"},O=Object.assign(q,{setup(x){const e="2021/11/01",n=new Date().getTime()/1e3-new Date(e).getTime()/1e3,o=parseInt(n/60/60/24);return(P,k)=>(l(),r("div",null,[u,f,g,a("p",null,[t("One-step-admin 自 "+i(e)+" 正式对外发布，截止到今天为止，已持续维护 "),a("strong",null,i(s(o)),1),t(" 天。")]),b]))}});export{F as __pageData,O as default}; diff --git a/assets/guide_window.md.s_rE98aQ.js b/assets/guide_window.md.s_rE98aQ.js new file mode 100644 index 00000000..321ca13a --- /dev/null +++ b/assets/guide_window.md.s_rE98aQ.js @@ -0,0 +1 @@ +import{_ as e,c as o,o as t,a6 as a}from"./chunks/framework.Bhh1y9_T.js";const w=JSON.parse('{"title":"窗口","description":"","frontmatter":{},"headers":[],"relativePath":"guide/window.md","filePath":"guide/window.md"}'),c={name:"guide/window.md"},d=a('窗口
窗口即组件，存放在 /src/views/windows/ 目录下，类似于全局组件，文件夹名即为组件名，在窗口打开的时候会动态加载组件。
每个窗口的文件夹内至少保留一个文件名为 index.vue 的入口文件。
注意
由于窗口展示的特殊性，请勿在窗口组件内使用 position: fixed; 样式。
技术支持
基础版
在使用框架的过程中难免会遇到问题，优先推荐在仓库提交 Issue ，你可以更详细描述问题产生的操作步骤，或者提供完整的最小复现，这样做可以让更多的人参与讨论，也方便后人查阅。
专业版
购买专业版的用户可以加我微信直接和我一对一沟通使用问题。
',6),n={align:"center"},l=["src"],p=JSON.parse('{"title":"技术支持","description":"","frontmatter":{},"headers":[],"relativePath":"support.md","filePath":"support.md"}'),c={name:"support.md"},m=Object.assign(c,{setup(_){return(h,d)=>(r(),a("div",null,[o,e("p",n,[e("img",{src:t(i)("/friend-wechat.png"),width:"300"},null,8,l)])]))}});export{p as __pageData,m as default}; diff --git a/assets/support.md.C9-w0WzG.lean.js b/assets/support.md.C9-w0WzG.lean.js new file mode 100644 index 00000000..45410c3c --- /dev/null +++ b/assets/support.md.C9-w0WzG.lean.js @@ -0,0 +1 @@ +import{c as a,j as e,k as t,a6 as s,o as r,g as i}from"./chunks/framework.Bhh1y9_T.js";const o=s("",6),n={align:"center"},l=["src"],p=JSON.parse('{"title":"技术支持","description":"","frontmatter":{},"headers":[],"relativePath":"support.md","filePath":"support.md"}'),c={name:"support.md"},m=Object.assign(c,{setup(_){return(h,d)=>(r(),a("div",null,[o,e("p",n,[e("img",{src:t(i)("/friend-wechat.png"),width:"300"},null,8,l)])]))}});export{p as __pageData,m as default}; diff --git a/buy.html b/buy.html new file mode 100644 index 00000000..5c245371 --- /dev/null +++ b/buy.html @@ -0,0 +1,33 @@ + + + + + + Skip to content 
购买专业版
专业版超值优惠合集①：One-step-admin ＋ Fantastic-admin
原价：￥999.00 One-step-admin ＋ ￥1199.00 Fantastic-admin ＝ ￥2198.00
合集优惠价：￥1299.00 (本价格不参与任何限时优惠活动)
请加作者微信进行购买
专业版超值优惠合集②：One-step-admin ＋ Fantastic-mobile
原价：￥999.00 One-step-admin ＋ ￥599.00 Fantastic-mobile ＝ ￥1598.00
合集优惠价：￥899.00 (本价格不参与任何限时优惠活动)
请加作者微信进行购买
专业版超值优惠合集③：One-step-admin ＋ Fantastic-admin ＋ Fantastic-mobile
原价：￥999.00 One-step-admin ＋ ￥1199.00 Fantastic-admin ＋ ￥599.00 Fantastic-mobile ＝ ￥2797.00
合集优惠价：￥1499.00 (本价格不参与任何限时优惠活动)
请加作者微信进行购买
购买流程
- 请先加作者微信进行在线咨询。
- 通过微信或支付宝扫码支付，并在备注里留下手机/微信/QQ/邮箱等任意一种联系方式。
- 支付成功后需提供：
- 付款截图凭证
- 授权邮箱号（常用邮箱）。专业版客户的唯一凭证，用于接收框架相关通知公告的唯一方式，但通常情况下我们不会随意打扰你。
- Github 用户名。专业版源码托管在 Github 平台，需提供你的 Github 用户名，我们会邀请你加入组织。
- 同意邀请后，进入专业版开发者私有组织，获取源码。
支付方式
领红包
若你打算使用支付宝进行付款，可以先扫下面这个二维码领取红包。
| One-step-admin 专业版 | |
|---|---|
限时优惠：￥699.00 原价：￥999.00 | |
 |  |
产品生命周期内提供长期更新维护 | |
企业/团队购买
如果你有以下场景需求，推荐购买企业/团队版：
- 我们是公司，开发团队有多名开发者，需要都能加入到 Github 组织；同时考虑到人员流动，需要可以更换加入到 Github 组织的开发者账号
- 我们是给客户开发项目的，开发完毕后需要将完整源码一起交付给客户
- 我们希望能有一个独立的技术支持微信群，方便我们的开发者可以随时咨询框架相关问题
| One-step-admin 专业版 (企业/团队版) | |
|---|---|
限时优惠：￥2799.00 原价：￥3599.00 |
| ⭐服务⭐ | 个人 | 企业/团队 |
|---|---|---|
| 允许加入 Github 组织账号数 | 1 | 5 |
| 是否允许二开后交付源码 | ✅ | |
| 提供独立技术支持微信群 | ✅ | |
| 是否可以开发票 | 支持开普票，价格已含税 |
使用说明
- 购买者可将本产品用于任意「符合国家法律法规」的应用平台，禁止用于黄赌毒等危害国家安全与稳定的网站。
- 本产品购买后可用于开发商业项目，不限制域名和项目数量。
- 购买者需保证不传播产品源码，不得直接对本产品（或简单包装成同类产品）进行二次转售或发布。无论有意或无意，我们有权利收回产品授权及更新权限。
- 本产品的源码（包含全部源码，及部分源码片段），在未经我们许可下，不可以用于任何形式的开源项目，否则我们有权利收回产品授权及更新权限。
- 因使用本产品所产生的损害及风险，包括但不限于个人损害、商业赢利丧失、贸易中断、商业信息丢失或任何其它经济损失，需由购买者自行承担，我们不承担任何责任。
- 虚拟物品不支持退货退款。
- 最终解释权归 One-step-admin 所有。
专业版与基础版区别
| ⭐功能与服务⭐ | 基础版 | 专业版 |
|---|---|---|
| 长期维护更新，提供新特性 | ✅ | |
| 定期修复 bug | ✅ | |
| 开发与构建工具 | Vue 3 / Vite | |
| UI 组件库 | Element Plus | |
| 页面布局 | 3 套 | 5 套 |
| 主题风格 | 明亮 1 款 / 暗黑 1 款 | 明亮 6 款 / 暗黑 6 款 |
| 导航路由配置项 | 5 个 | 8 个 |
| 外链导航 | ✅ | ✅ |
| 窗口 API | 支持部分 | ✅ |
| 窗口右键功能 | ✅ | |
| 窗口预览模式 | ✅ | ✅ |
| 窗口专注模式 | ✅ | |
| 窗口拖拽排序 | ✅ | |
| 收藏夹 | ✅ | |
| 全方位权限验证 | ✅ | ✅ |
| 扩展组件 | 12 个 | 20 个 |
| 用户偏好设置 | ✅ | |
| 国际化 | ✅ | |
| Mock 数据 | ✅ | ✅ |
| 错误日志上报 | ✅ | |
| 文件自动生成 | 支持部分 | ✅ |
| 业务应用静态页面 | ✅ | |
| 团队代码规范 | ✅ | ✅ |
| 框架版权信息 | 需保留 | 可删除 |
| 技术支持 | 查看 | |
| 演示地址 | 访问 | 访问 |
什么场景需要 One-step-admin
- 没有前端开发人员的小型公司。 据了解，有些小型公司没有前端开发人员，而这些公司在开发中后台系统的时候，直接要求后端开发人员来进行开发工作。所以借助 Vue 的易学习易上手特性，再加上本框架的加持，可以让后端开发人员能在短时间内转型成为全栈开发。
- 前端开发人员不足的中小型公司。 根据招聘网站统计，几乎所有公司都缺前端，其中有很大一部分中小型公司标配只有1-2名前端开发人员，而这些公司在开发中后台系统的时候，如果能有一套现成的中后台框架系统，不仅能提高项目开发效率，同时还大大减轻前端开发人员工作压力。
- 项目型公司。 特点为项目多，周期短，甲方对页面布局和主题风格有绝对话语权，而通过专业版提供的布局和主题风格，可应对绝大部分甲方需求，并且可自定义扩展主题风格的样式，实现高度定制化。
- 产品型公司。 产品型公司最担心的就是产品开发中代码不可控的因素，本框架除了提供完善的开发文档和代码注释外，作者还提供一对一的技术支持，确保开发人员尽可能理解整套框架源码的方方面面，为产品保驾护航。
- 个人开发者。 手里有一套可高度定制化的中后台框架，什么项目都不用担心啦~
为什么选择 One-step-admin
- 作者拥有10年+的前后端开发经验。 部分框架的作者由于缺少后端开发经验，可能会在设计框架的时候，很少或者没有考虑后端的实现逻辑，导致框架在实际使用中，业务场景无法落地，开发人员得通过修改源码自行实现业务。
- 经历过数十个真实项目的打磨。 没用在真实业务场景中使用过的框架都是纸飞机，哪怕它提供的演示功能特别华丽。而本框架在作者就职的公司，已经稳定应用在电商、直播、OA、CRM、ERP等多个不同领域的中后台系统中。
- 丰富的组件库。 除了支持 Element Plus 自带的组件外，框架还扩充了部分业务组件，以及第三方插件。借助以往的项目经验，提供最佳实践方案，方便开发人员直接使用。
- 持续更新的业务应用静态页面。 通过项目积累，沉淀出数十个业务应用的静态页面，做到开发人员拿来即可使用，极大提升开发效率的同时，还省去了产品和设计人员的工作。
- 长期维护。 无论是免费的基础版，还是付费的专业版，均提供长期维护。区别在于基础版侧重于稳定性维护，主要在修复 bug ，不定期增加新特性；专业版侧重于新特性开发，在确保稳定的基础上，会长期深挖中后台系统框架，持续产出可落地的特性或开发规范。
Skip to content
FileUpload 文件上传
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| action | 必选参数，上传的地址 | string | - | - |
| headers | 设置上传的请求头部 | object | - | - |
| data | 上传时附带的额外参数 | object | - | - |
| name | 上传的文件字段名 | string | - | file |
| size | 上传文件大小限制，单位为MB | number | - | 2 |
| max | 上传数量限制 | number | - | 3 |
| files | 上传的文件列表，例如：[{name: 'xxx.jpg', url: 'http://xxx.cdn.com/xxx.jpg'}] | array | - | [] |
| notip | 是否隐藏提示栏 | boolean | - | false |
| ext | 支持的文件类型 | array | - | ['zip', 'rar'] |
Skip to content
ImageUpload 单图上传
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| v-model | 图片地址 | string | - | - |
| action | 必选参数，上传的地址 | string | - | - |
| headers | 设置上传的请求头部 | object | - | - |
| data | 上传时附带的额外参数 | object | - | - |
| name | 上传的文件字段名 | string | - | file |
| size | 上传文件大小限制，单位为MB | number | - | 2 |
| width | 展示宽度 | number | - | 150 |
| height | 展示高度 | number | - | 150 |
| placeholder | 占位图 | string | - | - |
| notip | 是否隐藏提示栏 | boolean | - | false |
| ext | 支持的文件类型 | array | - | ['jpg', 'png', 'gif', 'bmp'] |
Skip to content
ImagesUpload 多图上传
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| v-model | 图片列表 | array | - | [] |
| action | 必选参数，上传的地址 | string | - | - |
| headers | 设置上传的请求头部 | object | - | - |
| data | 上传时附带的额外参数 | object | - | - |
| name | 上传的文件字段名 | string | - | file |
| max | 上传数量限制 | number | - | 3 |
| size | 上传文件大小限制，单位为MB | number | - | 2 |
| width | 展示宽度 | number | - | 150 |
| height | 展示高度 | number | - | 150 |
| placeholder | 占位图 | string | - | - |
| notip | 是否隐藏提示栏 | boolean | - | false |
| ext | 支持的文件类型 | array | - | ['jpg', 'png', 'gif', 'bmp'] |
Skip to content
介绍
框架提供一系列的组件方便快速开发。
基础组件
基础组件由 Element Plus 提供，其中包含按钮、文字链接、单选框、多选框、输入框、计数器、级联选择器、开关、滑块等 50+ 个组件。
阅读并学习请查看 Element Plus 官方文档。
说明
为了统一图标的使用，框架没有采用 Element Plus 官方图标的使用方式，这意味着部分 Element Plus 组件的 icon 属性将无法使用，例如 Button 按钮组件。
template
<!-- 无法使用 -->
+<el-button icon="el-icon-edit">编辑</el-button>
+
+<!-- 可以使用插槽代替 -->
+<el-button>
+ <template #icon>
+ <el-icon>
+ <svg-icon name="ep:edit" />
+ </el-icon>
+ </template>
+ 编辑
+</el-button>如果你习惯 Element Plus 官方图标的使用方式，需执行 pnpm install @element-plus/icons-vue 安装依赖，并按照官方的使用方式引入图标，点击查看详细介绍。
替换组件库
如果你不喜欢 Element Plus ，或者你想要将老项目迁移到 One-step-admin 上，但老项目里使用的组件库并不是 Element Plus ，框架也提供了组件库替换移方案：
如果你想使用的组件库不在上述方案中，可以通过参考任何一份方案，理解替换的整理思路，并自行替换，别担心会很复杂，我们已经将大部分工作做好了。
内建组件
为了实现 UI 组件库可替换，框架内建了一些组件，这些组件仅服务于框架自身，所以不建议在业务页面内使用。但如果你需要对框架进行二次开发，并保证视觉上的一致性，这时候你就会需要用到它们。
内建组件存放在 /src/layouts/ui-kit/ 目录下，并配置了使用时自动引入。
扩展组件
扩展组件为框架封装的组件，有全新开发的组件，也有在 Element Plus 组件上二次封装的组件，还有一些则是封装了第三方的插件。
组件源码完全开放，如果觉得用着不顺手，可以到 /src/components/ 目录下找到对应组件自行修改。
+
+
+
+
\ No newline at end of file
diff --git a/components/sparkline.html b/components/sparkline.html
new file mode 100644
index 00000000..627d38e8
--- /dev/null
+++ b/components/sparkline.html
@@ -0,0 +1,33 @@
+
+
+
+
+
+
Skip to content
Sparkline 迷你图 专业版
Props
| 参数 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| value | 迷你图数据，支持一维数组和对象数组，当为对象数组时，对象内参数为 {tooltip: 'xxx', value: 1} | array | - | - |
| width | 展示宽度 | number | - | 100 |
| height | 展示高度 | number | - | 30 |
| stroke-width | 折线宽度 | number | - | 3 |
| stroke-color | 折线颜色 | string | - | #dc2b33 |
| fill-color | 填充颜色 | string | - | - |
| cursor-color | 鼠标 hover 时辅助线颜色 | string | - | #dc2b33 |
| spot-color | 鼠标 hover 时辅助点颜色 | string | - | #dc2b33 |
| tooltip | 鼠标 hover 时是否显示文字提示 | boolean | - | false |
+
+
+
+
\ No newline at end of file
diff --git a/components/trend.html b/components/trend.html
new file mode 100644
index 00000000..70ba3212
--- /dev/null
+++ b/components/trend.html
@@ -0,0 +1,33 @@
+
+
+
+
+
+
Skip to content
常用 API
接口请求
详细可阅读《与服务端交互 - 接口请求》。
ts
import api from '@/api'
+
+api.get()
+api.post()鉴权
详细可阅读《权限 - 鉴权函数》。
ts
import useAuth from '@/utils/composables/useAuth'
+
+const { auth, authAll } = useAuth()
+
+auth()
+authAll()主导航
切换
切换主导航，index 为主导航序列数。
ts
import useMenu from '@/utils/composables/useMenu'
+
+useMenu().switchTo(index)窗口
新增窗口
ts
import useWindow from '@/utils/composables/useWindow'
+
+useWindow.add('windowName')
+
+useWindow.add({
+ title: '窗口标题',
+ name: 'windowName'
+})关闭窗口
ts
import useWindow from '@/utils/composables/useWindow'
+
+useWindow().remove('windowName')窗口全屏切换 专业版
ts
import useWindow from '@/utils/composables/useWindow'
+
+useWindow().toggleMaximize('windowName')判断窗口是否全屏 专业版
ts
import useWindow from '@/utils/composables/useWindow'
+
+useWindow().isMaximize('windowName') // true / false窗口刷新
ts
import useWindow from '@/utils/composables/useWindow'
+
+useWindow().reload('windowName')事件总线
基于 mitt 简单封装，使用方法请查阅官方文档。
ts
import eventBus from '@/utils/eventBus'
+
+eventBus.on()
+eventBus.emit()
+eventBus.off()日期 专业版
基于 dayjs 简单封装，使用方法请查阅官方文档。
ts
import dayjs from '@/utils/dayjs'
+
+dayjs() Skip to content
与服务端交互
框架使用 Axios 做为异步请求工具，并进行了简单的封装。
接口请求
设置 baseURL
在根目录 .env.* 文件里的 VITE_APP_API_BASEURL 这个参数就是配置 axios 的 baseURL 。
例如项目的真实接口请求地址为：
http://api.test.com/news/listhttp://api.test.com/news/createhttp://api.test.com/shop/info
则可设置为 VITE_APP_API_BASEURL = http://api.test.com/ 。
请求调用
常用的 GET 和 POST 请求可使用以下的方法：
ts
import api from '@/api'
+
+// GET 请求
+api.get('news/list', {
+ params: {
+ page: 1,
+ size: 10,
+ },
+}).then((res) => {
+ // 后续业务代码
+})
+
+// POST 请求
+api.post('news/create', {
+ title: '新闻标题',
+ content: '新闻内容',
+}).then((res) => {
+ // 后续业务代码
+})拦截器
在 /src/api/index.ts 文件里实例化了 axios 对象，并对 request 和 response 设置了拦截器，拦截器的用处就是拦截每一次的请求和响应，然后做一些全局的处理。例如接口响应报错，可以在拦截器里用统一的报错提示来展示，方便业务开发。但因为每个公司提供的接口标准不同，所以该文件拦截器部分的代码，需要开发者根据实际情况去修改调整。
代码很简单，首先初始化 axios 对象，然后 axios.interceptors.request.use() 和 axios.interceptors.response.use() 就分别是请求和响应的拦截代码了。
参考代码里只做了简单的拦截处理，例如请求的时候会自动带上 token ，响应的时候会根据错误信息判断是登录失效还是接口报错，并做相应动作。
模块管理
如果项目里的接口很多，推荐根据模块来统一管理接口，目录为 /src/api/modules/ 。
跨域处理
生产环境的跨域需要服务端去解决，开发环境的跨域问题可在本地设置代理解决。如果本地开发环境请求接口提示跨域，可以设置 .env.development 文件里 VITE_OPEN_PROXY = true 开启代理。
ts
import api from '@/api'
+
+api.get('news/list') // http://localhost:9000/proxy/news/list
+api.post('news/add') // http://localhost:9000/proxy/news/add开启代理后，原有请求都会被指向到本地 http://localhost:9000/proxy ，因为 /proxy 匹配到了 vite.config.ts 里代理部分的设置，所以实际是请求依旧是 VITE_APP_API_BASEURL 所设置的地址。
ts
server: {
+ // vite.config.ts 中 proxy 配置，该配置即用于代理 API 请求
+ proxy: {
+ '/proxy': {
+ target: loadEnv(mode, process.cwd()).VITE_APP_API_BASEURL,
+ changeOrigin: command === 'serve' && loadEnv(mode, process.cwd()).VITE_OPEN_PROXY == 'true',
+ rewrite: path => path.replace(/\/proxy/, ''),
+ },
+ },
+},多数据源
如果项目里需要从多个不同地址的数据源请求数据，你有两种方式可以实现。
如果只是几个接口需求从其它数据源请求，你可以使用覆盖 baseURL 的方式：
ts
import api from '@/api'
+
+api.get('/new/list', {
+ baseURL: 'http://baidu.com/', // 直接覆盖 baseURL
+})这种方式的前提是，两个数据源的 request 和 response 规则要保持一致，因为只是覆盖 baseURL ，拦截器还是用的同一套规则。
所以如果两个数据源的请求和响应是完全不同的标准，你需要给第二个数据源单独实例化一个 axios 对象。首先在 .env.* 文件里配置第二个数据源的 baseURL ：
# 命名可随意，以 VITE_APP_ 开头即可
+VITE_APP_API_BASEURL_2 = 此处填写接口地址然后把 /src/api/index.ts 文件复制一份，例如就叫 /src/api/index2.ts ，并且将代码中使用到 VITE_APP_API_BASEURL 也替换为 VITE_APP_API_BASEURL_2 ，这样你就可以在页面中通过引入不同的文件分别请求两个数据源了：
ts
import api from '@/api'
+import api2 from '@/api/index2'
+
+// 请求默认数据源
+api.get('/new/list')
+// 请求第 2 个数据源
+api2.get('/new/list')需注意，如果第二个数据源也需要开启跨域处理的话，需要在 /src/api/index2.ts 里定一个新的 proxy 路径，例如 /proxy2/ ：
ts
const api = axios.create({
+ baseURL: import.meta.env.DEV && import.meta.env.VITE_OPEN_PROXY === 'true' ? '/proxy2/' : import.meta.env.VITE_APP_API_BASEURL_2,
+ timeout: 10000,
+ responseType: 'json',
+})同时在 vite.config.ts 里增加一段新的 proxy 配置：
ts
server: {
+ // vite.config.ts 中 proxy 配置，该配置即用于代理 API 请求
+ proxy: {
+ '/proxy': {
+ target: loadEnv(mode, process.cwd()).VITE_APP_API_BASEURL,
+ changeOrigin: command === 'serve' && loadEnv(mode, process.cwd()).VITE_OPEN_PROXY == 'true',
+ rewrite: path => path.replace(/\/proxy/, ''),
+ },
+ '/proxy2': {
+ target: loadEnv(mode, process.cwd()).VITE_APP_API_BASEURL_2,
+ changeOrigin: command === 'serve' && loadEnv(mode, process.cwd()).VITE_OPEN_PROXY == 'true',
+ rewrite: path => path.replace(/\/proxy2/, ''),
+ },
+ },
+},Mock
Mock 数据是前端开发过程中必不可少的一环，是分离前后端开发的关键链路。通过预先跟服务器端约定好的接口，模拟请求数据甚至逻辑，能够让前端开发独立自主，不会被服务端的开发所阻塞。
开发环境 mock
mock 文件存放在 /src/mock/ 下，建议按照不同模块区分文件夹。文件新增或修改后会自动更新，不需要手动重启，可以在代码控制台查看日志信息。
以下为示例代码：
ts
import { defineFakeRoute } from 'vite-plugin-fake-server/client'
+import Mock from 'mockjs'
+
+export default defineFakeRoute([
+ {
+ url: '/mock/news/list',
+ method: 'get',
+ response: () => {
+ return {
+ error: '',
+ status: 1,
+ data: Mock.mock({
+ 'list|5-10': [
+ {
+ title: '@ctitle',
+ },
+ ],
+ }),
+ }
+ },
+ },
+])参数获取：
- GET：
({ query }) => { } - POST：
({ body }) => { }
为了让 mock 接口与真实接口共存，即项目开发中，部分请求 mock 接口，部分请求真实接口。需要在配置 mock 接口的时候，给 url 参数统一设置 /mock/ 前缀，并在调用接口的时候，使用 baseURL 强制修改此次请求的地址。
如下所示，其中 news/list 会请求本地的 mock 接口，而 news/create 依旧请求真实接口，即使开启跨域代理也不影响。
ts
import api from '@/api'
+
+api.get('news/list', {
+ baseURL: '/mock/',
+ params: {
+ page: 1,
+ size: 10,
+ },
+}).then((res) => {
+ // 后续业务代码
+})
+
+api.post('news/create', {
+ title: '新闻标题',
+ content: '新闻内容',
+}).then((res) => {
+ // 后续业务代码
+})生产环境 mock
注意
生产环境一般都是调用真实接口，如果需要使用 mock 也只适用于一些简单的示例网站及预览网站。
模板默认已经配置好生产环境 mock ，如果不想让生产环境里的请求走 mock ，可在接口调用处删除 baseURL 设置，或直接删除 mock 接口文件。
需要注意一点，如果项目中有涉及到上传功能，请彻底关闭线上环境 mock ，在环境配置里设置 VITE_BUILD_MOCK = false ，不然线上环境将会报错。
开发环境与生产环境使用 mock 差异不大，比较大的区别是生产环境里调用 mock 接口，在控制台内看不到接口请求日志。
Skip to content
构建与预览
构建
项目开发完成之后，可以执行 pnpm run build 命令进行构建，构建打包成功之后，会在根目录生成 dist 文件夹，里面就是构建打包好的文件。
如果是需要构建测试环境，则执行 pnpm run build:test 命令，对应会在根目录生成 dist-test 文件夹。
TIP
如果最终访问地址为域名非根节点，如 https://www.example.com/app，则需要在 vite.config.ts 中设置 base 选项为 /app/，否则会出现资源引用错误。
预览
生成好的 dist 文件夹一般需要部署至服务器才算部署发布成功，但为了保证构建出来的文件能正常运行，开发者通常希望能在本地先预览一下，可执行 pnpm run serve 或 pnpm run serve:test 命令预览不同环境构建出的文件夹。
压缩
在环境配置文件里设置 VITE_BUILD_COMPRESS 即可在构建时生成 .gz 或 .br 文件。
# 单独开启 gzip
+VITE_BUILD_COMPRESS = gzip
+
+# 单独开启 brotli ，brotli 是比 gzip 压缩率更高的算法
+VITE_BUILD_COMPRESS = brotli
+
+# 或者也可以都开启，两者可以共存
+VITE_BUILD_COMPRESS = gzip,brotli两者均需要 nginx 安装指定模块并开启后才会生效。
其它设置
在环境配置文件里除了可以设置压缩选项，还可设置：
# 是否在打包时生成 sourcemap
+VITE_BUILD_SOURCEMAP = true Skip to content
更新日志
只记录 feat/fix 以及破坏性更新记录。
4.7.0
🚨 Breaking Changes
🚀 Features
4.6.0
🚨 Breaking Changes
🚀 Features
🚨 Breaking Changes
- 移除
createInjectionKey函数，全局provide的generateI18nTitle函数放到useMenu()里提供 - by @hooray (ebc63) - 调整
menu.enableSubMenuCollapseButton的展示逻辑 - by @hooray (3a6d7)
🚀 Features
- 上传组件增加自定义上传 - by @hooray (dab41)
- 窗口宽度改为在配置文件全局设置，支持单独设置窗口宽度 - by @hooray (3837a)
- FileUpload 组件文件列表增加下载功能 - by @hooray (fd0ca)
🐞 Bug Fixes
4.5.0
🚨 Breaking Changes
- 配置项
menu.menuMode变更为menu.mode- by @hooray (10415)
🚀 Features
🐞 Bug Fixes
- 修复vscode失效配置 - by @hooray (e5cfa)
🚨 Breaking Changes
- 配置项
menu.menuActiveStyle变更为menu.style- by @hooray (fce08) - 配置项
menu.menuMode变更为menu.mode- by @hooray (9091d)
🚀 Features
- 增加2种导航栏模式
side-panel/head-panel- by @hooray (cab92) - 增加禁用开发者工具环境变量 - by @hooray (f2ef8)
- 新增哀悼模式和色弱模式 - by @hooray (9ebc8)
🐞 Bug Fixes
4.4.1
无重大变化
4.4.0
🚨 Breaking Changes
- 移除导航
i18n配置项，合并到title配置项内 - by @hooray (1921b)
🚀 Features
- 登录页增加扫码登录参考 - by @hooray (fc082)
🐞 Bug Fixes
4.3.0
无重大变化
🚀 Features
- 提供
$t函数,用于菜单i18n能在 VSCode I18n Ally 插件下正确显示 - by @hooray (d8039) - 工具栏部分按钮增加交互动效 - by @hooray (8f597)
- 支持 RTL 模式 - by @hooray (97483)
🐞 Bug Fixes
- 修复 mock 模板请求无响应数据 - by @hooray (6c92d)
4.2.3
无重大变化
无重大变化
4.2.2
无重大变化
无重大变化
4.2.1
无重大变化
4.2.0
🚀 Features
- 引入 unplugin-turbo-console 优化开发体验 - by @hooray (43d09)
- 增加打包后生成存档文件支持 - by @hooray (66d9e)
- 增加图片支持，整站图标改用 unocss icon 方式使用，方便在内网环境使用 - by @hooray (4bccd)
- 导航菜单收起时，无二级的一级导航增加 tooltip 展示 - by @hooray (5e61c)
- 明暗模式设置为跟随系统时，支持动态切换 - by @hooray (98792)
🐞 Bug Fixes
- Mock 数据修复 - by @hooray (fd2f6)
🚨 Breaking Changes
- 重构用户偏好模块，偏好设置可存放在 localStorage - by @hooray (7a554)
- 重构页面水印，支持动态更新 - by @hooray (7cdc8)
- 移除内置 v-waves 指令，使用第三方 v-wave 插件 - by @hooray (a7505)
🚀 Features
- 引入 unplugin-turbo-console 优化开发体验 - by @hooray (f644e)
- 增加打包后生成存档文件支持 - by @hooray (2bb50)
- SvgIcon 增加图片支持，整站图标改用 unocss icon 方式使用，方便在内网环境使用 - by @hooray (d5715)
- 导航菜单收起时，无二级的一级导航增加 tooltip 展示 - by @hooray (95cf8)
- 明暗模式设置为跟随系统时，支持动态切换 - by @hooray (c7bcb)
- 增加
v-zoomable图片预览指令 - by @hooray (3d58e)
🐞 Bug Fixes
- Mock 数据修复 - by @hooray (5c9ba)
4.1.0
🚨 Breaking Changes
🚨 Breaking Changes
- Vite-plugin-fake-server 替换 vite-plugin-mock - by @hooray (bdfa4)
- 应用配置
toolbar对象内属性调整 - by @hooray (c2915)
🚀 Features
4.0.1
4.0.0
🚨 Breaking Changes
🚀 Features
拥抱原子化 CSS ，启用 UnoCSS ，并对框架部分组件样式进行了重构
如果你正在将老版本的业务代码向新版本迁移，推荐安装 UnoCSS 这个 VSCode 插件，它能高亮显示 UnoCSS 的代码。如果你的业务页面代码中定义的 class 和 UnoCSS 的 class 重名，也可以通过这个插件快速识别到并修改。
与 Element Plus 组件库解耦，方便替换成其他第三方 UI 组件库，详细可阅读：
ESLint 配置文件格式调整，详细可阅读《代码规范 - ESLint 配置》
ESLint 提供了全新的配置方式，所有配置项将都在一个
eslint.config.js文件中实现。基础版现在可以使用 Iconify 完整图标库，详细可阅读《图标 - Iconify 图标》
全新的主题配色方案，详细可阅读《主题 - 框架主题》
移除 Element Plus 自定义主题配置
如果你依旧需要自定义 Element Plus 的主题，可以阅读 Element Plus 官方文档《自定义主题》，或者参考下面提供的最佳实践。
在
/src/assets/styles/目录下分别新建element-plus.scss和element-plus.dark.scss并写入下面的代码：scss// element-plus.scss +@forward "element-plus/theme-chalk/src/common/var.scss" with ( + $colors: ( + "primary": ( + "base": green + ) + ) +); +@use "element-plus/theme-chalk/src/index.scss" as *; +@use "./element-plus.dark.scss" as *;scss// element-plus.dark.scss +@forward "element-plus/theme-chalk/src/dark/var.scss" with ( + $bg-color: ( + "page": #0a0a0a, + "": #141414, + "overlay": #1d1e1f, + ) +); +@use "element-plus/theme-chalk/src/dark/css-vars.scss" as *;修改
/src/main.tsts... +import ElementPlus from 'element-plus' +import 'element-plus/dist/index.css' +import 'element-plus/theme-chalk/dark/css-vars.css' +import '@/assets/styles/element-plus.scss' +...移除应用配置中 Element Plus 默认尺寸的配置项
如果你依旧需要全局配置 Element Plus 的默认尺寸，可以参考《Config Provider 全局配置》并在
/src/App.vue中进行修改。移除精灵图支持
原有
/src/assets/sprites/目录中的图片，现在可以移动到/src/assets/images/目录中，并修改代码中的使用方式。应用配置中导航栏填充风格的配置项名称变更 专业版
tsconst globalSettings: Settings.all = { + menu: { + /** + * 留空默认 + * radius 圆角 + */ + menuFillStyle: '', + // 导航栏是否圆角 + isRounded: false, + }, +}
3.1.3
无重大变化
无重大变化
3.1.2
无重大变化
无重大变化
3.1.1
无重大变化
无重大变化
3.1.0
无重大变化
3.0.0
🚨 Breaking Changes
- 移除
BatchActionBar组件 - by @hooray (b1f8f) - 移除
Editor组件 - by @hooray (2ea5f) - 移除 vite-plugin-html 插件 - by @hooray (9d1d3)
- 调整应用配置的配置项，并将应用配置按钮从工具栏删除 - by @hooray (ceffd)
- 重构接口请求，统一管理接口请求模块 - by @hooray (301d7)
🚀 Features
- 引入 stylelint-stylistic 插件 - by @hooray (38e3f)
🐞 Bug Fixes
- 修复 axios baseURL 配置，解决构建后 baseURL 不生效的问题 - by @hooray (87963)
🚨 Breaking Changes
- 移除
BatchActionBar组件 - by @hooray (ca569) - 移除
Editor组件 - by @hooray (6fff3) - 移除 vite-plugin-html 插件 - by @hooray (f9c4e)
- 调整应用配置的配置项，并将应用配置按钮从工具栏删除 - by @hooray (abea5)
- 重构标准模块，增加表格高度自适应功能 - by @hooray (f20ca)
- 重构接口请求，统一管理接口请求模块 - by @hooray (831ab)
🚀 Features
- 引入 stylelint-stylistic 插件 - by @hooray (f0826)
- 新增 StorageBox 组件 - by @hooray (38efb)
- 增加明暗切换过渡动效 - by @hooray (44045)
🐞 Bug Fixes
2.3.2
无重大变化
无重大变化
2.3.1
无重大变化
无重大变化
2.3.0
🚨 Breaking Changes
🚨 Breaking Changes
- Pinia store 改为 setup 写法 - by @hooray (040a5)
- UseCurrentInstance() 重命名为 useGlobalProperties() - by @hooray (39d56)
🐞 Bug Fixes
2.2.0
2.1.0
🐞 Bug Fixes
2.0.0
v1.0.0
JS 版本存档，框架下次更新将切换到 TS 版本，JS 版本将不再维护。
JS 版本存档，框架下次更新将切换到 TS 版本，JS 版本将不再维护。
Skip to content
代码规范
建议
请确保已阅读《准备工作 - 开发环境》，并且按照文档说明安装好相关软件及扩展。
为保证代码风格统一，请使用 Visual Studio Code 做为开发 IDE ，框架源码里已提供相关配置文件，可直接测试效果：在保存代码时，会自动对当前文件进行代码格式化操作。
IDE 配置
配置文件为 .editorconfig ，通常情况下无需做任何修改。
ESLint 配置
配置文件为 eslint.config.js ，框架使用 antfu/eslint-config 做为基础规范，如果你对默认的规则有异议，可以查阅 ESLint 官网规则并在 eslint.config.js 文件中进行覆盖。
当你对规则进行修改后，原有的代码可能会因为规则的变动导致编辑器大量提示错误，你可以通过运行 pnpm run lint:eslint 进行一次格式校验，如果规则支持自动修复，则会将不符合规则的代码自动进行格式化。
TIP
通过修改 eslint.config.js 中 ignores 配置可忽略无需做代码规范校验的目录或文件，例如在项目中导入了一些第三方的插件代码或组件代码，我们就可以将其进行忽略。
StyleLint 配置
配置文件为 .stylelintrc ，如果你对默认的规则有异议，可以查阅 Stylelint 官网规则并在 .stylelintrc 文件中进行修改。
当你对规则进行修改后，原有的代码可能会因为规则的变动导致编辑器大量提示错误，你可以通过运行 pnpm run lint:stylelint 进行一次格式校验，如果规则支持自动修复，则会将不符合规则的代码自动进行格式化。
TIP
通过修改 .stylelintignore 可忽略无需做代码规范校验的文件，例如在项目中导入了一些第三方的插件代码或组件代码，我们就可以将其进行忽略。
simple-git-hooks 和 lint-staged
由于 IDE 能做的事比较有限，只能对代码的书写规范进行格式化，对于一些无法自动修复的错误代码，如果没有改正到就被推送到 git 仓库，在多人协作开发时，可能会影响到别人的开发体验。所以框架集成了 simple-git-hooks 和 lint-staged 这两个依赖来解决这一问题。
在提交代码时， simple-git-hooks 会通过 lint-staged 对本次提交变更的文件进行分别进行 eslint 和 stylelint 检测，如果有报错，则会阻止本次代码提交，直到开发者修改完所有错误代码后，才允许提交到 git 仓库，这样可以确保 git 仓库里的代码不会有不规范的代码。
注意
请确保在安装依赖前，已经使用 git init 对项目进行过 git 环境初始化，如果你在安装依赖后再初始化了 git 环境，请在 git 环境初始化之后再执行一遍 pnpm install 安装命令。
此外，如果 git 仓库目录和框架目录并非同一个，则需要在 package.json 中修改 postinstall 脚本，切换到 git 所在目录。例如 git 目录是 project/ ，而框架目录是 project/one-step-admin/ ，则在 package.json 里找到 simple-git-hooks 配置并修改：
json
"simple-git-hooks": {
+ "pre-commit": "cd ./one-step-admin/ && pnpm lint-staged",
+ "preserveUnused": true
+}修改后重新执行一下 pnpm install 即可。
移除
如果不想在 git 提交时强制进行代码规范校验，可以在 package.json 中移除 simple-git-hooks 配置：
json
{
+ "scripts": {
+ "postinstall": "simple-git-hooks && esno scripts/prepare.js",
+ "postinstall": "esno scripts/prepare.js",
+ },
+ "simple-git-hooks": {
+ "pre-commit": "pnpm lint-staged",
+ "preserveUnused": true
+ },
+}json
{
+ "scripts": {
+ "postinstall": "simple-git-hooks",
+ },
+ "simple-git-hooks": {
+ "pre-commit": "pnpm lint-staged",
+ "preserveUnused": true
+ },
+}然后手动删除 .git/hooks/pre-commit 文件即可。
Skip to content
介绍
框架提供一系列的组件方便快速开发，其中基础组件为 Element Plus 原生提供的组件；而扩展组件有一部分是在 Element Plus 组件上进行了二次开发，还有一部分是封装了第三方插件。
组件源码完全开放，如果觉得用着不顺手，可以到 /src/components/ 目录下找到对应组件进行修改。
基础组件
基础组件由 Element Plus 提供，其中包含按钮、文字链接、单选框、多选框、输入框、计数器、级联选择器、开关、滑块等 50+ 个组件。
阅读并学习请查看 Element Plus 官方文档。
TIP
框架严格按照 Element Plus 推荐的使用方式进行引入，即按需自动导入，意味着你可以直接在代码里使用组件，而无需手动注册。
但也意味着 Element Plus 一些全局方法将无法使用，例如 Message 消息提示组件。
js
// 无法使用
+const { proxy } = getCurrentInstance()
+proxy.$message.success(options)
+
+// 可以使用
+ElMessage.success(options)另外因为框架没有采用 Element Plus 官方的图标使用方式，这也意味着部分组件的 icon 属性将无法使用，例如 Button 按钮组件。
template
<!-- 无法使用 -->
+<el-button icon="el-icon-edit">编辑</el-button>
+
+<!-- 可以使用插槽代替 -->
+<el-button>
+ <template #icon>
+ <el-icon>
+ <svg-icon name="ep:edit" />
+ </el-icon>
+ </template>
+ 编辑
+</el-button>扩展组件
Skip to content
配置
环境配置
默认提供三套环境配置，分别为：
yaml
# 应用配置面板
+VITE_APP_SETTING = true
+# 页面标题
+VITE_APP_TITLE = One-step-admin
+# 接口请求地址，会设置到 axios 的 baseURL 参数上
+VITE_APP_API_BASEURL = /
+# 调试工具，可设置 eruda 或 vconsole，如果不需要开启则留空
+VITE_APP_DEBUG_TOOL =
+# 是否禁用开发者工具，可防止被调试
+VITE_APP_DISABLE_DEVTOOL = false
+
+# 是否开启代理
+VITE_OPEN_PROXY = falseyaml
# 应用配置面板
+VITE_APP_SETTING = false
+# 页面标题
+VITE_APP_TITLE = One-step-admin
+# 接口请求地址，会设置到 axios 的 baseURL 参数上
+VITE_APP_API_BASEURL = /
+# 调试工具，可设置 eruda 或 vconsole，如果不需要开启则留空
+VITE_APP_DEBUG_TOOL =
+# 是否禁用开发者工具，可防止被调试
+VITE_APP_DISABLE_DEVTOOL = false
+
+# 是否在打包时启用 Mock
+VITE_BUILD_MOCK = false
+# 在构建时生成 sourcemap
+VITE_BUILD_SOURCEMAP = true
+# 在构建时开启压缩，支持 gzip 和 brotli
+VITE_BUILD_COMPRESS =
+# 是否在打包后生成存档，支持 zip 和 tar
+VITE_BUILD_ARCHIVE =yaml
# 应用配置面板
+VITE_APP_SETTING = false
+# 页面标题
+VITE_APP_TITLE = One-step-admin
+# 接口请求地址，会设置到 axios 的 baseURL 参数上
+VITE_APP_API_BASEURL = /
+# 调试工具，可设置 eruda 或 vconsole，如果不需要开启则留空
+VITE_APP_DEBUG_TOOL =
+# 是否禁用开发者工具，可防止被调试
+VITE_APP_DISABLE_DEVTOOL = false
+
+# 是否在打包时启用 Mock
+VITE_BUILD_MOCK = true
+# 在构建时生成 sourcemap
+VITE_BUILD_SOURCEMAP = false
+# 在构建时开启压缩，支持 gzip 和 brotli
+VITE_BUILD_COMPRESS = gzip,brotli
+# 是否在打包后生成存档，支持 zip 和 tar
+VITE_BUILD_ARCHIVE =其中 VITE_APP_SETTING VITE_APP_TITLE VITE_APP_API_BASEURL VITE_APP_DEBUG_TOOL VITE_APP_DISABLE_DEVTOOL 为必要配置，即不管是在开发、测试，还是生产环境都需要使用到。而其余配置则在不同环境下有不同用途，例如开发环境用于本地开发使用，测试环境和生产环境用于构建使用。
开发者可根据实际业务需求进行扩展，如果对这块不熟悉，请阅读 Vite - 环境变量和模式 章节。
注意
VITE_APP_SETTING 该变量是开启应用配置面板，目的是方便开发者在开发阶段调试，生产环境下默认关闭，也建议关闭。
如果希望提供用户一些定制化的能力，可以开启偏好设置，详细可阅读《用户偏好设置》
应用配置（框架配置）
开发者请在 /src/settings.ts 文件中设置自定义配置，而 /src/settings.default.ts 为框架的默认配置，请勿在该文件内修改。
关于配置的类型定义，可以在 /src/types/globals.d.ts 文件中查阅。
ts
// 这是基础版演示源码里的自定义配置示例
+const globalSettings: Settings.all = {
+ app: {
+ enablePermission: true,
+ },
+ menu: {
+ enableSubMenuCollapseButton: true,
+ enableHotkeys: true,
+ },
+ toolbar: {
+ enableFullscreen: true,
+ enableColorScheme: true,
+ },
+}注意
如果文档中提供的配置介绍，在你本地的开发环境中报错或者无法生效，说明你使用的版本不支持或者配置参数有变动，你可以打开 /src/settings.default.ts 查看当前版本的完整配置作为参考。并且如果你使用的是 Visual Studio Code ，鼠标悬浮到属性上时，会有属性的介绍：
Skip to content
版权信息
版权信息位于页面底部显示。
使用
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ copyright: {
+ enable: true,
+ },
+}网站运行日期
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ copyright: {
+ dates: '2021-2022',
+ },
+}公司名称
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ copyright: {
+ company: 'One-step-admin',
+ },
+}网站地址
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ copyright: {
+ website: 'https://one-step-admin.hurui.me',
+ },
+}如果未设置公司名称，则该设置将被忽略。
备案号
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ copyright: {
+ beian: '',
+ },
+} Skip to content
错误日志 专业版
首先需要在应用配置里开启错误日志。
ts
const globalSettings: Settings.all = {
+ app: {
+ enableErrorLog: true,
+ },
+}然后需要到 /src/utils/error.log.ts 文件里编写业务代码，框架为方便演示，将错误日志记录在 sessionStorage 里。
开发者需要根据实际业务情况修改代码，例如将增加上报信息，记录用户账号、token等数据，并且将错误日志进行上报。
由于开启错误日志监控后，Vue 相关的错误都不会在控制台里显示，所以在开发环境下即使开启错误日志也不会被启用，如果需要在开发环境下测试，可在 /src/util/error.log.ts 里修改开启的条件判断。
Skip to content
收藏夹 专业版
需在工具栏开启，开启后用户可将常用的导航菜单添加进收藏夹，方便快速访问。
处理请求
收藏夹默认存储在浏览器本地 localStorage 里，如果需要将数据存储到服务器，可以通过 favorites.storageTo 配置项来实现，具体配置如下：
ts
const globalSettings: Settings.all = {
+ favorites: {
+ storageTo: 'server',
+ },
+}然后到 /src/api/modules/user.ts 中找到 favorites() 和 favoritesEdit() 这两个函数，并分别修改这两个函数的请求地址。
建议
为减轻后端处理，数据会直接以 JSON 字符串进行存储，建议后端可以在用户表增加相关字段，并将字段类型设为 lonetext 。
Skip to content
自定义字体 专业版
用户访问使用了自定义字体的页面时，会自动下载字体文件，字体文件有大有小，所以不建议在非英文环境中使用。
框架预设了 Digital 7 的两套字体，除此之外，你也可以通过以下方法引入你需要的自定义字体。
找字体
访问 DaFont 或其它字体下载网站，下载 .ttf 格式的字体文件。
生成字体
因为 .ttf 格式的字体文件不是浏览器支持的字体格式，所以需要通过 .ttf 生成其它格式的字体文件。
访问 Font Squirrel，上传 .ttf 文件，并按照下面设置后，点击下载。
使用
将上一步下载的压缩包解压并放入 /src/assets/fonts/ 目录下，注意按文件夹区分，随后引入文件夹中的 stylesheet.css 即可使用，以 Digital 7 字体为例：
scss
@import '../../assets/fonts/digital-7/stylesheet.css';
+.digital-7 {
+ font-family: 'digital-7regular';
+}字体的 font-family 名称在 stylesheet.css 里查看。
另外你也可以将 @import '../../assets/fonts/digital-7/stylesheet.css'; 这句代码放到全局引入，这样所有页面就都可以通过设置 font-family: 'digital-7regular'; 直接使用了。
Skip to content
国际化 专业版
INFO
该特性由 vue-i18n 提供技术支持。
vscode 扩展
如果使用 vscode 进行开发，推荐安装 i18n Ally 这个扩展。
安装该扩展后，代码里可以实时查看对应语言的内容。
语言选择器
在应用配置里设置后，会在顶栏里显示语言选择器。
ts
const globalSettings: Settings.all = {
+ toolbar: {
+ enableI18n: true,
+ },
+}同时还可在应用配置里设置默认语言，可选设置的值参考 /src/locales/lang/ 目录下文件名，留空则会根据浏览器语言自动判断，如果找不到对应的语言则使用 中文(简体) 兜底。
ts
const globalSettings: Settings.all = {
+ app: {
+ defaultLang: '',
+ },
+}语言包
语言包存放在 /src/locales/lang/ 目录下，因为 Element Plus 本身也有自己的语言包，所以在做国际化支持的时候，框架的语言包文件命名需要和 Element Plus 保持一致，可点击这里查看 Element Plus 的语言包文件。
假设你已经在 /src/locales/lang/ 目录下新增并配置好了一个日文语言包 ja.json ，然后你需要到 /src/locales/index.ts 文件里做以下调整。
ts
import elementLocaleZhCN from 'element-plus/lib/locale/lang/zh-cn'
+import elementLocaleZhTW from 'element-plus/lib/locale/lang/zh-tw'
+import elementLocaleEn from 'element-plus/lib/locale/lang/en'
+// 引用 Element Plus 的日文语言包
+import elementLocaleJa from 'element-plus/lib/locale/lang/ja'
+
+function getElementLocales() {
+ const locales: {
+ [key: string]: any
+ } = {}
+ for (const key in messages) {
+ locales[key] = {}
+ switch (key) {
+ case 'zh-cn':
+ Object.assign(locales[key], elementLocaleZhCN, { labelName: '中文(简体)' })
+ break
+ case 'zh-tw':
+ Object.assign(locales[key], elementLocaleZhTW, { labelName: '中文(繁體)' })
+ break
+ case 'en':
+ Object.assign(locales[key], elementLocaleEn, { labelName: 'English' })
+ break
+ // 在这里增加一个 case 选项，其中 labelName 会在语言选择器里显示
+ case 'ja':
+ Object.assign(locales[key], elementLocaleJa, { labelName: '日本語' })
+ break
+ }
+ }
+ return locales
+}修改完成后，需要重新启动项目才会生效。
导航设置
如果需要新增某个导航的国际化支持，光设置好中文(简体)的还不行，其它语言包文件里也要同步添加。当都设置好后，可在该导航里设置 title 参数，例如：
ts
title: 'menu.i18n',框架设置
以中文(简体)为例，打开 /src/locales/lang/zh-cn.json 文件可以看到框架相关的配置，在 app 对象里的就是框架部分的语言信息，如果需要对框架进行二次开发，请在这里扩展。
json
{
+ "app": {
+ "account": "用户名",
+ "captcha": "验证码",
+ "check": "确认",
+ "goLogin": "去登录",
+ "login": "登录",
+ "logout": "退出登录",
+ "newPassword": "新密码",
+ "password": "密码",
+ "profile": "个人设置",
+ "sendCaptcha": "发送验证码"
+ }
+}单页组件
如果每个页面都要做国际化支持，那语言包文件就会变得无比庞大且难以维护，推荐在每个页面组件里使用 <i18n> 自定义块进行语言维护，可访问 /src/views/feature_example/i18n.vue 查看示例。
与服务端交互
所有的请求均会在请求头里带上 Accept-Language ，后端可根据这一状态信息做动态数据国际化处理。
关闭国际化
如果不想开启国际化，可参考以下设置，该设置表示关闭语言选择器，并以中文(简体)显示。
ts
const globalSettings: Settings.all = {
+ app: {
+ defaultLang: 'zh-cn',
+ },
+ toolbar: {
+ enableI18n: false,
+ },
+} Skip to content
布局
通过 7 种导航栏模式和 4 种页宽模式的组合搭配，可实现 28 种布局结构，再搭配默认提供的 6 款主题，即可实现上百种界面风格。
导航栏模式
在应用配置里进行设置，可实现 7 种导航栏模式：
- 顶部模式
- 侧边栏模式（含主导航）
- 侧边栏模式（无主导航）
- 侧边栏精简模式 专业版
- 顶部精简模式 专业版
- 侧边栏面板模式 专业版 v4.5.0 新增
- 顶部面板模式 专业版 v4.5.0 新增
顶部模式
ts
const globalSettings: Settings.all = {
+ menu: {
+ mode: 'head', // v4.5.0 之前版本为 menuMode
+ },
+}侧边栏模式（含主导航）
ts
const globalSettings: Settings.all = {
+ menu: {
+ mode: 'side', // v4.5.0 之前版本为 menuMode
+ },
+}侧边栏模式（无主导航）
ts
const globalSettings: Settings.all = {
+ menu: {
+ mode: 'single', // v4.5.0 之前版本为 menuMode
+ },
+}侧边栏精简模式 专业版
ts
const globalSettings: Settings.all = {
+ menu: {
+ mode: 'only-side', // v4.5.0 之前版本为 menuMode
+ },
+}顶部精简模式 专业版
ts
const globalSettings: Settings.all = {
+ menu: {
+ mode: 'only-head', // v4.5.0 之前版本为 menuMode
+ },
+}侧边栏面板模式 专业版 v4.5.0 新增
ts
const globalSettings: Settings.all = {
+ menu: {
+ mode: 'side-panel',
+ },
+}顶部面板模式 专业版 v4.5.0 新增
ts
const globalSettings: Settings.all = {
+ menu: {
+ mode: 'head-panel',
+ },
+}变量
布局相关的变量存放在 /src/assets/styles/globals.css 文件中（注意看注释），均为 CSS 变量。
Skip to content
登录
开发者通常在简单熟悉本框架后，涉及到的第一步业务开发就是修改登录功能，将其替换为自己的登录接口。
但在实践过程中，经常会遇到一些问题，比如：
- 替换真实接口后，无法正常登录
- 登录接口请求成功，但是无法跳转到后台主页
- ...
针对这些问题你需要依次检查以下几点：
- 在
.env.development里检查接口请求地址是否正确。 - 在
/src/api/index.ts里修改响应拦截器里的代码，按照实际情况进行调整。例如什么状态下是请求成功，什么状态下是请求异常，并进行错误提示。 - 在
/src/api/modules/user.ts里修改login函数，确保接口可以请求成功。 - 在
/src/store/modules/user.ts里修改isLogin计算属性，这部分需要根据实际存储的用户信息去判断是否登录。
+
+
+
+
\ No newline at end of file
diff --git a/guide/permission.html b/guide/permission.html
new file mode 100644
index 00000000..23a57121
--- /dev/null
+++ b/guide/permission.html
@@ -0,0 +1,76 @@
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/guide/plop-module.html b/guide/plop-module.html
new file mode 100644
index 00000000..21b69e03
--- /dev/null
+++ b/guide/plop-module.html
@@ -0,0 +1,88 @@
+
+
+
+
+
+
Skip to content
标准模块 专业版
在《代码文件自动生成 - module》里介绍了如何快速生成一个标准模块，这个标准模块是一个最基础的 CURD 模块，它包含列表页和编辑页，同时提供了搜索和删除的功能，并且同时也可以生成对应的 mock 文件，在这基础上可以更方便的进行业务扩展。
下面我就实际操作一遍，并介绍一下这个标准模块有哪些特性。
用法说明
? 请选择需要创建的模式： module - 创建标准窗口
+? 请输入窗口组件名称 test window
+? 请输入模块中文名称 默认模块
+? 是否生成 Mock Yes
+√ ++ \src\views\windows\TestWindow\index.vue
+√ ++ \src\views\windows\TestWindow\components\DetailForm\index.vue
+√ ++ \src\views\windows\TestWindow\components\FormMode\index.vue
+√ ++ \src\mock\test-window.js这里我已经通过命令在 /src/views/windows/ 目录下创建好了一个 TestWindow 文件夹，并且也生成了 mock 数据。接下来需要去配置下导航，这样我们才可以在导航栏里访问到。
首先在 /src/menu/modules/ 目录下新建一个 test.window.ts 文件，并在里面复制以下代码：
ts
cosnt menus: Menu.recordRaw = {
+ title: '测试模块',
+ windowName: 'TestWindow'
+}
+
+export default menus然后到 /src/router/routes.ts 文件里加上这个路由配置文件的引用。
ts
import TestWindow from './modules/test.window'
+
+const menu = [
+ ...,
+ {
+ title: '页面',
+ icon: 'ri-pages-line',
+ children: [
+ ...PagesExample,
+ TestWindow,
+ ],
+ },
+ ...
+]这时候就可以通过导航栏访问到我们的窗口了，我们的一个演示模块也就初步创建好了。
特性介绍
功能部分的介绍主要还是要看代码，先从列表页 index.vue 开始。
最先看到的是这句文件导入代码，因为几乎每个列表页都需要翻页功能，所以把翻页相关的东西都存放在 /src/utils/composables/pagination/index.ts 方便复用。
ts
import usePagination from '@/utils/composables/usePagination'
+
+const { pagination, getParams, onSizeChange, onCurrentChange, onSortChange } = usePagination()接着在 data 里存放的是标准模块提供的一些配置项和必要数据参数字段。
ts
const data = ref({
+ loading: false,
+ /**
+ * 详情展示模式
+ * dialog 对话框
+ * drawer 抽屉
+ */
+ formMode: 'dialog',
+ // 详情
+ formModeProps: {
+ visible: false,
+ id: '',
+ },
+ // 搜索
+ search: {
+ account: '',
+ name: '',
+ mobile: '',
+ sex: '',
+ },
+ searchMore: false,
+ // 批量操作
+ batch: {
+ enable: true,
+ selectionDataList: [],
+ },
+ // 列表数据
+ dataList: [],
+})标准模块提供了 2 种详情展示模式，默认是弹窗的方式，你可以修改 formMode: 'drawer' 开启抽屉模式，保存后效果如下：
再往下就是需要你修改或编写业务代码的部分，这里就不继续展开了。
详情页的代码就不多介绍了，相对比较简单，可自行阅读理解。其中表单部分单独封装成组件存放在 /src/views/windows/[模块文件夹]/components/DetailForm/index.vue 里了，同样你在 components/ 文件夹下还能看到另外一个 FormMode 的文件夹，这样的用意是让表单可以复用，可以通过弹窗或抽屉的形式打开详情页。
可能有人会有疑问，为什么不在生成文件的时候直接让我选择用哪种形式，这样生成出来就是哪种，而是在生成好的代码文件里再进行配置？
这样设计的目的主要有三点：
- 合理使用。关于表单具体使用哪种展示模式比较好，我们的建议是，当表单与当前列表页关联性较强，内容少则使用弹窗，内容多则使用抽屉；而当表单与当前列表页关联性较弱，且内容多，可以使用新建窗口的形式，让新窗口进行承载。
- 方便后期维护。考虑到需求会变，可能一开始是一个很简单的表单，后期需求一点点增加，变成了一个庞大的表单，这时候就要从弹窗改成抽屉的形式，反之也可能是从抽屉改成弹窗的形式，处理起来都很麻烦。所以方便后期维护，这部分是有意而为之，做成了 2 种形式共存，通过配置可一键切换。
- 跨窗口的组件调用。第一点里有提到，如果既不想使用弹窗，也不想使用抽屉，你还可以使用新窗口的形式进行处理，这时候由于表单部分已抽象成组件，所以即便是在新窗口里，也可以直接调用该组件，从而无需编写重复代码。
当然标准模块也只是框架提供的一个标准，你可以沿用，也可以根据自己的需求指定一套标准，毕竟最终目的都是提高开发效率，同时也确保多人协作开发的时候有个统一标准，不会出现每个人做出来的模块风格都不一样。
Skip to content
代码文件自动生成
INFO
该功能基于 plop 实现，在扩展新的模式前，请先详细阅读 plop 官方文档。
开发过程中，避免不了手动去频繁创建页面、组件等文件，并且还要在文件里写一些必要的代码，是不是觉得很麻烦？现在你可以用更简洁的方式来处理这一切。
框架默认提供了 5 种模式，通过 pnpm run new 指令可以自行选择。
page页面文件component组件文件storepinia 全局状态文件mockmock 文件module页面模块文件 专业版
除了框架提供的 5 种模式，你还可以自定义新的模式，其原理就是通过预设模板，按照特定规则创建文件或者文件夹。
预设模板文件存放在 /plop-templates/ 目录下，并在 /plopfile.js 文件里进行引用，你可以参考现有 5 种模式的目录结构进行创建新的模板。
page
page 模式下，只能在 /src/views/ 目录下选择指定的文件夹进行生成，生成的文件中，部分关键位置会被替换掉，例如 <page-header /> 中的 title 会按照你输入的中文名称替换，页面的 name 会根据当前文件目录和文件名自动生成，确保唯一。
component
component 模式可以选择生成的是公共组件还是局部组件，公共组件生成目录为 /src/components/ ，局部组件则在 /src/views/ 目录下选择指定的文件夹进行生成。
store
store 模式则会在 /src/store/modules/ 目录下生成一个空模板
mock
mock 模式则会在 /src/mock/ 目录下生成一个标准 CURD 的 mock 数据
module 专业版
module 模式是一个标准模块模板，会在指定目录下生成模块文件夹，并且包含列表页、编辑（详情）页，以及相关局部组件。
这块部分详细介绍请阅读《标准模块》。
Skip to content
用户偏好设置 专业版
如果希望将框架的部分应用配置项暴露给用户，让用户可以自行设置，那么可以使用用户偏好设置功能。
开启
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ userPreferences: {
+ enable: true,
+ },
+}
定制偏好设置内容
然后打开 /src/store/modules/user.ts 文件，你可以在文件里进一步定制用户偏好设置里的内容：
ts
// 框架已将可提供给用户配置的选项提取出来，请勿新增其他选项，不需要的选项可以在这里注释掉
+const preferences = ref<Settings.all>({
+ app: {
+ colorScheme: settingsDefault.app.colorScheme,
+ theme: settingsDefault.app.theme,
+ },
+ ...
+})如果仔细对比，会发现这里的配置项并不是框架的完整应用配置，这是因为有部分配置项并不适合暴露给用户，比如 userPreferences.enable 这个配置项就是用来控制是否开启用户偏好设置的，如果开启了用户偏好设置，那么这个配置项就不应该再暴露给用户了，否则用户就可以关闭用户偏好设置了，这样就没有意义了。再比如 menu.baseOn 这个配置项是用来控制导航数据来源的，修改它会直接影响代码的调整，所以也是不能暴露给用户的。
所以请勿新增这里的配置项，你需要做的就是将不需要暴露给用户的配置项注释掉即可。
处理请求
用户偏好设置默认存储在浏览器本地 localStorage 里，如果需要将数据存储到服务器，可以通过 userPreferences.storageTo 配置项来实现，具体配置如下：
ts
const globalSettings: Settings.all = {
+ userPreferences: {
+ storageTo: 'server',
+ },
+}然后到 /src/api/modules/user.ts 中找到 preferences() 和 preferencesEdit() 这两个函数，并分别修改这两个函数的请求地址。
建议
为减轻后端处理，数据会直接以 JSON 字符串进行存储，建议后端可以在用户表增加相关字段，并将字段类型设为 lonetext 。
Skip to content
常见问题
安装依赖时有警告
这是一个可以无视的警告，因为依赖已经安装成功了。
如果对这个问题感兴趣，可以浏览下这个 issue ，里面有给出一个忽略警告的方案，就是在 package.json 中添加：
json
{
+ "pnpm": {
+ "peerDependencyRules": {
+ "ignoreMissing": [
+ "postcss",
+ "rollup"
+ ]
+ }
+ }
+}这样你下次再安装依赖的时候，就不会出现该警告了。
为什么本地开发环境首次载入很慢
主要是 Vite 的原因，具体可以阅读这篇文章了解《为什么有人说 vite 快，有人却说 vite 慢？》。
Vite 4.3 显著提升了开发服务器的性能，具体可以阅读这篇文章了解《Vite 4.3 is out!》，同时框架 v3.0.0 版本开始，vite 也升级到了 4.3 版本。
项目 URL 里的 # 号能不能去掉
这是因为路由默认使用的是 Hash 模式，你可以在 /src/router/index.ts 修改为 HTML5 模式，但需要注意，开启 HTML5 模式，服务器也需要做相应的配置调整，详细可阅读《Vue-router 不同的历史模式》。
构建报错，提示内存溢出
构建时失败并在错误信息里提示 Reached heap limit Allocation failed - JavaScript heap out of memory 。
你可以执行 pnpm add cross-env -D 安装 cross-env 依赖，并在 package.json 里修改构建脚本指令：
json
{
+ "scripts": {
+ "build": "vue-tsc --noEmit && cross-env NODE_OPTIONS=--max-old-space-size=8192 vite build"
+ }
+}其中 8192 表示内存空间大小。
直接修改构建产物的接口地址
如果你需要将构建产物部署到多台服务器，并且根据不同服务器配置不同的接口地址。这时候如果采用新增环境配置文件的方式，会存在一个弊端，就是不同环境需要分别进行构建。下面的方法可以让你直接修改构建产物的接口地址。
新增 /public/config.js 文件：
js
window.globalConfig = {
+ API_BASEURL: '/',
+}在 /index.html 中引入：
html
<body>
+ ...
+ <script src="/config.js"></script>
+ <script type="module" src="/src/main.ts"></script>
+</body>修改 /src/api/index.ts ，仅在生产环境时使用：
ts
const api = axios.create({
+ baseURL: (import.meta.env.DEV && import.meta.env.VITE_OPEN_PROXY === 'true') ? '/proxy/' : import.meta.env.VITE_APP_API_BASEURL,
+ baseURL: (import.meta.env.DEV && import.meta.env.VITE_OPEN_PROXY === 'true') ? '/proxy/' : (import.meta.env.DEV ? import.meta.env.VITE_APP_API_BASEURL : (window as any).globalConfig.API_BASEURL),
+ timeout: 1000 * 60,
+ responseType: 'json',
+})之后你就可以在构建产物目录下直接修改 config.js 文件内的接口地址了，此方法不仅适用于接口地址，可以自行扩展。
不会 TypeScript 怎么办
不管个人还是团队、产品或者项目，从长远考虑我们都建议你学习 TypeScript，因为它是未来的趋势，而且大部分框架、库、插件都是用 TypeScript 开发的，足以证明它是构建一款成熟稳健产品的基石。
但考虑到实际情况，会各种客观原因存在，如果必须要用传统 JavaScript 进行开发，你可以在 tsconfig.json 里将 allowJs 设置为 true 即可，框架原有的 TypeScript 代码不会受到影响，并且你也可以在项目中使用 JavaScript 编写代码。
Skip to content
准备工作
源码
阅读开发文档前，请确保手上已经有 One-step-admin 源码，因为文档中提及的内容，都是需要在本地项目中编写或修改代码并运行才能呈现的。如果还没有源码，可以通过下面两种方式获取：
基础版
说明
- 框架源码 不含示例代码，可直接用于实际开发
- 演示源码 同演示站，在框架源码基础上，提供了大量示例代码
到 Github Releases 页面下载最新版本的压缩包，如下图所示：
或者也可以从 Github/Gitee 上拉取源码，但需要注意的是，这种方式拉取的是最新的代码，而不是稳定版本，可能会存在一些问题，所以请谨慎使用。
sh
# 拉取框架源码
+git clone https://github.com/one-step-admin/basic.git
+# 拉取演示源码
+git clone -b example https://github.com/one-step-admin/basic.gitsh
# 拉取框架源码
+git clone https://gitee.com/one-step-admin/basic.git
+# 拉取演示源码
+git clone -b example https://gitee.com/one-step-admin/basic.git专业版
专业版用户会邀请加入到私有组织，获取源码的方式和基础版一致，只是仓库地址不同。
如果你想获取专业版源码，可以点这里去购买。
开发环境
使用本模板前，需要在本地依次安装好 Node.js, pnpm, Git 和 Visual Studio Code。
注意
Node.js 需要使用 18+ / 20+ 版本。
然后在 Visual Studio Code 里安装好以下扩展：
在 Visual Studio Code 里打开源码的文件夹，右下角会自动提示需要安装的依赖，直接点击安装即可。
建议
以上为开发时必备扩展，以下则是作者推荐安装的扩展，安装它们将在一定程度上提升开发效率。
- Chinese (Simplified) Language Pack for Visual Studio Code 中文语言包
- Color Highlight 在代码中高亮颜色
- Highlight Matching Tag 高亮显示匹配的标签
- Image preview 图片预览
- indent-rainbow 彩虹缩进提示
除此之外，还需要准备好开发使用的浏览器，推荐使用 Chrome ，并且在 Chrome 里安装好 Vue.js devtools 扩展，安装 Vue 官方提供的调试工具在一定程度上可以提升解决 bug 的效率，当然这个扩展开启后，可能在开发环境操作会有些许卡顿，建议不需要时候可以将扩展禁用。
不过由于安装 Vue.js devtools 需要访问 Chrome 应用商店，如果在大陆地区访问，需要自行准备相关可访问外网的工具。如果不具备该条件，也可访问 Vue.js devtools 官网 了解本地构建或者下载支持 Edge/Firefox 的 Vue.js devtools 。
技术栈
了解并熟悉框架使用到的技术栈，能让你使用本框架更得心应手。
Skip to content
替换为 Ant Design Vue
注意
v4.0 之前的版本不支持替换组件库，本文适用于 v4.0 及之后的版本。
由于框架默认使用的是 Element Plus 组件库，并且演示源码中大量示例也使用了 Element Plus，如果你需要使用 Ant Design Vue，请拉取框架源码分支，或者到 Github Releases 页面下载框架源码压缩包。
专业版用户也同样，请到专业版仓库下载框架源码。
安装
sh
# 安装依赖
+pnpm install
+
+# 安装 Ant Design Vue
+pnpm add ant-design-vue@4.x代码调整
基础版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import Antd from 'ant-design-vue'
+import 'ant-design-vue/dist/reset.css'
+
+function install(app: App) {
+ app.use(Antd)
+}
+
+export default { install }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import antDesignVueLocaleZhCN from 'ant-design-vue/es/locale/zh_CN'
+import { theme } from 'ant-design-vue'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+</script>
+
+<template>
+ <AConfigProvider :locale="antDesignVueLocaleZhCN" :theme="settingsStore.currentColorScheme === 'dark' ? { algorithm: [theme.darkAlgorithm] } : {}">
+ <slot />
+ </AConfigProvider>
+</template>删除相关文件
.
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader专业版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import Antd from 'ant-design-vue'
+import 'ant-design-vue/dist/reset.css'
+
+import zhCN from 'ant-design-vue/es/locale/zh_CN'
+import zhTW from 'ant-design-vue/es/locale/zh_TW'
+import en from 'ant-design-vue/es/locale/en_US'
+
+function install(app: App) {
+ app.use(Antd)
+}
+
+// 此处的对象属性和 src/locales/index.ts 中的 messages 对象属性一一对应
+const locales: { [key: string]: any } = {
+ 'zh-cn': zhCN,
+ 'zh-tw': zhTW,
+ 'en': en,
+}
+
+export default { install }
+export { locales }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { theme } from 'ant-design-vue'
+import { locales } from './index'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+</script>
+
+<template>
+ <AConfigProvider :locale="locales[settingsStore.lang]" :theme="settingsStore.currentColorScheme === 'dark' ? { algorithm: [theme.darkAlgorithm] } : {}">
+ <slot />
+ </AConfigProvider>
+</template>删除相关文件
.
+├─ plop-templates
+│ └─ module // 标准模块模板基于 Element Plus 开发，需要删除
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ IconPicker
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader修改登录页
由于登录页使用了 Element Plus 组件，并且删除会导致框架无法正常使用，所以此处需要开发者自行修改或者重新制作登录页，或者也可以参考下方示例中已经修改好的登录页。
卸载
sh
# 卸载 Element Plus
+pnpm remove element-plus完成
至此，你已经将框架中的 Element Plus 组件库替换为 Ant Design Vue 组件库，并且可以开始使用 Ant Design Vue 进行业务开发了。
示例
如果对上述的步骤还有不清楚的地方，可以访问此仓库查看示例源码，以及此链接查看示例网站。
Skip to content
替换为 Arco Design Vue
注意
v4.0 之前的版本不支持替换组件库，本文适用于 v4.0 及之后的版本。
由于框架默认使用的是 Element Plus 组件库，并且演示源码中大量示例也使用了 Element Plus，如果你需要使用 Arco Design Vue，请拉取框架源码分支，或者到 Github Releases 页面下载框架源码压缩包。
专业版用户也同样，请到专业版仓库下载框架源码。
安装
sh
# 安装依赖
+pnpm install
+
+# 安装 Arco Design Vue
+pnpm add @arco-design/web-vue -D代码调整
基础版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global",
+ ...
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import ArcoVue from '@arco-design/web-vue'
+import '@arco-design/web-vue/dist/arco.css'
+
+function install(app: App) {
+ app.use(ArcoVue)
+}
+
+export default { install }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import zhCN from '@arco-design/web-vue/es/locale/lang/zh-cn'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+
+const prefersColorScheme = window.matchMedia('(prefers-color-scheme: dark)')
+watch(() => settingsStore.settings.app.colorScheme, (colorScheme) => {
+ if (colorScheme === '') {
+ prefersColorScheme.addEventListener('change', updateTheme)
+ }
+ else {
+ prefersColorScheme.removeEventListener('change', updateTheme)
+ }
+ nextTick(() => {
+ updateTheme()
+ })
+}, {
+ immediate: true,
+})
+function updateTheme() {
+ switch (settingsStore.currentColorScheme) {
+ case 'light':
+ document.body.removeAttribute('arco-theme')
+ break
+ case 'dark':
+ document.body.setAttribute('arco-theme', 'dark')
+ break
+ }
+}
+</script>
+
+<template>
+ <AConfigProvider :locale="zhCN">
+ <slot />
+ </AConfigProvider>
+</template>删除相关文件
.
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader专业版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import ArcoVue from '@arco-design/web-vue'
+import '@arco-design/web-vue/dist/arco.css'
+
+import zhCN from '@arco-design/web-vue/es/locale/lang/zh-CN'
+import zhTW from '@arco-design/web-vue/es/locale/lang/zh-TW'
+import en from '@arco-design/web-vue/es/locale/lang/en-US'
+
+function install(app: App) {
+ app.use(ArcoVue)
+}
+
+// 此处的对象属性和 src/locales/index.ts 中的 messages 对象属性一一对应
+const locales: { [key: string]: any } = {
+ 'zh-cn': zhCN,
+ 'zh-tw': zhTW,
+ 'en': en,
+}
+
+export default { install }
+export { locales }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { locales } from './index'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+
+const prefersColorScheme = window.matchMedia('(prefers-color-scheme: dark)')
+watch(() => settingsStore.settings.app.colorScheme, (colorScheme) => {
+ if (colorScheme === '') {
+ prefersColorScheme.addEventListener('change', updateTheme)
+ }
+ else {
+ prefersColorScheme.removeEventListener('change', updateTheme)
+ }
+ nextTick(() => {
+ updateTheme()
+ })
+}, {
+ immediate: true,
+})
+function updateTheme() {
+ switch (settingsStore.currentColorScheme) {
+ case 'light':
+ document.body.removeAttribute('arco-theme')
+ break
+ case 'dark':
+ document.body.setAttribute('arco-theme', 'dark')
+ break
+ }
+}
+</script>
+
+<template>
+ <AConfigProvider :locale="locales[settingsStore.lang]">
+ <slot />
+ </AConfigProvider>
+</template>删除相关文件
.
+├─ plop-templates
+│ └─ module // 标准模块模板基于 Element Plus 开发，需要删除
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ IconPicker
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader修改登录页
由于登录页使用了 Element Plus 组件，并且删除会导致框架无法正常使用，所以此处需要开发者自行修改或者重新制作登录页，或者也可以参考下方示例中已经修改好的登录页。
卸载
sh
# 卸载 Element Plus
+pnpm remove element-plus完成
至此，你已经将框架中的 Element Plus 组件库替换为 Arco Design Vue 组件库，并且可以开始使用 Arco Design Vue 进行业务开发了。
示例
如果对上述的步骤还有不清楚的地方，可以访问此仓库查看示例源码，以及此链接查看示例网站。
Skip to content
替换为 iDux
注意
v4.0 之前的版本不支持替换组件库，本文适用于 v4.0 及之后的版本。
由于框架默认使用的是 Element Plus 组件库，并且演示源码中大量示例也使用了 Element Plus，如果你需要使用 iDux，请拉取框架源码分支，或者到 Github Releases 页面下载框架源码压缩包。
专业版用户也同样，请到专业版仓库下载框架源码。
安装
sh
# 安装依赖
+pnpm install
+
+# 安装 iDux
+pnpm add @idux/cdk @idux/components代码调整
基础版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import IduxCdk from '@idux/cdk'
+import IduxComponents from '@idux/components'
+import { IDUX_ICON_DEPENDENCIES, addIconDefinitions } from '@idux/components/icon'
+import { createGlobalConfig } from '@idux/components/config'
+import { zhCN } from '@idux/components/locales'
+import '@idux/components/index.full.css'
+
+function install(app: App) {
+ addIconDefinitions(IDUX_ICON_DEPENDENCIES)
+ app.use(IduxCdk).use(IduxComponents).use(createGlobalConfig({ locale: zhCN }))
+}
+
+export default { install }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+</script>
+
+<template>
+ <IxThemeProvider :preset-theme="settingsStore.currentColorScheme === 'dark' ? 'dark' : 'default'">
+ <IxMessageProvider>
+ <slot />
+ </IxMessageProvider>
+ </IxThemeProvider>
+</template>删除相关文件
.
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader专业版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import IduxCdk from '@idux/cdk'
+import IduxComponents from '@idux/components'
+import { IDUX_ICON_DEPENDENCIES, addIconDefinitions } from '@idux/components/icon'
+import { enUS, zhCN } from '@idux/components/locales'
+import '@idux/components/index.full.css'
+
+// 此处的对象属性和 src/locales/index.ts 中的 messages 对象属性一一对应
+const locales: { [key: string]: any } = {
+ 'zh-cn': zhCN,
+ 'zh-tw': zhCN,
+ 'en': enUS,
+}
+
+function install(app: App) {
+ addIconDefinitions(IDUX_ICON_DEPENDENCIES)
+ app.use(IduxCdk).use(IduxComponents)
+}
+
+export default { install }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { useGlobalConfig } from '@idux/components/config'
+import { locales } from './index'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+
+const [, setLocale] = useGlobalConfig('locale', locales[settingsStore.lang])
+watch(() => settingsStore.lang, val => setLocale(locales[settingsStore.lang]))
+</script>
+
+<template>
+ <IxThemeProvider :preset-theme="settingsStore.currentColorScheme === 'dark' ? 'dark' : 'default'">
+ <IxMessageProvider>
+ <slot />
+ </IxMessageProvider>
+ </IxThemeProvider>
+</template>删除相关文件
.
+├─ plop-templates
+│ └─ module // 标准模块模板基于 Element Plus 开发，需要删除
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ IconPicker
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader修改登录页
由于登录页使用了 Element Plus 组件，并且删除会导致框架无法正常使用，所以此处需要开发者自行修改或者重新制作登录页，或者也可以参考下方示例中已经修改好的登录页。
卸载
sh
# 卸载 Element Plus
+pnpm remove element-plus完成
至此，你已经将框架中的 Element Plus 组件库替换为 iDux 组件库，并且可以开始使用 iDux 进行业务开发了。
示例
如果对上述的步骤还有不清楚的地方，可以访问此仓库查看示例源码，以及此链接查看示例网站。
Skip to content
替换为 Naive UI
注意
v4.0 之前的版本不支持替换组件库，本文适用于 v4.0 及之后的版本。
由于框架默认使用的是 Element Plus 组件库，并且演示源码中大量示例也使用了 Element Plus，如果你需要使用 Naive UI，请拉取框架源码分支，或者到 Github Releases 页面下载框架源码压缩包。
专业版用户也同样，请到专业版仓库下载框架源码。
安装
sh
# 安装依赖
+pnpm install
+
+# 安装 Naive UI
+pnpm add naive-ui -D代码调整
基础版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ "naive-ui/volar"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import naive from 'naive-ui'
+
+function install(app: App) {
+ app.use(naive)
+}
+
+export default { install }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { darkTheme, dateZhCN, zhCN } from 'naive-ui'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+</script>
+
+<template>
+ <NConfigProvider :locale="zhCN" :date-locale="dateZhCN" :theme="settingsStore.currentColorScheme === 'dark' ? darkTheme : undefined" style="height: 100%;">
+ <NMessageProvider>
+ <slot />
+ <NGlobalStyle />
+ </NMessageProvider>
+ </NConfigProvider>
+</template>删除相关文件
.
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader专业版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ "naive-ui/volar"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import naive, { dateEnUS, dateZhCN, dateZhTW, enUS, zhCN, zhTW } from 'naive-ui'
+
+function install(app: App) {
+ app.use(naive)
+}
+
+// 此处的对象属性和 src/locales/index.ts 中的 messages 对象属性一一对应
+const locales: { [key: string]: any } = {
+ 'zh-cn': {
+ ui: zhCN,
+ date: dateZhCN,
+ },
+ 'zh-tw': {
+ ui: zhTW,
+ date: dateZhTW,
+ },
+ 'en': {
+ ui: enUS,
+ date: dateEnUS,
+ },
+}
+
+export default { install }
+export { locales }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { darkTheme } from 'naive-ui'
+import { locales } from './index'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+</script>
+
+<template>
+ <NConfigProvider :locale="locales[settingsStore.lang].ui" :date-locale="locales[settingsStore.lang].date" :theme="settingsStore.currentColorScheme === 'dark' ? darkTheme : undefined" style="height: 100%;">
+ <NMessageProvider>
+ <slot />
+ <NGlobalStyle />
+ </NMessageProvider>
+ </NConfigProvider>
+</template>修改登录页
由于登录页使用了 Element Plus 组件，并且删除会导致框架无法正常使用，所以此处需要开发者自行修改或者重新制作登录页，或者也可以参考下方示例中已经修改好的登录页。
卸载
sh
# 卸载 Element Plus
+pnpm remove element-plus完成
至此，你已经将框架中的 Element Plus 组件库替换为 Naive UI 组件库，并且可以开始使用 Naive UI 进行业务开发了。
示例
如果对上述的步骤还有不清楚的地方，可以访问此仓库查看示例源码，以及此链接查看示例网站。
Skip to content
替换为 TDesign
注意
v4.0 之前的版本不支持替换组件库，本文适用于 v4.0 及之后的版本。
由于框架默认使用的是 Element Plus 组件库，并且演示源码中大量示例也使用了 Element Plus，如果你需要使用 TDesign，请拉取框架源码分支，或者到 Github Releases 页面下载框架源码压缩包。
专业版用户也同样，请到专业版仓库下载框架源码。
安装
sh
# 安装依赖
+pnpm install
+
+# 安装 TDesign
+pnpm add tdesign-vue-next代码调整
基础版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ },
+ ...
+ "include": [
+ "src/**/*.ts",
+ "src/**/*.d.ts",
+ "src/**/*.tsx",
+ "src/**/*.vue"
+ "src/**/*.vue",
+ "node_modules/tdesign-vue-next/global.d.ts"
+ ]
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import TDesign from 'tdesign-vue-next'
+import 'tdesign-vue-next/es/style/index.css'
+
+function install(app: App) {
+ app.use(TDesign)
+}
+
+export default { install }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { merge } from 'lodash-es'
+import zhCN from 'tdesign-vue-next/es/locale/zh_CN'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+
+const prefersColorScheme = window.matchMedia('(prefers-color-scheme: dark)')
+watch(() => settingsStore.settings.app.colorScheme, (colorScheme) => {
+ if (colorScheme === '') {
+ prefersColorScheme.addEventListener('change', updateTheme)
+ }
+ else {
+ prefersColorScheme.removeEventListener('change', updateTheme)
+ }
+ nextTick(() => {
+ updateTheme()
+ })
+}, {
+ immediate: true,
+})
+function updateTheme() {
+ switch (settingsStore.currentColorScheme) {
+ case 'light':
+ document.documentElement.removeAttribute('theme-mode')
+ break
+ case 'dark':
+ document.documentElement.setAttribute('theme-mode', 'dark')
+ break
+ }
+}
+</script>
+
+<template>
+ <TConfigProvider :global-config="merge(zhCN)">
+ <slot />
+ </TConfigProvider>
+</template>删除相关文件
.
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader专业版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ },
+ ...
+ "include": [
+ "src/**/*.ts",
+ "src/**/*.d.ts",
+ "src/**/*.tsx",
+ "src/**/*.vue"
+ "src/**/*.vue",
+ "node_modules/tdesign-vue-next/global.d.ts"
+ ]
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import TDesign from 'tdesign-vue-next'
+import 'tdesign-vue-next/es/style/index.css'
+
+import zhCN from 'tdesign-vue-next/es/locale/zh_CN'
+import zhTW from 'tdesign-vue-next/es/locale/zh_TW'
+import en from 'tdesign-vue-next/es/locale/en_US'
+
+function install(app: App) {
+ app.use(TDesign)
+}
+
+// 此处的对象属性和 src/locales/index.ts 中的 messages 对象属性一一对应
+const locales: { [key: string]: any } = {
+ 'zh-cn': zhCN,
+ 'zh-tw': zhTW,
+ 'en': en,
+}
+
+export default { install }
+export { locales }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { merge } from 'lodash-es'
+import { locales } from './index'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+
+const prefersColorScheme = window.matchMedia('(prefers-color-scheme: dark)')
+watch(() => settingsStore.settings.app.colorScheme, (colorScheme) => {
+ if (colorScheme === '') {
+ prefersColorScheme.addEventListener('change', updateTheme)
+ }
+ else {
+ prefersColorScheme.removeEventListener('change', updateTheme)
+ }
+ nextTick(() => {
+ updateTheme()
+ })
+}, {
+ immediate: true,
+})
+function updateTheme() {
+ switch (settingsStore.currentColorScheme) {
+ case 'light':
+ document.documentElement.removeAttribute('theme-mode')
+ break
+ case 'dark':
+ document.documentElement.setAttribute('theme-mode', 'dark')
+ break
+ }
+}
+</script>
+
+<template>
+ <TConfigProvider :global-config="merge(locales[settingsStore.lang])">
+ <slot />
+ </TConfigProvider>
+</template>删除相关文件
.
+├─ plop-templates
+│ └─ module // 标准模块模板基于 Element Plus 开发，需要删除
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ IconPicker
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader修改登录页
由于登录页使用了 Element Plus 组件，并且删除会导致框架无法正常使用，所以此处需要开发者自行修改或者重新制作登录页，或者也可以参考下方示例中已经修改好的登录页。
卸载
sh
# 卸载 Element Plus
+pnpm remove element-plus完成
至此，你已经将框架中的 Element Plus 组件库替换为 TDesign 组件库，并且可以开始使用 TDesign 进行业务开发了。
示例
如果对上述的步骤还有不清楚的地方，可以访问此仓库查看示例源码，以及此链接查看示例网站。
Skip to content
替换为 Vexip UI
注意
v4.0 之前的版本不支持替换组件库，本文适用于 v4.0 及之后的版本。
由于框架默认使用的是 Element Plus 组件库，并且演示源码中大量示例也使用了 Element Plus，如果你需要使用 Vexip UI，请拉取框架源码分支，或者到 Github Releases 页面下载框架源码压缩包。
专业版用户也同样，请到专业版仓库下载框架源码。
安装
sh
# 安装依赖
+pnpm install
+
+# 安装 Vexip UI
+pnpm add vexip-ui代码调整
基础版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import { install as vexipInstall } from 'vexip-ui'
+import 'vexip-ui/css/index.css'
+import 'vexip-ui/css/dark/index.css'
+
+function install(app: App) {
+ app.use(vexipInstall, {
+ prefix: 'vxp',
+ })
+}
+
+export default { install }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { zhCNLocale } from 'vexip-ui'
+</script>
+
+<template>
+ <VxpConfigProvider :locale="zhCNLocale()">
+ <slot />
+ </VxpConfigProvider>
+</template>删除相关文件
.
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader专业版
修改 /tsconfig.json 文件
json
{
+ "compilerOptions": {
+ ...
+ "types": [
+ ...
+ "element-plus/global"
+ ],
+ ...
+ }
+}整体修改 /src/ui-provider/index.ts 文件
ts
import type { App } from 'vue'
+import { install as vexipInstall, zhCNLocale, zhTWLocale, enUSLocale } from 'vexip-ui'
+import 'vexip-ui/css/index.css'
+import 'vexip-ui/css/dark/index.css'
+
+function install(app: App) {
+ app.use(vexipInstall, {
+ prefix: 'vxp',
+ })
+}
+
+// 此处的对象属性和 src/locales/index.ts 中的 messages 对象属性一一对应
+const locales: { [key: string]: any } = {
+ 'zh-cn': zhCNLocale(),
+ 'zh-tw': zhTWLocale(),
+ 'en': enUSLocale(),
+}
+
+export default { install }
+export { locales }整体修改 /src/ui-provider/index.vue 文件
vue
<script setup lang="ts">
+import { locales } from './index'
+import useSettingsStore from '@/store/modules/settings'
+
+const settingsStore = useSettingsStore()
+</script>
+
+<template>
+ <VxpConfigProvider :locale="locales[settingsStore.lang]">
+ <slot />
+ </VxpConfigProvider>
+</template>删除相关文件
.
+├─ plop-templates
+│ └─ module // 标准模块模板基于 Element Plus 开发，需要删除
+└─ src
+ └─ components // 下列扩展组件基于 Element Plus 二次封装，需要删除
+ ├─ FileUpload
+ ├─ IconPicker
+ ├─ ImagePreview
+ ├─ ImagesUpload
+ ├─ ImageUpload
+ └─ PcasCascader修改登录页
由于登录页使用了 Element Plus 组件，并且删除会导致框架无法正常使用，所以此处需要开发者自行修改或者重新制作登录页，或者也可以参考下方示例中已经修改好的登录页。
卸载
sh
# 卸载 Element Plus
+pnpm remove element-plus完成
至此，你已经将框架中的 Element Plus 组件库替换为 Vexip UI 组件库，并且可以开始使用 Vexip UI 进行业务开发了。
示例
如果对上述的步骤还有不清楚的地方，可以访问此仓库查看示例源码，以及此链接查看示例网站。
Skip to content
资源
图片
全局公共
全局公共图片存放在 /src/assets/images/ 目录下，可自行新建文件夹分类管理。
局部私有
局部私有图片建议采用就近原则，你可以在需要的模块文件夹下建立一个 images 文件夹，专门用于存放局部私有图片。
样式
全局公共
全局公共样式存放在 /src/assets/styles/ 目录下，可自行新建文件，并在 /src/main.ts 中引入即可。
此目录下还有一个特殊目录，即 /src/assets/styles/resources/ ，这是全局 SCSS 资源目录，你可以在该目录下编写变量、函数、混合等支持 SCSS 特性的代码。
局部私有
基于单文件组件规范，局部私有样式建议直接在 .vue 文件中编写，框架集成了 UnoCSS / PostCSS / SCSS 方案，可选择自己适合的方案。更多单文件组件 CSS 功能请参考这里。
UnoCSS
vue
<template>
+ <div class="flex flex-1 flex-col select-none text-center all:transition-400">
+ <div class="ma">
+ <div class="animate-bounce-alt animate-duration-1s animate-count-infinite text-5xl fw100">
+ UnoCSS
+ </div>
+ </div>
+ </div>
+</template>PostCSS
框架内置了 postcss-nested 插件，可实现接近于 SCSS 的写法和特性。
vue
<style scoped>
+.phone {
+ &_title {
+ width: 500px;
+ @media (max-width: 500px) {
+ width: auto;
+ }
+ body.is_dark & {
+ color: white;
+ }
+ }
+ img {
+ display: block;
+ }
+}
+</style>SCSS
vue
<style lang="scss" scoped>
+$width: 500px;
+
+.phone {
+ &_title {
+ width: $width;
+ @media (max-width: $width) {
+ width: auto;
+ }
+ body.is_dark & {
+ color: white;
+ }
+ }
+ img {
+ display: block;
+ }
+}
+</style>组件
全局公共
说明
全局公共组件在使用时，无需手动引入，框架会在你使用时自动引入，该特性由 unplugin-vue-components 提供支持。
全局公共组件存放在 /src/components/ 目录下，每个组件按文件夹进行区分。
每个组件的文件夹内至少保留一个文件名为 index.vue 的组件入口（可参考 SvgIcon 组件），文件夹名称即为组件名。
推荐使用 pnpm new 指令进行组件生成，详细可查看《代码文件自动生成》。
局部私有
局部私有组件建议采用就近原则，你可以在需要的模块文件夹下建立一个 components 文件夹，专门用于存放局部私有组件。
Skip to content
路由
由于框架采用了全新的交互方式，使得路由在本框架中并非核心功能。通过打开 /src/router/index.ts 可以看到，框架一共定义了两个路由地址，一个是登录地址，另一个是登录成功后的地址。
免登录页面 专业版
基于设置的路由规则，新增的任何路由，都必须登录后才能访问。如果希望增加免登录的页面，也就是脱离框架本身，相对独立的页面，你可以按照下面的方式处理。
首先在 /src/router/index.ts 里 routes 配置免登录页面的路由，然后在 noLoginWhitelist 里增加一句路由完整地址。例如下面的例子，就增加了一个 /no/login/example 的免登录页面地址。
ts
// 固定路由
+const routes = [
+ ...,
+ {
+ path: '/no/login/example',
+ name: 'noLoginExample',
+ component: () => import('@/views/no-login-example.vue'),
+ meta: {
+ title: '免登录页面',
+ },
+ },
+]
+
+// 免登录白名单
+const noLoginWhitelist = [
+ ...,
+ '/no/login/example',
+] Skip to content
开始
做好准备工作后，请在项目根目录下依次执行以下命令：
sh
# 安装依赖
+# 注意，必须使用 pnpm 安装依赖，请勿使用 npm 或 yarn 安装依赖
+pnpm install
+
+# 运行
+pnpm run dev运行成功后，会自动访问页面，默认地址为 http://localhost:9000
报错
安装依赖时提示 404 ，或者安装结束后，运行时提示「 'vite' 不是内部或外部命令，也不是可运行的程序或批处理文件 」，都些都是依赖未安装成功导致的。可以尝试执行 pnpm config set registry https://registry.npmmirror.com/ 切换为国内 npmmirror 源（也可以使用 nrm 一键切换源），然后删除根目录下 /node_modules 文件夹并重新安装依赖。
如果依旧无法运行（基本不太可能），可尝试删除根目录下 /node_modules 文件夹与 pnpm-lock.yaml 文件后，再删除 package.json 中 "preinstall": "npx only-allow pnpm" 这句脚本，最后使用 npm / yarn 进行安装依赖。但需要清楚一点，这样操作后，将无法与官方环境锁定的依赖包版本保持一致，可能会出现无法预知的问题，非必要情况下，请勿使用该方案。
Skip to content
私有 Storage 数据 专业版
由于 localStorage 和 sessionStorage 的同源策略，同一域名下的 storage 数据会共享。如果你恰好需要在同一域名下部署两套(及以上)系统，不可避免会出现 storage 数据冲突，框架提供了一个 storage 类来解决这个问题。
解决同源 storage 数据冲突的方式就是增加前缀区分，首先需要在应用配置里设置，这里需要你设置一个唯一且不重名的前缀。
ts
const globalSettings: Settings.all = {
+ app: {
+ storagePrefix: 'osa_',
+ },
+}然后在需要使用到 storage 的地方引入：
ts
import storage from '@/utils/storage'这个类封装了 setItem() ，getItem() ，removeItem() ，clear() 方法，同时还增加了一个 has() 方法用来判断对象是否存在：
ts
// localStorage
+storage.local.has(key)
+storage.local.get(key)
+storage.local.set(key, value)
+storage.local.remove(key)
+storage.local.clear()
+
+// sessionStorage
+storage.session.has(key)
+storage.session.get(key)
+storage.session.set(key, value)
+storage.session.remove(key)
+storage.session.clear()注意
由于 localStorage 有容量上限，一般为 5M ，如果一同域名下部署两套系统，意味着两套系统共享 5M 容量，所以不建议在同一域名部署太多套系统，避免出现 localStorage 不够用的情况。
Skip to content
全局状态管理
TIP
Pinia 已正式成为 Vue.js 官方状态库，如果你对 Pinia 还不熟悉，除了通过 Pinia 官网学习外，我还收集了一些文字/视频的介绍，可以帮助你快速上手。
全局状态文件存放在 /src/store/modules/ 目录下，请按模块进行区分。同时请保证文件名和文件内唯一ID保持一致，建议使用 pnpm new 指令进行创建。
例如新建一个 example.ts 的文件：
ts
const useExampleStore = defineStore(
+ // 唯一ID
+ 'example',
+ () => {
+ const someThing = ref(0)
+
+ return {
+ someThing,
+ }
+ },
+)
+
+export default useExampleStore使用方法：
ts
import useExampleStore from '@/store/modules/example'
+const exampleStore = useExampleStore()
+
+exampleStore.someThing Skip to content
图标
框架提供了三种使用图标的方式，你可以根据自己的使用需求自行选择。
自定义图标
你可以去阿里巴巴矢量图标库，或者其它支持下载 SVG 图标文件的网站，又或者是设计师绘制的 SVG 文件，将准备好的 SVG 图标文件放到 /src/assets/icons/ 目录下，然后在页面中就可以通过 SvgIcon 组件使用了，name 就是 svg 的文件名。
vue
<!-- /src/assets/icons/example.svg -->
+<SvgIcon name="example" />Iconify 图标
介绍
Iconify 提供 100+ 套图标集，有 100,000+ 个图标可以免费使用。
除了可以在 Iconify 官网上查找搜需要的图标，你还可以在 Icônes 网站 上查找，这是一个基于 Iconify 的在线图标搜索网站，它比 Iconify 官网的操作更直观。
Unocss 方案
说明
Unocss 方案采用了 CSS 去处理图标的展示，框架大部分核心模块里采用的是这种方式，如果你对其中的技术细节感兴趣，可以阅读这篇 Unocss 作者的《聊聊纯 CSS 图标》这篇文章。
框架已经做好了所有配置，使用方式也极为简单，你只需进入 Iconify 官网 上查找 Iconify 提供的所有图标，然后点击需要使用的图标，复制图标名称，在任意原生 HTML 标签上通过设置 class ，格式为 i-{集合名}:{图标名}，例如：
vue
<div class="i-ep:arrow-right" />
+<i class="i-ep:search" />当然你同样也可以通过 SvgIcon 使用它。
vue
<SvgIcon name="i-ep:arrow-right" />在使用 Unocss 图标时，需要注意以下两点：
图标字符串不支持拼接
vue<!-- 这样不会生效 --> +<SvgIcon :name="'i-ep' + ':search'" />图标字符串不支持异步返回
vue<!-- 这样不会生效 --> +<!-- 假设 name 是异步请求返回的数据，name 为 i-ep:search --> +<SvgIcon :name="name" />
如果确实有以上需求，你可以使用 Iconify 原生提供的方案。
Iconify 原生方案
说明
框架保留了 Iconify 官方提供的使用方式，格式为 {集合名}:{图标名} 。
vue
<script setup>
+import { Icon } from '@iconify/vue'
+</script>
+
+<template>
+ <Icon icon="ep:arrow-right" />
+</template>当然这么使用并没有很方便，依旧还是需要手动导入一个 Icon 组件。如果你也觉得麻烦的话，那么你可以使用 SvgIcon 组件来展示，框架已经帮你做好的所有处理。
vue
<SvgIcon name="ep:arrow-right" />离线/内网环境使用
说明
优先推荐使用 Unocss 方案，它不受网络环境限制，且相对于 Iconify 原生方案，它的性能更好。
如果你清楚自己需要使用 Iconify 原生方案，并且想要在离线/内网环境使用，需要做一些额外的配置。因为 Iconify 图标默认是提供在线的服务，即首次调用会触发一个外部网络请求去获取 svg 原始数据，并缓存在 localStorage 和 sessionStorage 中，这样下次再调用的时候，则直接从缓存中获取并展示。
框架提供了一份解决方案，在命令行执行 pnpm run generate:icons ，按照指引选择你需要用到的图标集（此处选择的图标集也是图标选择器里展示的图标集），并选择使用方式为离线。这样再在框架中使用这些图标，就不会触发外部网络请求了，但如果使用选择之外的图标，依旧还是会触发外部网络请求。
图标选择器 专业版
图标选择器是一个特殊的组件，它需要展示多套图标集内的所有图标。
通过执行 pnpm run generate:icons 命令，并按照指引完成操作后，图标选择器就会自动生效了。
Skip to content
主题
框架主题
主题配色存放在 /themes/index.ts 文件中，基础版和专业版内容略有不同。
基础版
ts
import { hex2rgba } from '@unocss/preset-mini/utils'
+
+export const lightTheme = {
+ 'color-scheme': 'light',
+ // 内置 UI
+ '--ui-primary': hex2rgba('#0f0f0f')!.join(' '),
+ '--ui-text': hex2rgba('#fcfcfc')!.join(' '),
+ // 主体
+ '--g-app-bg': '#fff',
+ '--g-main-bg': '#f2f2f2',
+ '--g-border-color': '#f2f2f2',
+ // 头部
+ '--g-header-bg': '#fff',
+ '--g-header-color': '#0f0f0f',
+ '--g-header-menu-color': '#0f0f0f',
+ '--g-header-menu-hover-bg': '#dde1e3',
+ '--g-header-menu-hover-color': '#0f0f0f',
+ '--g-header-menu-active-bg': '#0f0f0f',
+ '--g-header-menu-active-color': '#fff',
+ // 主导航
+ '--g-main-sidebar-bg': '#f2f2f2',
+ '--g-main-sidebar-menu-color': '#0f0f0f',
+ '--g-main-sidebar-menu-hover-bg': '#dde1e3',
+ '--g-main-sidebar-menu-hover-color': '#0f0f0f',
+ '--g-main-sidebar-menu-active-bg': '#0f0f0f',
+ '--g-main-sidebar-menu-active-color': '#fff',
+ // 次导航
+ '--g-sub-sidebar-bg': '#fff',
+ '--g-sub-sidebar-logo-bg': '#0f0f0f',
+ '--g-sub-sidebar-logo-color': '#fff',
+ '--g-sub-sidebar-menu-color': '#0f0f0f',
+ '--g-sub-sidebar-menu-hover-bg': '#dde1e3',
+ '--g-sub-sidebar-menu-hover-color': '#0f0f0f',
+ '--g-sub-sidebar-menu-active-bg': '#0f0f0f',
+ '--g-sub-sidebar-menu-active-color': '#fff',
+ // 工具栏
+ '--g-toolbar-bg': '#fff',
+}
+
+export const darkTheme = {
+ 'color-scheme': 'dark',
+ // 内置 UI
+ '--ui-primary': hex2rgba('#e5e5e5')!.join(' '),
+ '--ui-text': hex2rgba('#0f0f0f')!.join(' '),
+ // 主体
+ '--g-app-bg': '#141414',
+ '--g-main-bg': '#0a0a0a',
+ '--g-border-color': '#15191e',
+ // 头部
+ '--g-header-bg': '#141414',
+ '--g-header-color': '#e5e5e5',
+ '--g-header-menu-color': '#a8a29e',
+ '--g-header-menu-hover-bg': '#141414',
+ '--g-header-menu-hover-color': '#e5e5e5',
+ '--g-header-menu-active-bg': '#e5e5e5',
+ '--g-header-menu-active-color': '#0a0a0a',
+ // 主导航
+ '--g-main-sidebar-bg': '#0a0a0a',
+ '--g-main-sidebar-menu-color': '#a8a29e',
+ '--g-main-sidebar-menu-hover-bg': '#141414',
+ '--g-main-sidebar-menu-hover-color': '#e5e5e5',
+ '--g-main-sidebar-menu-active-bg': '#e5e5e5',
+ '--g-main-sidebar-menu-active-color': '#0a0a0a',
+ // 次导航
+ '--g-sub-sidebar-bg': '#141414',
+ '--g-sub-sidebar-logo-bg': '#0f0f0f',
+ '--g-sub-sidebar-logo-color': '#e5e5e5',
+ '--g-sub-sidebar-menu-color': '#a8a29e',
+ '--g-sub-sidebar-menu-hover-bg': '#0a0a0a',
+ '--g-sub-sidebar-menu-hover-color': '#e5e5e5',
+ '--g-sub-sidebar-menu-active-bg': '#e5e5e5',
+ '--g-sub-sidebar-menu-active-color': '#0a0a0a',
+ // 工具栏
+ '--g-toolbar-bg': '#141414',
+}专业版
与基础版不同，专业版默认提供了 12 款主题，明亮和暗黑模式各 6 款，并且主题在运行时共存，可实现动态切换。
ts
import { hex2rgba } from '@unocss/preset-mini/utils'
+
+export default {
+ light: {
+ // 颜色主题
+ 'color-scheme': 'light',
+ // 内置 UI
+ '--ui-primary': hex2rgba('#0f0f0f')!.join(' '),
+ '--ui-text': hex2rgba('#fcfcfc')!.join(' '),
+ // 主体
+ '--g-app-bg': '#fff',
+ '--g-main-bg': '#f2f2f2',
+ '--g-border-color': '#f2f2f2',
+ // 头部
+ '--g-header-bg': '#fff',
+ '--g-header-color': '#0f0f0f',
+ '--g-header-menu-color': '#0f0f0f',
+ '--g-header-menu-hover-bg': '#dde1e3',
+ '--g-header-menu-hover-color': '#0f0f0f',
+ '--g-header-menu-active-bg': '#0f0f0f',
+ '--g-header-menu-active-color': '#fff',
+ // 主导航
+ '--g-main-sidebar-bg': '#f2f2f2',
+ '--g-main-sidebar-menu-color': '#0f0f0f',
+ '--g-main-sidebar-menu-hover-bg': '#dde1e3',
+ '--g-main-sidebar-menu-hover-color': '#0f0f0f',
+ '--g-main-sidebar-menu-active-bg': '#0f0f0f',
+ '--g-main-sidebar-menu-active-color': '#fff',
+ // 次导航
+ '--g-sub-sidebar-bg': '#fff',
+ '--g-sub-sidebar-logo-bg': '#0f0f0f',
+ '--g-sub-sidebar-logo-color': '#fff',
+ '--g-sub-sidebar-menu-color': '#0f0f0f',
+ '--g-sub-sidebar-menu-hover-bg': '#dde1e3',
+ '--g-sub-sidebar-menu-hover-color': '#0f0f0f',
+ '--g-sub-sidebar-menu-active-bg': '#0f0f0f',
+ '--g-sub-sidebar-menu-active-color': '#fff',
+ // 工具栏
+ '--g-toolbar-bg': '#fff',
+ },
+ ...
+ dark: {
+ // 颜色主题
+ 'color-scheme': 'dark',
+ // 内置 UI
+ '--ui-primary': hex2rgba('#e5e5e5')!.join(' '),
+ '--ui-text': hex2rgba('#0f0f0f')!.join(' '),
+ // 主体
+ '--g-app-bg': '#141414',
+ '--g-main-bg': '#0a0a0a',
+ '--g-border-color': '#15191e',
+ // 头部
+ '--g-header-bg': '#141414',
+ '--g-header-color': '#e5e5e5',
+ '--g-header-menu-color': '#a8a29e',
+ '--g-header-menu-hover-bg': '#141414',
+ '--g-header-menu-hover-color': '#e5e5e5',
+ '--g-header-menu-active-bg': '#e5e5e5',
+ '--g-header-menu-active-color': '#0a0a0a',
+ // 主导航
+ '--g-main-sidebar-bg': '#0a0a0a',
+ '--g-main-sidebar-menu-color': '#a8a29e',
+ '--g-main-sidebar-menu-hover-bg': '#141414',
+ '--g-main-sidebar-menu-hover-color': '#e5e5e5',
+ '--g-main-sidebar-menu-active-bg': '#e5e5e5',
+ '--g-main-sidebar-menu-active-color': '#0a0a0a',
+ // 次导航
+ '--g-sub-sidebar-bg': '#141414',
+ '--g-sub-sidebar-logo-bg': '#0f0f0f',
+ '--g-sub-sidebar-logo-color': '#e5e5e5',
+ '--g-sub-sidebar-menu-color': '#a8a29e',
+ '--g-sub-sidebar-menu-hover-bg': '#0a0a0a',
+ '--g-sub-sidebar-menu-hover-color': '#e5e5e5',
+ '--g-sub-sidebar-menu-active-bg': '#e5e5e5',
+ '--g-sub-sidebar-menu-active-color': '#0a0a0a',
+ // 工具栏
+ '--g-toolbar-bg': '#141414',
+ },
+ ...
+}
如果框架提供的主题风格满足不了你的需求，你还可以自定义新的主题。
ts
import { hex2rgba } from '@unocss/preset-mini/utils'
+
+export default {
+ newThemeName: { // 主题名称
+ // 颜色主题
+ 'color-scheme': 'light', // 可选值 light/dark ，表示该主题在明亮或暗黑模式下的配色
+ // 内置 UI
+ '--ui-primary': hex2rgba('#409eff')!.join(' '),
+ '--ui-text': hex2rgba('#fcfcfc')!.join(' '),
+ // 主体
+ '--g-app-bg': '#fff',
+ '--g-main-bg': '#f2f2f2',
+ '--g-border-color': '#f2f2f2',
+ // 头部
+ '--g-header-bg': '#222b45',
+ '--g-header-color': '#fff',
+ '--g-header-menu-color': '#fff',
+ '--g-header-menu-hover-bg': '#334067',
+ '--g-header-menu-hover-color': '#fff',
+ '--g-header-menu-active-bg': '#334067',
+ '--g-header-menu-active-color': '#fff',
+ // 主导航
+ '--g-main-sidebar-bg': '#222b45',
+ '--g-main-sidebar-menu-color': '#fff',
+ '--g-main-sidebar-menu-hover-bg': '#334067',
+ '--g-main-sidebar-menu-hover-color': '#fff',
+ '--g-main-sidebar-menu-active-bg': '#334067',
+ '--g-main-sidebar-menu-active-color': '#fff',
+ // 次导航
+ '--g-sub-sidebar-bg': '#fff',
+ '--g-sub-sidebar-logo-bg': '#222b45',
+ '--g-sub-sidebar-logo-color': '#fff',
+ '--g-sub-sidebar-menu-color': '#0f0f0f',
+ '--g-sub-sidebar-menu-hover-bg': '#dde1e3',
+ '--g-sub-sidebar-menu-hover-color': '#0f0f0f',
+ '--g-sub-sidebar-menu-active-bg': '#409eff',
+ '--g-sub-sidebar-menu-active-color': '#fff',
+ // 工具栏
+ '--g-toolbar-bg': '#fff',
+ },
+}最后在应用配置中使用该主题：
ts
const globalSettings: Settings.all = {
+ app: {
+ // 如果主题是暗黑模式下使用的，则 darkTheme: 'newThemeName'
+ lightTheme: 'newThemeName',
+ },
+}颜色方案
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ app: {
+ /**
+ * 留空跟随系统
+ * light 明亮模式
+ * dark 暗黑模式
+ */
+ colorScheme: '',
+ },
+}哀悼模式 v4.5.0 新增
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ app: {
+ enableMournMode: true,
+ },
+}色弱模式 v4.5.0 新增
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ app: {
+ enableColorAmblyopiaMode: true,
+ },
+}导航栏风格 专业版
风格
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ menu: {
+ /**
+ * 留空默认
+ * arrow 箭头
+ * line 线条
+ * dot 圆点
+ */
+ style: '', // v4.5.0 之前版本为 menuActiveStyle
+ },
+}
圆角
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ menu: {
+ // 导航栏是否圆角
+ isRounded: true,
+ },
+}
开发注意
如果只在明亮或暗黑模式中，选择其中一种模式进行业务开发，那没有什么需要注意的，你可以按照以往的开发习惯进行开发，这也是框架推荐的方式。
但如果需要让用户可以自己选择明亮或暗黑模式，或者是根据浏览器主题来判断是使用明亮还是暗黑模式。这时候开发则需要注意，业务页面里使用到的颜色将不能写成固定值（例如 color 、background-color 、border-color 、box-shadow 等有涉及到颜色的属性），因为同一个色值是无法顾及到明亮和暗黑两种模式的。
这时候我们建议使用 UnoCSS 进行样式编写，例如 text-dark dark-text-white 、bg-green dark-bg-red 。如果你不习惯使用 UnoCSS ，那也可以使用下面这种方法，在页面中去自定义一些颜色。
scss
div {
+ color: #000;
+
+ [data-theme="dark"] & {
+ color: #fff;
+ }
+}最后分享一篇关于暗黑模式的文章《教你巧用UI设计中的暗黑模式——Dark Mode》，希望帮助你更好地在暗黑模式下开发出优秀的页面。
Skip to content
工具栏
工具栏主要是红框处各类功能图标。
窗口预览
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ toolbar: {
+ previewWindows: true,
+ },
+}收藏夹 专业版
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ toolbar: {
+ favorites: true,
+ },
+}详细可阅读《收藏夹》。
导航搜索
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ toolbar: {
+ navSearch: true,
+ },
+}通知中心 专业版
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ toolbar: {
+ notification: true,
+ },
+}通知中心不涉及具体业务，需开发者自行实现，相关文件在：
/src/views/components/Tools/Notification/index.vue通知中心下拉预览面板/src/views/windows/PersonalNotification/index.vue通知中心页面
国际化 专业版
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ toolbar: {
+ i18n: true,
+ },
+}如果设置为不启用，并不代表不支持国际化切换，只是不会在工具栏显示切换语言的图标，详细可阅读《国际化》。
浏览器全屏
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ toolbar: {
+ fullscreen: true,
+ },
+}颜色主题
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ toolbar: {
+ colorScheme: true,
+ },
+}如果设置为不启用，并不代表不支持颜色主题切换，只是不会在工具栏显示切换颜色主题的图标。
布局 专业版
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ toolbar: {
+ layout: ['previewWindows', 'favorites', '->', 'navSearch', 'notification', 'i18n', 'fullscreen', 'colorScheme'],
+ },
+}可自定义摆放位置和顺序，其中 -> 为分隔符，用于分隔左右两侧的工具栏。修改时请确保提供的所有值都存在，不可删减。
Skip to content
框架更新
首先明确一点，One-step-admin 无法像 npm 的插件一样更新，不仅我们的框架如此，其实大部分管理系统框架都是如此。
因为本质上这类框架其实是一个初始模板，开发者会根据自身需求去修改，然后基于业务开展业务代码编写。
所以一旦下载开始使用，基本是无法更新的，你在哪个时间点开始使用，项目就固定在什么版本了。
虽然有小部分框架选择将部分核心源码封装成 npm 依赖包，由作者全权维护，这样的处理在一定程度上有解决版本更新的问题，但弊端也很明显，开发者在二次开发上会有明显的局限，作者认为是得不偿失的。
那有没有解决办法么？其实也有，参考如下：
- 在基于 One-step-admin 做项目开发时尽量避免框架自带模块或组件的改动，或者改动地方做一个文档记录，可以清楚知道改动了哪些，这样当你需要进行新版本更新时，按照之前记录的文档可以有个大致的迁移方案，而业务代码则可以直接拷贝过去。
- 我们尽量在提交代码时标明每次提交改动的变更记录说明，这样你可以选择性的更新部分新代码到项目中，也就是局部更新。这种方案也是作者在公司内部项目经常使用的，因为大部分项目是无需全局更新到新版的，只需将必要的一些新特性或 bug 修复同步到原有项目中即可。
- 使用文件比较工具，例如 Beyond Compare，这款工具可以直接对比文件夹，可以清晰的列出文件夹内所有文件的差异，可以协助升级工作开展。
当然个人建议是，做为一个中后台系统框架，稳定是第一诉求，不到万不得已不建议频繁更新，因为更新的成本挺高的，每一次大更新，都需要一次完整的回归测试，以确保功能正常运行。
Skip to content
使用 Composition API 开发
TIP
Composition API 是 Vue3 全新提供的一种语法，对于从 Vue2 就在使用的开发者，如果一时半会没办法立马上手 Composition API ，你依旧可以在项目中使用 Options API 做开发。当然我们更建议你使用 Composition API 进行开发，它比 Options API 更灵活且易读。
使用
如果你还不熟悉 Composition API ，那么我们建议你阅读 Vue3 官方文档了解；如果你已经熟悉 Composition API ，那么我们建议你在开发的时候，使用 <script setup> 语法糖进行开发，它将提高很多开发上的效率。
同时得益于 unplugin-auto-import 的特性，在 <script setup> 里无需导入相关 API ，该依赖会自动导入（默认支持 vue，vue-router 和 pinia ）。
vue
<script setup lang="ts">
+// 无需手动 import 相关 API
+import { computed, ref } from 'vue'
+
+const count = ref(0)
+const doubled = computed(() => count.value * 2)
+</script>组件 name
<script setup> 可以和普通的 <script> 一起使用，所以可以这样定义组件 name：
vue
<script lang="ts">
+export default {
+ name: 'componentName',
+}
+</script>
+
+<script setup lang="ts">
+...
+</script>Vue 3.3 开始，你可以使用 defineOptions 在 <script setup> 里定义组件的 name：
vue
<script setup lang="ts">
+defineOptions({
+ name: 'ComponentName',
+})
+</script> Skip to content
页面水印 专业版
使用
在应用配置中设置：
ts
const globalSettings: Settings.all = {
+ app: {
+ enableWatermark: true,
+ },
+}效果如下：
设置水印内容
在 /src/store/modules/watermark.ts 中可修改水印展示内容，以及其他水印相关配置。
水印同时支持动态更新，示例：
vue
<script setup lang="ts">
+import useWatermarkStore from '@/store/modules/watermark'
+
+const watermarkStore = useWatermarkStore()
+
+watermarkStore.update({
+ text: '设置水印',
+ // 更多设置项请查看 /src/utils/watermark.ts 中 settingsType 类型定义
+})
+
+// 重置水印，恢复到默认设置
+watermarkStore.update()
+</script> Skip to content
为什么选择我们 ?
如果你正在做后台框架相关的调研或选型，相信这篇介绍能帮助你快速了解 One-step-admin 的特点，以及与传统后台框架的对比。
长期且稳定
One-step-admin 自 2021/11/01 正式对外发布，截止到今天为止，已持续维护 1036 天。
高效的交互方式
摆脱传统后台框架路由跳转的交互，将每个模块以窗口的形式展示在同一个界面中，让使用人员可以做到跨模块的多线操作。
窗口最大化
窗口默认宽度为 800px ，可以在项目中进行调整，也可以通过最大化按钮将窗口最大化展示，以便展示更多信息。
快速定位操作窗口
提供的预览界面可以帮助使用人员快速定位到需要操作的窗口。
专注模式
可勾选多个窗口平均分布在页面中，专注于所勾选的窗口进行操作。
窗口排序
快速调整窗口的展示顺序。
继承自 Fantastic-admin
本框架继承了 Fantastic-admin 许多优秀的特性。例如同样提供了 5 款导航栏模式，3 款导航栏风格以及 6 款主题配色，导航也提供了各种展示形态的设置，显隐、标题、图标、徽标、外链等。
为什么不是 Fantastic-admin ?
这里的 Fantastic-admin 代表了市面上几乎所有的传统后台框架，它们的优势在于理解成本低，每个页面的功能明确，需要做什么操作就进入不同的页面。
而劣势也是因为这种优势导致的，例如要在多个模块之间进行操作，就需要频繁切换路由，而切换路由会导致之前页面上的数据丢失，进而扩展了页面缓存和标签栏的特性，但也变相增加了开发人员的开发成本。其次现在的显示器都在往高分屏/带鱼屏发展，当页面展示内容不多的时候，界面上会显示大量的留白，造成空间浪费。
基于传统后台框架的这些痛点，One-step-admin 应运而生，它探索出了一种全新的交互方式，有效提高了使用人员的操作效率，同时也减轻了开发人员的开发成本。
以上面举例的场景，在 One-step-admin 里，因为模块都以窗口的形式在同一个界面上展示，所以就不存在切换路由，也就不存在切换路由导致页面数据丢失的场景，开发人员只需关注模块内的业务实现即可。
Skip to content
窗口
窗口即组件，存放在 /src/views/windows/ 目录下，类似于全局组件，文件夹名即为组件名，在窗口打开的时候会动态加载组件。
每个窗口的文件夹内至少保留一个文件名为 index.vue 的入口文件。
注意
由于窗口展示的特殊性，请勿在窗口组件内使用 position: fixed; 样式。
Skip to content