From 05a0602d8938ff9a6e60e7ef8fa936ecfc666816 Mon Sep 17 00:00:00 2001 From: gimmyhehe <975402925@qq.com> Date: Tue, 2 Apr 2024 16:17:57 +0800 Subject: [PATCH] docs(sites): add aui adapter document (#1516) --- examples/sites/demos/pc/menus.js | 83 +++++-- .../sites/demos/pc/webdoc/aui-adapter-en.md | 207 ++++++++++++++++++ examples/sites/demos/pc/webdoc/aui-adapter.md | 207 ++++++++++++++++++ 3 files changed, 477 insertions(+), 20 deletions(-) create mode 100644 examples/sites/demos/pc/webdoc/aui-adapter-en.md create mode 100644 examples/sites/demos/pc/webdoc/aui-adapter.md diff --git a/examples/sites/demos/pc/menus.js b/examples/sites/demos/pc/menus.js index 30b92e18d..ffda8959e 100644 --- a/examples/sites/demos/pc/menus.js +++ b/examples/sites/demos/pc/menus.js @@ -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', diff --git a/examples/sites/demos/pc/webdoc/aui-adapter-en.md b/examples/sites/demos/pc/webdoc/aui-adapter-en.md new file mode 100644 index 000000000..aa4d10a72 --- /dev/null +++ b/examples/sites/demos/pc/webdoc/aui-adapter-en.md @@ -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 + + + +``` + +### 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 +Default 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 + + + +``` diff --git a/examples/sites/demos/pc/webdoc/aui-adapter.md b/examples/sites/demos/pc/webdoc/aui-adapter.md new file mode 100644 index 000000000..95c9193a8 --- /dev/null +++ b/examples/sites/demos/pc/webdoc/aui-adapter.md @@ -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 + + + +``` + +### 方法二 + +方法二需要额外安装以下依赖： + +- `@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 +默认按钮 +``` + +#### 全局切换 + +通过在 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 + + + +```