feat(ui/style-provider): add component style-provider

varletjs · Feb 25, 2022 · db1453b · db1453b
1 parent 0eb95c5
commit db1453b
Show file tree

Hide file tree

Showing 9 changed files with 450 additions and 10 deletions.
diff --git a/packages/varlet-vue2-ui/docs/quickstart.en-US.md b/packages/varlet-vue2-ui/docs/quickstart.en-US.md
@@ -11,16 +11,15 @@ Here are the most basic ways to access component libraries in common development
 
 ```html
 <div id="app"></div>
-<script src="https://cdn.jsdelivr.net/npm/vue@next"></script>
+<script src="https://cdn.jsdelivr.net/npm/vue@2.6.14"></script>
 <script src="https://cdn.jsdelivr.net/npm/@varlet-vue2/ui/umd/varlet.js"></script>
 <script>
   const App = Vue.use({
     template: '<var-button>按钮</var-button>'
   })
   new Vue({
-     el: '#app',
      render: h => h(App)
-  })
+  }).$mount('#app');
 </script>
 ```
 
@@ -48,9 +47,8 @@ import '@varlet-vue2/ui/es/style.js'
 Vue.use(Varlet)
 
 new Vue({
-  el: '#app',
   render: h => h(App)
-});
+}).$mount('#app');
 ```
 
 ### Components Playground

diff --git a/packages/varlet-vue2-ui/docs/quickstart.zh-CN.md b/packages/varlet-vue2-ui/docs/quickstart.zh-CN.md
@@ -11,16 +11,15 @@
 
 ```html
 <div id="app"></div>
-<script src="https://cdn.jsdelivr.net/npm/vue@next"></script>
+<script src="https://cdn.jsdelivr.net/npm/vue@2.6.14"></script>
 <script src="https://cdn.jsdelivr.net/npm/@varlet-vue2/ui/umd/varlet.js"></script>
 <script>
   const App = Vue.use({
     template: '<var-button>按钮</var-button>'
   })
   new Vue({
-     el: '#app',
      render: h => h(App)
-  })
+  }).$mount('#app');
 </script>
 ```
 
@@ -48,9 +47,8 @@ import '@varlet-vue2/ui/es/style.js'
 Vue.use(Varlet)
 
 new Vue({
-  el: '#app',
   render: h => h(App)
-});
+}).$mount('#app');;
 ```
 
 ### 在线编辑组件

diff --git a/packages/varlet-vue2-ui/src/style-provider/__tests__/index.spec.js b/packages/varlet-vue2-ui/src/style-provider/__tests__/index.spec.js
@@ -0,0 +1,38 @@
+import StyleProvider from '../index'
+import VarStyleProvider from '../StyleProvider'
+import Vue from 'vue'
+import { mount } from '@vue/test-utils'
+import { delay } from '../../utils/jest'
+
+test('test styleProvider component plugin', () => {
+  Vue.use(StyleProvider)
+  expect(Vue.component(StyleProvider.Component.name)).toBeTruthy()
+})
+
+test('test styleProvider plugin', () => {
+  Vue.use(VarStyleProvider)
+  expect(Vue.component(VarStyleProvider.name)).toBeTruthy()
+})
+
+test('test styleProvider functional', async () => {
+  StyleProvider({
+    'cell-font-size': '30px',
+  })
+
+  await delay(0)
+  expect(getComputedStyle(document.documentElement).getPropertyValue('--cell-font-size')).toBe('30px')
+})
+
+test('test styleProvider component', async () => {
+  const wrapper = mount(VarStyleProvider)
+
+  const el = wrapper.find('.var-style-provider')
+  expect(el.exists()).toBe(true)
+
+  await wrapper.setProps({
+    styleVars: {
+      'cell-font-size': '30px',
+    },
+  })
+  expect(el.attributes('style')).toBe('--cell-font-size: 30px;')
+})
diff --git a/packages/varlet-vue2-ui/src/style-provider/docs/en-US.md b/packages/varlet-vue2-ui/src/style-provider/docs/en-US.md
@@ -0,0 +1,143 @@
+# Style Provider
+
+### Intro
+
+Component libraries organize styles through [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).
+Each component has a corresponding style variable, you can directly replace the style variable on the root node by overriding it with a CSS file.
+Or use StyleProvider components.
+
+### Basic style variable
+
+Here are some basic style variables for the component library
+
+```css
+:root {
+  --font-size-xs: 10px;
+  --font-size-sm: 12px;
+  --font-size-md: 14px;
+  --font-size-lg: 16px;
+  --icon-size-xs: 16px;
+  --icon-size-sm: 18px;
+  --icon-size-md: 20px;
+  --icon-size-lg: 22px;
+  --color-body: #fff;
+  --color-text: #333;
+  --color-primary: #3a7afe;
+  --color-info: #00afef;
+  --color-success: #00c48f;
+  --color-warning: #ff9f00;
+  --color-danger: #f44336;
+  --color-disabled: #e0e0e0;
+  --color-text-disabled: #aaa;
+  --cubic-bezier: cubic-bezier(0.25, 0.8, 0.5, 1);
+}
+```
+
+### Modify styles at runtime
+
+Maybe you have a need to replace the style while the program is runtime，like a one-click skin change or something.
+The component library provides a StyleProvider component to assist in managing styles,
+Component provides' `component call` and `function call` and two invocation modes.
+
+### Install
+
+```js
+import Vue from 'vue'
+import { StyleProvider } from '@varlet-vue2/ui'
+
+Vue.use(StyleProvider)
+```
+
+### Scoped Install
+
+```js
+import { StyleProvider } from '@varlet-vue2/ui'
+
+export default {
+  components: {
+    [StyleProvider.Component.name]: StyleProvider
+  }
+}
+```
+
+### Component Call
+
+Component calls can have a scope of custom component styles, Scope contamination is avoided.
+Note that some elements sent outside the StyleProvider using the `teleport` will not work
+
+```html
+<var-style-provider :style-vars="styleVars">
+  <var-rate v-model="state.score" />
+  <var-switch v-model="state.license" />
+  <var-button 
+    style="margin-top: 10px" 
+    type="primary"
+    block
+    @click="toggleTheme"
+  >
+    Toggle Theme
+  </var-button>
+</var-style-provider>
+```
+
+```js
+export default {
+  data: () => ({
+    state: {
+      score: 5,
+      license: true,
+    },
+    successTheme: {
+      '--rate-primary-color': 'var(--color-success)',
+      '--button-primary-color': 'var(--color-success)',
+      '--switch-handle-active-background': 'var(--color-success)',
+      '--switch-track-active-background': 'var(--color-success)',
+    },
+    styleVars: null
+  }),
+  methods: {
+    toggleTheme() {
+      this.styleVars = this.styleVars ? null : this.successTheme
+    }
+  }
+}
+```
+
+### Function Call
+
+A functional call is to update variables directly on `:root`, which is suitable for situations where a global update style is required
+
+```html
+<var-button type="primary" block @click="toggleRootTheme">Toggle Root Theme</var-button>
+```
+
+```js
+export default {
+  data: () => ({
+    rootStyleVars: null,
+    darkTheme: {
+      '--color-primary': '#3f51b5'
+    }
+  }),
+  methods: {
+    toggleRootTheme() {
+      this.rootStyleVars = this.rootStyleVars ? null : this.darkTheme
+      StyleProvider(this.rootStyleVars)
+    }
+  }
+}
+```
+
+## API
+
+### Props
+
+| Prop | Description | Type | Default | 
+| --- | --- | --- | --- | 
+| `style-vars` | CSS variables | _Record<string, string>_ | `{}` |
+
+### Slots
+
+| Slot | Description | Arguments |
+| --- | --- | --- |
+| `default` | Component content | `-` |
diff --git a/packages/varlet-vue2-ui/src/style-provider/docs/zh-CN.md b/packages/varlet-vue2-ui/src/style-provider/docs/zh-CN.md
@@ -0,0 +1,140 @@
+# 样式定制
+
+### 介绍
+
+组件库通过 [css 变量](https://developer.mozilla.org/zh-CN/docs/Web/CSS/Using_CSS_custom_properties)来组织样式，每个组件都有对应的样式变量，
+您可以通过 css 文件覆盖的方式直接替换根节点上的样式变量, 或者使用 StyleProvider 组件。
+
+### 基本样式变量
+
+以下是组件库一些基本的样式变量
+
+```css
+:root {
+  --font-size-xs: 10px;
+  --font-size-sm: 12px;
+  --font-size-md: 14px;
+  --font-size-lg: 16px;
+  --icon-size-xs: 16px;
+  --icon-size-sm: 18px;
+  --icon-size-md: 20px;
+  --icon-size-lg: 22px;
+  --color-body: #fff;
+  --color-text: #333;
+  --color-primary: #3a7afe;
+  --color-info: #00afef;
+  --color-success: #00c48f;
+  --color-warning: #ff9f00;
+  --color-danger: #f44336;
+  --color-disabled: #e0e0e0;
+  --color-text-disabled: #aaa;
+  --cubic-bezier: cubic-bezier(0.25, 0.8, 0.5, 1);
+}
+```
+
+### 运行时修改样式
+
+可能您有在程序运行时替换样式的需求，比如一键换肤之类的，组件库提供了 StyleProvider 组件来辅助管理样式，
+组件提供了 `组件式调用` 和 `函数式调用` 和两种调用方式。
+
+### 引入
+
+```js
+import Vue from 'vue'
+import { StyleProvider } from '@varlet-vue2/ui'
+
+Vue.use(StyleProvider)
+```
+
+### 局部引入
+
+```js
+import { StyleProvider } from '@varlet-vue2/ui'
+
+export default {
+  components: {
+    [StyleProvider.Component.name]: StyleProvider
+  }
+}
+```
+
+### 组件式调用
+
+组件式调用可以有范围性的定制组件样式，避免了全局污染，需要注意是有些使用 `teleport` 传送到  `StyleProvider` 外的元素将不会生效。
+
+```html
+<var-style-provider :style-vars="styleVars">
+  <var-rate v-model="state.score" />
+  <var-switch v-model="state.license" />
+  <var-button
+    style="margin-top: 10px"
+    type="primary"
+    block
+    @click="toggleTheme"
+  >
+    切换样式变量
+  </var-button>
+</var-style-provider>
+```
+
+```js
+export default {
+  data: () => ({
+    state: {
+      score: 5,
+      license: true,
+    },
+    successTheme: {
+      '--rate-primary-color': 'var(--color-success)',
+      '--button-primary-color': 'var(--color-success)',
+      '--switch-handle-active-background': 'var(--color-success)',
+      '--switch-track-active-background': 'var(--color-success)',
+    },
+    styleVars: null
+  }),
+  methods: {
+    toggleTheme() {
+      this.styleVars = this.styleVars ? null : this.successTheme
+    }
+  }
+}
+```
+
+### 函数式调用
+
+函数式的调用是直接更新 `:root` 上的变量，适合需要全局更新样式的情况。
+
+```html
+<var-button type="primary" block @click="toggleRootTheme">切换根节点样式变量</var-button>
+```
+
+```js
+export default {
+  data: () => ({
+    rootStyleVars: null,
+    darkTheme: {
+      '--color-primary': '#3f51b5'
+    }
+  }),
+  methods: {
+    toggleRootTheme() {
+      this.rootStyleVars = this.rootStyleVars ? null : this.darkTheme
+      StyleProvider(this.rootStyleVars)
+    }
+  }
+}
+```
+
+## API
+
+### 属性
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| `style-vars` | css 变量 | _Record<string, string>_ | `{}` |
+
+### 插槽
+
+| 插槽名 | 说明 | 参数 |
+| --- | --- | --- |
+| `default` | 组件内容 | `-` |