From 1be7455d679fc23534dfa00c3561aa3e40499cee Mon Sep 17 00:00:00 2001 From: wanchun <445436867@qq.com> Date: Fri, 14 Jan 2022 16:12:37 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.vuepress/configs/navbar/en.ts | 2 +- docs/.vuepress/configs/navbar/zh.ts | 2 +- docs/.vuepress/configs/sidebar/en.ts | 15 ++- docs/.vuepress/configs/sidebar/zh.ts | 15 ++- docs/guide/directory-structure.md | 105 +++++++++++++++++---- docs/guide/env.md | 53 +++++++---- docs/guide/image.md | 61 ++++++++++++ docs/guide/public.md | 30 ++++++ docs/guide/template.md | 47 ++------- docs/reference/plugin/README.md | 26 +++-- docs/zh/guide/css.md | 2 +- docs/zh/guide/directory-structure.md | 105 +++++++++++++++++---- docs/zh/guide/env.md | 53 +++++++---- docs/zh/guide/image.md | 61 ++++++++++++ docs/zh/guide/public.md | 30 ++++++ docs/zh/guide/template.md | 47 ++------- docs/zh/reference/plugin/README.md | 26 +++-- docs/zh/reference/plugin/plugins/access.md | 2 - 18 files changed, 497 insertions(+), 185 deletions(-) create mode 100644 docs/guide/image.md create mode 100644 docs/guide/public.md create mode 100644 docs/zh/guide/image.md create mode 100644 docs/zh/guide/public.md diff --git a/docs/.vuepress/configs/navbar/en.ts b/docs/.vuepress/configs/navbar/en.ts index 1de7d98b..0b26649b 100644 --- a/docs/.vuepress/configs/navbar/en.ts +++ b/docs/.vuepress/configs/navbar/en.ts @@ -31,7 +31,7 @@ export const en: NavbarConfig = [ }, { text: 'v1 文档', - link: 'https://webank.gitee.io/fes.js-v0/', + link: 'https://webank.gitee.io/fes.js/', }, ], }, diff --git a/docs/.vuepress/configs/navbar/zh.ts b/docs/.vuepress/configs/navbar/zh.ts index 6d7da7a9..f6e85ca7 100644 --- a/docs/.vuepress/configs/navbar/zh.ts +++ b/docs/.vuepress/configs/navbar/zh.ts @@ -31,7 +31,7 @@ export const zh: NavbarConfig = [ }, { text: 'v1 文档', - link: 'https://webank.gitee.io/fes.js-v0/', + link: 'https://webank.gitee.io/fes.js/', }, ], }, diff --git a/docs/.vuepress/configs/sidebar/en.ts b/docs/.vuepress/configs/sidebar/en.ts index 2a45f895..53d0f1c1 100644 --- a/docs/.vuepress/configs/sidebar/en.ts +++ b/docs/.vuepress/configs/sidebar/en.ts @@ -17,18 +17,20 @@ export const en: SidebarConfig = { '/guide/directory-structure.md', '/guide/config.md', '/guide/runtime-config.md', + '/guide/env.md', '/guide/route.md', '/guide/plugin.md', '/guide/template.md', '/guide/mock.md', - '/guide/env.md', - '/guide/css.md', ] }, { // isGroup: true, - text: '进阶', + text: '样式和资源文件', children: [ + '/guide/image.md', + '/guide/css.md', + '/guide/public.md', ] }, "/guide/contributing.md", @@ -41,12 +43,7 @@ export const en: SidebarConfig = { '/reference/api/README.md' ], '/reference/plugin/': [ - { - // isGroup: true, - text: 'Presets', - children: [ - ], - }, + '/reference/plugin/README.md', { // isGroup: true, text: 'Plugins', diff --git a/docs/.vuepress/configs/sidebar/zh.ts b/docs/.vuepress/configs/sidebar/zh.ts index 00963d75..9b98629a 100644 --- a/docs/.vuepress/configs/sidebar/zh.ts +++ b/docs/.vuepress/configs/sidebar/zh.ts @@ -17,18 +17,20 @@ export const zh: SidebarConfig = { '/zh/guide/directory-structure.md', '/zh/guide/config.md', '/zh/guide/runtime-config.md', + '/zh/guide/env.md', '/zh/guide/route.md', '/zh/guide/plugin.md', '/zh/guide/template.md', '/zh/guide/mock.md', - '/zh/guide/env.md', - '/zh/guide/css.md', ] }, { // isGroup: true, - text: '进阶', + text: '样式和资源文件', children: [ + '/zh/guide/image.md', + '/zh/guide/css.md', + '/zh/guide/public.md', ] }, "/zh/guide/contributing.md", @@ -41,12 +43,7 @@ export const zh: SidebarConfig = { '/zh/reference/api/README.md' ], '/zh/reference/plugin/': [ - { - // isGroup: true, - text: 'Presets', - children: [ - ], - }, + '/zh/reference/plugin/README.md', { // isGroup: true, text: 'Plugins', diff --git a/docs/guide/directory-structure.md b/docs/guide/directory-structure.md index e23c28ad..dc28cf9f 100644 --- a/docs/guide/directory-structure.md +++ b/docs/guide/directory-structure.md @@ -18,18 +18,88 @@ fes-template └── app.js ``` -### 根目录 +### package.json +```json +{ + "name": "@fesjs/template", + "version": "2.0.0", + "description": "fes项目模版", + "scripts": { + "build": "fes build", + "prod": "FES_ENV=prod fes build", + "analyze": "ANALYZE=1 fes build", + "dev": "fes dev", + "test": "fes test" + }, + "keywords": [ + "管理端", + "fes", + "fast", + "easy", + "strong" + ], + "files": [ + ".eslintrc.js", + ".gitignore", + ".fes.js", + ".fes.prod.js", + "mock.js", + "package.json", + "README.md", + "tsconfig.json", + "/src", + "/config" + ], + "repository": { + "type": "git", + "url": "git+https://github.com/WeBankFinTech/fes.js.git", + "directory": "packages/fes-template" + }, + "author": "harrywan", + "license": "MIT", + "bugs": { + "url": "https://github.com/WeBankFinTech/fes.js/issues" + }, + "homepage": "https://github.com/WeBankFinTech/fes.js#readme", + "publishConfig": { + "access": "public" + }, + "devDependencies": { + "@webank/eslint-config-webank": "0.3.1" + }, + "dependencies": { + "@fesjs/fes": "^2.0.0", + "@fesjs/plugin-access": "^2.0.0", + "@fesjs/plugin-layout": "^3.0.0", + "@fesjs/plugin-locale": "^3.0.0", + "@fesjs/plugin-model": "^2.0.0", + "@fesjs/plugin-enums": "^2.0.0", + "@fesjs/plugin-jest": "^2.0.0", + "@fesjs/plugin-vuex": "^2.0.0", + "@fesjs/plugin-request": "^2.0.0", + "@fesjs/plugin-qiankun": "^2.0.0", + "@fesjs/plugin-sass": "^2.0.0", + "@fesjs/plugin-monaco-editor": "^2.0.0-beta.0", + "@fesjs/plugin-windicss": "^2.0.0", + "@fesjs/fes-design": "^0.1.10", + "vue": "^3.0.5", + "vuex": "^4.0.0" + }, + "private": true +} +``` +其中`@fesjs/fes`是 Fes.js 核心依赖，另外以 `@fesjs/preset-`、`@fesjs/plugin-`、`@webank/fes-preset-`、`@webank/fes-plugin-`、`fes-preset-` 和 `fes-plugin-` 开头的依赖会被自动注册为插件或插件集。 -#### package.json -包含插件和插件集，以 `@fesjs/preset-`、`@fesjs/plugin-`、`@webank/fes-preset-`、`@webank/fes-plugin-`、`fes-preset-` 和 `fes-plugin-` 开头的依赖会被自动注册为插件或插件集。 - -#### tsconfig.json +### tsconfig.json 解决 `@fesjs/fes` 和使用 `@` 的 API 提示 -#### .fes.js -配置文件，包含 Fes.js 内置功能和插件的配置。 +### .fes.js +配置文件，包含 Fes.js 内置功能和安装的其他插件配置。 -#### .env +### mock.js +`mock` 数据的配置文件。 + +### .env 定义环境变量。 比如 `.env` 文件内容如下： @@ -43,28 +113,27 @@ process.env.PORT = '8888'; process.env.FES_ENV = 'prod'; ``` -#### mock.js -mock 数据的配置文件。 ### dist 目录 执行 `fes build` 后，产物默认会存放在这里。 -### public 目录 -此目录下所有文件会被 `copy` 到输出路径。 +## public 目录 +此目录下所有文件为静态资源，会被复制到输出路径。 -#### index.html -默认的 `html` 模板文件，如果删除此 `html` 则会使用内置的 `html` 模板文件。 +### index.html +默认的 `html` 模板文件，如果删除此 `html` 则会使用内置的 `html` 模板文件。 -### src 目录 +## src 目录 -#### .fes 目录 +### .fes 目录 临时文件目录，比如入口文件、路由等，都会被临时生成到这里。 :::warning 不要提交 `.fes` 目录到 `git` 仓库，他们会在 `fes dev` 和 `fes build` 时被删除并重新生成。 ::: -#### pages 目录 + +### pages 目录 所有路由组件文件存放在这里。 -#### app.js +### app.js 运行时配置文件，可以在这里扩展运行时的能力，比如修改路由等。 \ No newline at end of file diff --git a/docs/guide/env.md b/docs/guide/env.md index dde8b29f..6bc88f58 100644 --- a/docs/guide/env.md +++ b/docs/guide/env.md @@ -2,9 +2,9 @@ 在构建或者代码在端上运行中需要一些跟区分于环境的变量，用于配置构建流程或者运行时过程，这时候我们可以配置环境变量。 -## 设置环境变量 +## 配置环境变量 -### 执行命令时添加 +### 命令行添加 比如： ```bash # OS X, Linux @@ -33,7 +33,7 @@ cross-env PORT=3000 fes dev -### 在 .env 文件中定义 +### `.env` 文件配置 Fes.js 中约定根目录下以 `.env` 开头的文件为环境变量配置文件。 比如： @@ -47,40 +47,33 @@ fes dev 会以 3000 端口启动 dev server。 #### 本地临时配置 -可以新建 `.env.local`，这份配置会和 `.env` 做 `merge` 后形成最终配置。 +可以新建 `.env.local`，这份配置会和 `.env` 做合并后形成最终配置。 -#### 多环境多份配置 +#### 环境配置 可以通过环境变量 `FES_ENV` 区分不同环境来指定配置，这时候必须在执行命令前添加 `FES_ENV` 保证执行加载环境变量配置文件逻辑前 `FES_ENV` 已设置。 举个 🌰 ： ```bash FES_ENV=sit fes dev ``` -如果存在 `.env.sit` 文件，则会将 `.env.sit` 的配置和 `.env` 做 `merge` 后形成最终配置。 +如果存在 `.env.sit` 文件，则会将 `.env.sit` 的配置和 `.env` 做合并后形成最终配置。 #### 配置优先级 -临时配置 > 环境配置 > .env +本地临时配置 > 环境配置 > 基础配置 ::: tip -如果两份配置中存在相同的项，则优先级高的会覆盖优先级低的。 +如果多份配置中存在相同的配置项，**则优先级高的会覆盖优先级低的**。 ::: -## 运行时环境变量 -运行时环境变量需要以 `FES_APP_` 开头，比如在 `.env` 中配置： -``` -FES_APP_KEY=11111 -``` -在代码中使用： -```js -console.log(process.env.FES_APP_KEY) -// 输出 11111 -``` - -## 编译时环境变量列表 +## 编译时配置列表 +编译时配置是在构建过程需要的变量，开放给用户配置。 ### FES_ENV 指定当前的环境，不同环境各自的配置文件。 +::: tip +`FES_ENV` 在会在加载`.env`前使用，所以只能用命令行方式配置。 +::: ### FES_PRESETS 添加额外的插件集入口 @@ -119,3 +112,23 @@ ANALYZE=1 fes build ### ANALYZE_PORT 默认是`8888` + + +## process.env +运行时配置需要以 `FES_APP_` 开头，比如在 `.env` 中配置： +``` +FES_APP_KEY=123456789 +``` +在代码中使用： +```js +console.log(process.env.FES_APP_KEY) +// 输出 123456789 +``` + +除了用户自定义的以`FES_APP_`开头的变量，还提供如下配置： + +- **NODE_ENV**：Node 环境变量 + +- **FES_ENV**：Fes.js 环境变量 + +- **BASE_URL**：等同于 publicPath \ No newline at end of file diff --git a/docs/guide/image.md b/docs/guide/image.md new file mode 100644 index 00000000..3c5cb5f1 --- /dev/null +++ b/docs/guide/image.md @@ -0,0 +1,61 @@ +# 使用图片 + +## 使用图片 + +假设在 `src/images` 目录下有 `logo.png`。 + +### Vue 里使用图片 + +```vue + +``` + +### JS 里使用图片 +```js +import imageUrl from '@/images/logo.png`' +``` + +### CSS 里使用图片 +```css +.logo { + background: url('@/images/logo.png') +} +``` +注意： + +1. 这是 `webpack` 的规则，如果切到其他打包工具，可能会有变化 +2. `less` 中同样适用 + + +## `public` 文件夹 + +有些内容不需要经过 `webpack` 模块化处理，则可以将这些内容放在 `public` 文件夹，构建后会直接复制到 `dist` 目录，所以你需要通过`BASE_URL`来引入它们。 + +### 在HTML模板中使用 + + +在 `public/index.html` 中需要设置： + +```html + +``` + +### 在.vue 文件中使用 + +```vue + + +``` + diff --git a/docs/guide/public.md b/docs/guide/public.md new file mode 100644 index 00000000..64717575 --- /dev/null +++ b/docs/guide/public.md @@ -0,0 +1,30 @@ +# 静态资源 + +有些内容不需要经过 `webpack` 模块化处理，则可以将这些内容放在 `public` 文件夹，构建后会直接复制到 `dist` 目录，所以你需要通过`BASE_URL`来引入它们。 + +### 在HTML模板中使用 + + +在 `public/index.html` 中需要设置： + +```html + +``` + +### 在.vue 和 js 文件中使用 + +```vue + + +``` + diff --git a/docs/guide/template.md b/docs/guide/template.md index db3f6bf0..1f7d85ee 100644 --- a/docs/guide/template.md +++ b/docs/guide/template.md @@ -1,6 +1,6 @@ -# HTML和静态资源 +# HTML 模板 -Fes.js 基于 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) 实现的模板功能，默认 HTML模板 是： +Fes.js 基于 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) 实现的模板功能，默认模板内容是： ```html @@ -16,14 +16,11 @@ Fes.js 基于 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plu ``` - -## 替换模板 +## 自定义模板 在 `src/public` 文件夹中创建`index.html`，Fes.js 约定如果这个文件存在，则会替换默认模板。 -## 配置模板 - -### 配置 -在配置文件（`.fes.js`）中配置 `html`，把配置的对象作为参数传入 `html-webpack-plugin` 实例。 +## 模板配置 +在配置文件（`.fes.js`）中配置 `html`，把[配置](https://github.com/jantimon/html-webpack-plugin#options)的对象作为参数传入 `html-webpack-plugin` 实例。 举个 :chestnut: ： ```js @@ -33,9 +30,9 @@ export default { } } ``` -页面的 title 会设置成'海贼王'。 +页面的标题会设置成'海贼王'。 -### 手动 +## 模板变量 当然我们也可以手动编写模板，在模板中添加`link`、`link`、`meta`等标签。在我们手动配置模板时，有时候需要用到一些环境变量，模板里可以获取到的变量如下： - **htmlWebpackPlugin**，特定于此插件的数据 @@ -47,37 +44,13 @@ export default { ``` -除上述 `html-webpack-plugin` 三点之外，Fes.js 还把 `process.env` 中的环境变量添加到模板作用域内： +除上述 `html-webpack-plugin` 插件提供的变量外，Fes.js 还把 `process.env` 中的环境变量添加到模板作用域内： - `NODE_ENV` - `FES_ENV` - `.env` 文件中以 `FES_APP_` 开头的变量 -## 处理静态资源 - -放置在 public 目录下或通过绝对路径被引用。这类资源将会直接被拷贝，而不会经过 webpack 的处理。 - -### `public` 文件夹 - -任何放置在 public 文件夹的静态资源都会被简单的复制，而不经过 webpack。你需要通过绝对路径来引用它们。 - -* 在 public/index.html 或其它通过 html-webpack-plugin 用作模板的 HTML 文件中，你需要通过 <%= BASE_URL %> 设置链接前缀： +举个 🌰 ： ```html -``` - -* 在模板中，你首先需要向你的组件传入基础 URL： - -```html -setup() { - return { - publicPath: process.env.BASE_URL - } -} -``` - -然后： - -```html - -``` +``` \ No newline at end of file diff --git a/docs/reference/plugin/README.md b/docs/reference/plugin/README.md index da38b421..35ad9aa0 100644 --- a/docs/reference/plugin/README.md +++ b/docs/reference/plugin/README.md @@ -1,12 +1,26 @@ +# 介绍 +## 插件列表 + +| 插件 | 介绍 | +| ---- | ---- | +| [@fesjs/plugin-access](./plugins/access.md) | 提供对页面资源的权限控制能力 | +| [@fesjs/plugin-enums](./plugins/enums.md) | 提供统一的枚举存取及丰富的函数来处理枚举 | +| [@fesjs/plugin-icon](./plugins/icon.md) | svg 文件自动注册为组件 | +| [@fesjs/plugin-jest](./plugins/jest.md) | 基于 `Jest`，提供单元测试、覆盖测试能力 | +| [ @fesjs/plugin-layout](./plugins/layout.md) | 简单的配置即可拥有布局，包括导航以及侧边栏 | +| [@fesjs/plugin-locale](./plugins/locale.md) | 基于 `Vue I18n`，提供国际化能力 | +| [@fesjs/plugin-model](./plugins/model.md) | 简易的数据管理方案 | +| [@fesjs/plugin-request](./plugins/request.md) | 基于 `Axios` 封装的 request，内置防止重复请求、请求节流、错误处理等功能 | +| [@fesjs/plugin-vuex](./plugins/vuex.md) | 基于 `Vuex`, 提供状态管理能力 | +| [@fesjs/plugin-qiankun](./plugins/qiankun.md) | 基于 `qiankun`，提供微服务能力 | +| [@fesjs/plugin-sass](./plugins/sass.md) | 样式支持sass | +| [@fesjs/plugin-monaco-editor](./plugins/editor.md) | 提供代码编辑器能力， 基于`monaco-editor`（VS Code使用的代码编辑器） | +| [@fesjs/plugin-windicss](./plugins/windicss.md) | 基于 `windicss`，提供原子化 CSS 能力 | + + ## 架构 架构 Fes.js 把大家常用的技术栈封装成一个个插件进行整理，收敛到一起，让大家只用 Fes.js 就可以完成 80% 的日常工作。 - -## 插件和插件集 -

- 插件 -

-Fes.js 支持插件和插件集，通过这张图应该很好理解到他们的关系，通过插件集我们把插件收敛依赖然后支持不同的业务类型。 \ No newline at end of file diff --git a/docs/zh/guide/css.md b/docs/zh/guide/css.md index 0cfaed03..d110f2cd 100644 --- a/docs/zh/guide/css.md +++ b/docs/zh/guide/css.md @@ -1,4 +1,4 @@ -# 样式 +# 使用 css :::tip 本文档以 css 为示例，把后缀换成 `.less` 同样适用。 diff --git a/docs/zh/guide/directory-structure.md b/docs/zh/guide/directory-structure.md index e23c28ad..dc28cf9f 100644 --- a/docs/zh/guide/directory-structure.md +++ b/docs/zh/guide/directory-structure.md @@ -18,18 +18,88 @@ fes-template └── app.js ``` -### 根目录 +### package.json +```json +{ + "name": "@fesjs/template", + "version": "2.0.0", + "description": "fes项目模版", + "scripts": { + "build": "fes build", + "prod": "FES_ENV=prod fes build", + "analyze": "ANALYZE=1 fes build", + "dev": "fes dev", + "test": "fes test" + }, + "keywords": [ + "管理端", + "fes", + "fast", + "easy", + "strong" + ], + "files": [ + ".eslintrc.js", + ".gitignore", + ".fes.js", + ".fes.prod.js", + "mock.js", + "package.json", + "README.md", + "tsconfig.json", + "/src", + "/config" + ], + "repository": { + "type": "git", + "url": "git+https://github.com/WeBankFinTech/fes.js.git", + "directory": "packages/fes-template" + }, + "author": "harrywan", + "license": "MIT", + "bugs": { + "url": "https://github.com/WeBankFinTech/fes.js/issues" + }, + "homepage": "https://github.com/WeBankFinTech/fes.js#readme", + "publishConfig": { + "access": "public" + }, + "devDependencies": { + "@webank/eslint-config-webank": "0.3.1" + }, + "dependencies": { + "@fesjs/fes": "^2.0.0", + "@fesjs/plugin-access": "^2.0.0", + "@fesjs/plugin-layout": "^3.0.0", + "@fesjs/plugin-locale": "^3.0.0", + "@fesjs/plugin-model": "^2.0.0", + "@fesjs/plugin-enums": "^2.0.0", + "@fesjs/plugin-jest": "^2.0.0", + "@fesjs/plugin-vuex": "^2.0.0", + "@fesjs/plugin-request": "^2.0.0", + "@fesjs/plugin-qiankun": "^2.0.0", + "@fesjs/plugin-sass": "^2.0.0", + "@fesjs/plugin-monaco-editor": "^2.0.0-beta.0", + "@fesjs/plugin-windicss": "^2.0.0", + "@fesjs/fes-design": "^0.1.10", + "vue": "^3.0.5", + "vuex": "^4.0.0" + }, + "private": true +} +``` +其中`@fesjs/fes`是 Fes.js 核心依赖，另外以 `@fesjs/preset-`、`@fesjs/plugin-`、`@webank/fes-preset-`、`@webank/fes-plugin-`、`fes-preset-` 和 `fes-plugin-` 开头的依赖会被自动注册为插件或插件集。 -#### package.json -包含插件和插件集，以 `@fesjs/preset-`、`@fesjs/plugin-`、`@webank/fes-preset-`、`@webank/fes-plugin-`、`fes-preset-` 和 `fes-plugin-` 开头的依赖会被自动注册为插件或插件集。 - -#### tsconfig.json +### tsconfig.json 解决 `@fesjs/fes` 和使用 `@` 的 API 提示 -#### .fes.js -配置文件，包含 Fes.js 内置功能和插件的配置。 +### .fes.js +配置文件，包含 Fes.js 内置功能和安装的其他插件配置。 -#### .env +### mock.js +`mock` 数据的配置文件。 + +### .env 定义环境变量。 比如 `.env` 文件内容如下： @@ -43,28 +113,27 @@ process.env.PORT = '8888'; process.env.FES_ENV = 'prod'; ``` -#### mock.js -mock 数据的配置文件。 ### dist 目录 执行 `fes build` 后，产物默认会存放在这里。 -### public 目录 -此目录下所有文件会被 `copy` 到输出路径。 +## public 目录 +此目录下所有文件为静态资源，会被复制到输出路径。 -#### index.html -默认的 `html` 模板文件，如果删除此 `html` 则会使用内置的 `html` 模板文件。 +### index.html +默认的 `html` 模板文件，如果删除此 `html` 则会使用内置的 `html` 模板文件。 -### src 目录 +## src 目录 -#### .fes 目录 +### .fes 目录 临时文件目录，比如入口文件、路由等，都会被临时生成到这里。 :::warning 不要提交 `.fes` 目录到 `git` 仓库，他们会在 `fes dev` 和 `fes build` 时被删除并重新生成。 ::: -#### pages 目录 + +### pages 目录 所有路由组件文件存放在这里。 -#### app.js +### app.js 运行时配置文件，可以在这里扩展运行时的能力，比如修改路由等。 \ No newline at end of file diff --git a/docs/zh/guide/env.md b/docs/zh/guide/env.md index dde8b29f..6bc88f58 100644 --- a/docs/zh/guide/env.md +++ b/docs/zh/guide/env.md @@ -2,9 +2,9 @@ 在构建或者代码在端上运行中需要一些跟区分于环境的变量，用于配置构建流程或者运行时过程，这时候我们可以配置环境变量。 -## 设置环境变量 +## 配置环境变量 -### 执行命令时添加 +### 命令行添加 比如： ```bash # OS X, Linux @@ -33,7 +33,7 @@ cross-env PORT=3000 fes dev -### 在 .env 文件中定义 +### `.env` 文件配置 Fes.js 中约定根目录下以 `.env` 开头的文件为环境变量配置文件。 比如： @@ -47,40 +47,33 @@ fes dev 会以 3000 端口启动 dev server。 #### 本地临时配置 -可以新建 `.env.local`，这份配置会和 `.env` 做 `merge` 后形成最终配置。 +可以新建 `.env.local`，这份配置会和 `.env` 做合并后形成最终配置。 -#### 多环境多份配置 +#### 环境配置 可以通过环境变量 `FES_ENV` 区分不同环境来指定配置，这时候必须在执行命令前添加 `FES_ENV` 保证执行加载环境变量配置文件逻辑前 `FES_ENV` 已设置。 举个 🌰 ： ```bash FES_ENV=sit fes dev ``` -如果存在 `.env.sit` 文件，则会将 `.env.sit` 的配置和 `.env` 做 `merge` 后形成最终配置。 +如果存在 `.env.sit` 文件，则会将 `.env.sit` 的配置和 `.env` 做合并后形成最终配置。 #### 配置优先级 -临时配置 > 环境配置 > .env +本地临时配置 > 环境配置 > 基础配置 ::: tip -如果两份配置中存在相同的项，则优先级高的会覆盖优先级低的。 +如果多份配置中存在相同的配置项，**则优先级高的会覆盖优先级低的**。 ::: -## 运行时环境变量 -运行时环境变量需要以 `FES_APP_` 开头，比如在 `.env` 中配置： -``` -FES_APP_KEY=11111 -``` -在代码中使用： -```js -console.log(process.env.FES_APP_KEY) -// 输出 11111 -``` - -## 编译时环境变量列表 +## 编译时配置列表 +编译时配置是在构建过程需要的变量，开放给用户配置。 ### FES_ENV 指定当前的环境，不同环境各自的配置文件。 +::: tip +`FES_ENV` 在会在加载`.env`前使用，所以只能用命令行方式配置。 +::: ### FES_PRESETS 添加额外的插件集入口 @@ -119,3 +112,23 @@ ANALYZE=1 fes build ### ANALYZE_PORT 默认是`8888` + + +## process.env +运行时配置需要以 `FES_APP_` 开头，比如在 `.env` 中配置： +``` +FES_APP_KEY=123456789 +``` +在代码中使用： +```js +console.log(process.env.FES_APP_KEY) +// 输出 123456789 +``` + +除了用户自定义的以`FES_APP_`开头的变量，还提供如下配置： + +- **NODE_ENV**：Node 环境变量 + +- **FES_ENV**：Fes.js 环境变量 + +- **BASE_URL**：等同于 publicPath \ No newline at end of file diff --git a/docs/zh/guide/image.md b/docs/zh/guide/image.md new file mode 100644 index 00000000..3c5cb5f1 --- /dev/null +++ b/docs/zh/guide/image.md @@ -0,0 +1,61 @@ +# 使用图片 + +## 使用图片 + +假设在 `src/images` 目录下有 `logo.png`。 + +### Vue 里使用图片 + +```vue + +``` + +### JS 里使用图片 +```js +import imageUrl from '@/images/logo.png`' +``` + +### CSS 里使用图片 +```css +.logo { + background: url('@/images/logo.png') +} +``` +注意： + +1. 这是 `webpack` 的规则，如果切到其他打包工具，可能会有变化 +2. `less` 中同样适用 + + +## `public` 文件夹 + +有些内容不需要经过 `webpack` 模块化处理，则可以将这些内容放在 `public` 文件夹，构建后会直接复制到 `dist` 目录，所以你需要通过`BASE_URL`来引入它们。 + +### 在HTML模板中使用 + + +在 `public/index.html` 中需要设置： + +```html + +``` + +### 在.vue 文件中使用 + +```vue + + +``` + diff --git a/docs/zh/guide/public.md b/docs/zh/guide/public.md new file mode 100644 index 00000000..64717575 --- /dev/null +++ b/docs/zh/guide/public.md @@ -0,0 +1,30 @@ +# 静态资源 + +有些内容不需要经过 `webpack` 模块化处理，则可以将这些内容放在 `public` 文件夹，构建后会直接复制到 `dist` 目录，所以你需要通过`BASE_URL`来引入它们。 + +### 在HTML模板中使用 + + +在 `public/index.html` 中需要设置： + +```html + +``` + +### 在.vue 和 js 文件中使用 + +```vue + + +``` + diff --git a/docs/zh/guide/template.md b/docs/zh/guide/template.md index db3f6bf0..1f7d85ee 100644 --- a/docs/zh/guide/template.md +++ b/docs/zh/guide/template.md @@ -1,6 +1,6 @@ -# HTML和静态资源 +# HTML 模板 -Fes.js 基于 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) 实现的模板功能，默认 HTML模板 是： +Fes.js 基于 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin) 实现的模板功能，默认模板内容是： ```html @@ -16,14 +16,11 @@ Fes.js 基于 [html-webpack-plugin](https://github.com/jantimon/html-webpack-plu ``` - -## 替换模板 +## 自定义模板 在 `src/public` 文件夹中创建`index.html`，Fes.js 约定如果这个文件存在，则会替换默认模板。 -## 配置模板 - -### 配置 -在配置文件（`.fes.js`）中配置 `html`，把配置的对象作为参数传入 `html-webpack-plugin` 实例。 +## 模板配置 +在配置文件（`.fes.js`）中配置 `html`，把[配置](https://github.com/jantimon/html-webpack-plugin#options)的对象作为参数传入 `html-webpack-plugin` 实例。 举个 :chestnut: ： ```js @@ -33,9 +30,9 @@ export default { } } ``` -页面的 title 会设置成'海贼王'。 +页面的标题会设置成'海贼王'。 -### 手动 +## 模板变量 当然我们也可以手动编写模板，在模板中添加`link`、`link`、`meta`等标签。在我们手动配置模板时，有时候需要用到一些环境变量，模板里可以获取到的变量如下： - **htmlWebpackPlugin**，特定于此插件的数据 @@ -47,37 +44,13 @@ export default { ``` -除上述 `html-webpack-plugin` 三点之外，Fes.js 还把 `process.env` 中的环境变量添加到模板作用域内： +除上述 `html-webpack-plugin` 插件提供的变量外，Fes.js 还把 `process.env` 中的环境变量添加到模板作用域内： - `NODE_ENV` - `FES_ENV` - `.env` 文件中以 `FES_APP_` 开头的变量 -## 处理静态资源 - -放置在 public 目录下或通过绝对路径被引用。这类资源将会直接被拷贝，而不会经过 webpack 的处理。 - -### `public` 文件夹 - -任何放置在 public 文件夹的静态资源都会被简单的复制，而不经过 webpack。你需要通过绝对路径来引用它们。 - -* 在 public/index.html 或其它通过 html-webpack-plugin 用作模板的 HTML 文件中，你需要通过 <%= BASE_URL %> 设置链接前缀： +举个 🌰 ： ```html -``` - -* 在模板中，你首先需要向你的组件传入基础 URL： - -```html -setup() { - return { - publicPath: process.env.BASE_URL - } -} -``` - -然后： - -```html - -``` +``` \ No newline at end of file diff --git a/docs/zh/reference/plugin/README.md b/docs/zh/reference/plugin/README.md index da38b421..35ad9aa0 100644 --- a/docs/zh/reference/plugin/README.md +++ b/docs/zh/reference/plugin/README.md @@ -1,12 +1,26 @@ +# 介绍 +## 插件列表 + +| 插件 | 介绍 | +| ---- | ---- | +| [@fesjs/plugin-access](./plugins/access.md) | 提供对页面资源的权限控制能力 | +| [@fesjs/plugin-enums](./plugins/enums.md) | 提供统一的枚举存取及丰富的函数来处理枚举 | +| [@fesjs/plugin-icon](./plugins/icon.md) | svg 文件自动注册为组件 | +| [@fesjs/plugin-jest](./plugins/jest.md) | 基于 `Jest`，提供单元测试、覆盖测试能力 | +| [ @fesjs/plugin-layout](./plugins/layout.md) | 简单的配置即可拥有布局，包括导航以及侧边栏 | +| [@fesjs/plugin-locale](./plugins/locale.md) | 基于 `Vue I18n`，提供国际化能力 | +| [@fesjs/plugin-model](./plugins/model.md) | 简易的数据管理方案 | +| [@fesjs/plugin-request](./plugins/request.md) | 基于 `Axios` 封装的 request，内置防止重复请求、请求节流、错误处理等功能 | +| [@fesjs/plugin-vuex](./plugins/vuex.md) | 基于 `Vuex`, 提供状态管理能力 | +| [@fesjs/plugin-qiankun](./plugins/qiankun.md) | 基于 `qiankun`，提供微服务能力 | +| [@fesjs/plugin-sass](./plugins/sass.md) | 样式支持sass | +| [@fesjs/plugin-monaco-editor](./plugins/editor.md) | 提供代码编辑器能力， 基于`monaco-editor`（VS Code使用的代码编辑器） | +| [@fesjs/plugin-windicss](./plugins/windicss.md) | 基于 `windicss`，提供原子化 CSS 能力 | + + ## 架构 架构 Fes.js 把大家常用的技术栈封装成一个个插件进行整理，收敛到一起，让大家只用 Fes.js 就可以完成 80% 的日常工作。 - -## 插件和插件集 -

- 插件 -

-Fes.js 支持插件和插件集，通过这张图应该很好理解到他们的关系，通过插件集我们把插件收敛依赖然后支持不同的业务类型。 \ No newline at end of file diff --git a/docs/zh/reference/plugin/plugins/access.md b/docs/zh/reference/plugin/plugins/access.md index b06f8783..1300cb9d 100644 --- a/docs/zh/reference/plugin/plugins/access.md +++ b/docs/zh/reference/plugin/plugins/access.md @@ -1,7 +1,5 @@ # @fesjs/plugin-access - - ## 介绍 对于前端应用来说，权限就是页面、页面元素是否可见。