此文章是由个人对该技术的理解和解读官网翻译而来,不免有不太恰当的地方,望多多指教,共同学习。
react-styleguidist 会把所有组件都显示在一个页面上,包含 props 文档和用法示例,以及一个独立开发组件的环境。 在Styleguidist 中,可以在 Markdown 中编写示例,每个代码段都会立即呈现;
Styleguidist会加载组件,使用react-docgen生成文档,可能需要更改代码才能正常工作。
React-docgen会把组件作为静态文本文件读取,然后类似于查找React组件的模式去查找组件(例如类或函数声明)。React-docgen不会运行任何JavaScript代码,因此,如果组件是动态生成,或包装在高阶组件中,或拆分为多个文件,react-docgen可能无法理解。
React-docgen支持通过React.createClass,ES6 classes 和函数组件定义的组件;
React-docgen支持Flow和TypeScript注释;
在某些情况下,可以通过导出两个组件 欺骗 Styleguidist和react-docgen:
import React from 'react'
import CSSModules from 'react-css-modules'
import styles from './Button.css'
// Base component will be used by react-docgen to generate documentation
export function Button({ color, size, children }) {
/* ... */
}
// Enhanced component will be used when you write <Button /> in your example files
export default CSSModules(Button, styles)
安装 Styleguidist:
// npm
npm install --save react-styleguidist
// yarn
yarn add react-styleguidist
配置package.json脚本
"scripts": {
"styleguide": "NODE_ENV=development styleguidist server",
"styleguide:build": "NODE_ENV=production styleguidist build",
}
运行Styleguidist
npm run styleguide //启动styleguidist开发服务器
npm run styleguide:build //构建生产HTML版本
Styleguidist根据组件中的注释,propTypes声明和Readerme.md
为组件生成文档。
默认行为:Styleguidist从propTypes中获取props并生成一个表格,并根据props的注释显示组件的说明,根据defaultProps获取props的默认值。
import React from 'react'
import PropTypes from 'prop-types'
/**
* General component description in JSDoc format. Markdown is *supported*.
*/
export default class Button extends React.Component {
static propTypes = {
/** Description of prop "foo". */
foo: PropTypes.number,
/** Description of prop "baz". */
baz: PropTypes.oneOfType([PropTypes.number, PropTypes.string])
}
static defaultProps = {
foo: 42
}
render() {
/* ... */
}
}
可以使用propsParser
和resolver
更改解析props默认行为;
propsParser: Function
此方法可以重新个从源文件如何解析props。默认是使用react-docgen进行解析。
module.exports = {
propsParser(filePath, source, resolver, handlers) {
return require('react-docgen').parse(source, resolver, handlers)
}
}
resolver
此方法可以确定哪些类/组件需要解析。默认行为是在每个文件中查找所有导出的组件,可以配置它以让所有查找到的组件使用自定义解析方法。
module.exports = {
resolver: require('react-docgen').resolver
.findAllComponentDefinitions
}
组件的PropType和文档注释由react-docgen库解析, 可以使用updateDocs函数对其进行修改。有关解析props的更多信息,可参见react-docgen文档。
默认行为:Styleguidist默认在组件文件夹下查找Readme.md
或[ComponentName].md
的文件并生成示例文件。
带有js,jsx或javascript标记的代码块将被呈现为带有交互式的React组件。为了向后兼容,不带语言标签的代码块也会展示成带有交互式的React组件。
React component example:
?```js
<Button size="large">Push Me</Button>
?```
You can add a custom props to an example wrapper:
?```js { "props": { "className": "checks" } }
<Button>I’m transparent!</Button>
?```
To render an example as highlighted source code add a `static` modifier:
?```jsx static
import React from 'react';
?```
可以通过getExampleFilename
自定义md 文件名字,此方法通过提供的组建文件路径返回新的 md 文件路径。
例如:用 ComponentName.examples.md
代替 Readme.md
module.exports = {
getExampleFilename(componentPath) {
return componentPath.replace(/\.jsx?$/, '.examples.md')
}
}
可以使用@example doclet
语法将其他示例文件与组件关联。
例子:Button 组件有一个从extra.examples.md文件加载的示例
/**
* Component is described here.
*
* @example ./extra.examples.md
*/
export default class Button extends React.Component {
// ...
}
// ```jsx inside Markdown
import React from 'react'
import Button from 'rsg-example/components/Button'
import Placeholder from 'rsg-example/components/Placeholder'
;<Button size="large">Push Me</Button>
// ```jsx inside Markdown
const [isOpen, setIsOpen] = React.useState(false)
;<div>
<button onClick={() => setIsOpen(true)}>Open</button>
<Modal isOpen={isOpen}>
<h1>Hallo!</h1>
<button onClick={() => setIsOpen(false)}>Close</button>
</Modal>
</div>
moduleAliases
定义模块的别名,可以在示例文件中导入这些别名,以使示例代码更加实际和可复制;
const path = require('path');
module.exports = {
moduleAliases: {
'rsg-example': path.resolve(__dirname, 'src')
}
}
- Markdown语法都被支持;
- 如果需要在文档中显示一些不想被呈现为交互式的JavaScript代码,则可以将static修饰符与语言标签一起使用;
- Styleguidist 通过 Bublé 运行ES6代码, 大多数ES6功能都支持;
- rsg-example模块是由moduleAliases 选项定义的别名;
- 如果需要更复杂的演示,通常最好将其定义在一个单独的JavaScript文件中,然后将其导入Markdown中
默认情况下,组件所具有的任何方法均被视为私有方法,不会被发布。使用JSDoc @public
标记方法,就可以使其成为公共方法并会在文档中发布。
/**
* @param {string} name
* @public
*/
getName(name) {
// ...
}
默认情况下,组件所有的props都是公开并可发布。在某些情况下代码存在某props, 希望文档中不展示这个props,使用JSDoc @ignore
标记props,就可以将其从文档中删除。
Button.propTypes = {
/**
* A prop that should not be visible in the documentation.
* @ignore
*/
hiddenProp: React.PropTypes.string
}
默认情况下,Styleguidist将使用此模式定位组件:src/components/**/*.{js,jsx,ts,tsx}
。
例如:
src/components/Button.js
src/components/Button/Button.js
src/components/Button/index.js
但是会忽略 tests 文件:
__tests__
文件夹.test.js
或 .spec.js
(类似于: .jsx
, .ts
, .tsx
)在styleguide.config.js
文件里的配置components
可以修改组件查找方式来适应不同的项目;
例如:如果组件路径是components/Button/Button.js
,为了简化导入在components/Button/index.js
中再次导出(export { default } from './Button'
),【为了让components/Button
替代components/Button/Button
】, 这时候需要跳过 index.js。
module.exports = {
components: 'src/components/**/[A-Z]*.js'
}
ignore
可将某些文件从样式指南中排除ignore:String[]
默认值:
[
'**/__tests__/**',
'**/*.test.{js,jsx,ts,tsx}',
'**/*.spec.{js,jsx,ts,tsx}',
'**/*.d.ts'
]
getComponentPathLine
更改组件导入路径getComponentPathLine: Function
默认值: 组件文件名
返回值:返回组件路径
例如: 从components/Button
中导入Button,而不是components/Button /Button.js
const path = require('path');
module.exports = {
getComponentPathLine(componentPath) {
const name = path.basename(componentPath, '.js')
const dir = path.dirname(componentPath)
return `import ${name} from '${dir}';`
}
}
所有路径都相对于config文件夹;
Styleguidist加载组件并暴露在全局以供示例使用。
Styleguidist默认使用组件的displayName作为标识符。如果它不能理解displayName(displayName动态生成),它将退回到它可以理解的东西。
Sections: Array[{}]
将组件分组,或将额外的Markdown文档添加到样式指南中。
Sections数组的每一项有:
name
— Sections 标题;content
— 包含概述内容的Markdown文件的位置;components
— 可以是glob模式字符串,组件路径数组,glob模式字符串数组,返回一个组件数组的函数或返回glob模式字符串的函数。规则与根选项components
相同;sections
— 嵌套的Sections数组(可以再嵌套);description
— section描述;sectionDepth
— 单个页面的小节数,仅在pagePerSection
中可用;exampleMode
— 代码示例的初始状态,使用 exampleMode.usageMode
— props和方法的初始状态, 使用 usageMode.ignore
— 需要忽略的文件,值可以是字符串或数组;href
- navigate的URL(不是导航到Sections 内容的URL);external
- 如果设置,会打开一个新页面;expand
- 在常规设置中将tocMode
设置为collapse
折叠时,确认是否应该被展开;上述所有字段都是可选的;
// styleguide.config.js
module.exports = {
sections: [
{
name: 'Introduction',
content: 'docs/introduction.md'
},
{
name: 'Documentation',
sections: [
{
name: 'Installation',
content: 'docs/installation.md',
description: 'The description for the installation section'
},
{
name: 'Configuration',
content: 'docs/configuration.md'
},
{
name: 'Live Demo',
external: true,
href: 'http://example.com'
}
]
},
{
name: 'UI Components',
content: 'docs/ui.md',
components: 'lib/components/ui/*.js',
exampleMode: 'expand', // 'hide' | 'collapse' | 'expand'
usageMode: 'expand' // 'hide' | 'collapse' | 'expand'
}
]
}
Styleguidist依赖webpack,使用webpack确定如何加载项目的文件,但项目也不一定非要配置webpack。
默认情况下,Styleguidist会在项目的根目录中查找webpack.config.js
并使用它。
如果webpack配置在其他位置,则需要手动加载:
module.exports = {
webpackConfig: require('./configs/webpack.js')
}
也可以merge多个webpack配置:
module.exports = {
webpackConfig: Object.assign({}, require('./configs/webpack.js'), {
/* Custom config options */
})
}
- 配置
entry
,externals
,output
,watch
, 和stats
.会被忽略。生产上,devtool
也会被忽略;- 插件
CommonsChunkPlugins
,HtmlWebpackPlugin
,MiniHtmlWebpackPlugin
,UglifyJsPlugin
,TerserPlugin
,HotModuleReplacementPlugin
会被忽略, 因为 Styleguidist 已经引入了他们,再次引入会影响 Styleguidist;- 如果loaders 不起作用,请尝试包含和排除绝对路径;
title: String
serverPort: Number
端口号
require: Array
添加用户自定义的js, CSS 或 polyfills
assetsDir: String
资源文件名
styleguideDir: String
默认值:styleguide
定义styleguidist构建命令生成的静态HTML的文件夹;
getComponentPathLine: Function
获取组件加载路径
template: Object | Function
更改应用程序的HTML。 一个可以添加favicon,meta 标签, 内嵌JavaScript或CSS的对象。
styles: Object | String | Function
自定义Styleguidist组件的样式。
theme: Object | String
配置值可以是对象或导出此类对象的文件的路径实现自定义UI字体,颜色等;
配置的文件路径是相对配置文件或者绝对路径。
sections
设置组件分组;
styleguideComponents: Object
重写被用于渲染到浏览器的React组件;
webpackConfig
自定义webpack配置;
更多配置选项查看官方文档:configuration
浏览器引擎前缀(Vendor Prefix)是什么? Vendor prefix浏览器引擎前缀,是一些放...
复制代码 代码如下: div id="test" a href="#" test /a /div div id="result"/di...
实现效果 实现思路 融化效果是利用 filfilter 的 contrast 和 blur 实现的。 在...
对404都是避之不及,何来体验之说?原因可能是大多数404页面 都太粗糙了,而今天...
网页上经常会看到漂浮的广告,这些广告可以利用Dreamweaver CS3的时间轴来制作,...
一、概述 最近在研究skywalking,打算使用k8s部署 skywalking 并将 pod 中的应用...
相信大家都有这样的感受,看个视频有个30秒的广告,让人非常的不爽。同样对于我...
接口和类型别名非常相似,在大多情况下二者可以互换。在写TS的时候,想必大家都...
今天给大家讲一下清楚浮动,在讲清除浮动前,需要了解什么是浮动,这里我就不给...
具体代码如下所示: !doctype htmlhtml class=no-jsheadmeta charset=utf-8meta ...