v3.3.5细节优化，使用手册更新

MANUAL.md

@@ -2,7 +2,7 @@
 
 ## 前言
 
-> `Ray Template` 默认使用 `yarn` 作为包管理器，并且默认启用严格模式的 `eslint`。
+> `Ray Template` 默认使用 `yarn` 作为包管理器，并且默认启用严格模式的 `eslint`。在导入模块的时候除 `.ts` `.tsx` `.d.ts` 文件等不需要手动补全后缀名，其余的模块导入应该手动补全所有后缀名。
 
 ### 使用
 
@@ -16,4 +16,146 @@ yarn
 npm i
 ```
 
-#### 未完待续。。。后续慢慢更新该文件
+#### 启动项目
+
+```sh
+# yarn
+yarn dev
+
+# npm
+npm run dev
+```
+
+#### 构建项目
+
+```sh
+# yarn
+yarn build
+
+# npm
+npm run build
+```
+
+### 国际化
+
+#### Tip
+
+- 每个新的语言包文件的文件名视为 path 开头（menu.json => menu.xxx）
+
+#### 新增语言包、新增语言模块
+
+> 项目国际化管理模块，统一放置于 `src/locales` 下。
+
+##### 文件包
+
+- lang
+- helper.ts
+- index.ts
+- useI18n.ts
+
+> 项目中使用 t locale 方法时，使用模板提供方法（useI18n.ts）
+
+```tsx
+// 引入包
+import { useI18n } from '@/locales/useI18n'
+
+const { t, locale } = useI18n()
+
+/**
+ *
+ * t: 用于绑定国际化 path
+ * locale: 用于切换系统语言。参数 key 必须与 lang 包中的语言包一致
+ */
+
+const demo = () => <span>{t('demo.demo')}</span>
+
+locale('zh-CN')
+locale('en-US')
+```
+
+##### 新增语言包
+
+> 我们举例新增台湾地区语言包。
+
+- `src/locales/lang` 文件下创建对应新语言包文件夹与语言文件
+  - zh-TW 文件夹
+  - zh-TW.ts 文件
+- 创建与原有语言格式一样的文件夹（可以直接 cv 过去）
+- 配置语言下拉项（LOCAL_OPTIONS）
+- 配置 dayjs 国际化映射（DAYJS_LOCAL_MAP）
+
+> 具体注意事项看注释。
+
+##### 最后
+
+> 按照上述步骤操作后，就已经给模板添加了一个新的语言包了。可以在页面的右上角国际化下拉框中看到新增的下拉选项，点击切换后，即可切换到对应的语言了。
+
+### 路由
+
+#### Tip
+
+- 在该模板中，路由 path 属性视 `/` 开头的路由为根路由
+- 路由会在初始化的时候将所有路由进行提升（全部提升为顶级路由），所以注意第一条 Tip
+- 路由模块会影响菜单的输出显示（菜单模块与路由模块进行拆分开来的）
+- 具体路由支持配置属性看 router/README.md 文件
+
+#### 文件包
+
+- constant 文件放置一些公共东西
+- helper 文件放置 router 的一些 hook 方法
+- modules 页面路由入口（modules 文件中每一个 xxx.ts 文件都会被视为是一个路由模块）
+- utils router 拓展方法
+- ...
+
+##### 新增路由页面
+
+- modules 中添加一个新的模块（log.ts）
+- 配置路由的相关信息
+- views 中创建 log 相关的页面信息
+
+```ts
+// 辅助函数，配合 i18n-ally 插件使用
+import { t } from '@/locales/useI18n'
+
+// 路由配置类型提示
+import type { AppRouteRecordRaw } from '@/router/type'
+
+const log: AppRouteRecordRaw = {
+  path: '/log',
+  name: 'Log',
+  component: () => import('@/views/log/index.vue'),
+  meta: {
+    i18nKey: t('menu.Log'),
+    icon: 'log',
+    order: 3,
+  },
+  children: [
+    {
+      path: 'my-log',
+      name: 'MyLog',
+      component: () => import('@/views/my-log/index.vue'),
+      meta: {
+        i18nKey: t('menu.MyLog'),
+        order: 0,
+      },
+    },
+    {
+      path: 'group-log',
+      name: 'MyLog',
+      component: () => import('@/views/group-log/index.vue'),
+      meta: {
+        i18nKey: t('menu.GroupLog'),
+        order: 0,
+      },
+    },
+  ],
+}
+
+export default log
+```
+
+##### 最后
+
+> 打开浏览器可以看到页面菜单上已经有一个日志菜单。
+
+#### 未完待续。。。后续慢慢更新该手册

src/components/RayChart/index.tsx

@@ -1,3 +1,19 @@
+/**
+ *
+ * 基于 `echarts` 的组件. 意在便捷的使用 `chart` 图
+ *
+ * 暂时不支持自动解析导入 `chart` 组件, 如果使用未注册的组件, 需要在顶部手动导入并且再使用 `use` 注册
+ *
+ * 预引入: 柱状图, 折线图, 饼图, k线图, 散点图等
+ * 预引入: 提示框, 标题, 直角坐标系, 数据集, 内置数据转换器等
+ *
+ * 如果需要大批量数据渲染, 可以通过获取实例后阶段性调用 `setOption` 方法注入数据
+ *
+ * 该组件会在卸载组件时, 自动释放资源
+ *
+ * 注意: 尽量别一次性倒入全部 `chart` 会造成打包体积异常大
+ */
+
 import './index.scss'
 
 import * as echarts from 'echarts/core' // `echarts` 核心模块
@@ -24,7 +40,7 @@ import { CanvasRenderer } from 'echarts/renderers' // `echarts` 渲染器
 
 import { useSetting } from '@/store'
 import { cloneDeep, debounce } from 'lodash-es'
-import { on, off, addStyle } from '@/utils/element'
+import { on, off, addStyle, completeSize } from '@/utils/element'
 
 import type { PropType } from 'vue'
 
@@ -209,8 +225,8 @@ const RayChart = defineComponent({
 
     const cssVarsRef = computed(() => {
       const cssVars = {
-        '--ray-chart-width': props.width,
-        '--ray-chart-height': props.height,
+        '--ray-chart-width': completeSize(props.width),
+        '--ray-chart-height': completeSize(props.height),
       }
 
       return cssVars
@@ -483,19 +499,3 @@ const RayChart = defineComponent({
 })
 
 export default RayChart
-
-/**
- *
- * 基于 `echarts` 的组件. 意在便捷的使用 `chart` 图
- *
- * 暂时不支持自动解析导入 `chart` 组件, 如果使用未注册的组件, 需要在顶部手动导入并且再使用 `use` 注册
- *
- * 预引入: 柱状图, 折线图, 饼图, k线图, 散点图等
- * 预引入: 提示框, 标题, 直角坐标系, 数据集, 内置数据转换器等
- *
- * 如果需要大批量数据渲染, 可以通过获取实例后阶段性调用 `setOption` 方法注入数据
- *
- * 该组件会在卸载组件时, 自动释放资源
- *
- * 注意: 尽量别一次性倒入全部 `chart` 会造成打包体积异常大
- */

src/locales/index.ts

@@ -20,7 +20,6 @@
  * `naive ui` 语言包切换
  *
  * 注意:
- *   - 因使用 `i18n` 提供虚拟文件注入缘故, 每次修改 `locales` 中的文件后, 需要重启项目
  *   - 建议按照主流约定语言包命名
  */
 

src/locales/useI18n.ts

@@ -42,3 +42,12 @@ export const useI18n = (namespace?: string) => {
     locale: overrideLocaleFunc,
   }
 }
+
+/**
+ *
+ * 该方法为纯函数, 无任何副作用
+ * 单纯为了配合 i18n-ally 插件使用
+ *
+ * 该插件识别 t 方法包裹 path 进行提示文案内容
+ */
+export const t = <T = unknown>(key: T) => key

src/router/modules/axios.ts

@@ -1,3 +1,5 @@
+import { t } from '@/locales/useI18n'
+
 import type { AppRouteRecordRaw } from '@/router/type'
 
 const axios: AppRouteRecordRaw = {
@@ -5,7 +7,7 @@ const axios: AppRouteRecordRaw = {
   name: 'Axios',
   component: () => import('@/views/axios/index'),
   meta: {
-    i18nKey: 'Axios',
+    i18nKey: t('menu.Axios'),
     icon: 'axios',
     order: 3,
     keepAlive: true,

src/router/modules/dashboard.ts

@@ -1,3 +1,5 @@
+import { t } from '@/locales/useI18n'
+
 import type { AppRouteRecordRaw } from '@/router/type'
 
 const dashboard: AppRouteRecordRaw = {
@@ -5,7 +7,7 @@ const dashboard: AppRouteRecordRaw = {
   name: 'Dashboard',
   component: () => import('@/views/dashboard/index'),
   meta: {
-    i18nKey: 'Dashboard',
+    i18nKey: t('menu.Dashboard'),
     icon: 'dashboard',
     order: 0,
   },

src/router/modules/doc-local.ts

@@ -1,3 +1,5 @@
+import { t } from '@/locales/useI18n'
+
 import type { AppRouteRecordRaw } from '@/router/type'
 
 const docLocal: AppRouteRecordRaw = {
@@ -5,7 +7,7 @@ const docLocal: AppRouteRecordRaw = {
   name: 'DocLocal',
   component: () => import('@/views/doc/index'),
   meta: {
-    i18nKey: 'DocLocal',
+    i18nKey: t('menu.DocLocal'),
     icon: 'doc',
     windowOpen: 'https://ray-template.yunkuangao.com/ray-template-doc/',
     order: 6,

src/router/modules/doc.ts

@@ -1,3 +1,5 @@
+import { t } from '@/locales/useI18n'
+
 import type { AppRouteRecordRaw } from '@/router/type'
 
 const doc: AppRouteRecordRaw = {
@@ -5,7 +7,7 @@ const doc: AppRouteRecordRaw = {
   name: 'Doc',
   component: () => import('@/views/doc/index'),
   meta: {
-    i18nKey: 'Doc',
+    i18nKey: t('menu.Doc'),
     icon: 'doc',
     windowOpen: 'https://xiaodaigua-ray.github.io/ray-template-doc/',
     order: 5,

src/router/modules/echart.ts

@@ -1,3 +1,5 @@
+import { t } from '@/locales/useI18n'
+
 import type { AppRouteRecordRaw } from '@/router/type'
 
 const echart: AppRouteRecordRaw = {
@@ -5,7 +7,7 @@ const echart: AppRouteRecordRaw = {
   name: 'Echart',
   component: () => import('@/views/echart/index'),
   meta: {
-    i18nKey: 'Echart',
+    i18nKey: t('menu.Echart'),
     icon: 'echart',
     order: 1,
   },

src/router/modules/error.ts

@@ -1,3 +1,5 @@
+import { t } from '@/locales/useI18n'
+
 import type { AppRouteRecordRaw } from '@/router/type'
 
 const error: AppRouteRecordRaw = {
@@ -5,7 +7,7 @@ const error: AppRouteRecordRaw = {
   name: 'ErrorPage',
   component: () => import('@/error/views/Error404/index'),
   meta: {
-    i18nKey: 'Error',
+    i18nKey: t('menu.Error'),
     icon: 'error',
     hidden: true,
   },

src/router/modules/iframe.ts

@@ -1,3 +1,5 @@
+import { t } from '@/locales/useI18n'
+
 import type { AppRouteRecordRaw } from '@/router/type'
 
 const iframe: AppRouteRecordRaw = {

src/router/modules/multi-menu.ts

@@ -1,3 +1,5 @@
+import { t } from '@/locales/useI18n'
+
 import type { AppRouteRecordRaw } from '@/router/type'
 
 import { LAYOUT } from '@/router/constant/index'
@@ -7,7 +9,7 @@ const multiMenu: AppRouteRecordRaw = {
   name: 'MultiMenu',
   component: LAYOUT,
   meta: {
-    i18nKey: 'MultiMenu',
+    i18nKey: t('menu.MultiMenu'),
     icon: 'table',
     order: 4,
   },

src/router/modules/office.ts

@@ -1,3 +1,5 @@
+import { t } from '@/locales/useI18n'
+
 import type { AppRouteRecordRaw } from '@/router/type'
 
 const office: AppRouteRecordRaw = {
@@ -5,7 +7,7 @@ const office: AppRouteRecordRaw = {
   name: 'Office',
   component: () => import('@/views/office/index'),
   meta: {
-    i18nKey: 'Office',
+    i18nKey: t('menu.Office'),
     icon: 'office',
     hidden: true,
   },

src/router/modules/precision.ts

@@ -1,3 +1,5 @@
+import { t } from '@/locales/useI18n'
+
 import type { AppRouteRecordRaw } from '@/router/type'
 
 const precision: AppRouteRecordRaw = {
@@ -5,7 +7,7 @@ const precision: AppRouteRecordRaw = {
   name: 'CalculatePrecision',
   component: () => import('@/views/precision/index'),
   meta: {
-    i18nKey: 'CalculatePrecision',
+    i18nKey: t('menu.CalculatePrecision'),
     icon: 'rely',
     order: 2,
   },

src/router/modules/rely.ts

@@ -1,3 +1,5 @@
+import { t } from '@/locales/useI18n'
+
 import type { AppRouteRecordRaw } from '@/router/type'
 
 import { LAYOUT } from '@/router/constant/index'
@@ -7,7 +9,7 @@ const rely: AppRouteRecordRaw = {
   name: 'Rely',
   component: LAYOUT,
   meta: {
-    i18nKey: 'Rely',
+    i18nKey: t('menu.Rely'),
     icon: 'rely',
     order: 7,
   },

src/router/modules/scroll-reveal.ts

@@ -1,3 +1,5 @@
+import { t } from '@/locales/useI18n'
+
 import type { AppRouteRecordRaw } from '@/router/type'
 
 const scrollReveal: AppRouteRecordRaw = {
@@ -5,7 +7,7 @@ const scrollReveal: AppRouteRecordRaw = {
   name: 'ScrollReveal',
   component: () => import('@/views/scroll-reveal/index'),
   meta: {
-    i18nKey: 'scrollReveal',
+    i18nKey: t('menu.scrollReveal'),
     icon: 'scroll_reveal',
     hidden: true,
   },

src/router/modules/table.ts

@@ -1,3 +1,5 @@
+import { t } from '@/locales/useI18n'
+
 import type { AppRouteRecordRaw } from '@/router/type'
 
 const table: AppRouteRecordRaw = {
@@ -5,7 +7,7 @@ const table: AppRouteRecordRaw = {
   name: 'TableView',
   component: () => import('@/views/table/index'),
   meta: {
-    i18nKey: 'Table',
+    i18nKey: t('menu.Table'),
     icon: 'table',
     order: 2,
   },

src/store/modules/menu/index.ts

@@ -179,7 +179,7 @@ export const useMenu = defineStore(
 
         /** 设置 label, i18nKey 优先级最高 */
         const label = computed(() =>
-          meta?.i18nKey ? t(`menu.${meta!.i18nKey}`) : meta?.noLocalTitle,
+          meta?.i18nKey ? t(`${meta!.i18nKey}`) : meta?.noLocalTitle,
         )
         /** 拼装菜单项 */
         const route = {