# styleguidist_demo

**Repository Path**: amazing_steven/styleguidist_demo

## Basic Information

- **Project Name**: styleguidist_demo
- **Description**: 结合 styleguidist + vue + elementui 搭建的建议demo。
可以识别国际化，scss ，elementui 并提供可供查看的demo
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-01-03
- **Last Updated**: 2024-01-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 思路文档

[Vue Styleguidist docs](https://vue-styleguidist.github.io/Examples.html)

[如何让你的vue组件更好的被使用（Vue-Styleguidist中文文档） - 菜鸟学院](http://www.noobyard.com/article/p-dlckniis-ck.html)

[](https://segmentfault.com/a/1190000022721297?utm_source=tag-newest)

[Vue Styleguidist 生成组件说明文档 - 掘金](https://juejin.cn/post/7194369030696730682)

tips:

nrm 可以切换npm 源

nvm 可以切换node 版本，每次切换版本后都需要重新下载全局文件, 例如 npm i -g yarn 

# 前置条件

1. node 版本 ≥ 16.14
2. yarn
3. 全局安装vue-cli,  npm i -g @vue/cli

# 使用说明

## 安装

```jsx
vue add styleguidist
```

安装成功主要会有以下3个变化：

1. 根目录下出现  `@styleguide.config.js`  文件
2. src/components 会出现 AppButton.vue 文件
3. package.json 脚本中会出现，`styleguide`  和 `styleguide:build`命令 

## 配置文件说明

 styleguide.config.js

## 解释

### 解析demo

```jsx
<template>
	<button :style="styles" @click="handleClick">
// ❤ 使用 @slot 会出现在slot 说明里，并会自动解析name 值，没有则默认为default
		<!-- @slot Use this slot to place the button content -->
		<slot name="test"></slot>
	</button>
</template>

<script>
import sizeMixin from './sizeMixin'
export default {
	name: 'mc-button',  // ❤ 组件名称，必填
	mixins: [sizeMixin], //  ❤ 可以识别mixins
	props: {
		/**
		 * Sets the button font color ❤ 属性说明
		 */
		color: {
			type: String,
			default: 'black'
		},
		/** Sets background color of the button
		 * @values white / black / orange  ❤ 可以设定不同value值
	
		 */
		background: {
			type: String,
			default: 'white'
		},
		/** @deprecated Use color instead ❤ 不建议使用此方法*/
		oldColor: String
	},
	computed: {
		styles() {
			return {
				'font-size': this.size,
				color: this.color,
				background: this.background
			}
		}
	},
	methods: {
		handleClick(e) {
			/** Triggered when button is clicked ❤ 方法的描述
			 * @event click ❤ 触发的事件名
			 * @type {Boolean}  ❤ 定义传参的格式
			 */
			this.$emit('click', e)
		}
	}
}
</script>
// ❤ 对文档进行详细的说明，支持markdown
<docs lang="md">
❤ 组件说明
This button is amazing, use it responsibly.

## 举例说明

Orange button:

```jsx
<app-button color="orange">Push Me</app-button>
```

Ugly button with pink font and blue background:

```jsx
<app-button color="pink" background="blue">
	Ugly button
</app-button>
```

Button containing custom tags:

```jsx
<app-button>
	Text with <b>bold</b>
</app-button>
```
</docs>
```

### 其他使用方法

不使用  `<doc lang="md"` 的情况下

```jsx
<template>
    <div class="Button">
      /* ... */
    </div>
  </template>
  
  <script>
    /**
     * The only true button.
     * @displayName Best Button
     */
    export default {
      name: 'mc-button', // ❤ 这里使用连接符
      props: {
        /**
         * The color for the button.
         */
        color: {
          type: String,
          default: '#333'
        },
        /**
         * The size of the button
         * @values small, normal, large
         */
        size: {
          type: String,
          default: 'normal'
        },
        /**
         * Gets called when the user clicks on the button
         */
        onClick: {
          type: Function,
          default: event => {
            console.log('You have clicked me!', event.target)
          }
        }
      }
      /* ... */
    }
  </script>vvvv
```

1. 使用了`@displayName`标签将该变组件名称，这是一个顶层的注释，必须出现在脚本标签`export default`之前。
2. 使用 `@values` 可以设定不同的value值
3. 对methods 中使用 `@property {number} newvalue 这里对value进行说明`
4. 对属性使用 `@binding {object} icon 这里是对icon的说明` 
5. 默认的组件中**`methods`**中的方法被视为私有的，是不会被公开的。可使用JSDoc中**`@public`**标签让方法视为公开，并展现在文档中
6. 默认状况下，组件中的全部属性**`props`**被认为是公开发的。在极少数状况下，想要只在文档中的移除部分属性说明。为此，可使用JSDoc的**`@ignore`**标签注释在属性前面，用于标记在文档中移除它。
7. 使用**`@example`**注释，添加外部示例文件。

# 结合项目使用

项目里使用需要满足以下几个条件：

- [x]  可以结合elementui
- [x]  可以满足组件嵌套
- [x]  可以使用全局scss变量
- [x]  可以使用全局的国际化
- [x]  尽可能的提供可运行的demo
- [x]  结构清晰
- [x]  可以做到忽略某些不需要说明的组件

## 结合elementui

### 引入全局组件依赖

因为styleguide是不会加载main.js的，所以需要把组件用到的依赖重新引入

根目录下新建一个styleguide文件，添加global.require.js文件，此文件会在styleguide.config.js里被引用；

```jsx
import Vue from 'vue';
import Element from 'element-ui';
import 'element-ui/lib/theme-chalk/index.css';
Vue.use(Element, {
  size: 'medium' // set element-ui default size
})
```

### 添加将新增文件放入

在styleguide.config.js 中加入

```jsx
const path = require('path')
module.exports = {
	require: [path.join(__dirname, 'styleguide/global.require.js')], //全局vue组件使用的插件
}
```

此时正常显示。


## 可以全局的国际化变量

新增  **`styleguide.root.js` 并在 styleguide.config.js 中配置**

```jsx
require: [  path.join(__dirname, 'src/config/global.requires.js') ], //全局vue组件使用的插件
renderRootJsx: path.join(__dirname, 'src/config/styleguide.root.js'),
```

**`styleguide.root.js` 内容如下：**

```jsx
import ElementUI from 'element-ui';
import i18n from '@/lang'

export default function(previewComponent) {
	return {
		i18n,
		ElementUI,
		render(h) {
			return h(
				'div',
				{
					props: {
						id: 'v-app'
					}
				},
				['', h(Object.assign(previewComponent))]
			)
		}
	}
}
```