docs(sites): add aui adapter document (#1516)

This commit is contained in:
gimmyhehe 2024-04-02 16:17:57 +08:00 committed by GitHub
parent 059742e49d
commit 05a0602d89
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 477 additions and 20 deletions

View File

@ -1,35 +1,78 @@
const isOpen = import.meta.env.VITE_BUILD_TARGET === 'open'
const envTarget = import.meta.env.VITE_BUILD_TARGET || 'open'
const envTheme = import.meta.env.VITE_TINY_THEME || 'default'
export const standaloneMenus = [
{
label: '组件总览',
key: 'overview'
}
]
const docMenusChildren = [
{ 'title': '更新日志', 'titleEn': 'Changelog', 'key': 'changelog' },
{ 'title': '环境准备', 'titleEn': 'envpreparation', 'key': 'envpreparation' },
{ 'title': '安装', 'titleEn': 'installation', 'key': 'installation' },
{ 'title': '引入组件', 'titleEn': 'importComponents', 'key': 'import-components' },
{
'title': '后端适配器',
'titleEn': 'adapter',
'key': 'adapter',
showScene: {
target: ['inner']
}
},
{
'title': '开发示例',
'titleEn': 'developDemo',
'key': 'develop-demo',
showScene: {
target: ['inner']
}
},
{ 'title': '创建项目', 'titleEn': 'tinyStage', 'key': 'tiny-stage' },
{ 'title': '国际化', 'titleEn': 'i18n', 'key': 'i18n' },
{
'title': '主题配置',
'titleEn': 'theme',
'key': 'theme',
showScene: {
theme: ['default']
}
},
{ 'title': '表单校验配置', 'titleEn': 'formValid', 'key': 'form-valid' },
{ 'title': '常见问题', 'titleEn': 'faq', 'key': 'faq' },
{
'title': '社区求助',
'titleEn': 'help',
'key': 'help',
showScene: {
target: ['inner']
}
},
{
'title': '适配AUI',
'titleEn': 'Adapter AUI',
'key': 'aui-adapter',
showScene: {
theme: ['saas']
}
}
]
export const docMenus = [
{
'label': '使用指南',
'labelEn': 'Usage Guidelines',
'key': 'docs_usage_guidelines',
// 为了保持新旧官网对应文档路由的一致文档对内和对外的差异判断逻辑放到了docs组件中。
'children': [
{ 'title': '更新日志', 'titleEn': 'Changelog', 'key': 'changelog' },
{ 'title': '环境准备', 'titleEn': 'envpreparation', 'key': 'envpreparation' },
{ 'title': '安装', 'titleEn': 'installation', 'key': 'installation' },
{ 'title': '引入组件', 'titleEn': 'importComponents', 'key': 'import-components' },
{ 'title': '开发示例', 'titleEn': 'developDemo', 'key': 'develop-demo' },
{ 'title': '国际化', 'titleEn': 'i18n', 'key': 'i18n' },
{ 'title': '主题配置', 'titleEn': 'theme', 'key': 'theme' },
{ 'title': '表单校验配置', 'titleEn': 'formValid', 'key': 'form-valid' },
{ 'title': '常见问题', 'titleEn': 'faq', 'key': 'faq' }
]
'children': docMenusChildren.filter((item) => {
if (!item.showScene) {
return true
}
// 根据envTarget和envTheme判断是否展示文档
const { target, theme } = item.showScene
return (target?.includes(envTarget) ?? true) && (theme?.includes(envTheme) ?? true)
})
}
]
// 内网比外网多出三文档为了保存文档顺序使用splice插入到对应位置
if (!isOpen) {
docMenus[0].children.splice(4, 0, { 'title': '后端适配器', 'titleEn': 'adapter', 'key': 'adapter' })
docMenus[0].children.splice(6, 0, { 'title': '创建项目', 'titleEn': 'tinyStage', 'key': 'tiny-stage' })
docMenus[0].children.splice(10, 0, { 'title': '社区求助', 'titleEn': 'help', 'key': 'help' })
}
export const cmpMenus = [
{
'label': '框架风格',
@ -292,7 +335,7 @@ export const cmpMenus = [
const showBusiness = location.pathname.split('/')?.[2] === 'all'
// 对内文档开放业务组件
if (!isOpen || showBusiness) {
if (envTarget === 'inner' || showBusiness) {
cmpMenus.splice(8, 0, {
'label': '业务组件',
'labelEn': 'Business Components',

View File

@ -0,0 +1,207 @@
## Adapter AUI
### Dependency mapping table
Currently, TinyVue is compatible with AUI. You only need to replace the package name and configure the style theme to get a consistent experience with AUI. The following is the mapping relationship between TinyVue packages and AUI packages.
| TinyVue package | AUI package |
| ------------------------ | --------------------- |
| @opentiny/vue | @aurora/vue |
| @opentiny/vue-renderless | @aurora/renderless |
| @opentiny/vue-theme | @aurora/theme |
| @opentiny/vue-theme-saas | @aurora/theme-sass |
| @opentiny/vue-icon | @aurora/vue-icon |
| @opentiny/vue-icon-saas | @aurora/vue-icon-saas |
### Using Saas themes
#### background
- With the prosperity of the application ecology, especially the mobile application ecology, and the development of diversified device ecology, multi-terminal and multi-theme are put on the agenda;
- The theme solution launched by the original AUI is too bloated (users need to set a bunch of `cssvar` variables to customize the theme, because the colors are not unified, and the threshold for configuring multiple themes is relatively high). Later, it will be based on [tailwindcss](https:// github.com/tailwindlabs/tailwindcss) Collect theme variables (simplifying developer configuration) and engineer them to make it easier to customize multiple themes. Currently, there is a relatively mature theme solution in the industry [daisyui](https://github.com/saadeghi/daisyui).
In view of the above reasons, the `SaaS` theme is launched. If you want to experience the `SaaS` theme, you can make packaging configuration changes according to the following documents:
#### method one
Option 1 requires additional installation of the following dependencies:
- `@opentiny/vue-theme-saas` Theme will make minor adjustments to existing component styles without affecting the original DOM structure and API.
- `@opentiny/vue-icon-saas` is an icon component matching the `SaaS` theme style.
- `@opentiny/vue-design-saas` is the design specification configuration matching the theme style of `SaaS`.
1. Install the SaaS theme package:
```sh
yarn add @opentiny/vue-theme-saas @opentiny/vue-icon-saas @opentiny/vue-design-saas
# Or npm install @opentiny/vue-theme-saas @opentiny/vue-icon-saas @opentiny/vue-design-saas
```
2. Switch to the SaaS theme package:
```js
// (webpack) vue.config.js
module.exports = {
chainWebpack: (config) => {
config.resolve.alias.set('@opentiny/vue-theme', '@opentiny/vue-theme-saas')
config.resolve.alias.set('@opentiny/vue-icon', '@opentiny/vue-icon-saas')
}
}
// (vite) vite.config.js
export default defineConfig({
resolve: {
alias: {
'@opentiny/vue-theme': '@opentiny/vue-theme-saas',
'@opentiny/vue-icon': '@opentiny/vue-icon-saas'
}
}
})
```
3. Switch to Saas design specification configuration:
```html
<script setup>
import { ConfigProvider } from '@opentiny/vue'
import designSaasConfig from '@opentiny/vue-design-saas'
</script>
<template>
<!-- Inject saas design specification configuration -->
<config-provider :design="designSaasConfig">
<my-app></my-app>
</config-provider>
</template>
```
### Method Two
Method 2 requires additional installation of the following dependencies:
- `@opentiny/vue-theme-saas` Theme will make minor adjustments to existing component styles without affecting the original DOM structure and API.
- `@opentiny/vue-icon-saas` is an icon component matching the `SaaS` theme style.
- `@opentiny/vue-common-saas` is an adaptation layer matching the `SaaS` theme style, and is inlined with the `@opentiny/vue-design-saas` of method 1.
1. Install the SaaS theme package:
```sh
yarn add @opentiny/vue-theme-saas @opentiny/vue-icon-saas @opentiny/vue-common-saas
# Or npm install @opentiny/vue-theme-saas @opentiny/vue-icon-saas @opentiny/vue-common-saas
```
2. Switch to the SaaS theme package:
```js
// (webpack) vue.config.js
module.exports = {
chainWebpack: (config) => {
config.resolve.alias.set('@opentiny/vue-theme', '@opentiny/vue-theme-saas')
config.resolve.alias.set('@opentiny/vue-icon', '@opentiny/vue-icon-saas')
config.resolve.alias.set('@opentiny/vue-common', '@opentiny/vue-common-saas')
}
}
// (vite) vite.config.js
export default defineConfig({
resolve: {
alias: {
'@opentiny/vue-theme': '@opentiny/vue-theme-saas',
'@opentiny/vue-icon': '@opentiny/vue-icon-saas',
'@opentiny/vue-common': '@opentiny/vue-common-saas'
}
}
})
```
## Multi-mode introduction
TinyVue provides PC and Mobile component libraries. The two component libraries rely on the same external dependency `@opentiny/vue`. The component with the same name switches the component mode through `tiny_mode`.
For SaaS business scenarios, TinyVue provides multi-terminal components based on `tailwind`.
Based on TinyVue, a new `multi-terminal mode` is added to support business switching of components with the same name. By default, the component with the same name is `desktop mode`, that is, `PC component`.
### Pattern classification
The AUI component library provides three component modes: `desktop mode`, `mobile mode`, `multi-terminal mode`
| Mode | Mode introduction | Mode configuration |
| ------------------- | -------------------------- | ------------------ |
| Desktop mode | Pure PC | pc |
| mobile mode | pure mobile | mobile |
| Multi-terminal mode | Multi-terminal consistency | mobile-first |
### Mode switch
AUI component mode setting priority
`Single component switching` > `Mode transparent transmission` > `Global switching` > `Component default mode`
#### Single component switching
You can configure the `tiny_mode` attribute on the component tag, specify the component mode, and the corresponding template will be selected for rendering:
- Desktop mode: `pc`
- Mobile mode: `mobile`
- Multi-terminal mode: `mobile-first`
Reference examples are as follows:
```html
<tiny-button tiny_mode="mobile-first">Default button</tiny-button>
```
#### Global switch
By setting tiny_mode globally on Vue's prototype, you can specify the default mode for all components with the same name.
After importing the Vue dependency in the project entry `src/main.js` file, add the following configuration:
```js
// Vue 2.0
Vue.prototype.tiny_mode = { value: 'mobile-first' }
// Vue 3.0
app.config.globalProperties.tiny_mode = { value: 'mobile-first' }
```
#### Mode transparent transmission
If you want to switch modes in some areas of the page, such as card-level control,
You can add the `tiny_mode_root` attribute to the outer AUI component to transparently transmit the `tiny_mode` configuration of the current AUI component to all child AUI components.
The reference demo example is as follows:
```html
<template>
<div>
<tiny-layout>
<tiny-row tiny_mode="pc" tiny_mode_root>
<tiny-button>PC button</tiny-button>
<tiny-button type="primary" native-type="submit">Primary button</tiny-button>
<tiny-button type="success">Success button</tiny-button>
<tiny-button type="info">Information button</tiny-button>
<tiny-button type="warning">Warning button</tiny-button>
<tiny-button type="danger">Danger button</tiny-button>
</tiny-row>
<tiny-row tiny_mode="mobile-first" tiny_mode_root>
<tiny-button>Multi-terminal button</tiny-button>
<tiny-button type="primary" native-type="submit">Primary button</tiny-button>
<tiny-button type="success">Success button</tiny-button>
<tiny-button type="info">Information button</tiny-button>
<tiny-button type="warning">Warning button</tiny-button>
<tiny-button type="danger">Danger button</tiny-button>
</tiny-row>
</tiny-layout>
</div>
</template>
<script>
import { Button, Layout, Row } from '@opentiny/vue'
export default {
components: {
TinyButton: Button,
TinyLayout: Layout,
TinyRow: Row
}
}
</script>
```

View File

@ -0,0 +1,207 @@
## 适配 AUI
### 依赖映射表
目前 TinyVue 已经兼容 AUI只需替换一下包名和配置一下样式主题即可获得于 AUI 一致的体验,以下是 TinyVue 包和 AUI 包的映射关系
| TinyVue 包 | AUI 包 |
| ------------------------ | --------------------- |
| @opentiny/vue | @aurora/vue |
| @opentiny/vue-renderless | @aurora/renderless |
| @opentiny/vue-theme | @aurora/theme |
| @opentiny/vue-theme-saas | @aurora/theme-sass |
| @opentiny/vue-icon | @aurora/vue-icon |
| @opentiny/vue-icon-saas | @aurora/vue-icon-saas |
### 使用 Saas 主题
#### 背景
- 随着应用生态特别是手机应用生态的繁荣,以及多样化设备生态的发展,`多端`、`多主题`被提上日程;
- 原有 AUI 推出的主题方案过于臃肿(用户定制主题需要设置一堆的  `cssvar`  变量,因为颜色没有统一,配置多主题的门槛也比较高),后期会基于  [tailwindcss](https://github.com/tailwindlabs/tailwindcss)  对主题变量进行收拢(简化开发者配置)以及工程化改造,使得定制多主题更加简单。目前业内比较成熟的主题方案  [daisyui](https://github.com/saadeghi/daisyui)。
鉴于以上原因, 推出  `SaaS`  主题,如果想体验  `SaaS`  主题可以按照下述文档,进行打包配置更改:
#### 方法一
方案一需要额外安装以下依赖:
- `@opentiny/vue-theme-saas`  主题会对现有组件样式进行细微调整,不会影响原有 DOM 结构以及 API 。
- `@opentiny/vue-icon-saas`  `SaaS`  主题风格配套的 icon 图标组件。
- `@opentiny/vue-design-saas`  `SaaS`  主题风格配套的设计规范配置。
一、安装 SaaS 主题包:
```shell
yarn add @opentiny/vue-theme-saas @opentiny/vue-icon-saas @opentiny/vue-design-saas
# 或者 npm install @opentiny/vue-theme-saas @opentiny/vue-icon-saas @opentiny/vue-design-saas
```
二、切换到 SaaS 主题包:
```js
// (webpack) vue.config.js
module.exports = {
chainWebpack: (config) => {
config.resolve.alias.set('@opentiny/vue-theme', '@opentiny/vue-theme-saas')
config.resolve.alias.set('@opentiny/vue-icon', '@opentiny/vue-icon-saas')
}
}
// (vite) vite.config.js
export default defineConfig({
resolve: {
alias: {
'@opentiny/vue-theme': '@opentiny/vue-theme-saas',
'@opentiny/vue-icon': '@opentiny/vue-icon-saas'
}
}
})
```
三、切换到 Saas 设计规范配置:
```html
<script setup>
import { ConfigProvider } from '@opentiny/vue'
import designSaasConfig from '@opentiny/vue-design-saas'
</script>
<template>
<!-- 注入saas设计规范配置 -->
<config-provider :design="designSaasConfig">
<my-app></my-app>
</config-provider>
</template>
```
### 方法二
方法二需要额外安装以下依赖:
- `@opentiny/vue-theme-saas`  主题会对现有组件样式进行细微调整,不会影响原有 DOM 结构以及 API 。
- `@opentiny/vue-icon-saas`  `SaaS`  主题风格配套的 icon 图标组件。
- `@opentiny/vue-common-saas`  `SaaS`  主题风格配套的适配层,内联了方法一的`@opentiny/vue-design-saas`。
一、安装 SaaS 主题包:
```shell
yarn add @opentiny/vue-theme-saas @opentiny/vue-icon-saas @opentiny/vue-common-saas
# 或者 npm install @opentiny/vue-theme-saas @opentiny/vue-icon-saas @opentiny/vue-common-saas
```
二、切换到 SaaS 主题包:
```js
// (webpack) vue.config.js
module.exports = {
chainWebpack: (config) => {
config.resolve.alias.set('@opentiny/vue-theme', '@opentiny/vue-theme-saas')
config.resolve.alias.set('@opentiny/vue-icon', '@opentiny/vue-icon-saas')
config.resolve.alias.set('@opentiny/vue-common', '@opentiny/vue-common-saas')
}
}
// (vite) vite.config.js
export default defineConfig({
resolve: {
alias: {
'@opentiny/vue-theme': '@opentiny/vue-theme-saas',
'@opentiny/vue-icon': '@opentiny/vue-icon-saas',
'@opentiny/vue-common': '@opentiny/vue-common-saas'
}
}
})
```
## 多模式介绍
TinyVue 提供了 PC 和 Mobile 组件库,两套组件库对外是同一份依赖`@opentiny/vue`,同名组件通过`tiny_mode`切换组件模式。
针对 SaaS 业务场景TinyVue 提供了基于`tailwind`实现的多端组件,
在 TinyVue 基础上新增`多端模式`,支持业务切换同名组件,同名组件默认情况下是`桌面模式`即`PC 组件`。
### 模式分类
AUI 组件库提供了三种组件模式:`桌面模式`、`移动模式`、`多端模式`
| 模式 | 模式介绍 | 模式配置 |
| -------- | --------- | ------------ |
| 桌面模式 | 纯 PC | pc |
| 移动模式 | 纯 mobile | mobile |
| 多端模式 | 多端一致 | mobile-first |
### 模式切换
AUI 组件模式设置优先级
`单组件切换` > `模式透传` > `全局切换` > `组件默认模式`
#### 单组件切换
可在组件标签上配置`tiny_mode`属性,指定组件模式,就会选择对应模板渲染:
- 桌面模式:`pc`
- 移动模式:`mobile`
- 多端模式:`mobile-first`
参考示例如下:
```html
<tiny-button tiny_mode="mobile-first">默认按钮</tiny-button>
```
#### 全局切换
通过在 Vue 的原型上全局设置`tiny_mode`,可以指定所有同名组件的默认模式。
在项目入口  `src/main.js`  文件中导入 Vue 依赖后,增加如下配置:
```js
// Vue 2.0
Vue.prototype.tiny_mode = { value: 'mobile-first' }
// Vue 3.0
app.config.globalProperties.tiny_mode = { value: 'mobile-first' }
```
#### 模式透传
如果想在页面部分区域切换模式,如卡片级控制,
可以在外层 AUI 组件上添加`tiny_mode_root`属性,透传当前 AUI 组件的`tiny_mode`配置到所有子级 AUI 组件上,
参考 demo 示例如下:
```html
<template>
<div>
<tiny-layout>
<tiny-row tiny_mode="pc" tiny_mode_root>
<tiny-button>PC按钮</tiny-button>
<tiny-button type="primary" native-type="submit">主要按钮</tiny-button>
<tiny-button type="success">成功按钮</tiny-button>
<tiny-button type="info">信息按钮</tiny-button>
<tiny-button type="warning">警告按钮</tiny-button>
<tiny-button type="danger">危险按钮</tiny-button>
</tiny-row>
<tiny-row tiny_mode="mobile-first" tiny_mode_root>
<tiny-button>多端按钮</tiny-button>
<tiny-button type="primary" native-type="submit">主要按钮</tiny-button>
<tiny-button type="success">成功按钮</tiny-button>
<tiny-button type="info">信息按钮</tiny-button>
<tiny-button type="warning">警告按钮</tiny-button>
<tiny-button type="danger">危险按钮</tiny-button>
</tiny-row>
</tiny-layout>
</div>
</template>
<script>
import { Button, Layout, Row } from '@opentiny/vue'
export default {
components: {
TinyButton: Button,
TinyLayout: Layout,
TinyRow: Row
}
}
</script>
```