npm
npmdoc
2年前 (2021-11-18)
1517次浏览
为什么是这个?
在 React 中还有其他降价方式,那么为什么要使用这个呢?
两个主要原因是他们经常依赖
dangerouslySetInnerHTML
或有错误处理降价的方式。
react-markdown
使用语法树来构建虚拟 dom,允许仅更新更改的 DOM 而不是完全覆盖。
react-markdown
100% 符合 CommonMark(可选 GFM)标准,并具有支持自定义语法的扩展。
一个基本的你好世界:
import React from 'react'
import ReactMarkdown from 'react-markdown'
import ReactDom from 'react-dom'
ReactDom.render(<ReactMarkdown># Hello, *world*!</ReactMarkdown>, document.body)
显示等效的 JSX
Hello,
<
em
>
world
<
/
em
>
!
这是一个示例,显示将降价作为字符串传递以及如何使用插件(
remark-gfm
,它直接添加了对删除线、表格、任务列表和 URL 的支持):
import React from 'react'
import ReactDom from 'react-dom'
import ReactMarkdown from 'react-markdown'
import remarkGfm from 'remark-gfm'
const markdown = `Just a link: https://reactjs.com.`
ReactDom.render(
<ReactMarkdown children={markdown} remarkPlugins={[remarkGfm]} />,
document.body
显示等效的 JSX
Just a link: <a href="https://reactjs.com">https://reactjs.com</a>.
应用程序接口
此包导出以下标识符:uriTransformer
. 默认导出为ReactMarkdown
.
props
children
( string
, 默认: ''
)
Markdown 解析
className
( string?
)用这个类名将
markdown 包裹在 a 中div
skipHtml
( boolean
, 默认: false
)
完全忽略 Markdown 中的 HTML
sourcePos
( boolean
, 默认: false
) 将
一个 prop 传递给所有具有序列化位置的组件 ( data-sourcepos="3:1-3:13"
)
rawSourcePos
( boolean
, 默认值: false
)
将 prop 传递给所有组件及其位置
( sourcePosition: {start: {line: 3, column: 1}, end:…}
)
includeElementIndex
( boolean
, 默认: false
)
将index
(它之前的元素数)和siblingCount
(父元素中的元素数)作为道具传递给所有组件
allowedElements
( Array.<string>
, 默认值: undefined
)
允许的标签名称(不能与 w/ 组合disallowedElements
)。默认情况下允许所有元素
disallowedElements
( Array.<string>
, 默认值: undefined
)
要禁止的标签名称(不能与 w/ 组合allowedElements
)。默认情况下,不允许任何元素
allowElement
( (element, index, parent) => boolean?
, 可选)
调用函数以检查元素是否被允许(真实时)。
allowedElements
/disallowedElements
最先使用!
unwrapDisallowed
( boolean
, 默认: false
)
提取(解包)不允许元素的子元素。默认情况下,当strong
不允许时,它及其子unwrapDisallowed
元素被删除,但元素本身被删除但子元素被使用
linkTarget
(string
或(href, children, title) => string
,可选)
在链接上使用的目标(例如_blank
for <a target="_blank"…
)
transformLinkUri
( (href, children, title) => string
, 默认值:
./uri-transformer.js
, 可选)
用于链接的 URL。默认只允许http
, https
, mailto
, and tel
, 并且从这个模块导出为uriTransformer
. 通过null
以允许所有 URL。查看安全
transformImageUri
( (src, alt, title) => string
, 默认值:
./uri-transformer.js
, 可选)
与transformLinkUri
图像相同但用于图像
components
( Object.<string, Component>
, 默认: {}
)
对象映射标签名称到 React 组件
remarkPlugins
( Array.<Plugin>
, 默认: []
)要使用
的注释插件列表。有关如何传递选项的示例,请参阅下一节
rehypePlugins
( Array.<Plugin>
, 默认: []
)要使用
的rehype 插件列表。有关如何传递选项的示例,请参阅下一节
此示例展示了如何使用备注插件。在这种情况下,remark-gfm
,它直接添加了对删除线、表格、任务列表和 URL 的支持:
import React from 'react'
import ReactMarkdown from 'react-markdown'
import ReactDom from 'react-dom'
import remarkGfm from 'remark-gfm'
const markdown = `A paragraph with *emphasis* and **strong importance**.
> A block quote with ~strikethrough~ and a URL: https://reactjs.org.
* Lists
* [ ] todo
* [x] done
A table:
| a | b |
| - | - |
ReactDom.render(
<ReactMarkdown children={markdown} remarkPlugins={[remarkGfm]} />,
document.body
显示等效的 JSX
A paragraph with <em>emphasis</em> and <strong>strong importance</strong>.
<blockquote>
A block quote with <del>strikethrough</del> and a URL:{' '}
<a href="https://reactjs.org">https://reactjs.org</a>.
</blockquote>
<li>Lists</li>
<input checked={false} readOnly={true} type="checkbox" /> todo
<input checked={true} readOnly={true} type="checkbox" /> done
<p>A table:</p>
<table>
<thead>
<td>a</td>
<td>b</td>
</thead>
</table>
使用带有选项的插件
此示例展示了如何使用插件并为其提供选项。为此,首先使用带有插件的数组,然后使用选项。
remark-gfm
可以选择只允许双波浪线作为删除线:
import React from 'react'
import ReactMarkdown from 'react-markdown'
import ReactDom from 'react-dom'
import remarkGfm from 'remark-gfm'
ReactDom.render(
<ReactMarkdown remarkPlugins={[[remarkGfm, {singleTilde: false}]]}>
This ~is not~ strikethrough, but ~~this is~~!
</ReactMarkdown>,
document.body
显示等效的 JSX
This ~is not~ strikethrough, but <del>this is</del>!
使用自定义组件(语法高亮)
这个例子展示了如何通过传递一个组件来覆盖一个元素的正常处理。在这种情况下,我们应用的语法高亮与严重的超惊人
react-syntax-highlighter
的
@conorhastings:
import React from 'react'
import ReactDom from 'react-dom'
import ReactMarkdown from 'react-markdown'
import {Prism as SyntaxHighlighter} from 'react-syntax-highlighter'
import {dark} from 'react-syntax-highlighter/dist/esm/styles/prism'
// Did you know you can use tildes instead of backticks for code in markdown? ✨
const markdown = `Here is some JavaScript code:
~~~js
console.log('It works!')
ReactDom.render(
<ReactMarkdown
children={markdown}
components={{
code({node, inline, className, children, ...props}) {
const match = /language-(\w+)/.exec(className || '')
return !inline && match ? (
<SyntaxHighlighter
children={String(children).replace(/\n$/, '')}
style={dark}
language={match[1]}
PreTag="div"
{...props}
) : (
<code className={className} {...props}>
{children}
</code>
document.body
显示等效的 JSX
<p>Here is some JavaScript code:</p>
<SyntaxHighlighter language="js" style={dark} PreTag="div" children="console.log('It works!')" />
</pre>
使用 remark 和 rehype 插件(数学)
此示例展示了如何使用语法扩展(通过remark-math
)来支持 Markdown 中的数学,以及如何使用转换插件 ( rehype-katex
) 来呈现该数学。
import React from 'react'
import ReactDom from 'react-dom'
import ReactMarkdown from 'react-markdown'
import remarkMath from 'remark-math'
import rehypeKatex from 'rehype-katex'
import 'katex/dist/katex.min.css' // `rehype-katex` does not import the CSS for you
ReactDom.render(
<ReactMarkdown
children={`The lift coefficient ($C_L$) is a dimensionless coefficient.`}
remarkPlugins={[remarkMath]}
rehypePlugins={[rehypeKatex]}
document.body
显示等效的 JSX
The lift coefficient (
<span className="math math-inline">
<span className="katex">
<span className="katex-mathml">
<math xmlns="http://www.w3.org/1998/Math/MathML">{/* … */}</math>
</span>
<span className="katex-html" aria-hidden="true">
{/* … */}
</span>
</span>
</span>
) is a dimensionless coefficient.
react-markdown
+-------------------------------------------------------------------------------------------------------------------------------------------+
| |
| +----------+ +----------------+ +---------------+ +----------------+ +------------+ |
| | | | | | | | | | | |
| -markdown->+ remark +-mdast->+ remark plugins +-mdast->+ remark-rehype +-hast->+ rehype plugins +-hast->+ components +-react elements-> |
| | | | | | | | | | | |
| +----------+ +----------------+ +---------------+ +----------------+ +------------+ |
| |
+-------------------------------------------------------------------------------------------------------------------------------------------+
相关链接:markdown , remark , mdast , remark plugins , remark-rehype , hast , rehype plugins , components
要了解这个项目的作用,首先要了解统一的作用是非常重要的:请通读unifiedjs/unified
自述文件(直到您点击 API 部分的部分是必读的)。
react-markdown 是一个统一的管道 – 被包装,因此大多数人不需要直接与统一进行交互。处理器执行以下步骤:
将 Markdown 解析为 mdast(markdown 语法树)
通过备注转化(降价生态系统)
将 mdast 转换为 hast(HTML 语法树)
通过再炒作进行转型(HTML 生态系统)
渲染必须与组件做出反应
附录 A:markdown 中的 HTML
react-markdown
通常会转义 HTML(或忽略它,使用skipHtml
),因为它很危险并且违背了这个库的目的。
但是,如果您处于受信任的环境中(您信任降价),并且可以节省包大小(±60kb minzipped),那么您可以使用
rehype-raw
:
import React from 'react'
import ReactDom from 'react-dom'
import ReactMarkdown from 'react-markdown'
import rehypeRaw from 'rehype-raw'
const input = `<div class="note">
Some *emphasis* and <strong>strong</strong>!
</div>`
ReactDom.render(
<ReactMarkdown rehypePlugins={[rehypeRaw]} children={input} />,
document.body
显示等效的 JSX
<div class="note">
<p>Some <em>emphasis</em> and <strong>strong</strong>!</p>
</div>
注意:markdown 中的 HTML 仍然受CommonMark 中 HTML 工作方式的约束。确保在再次包含 Markdown 的块级 HTML 周围使用空行!
附录 B:组件
您还可以更改来自 markdown 的内容:
<ReactMarkdown
components={{
// Map `h1` (`# heading`) to use `h2`s.
h1: 'h2',
// Rewrite `em`s (`*like so*`) to `i` with a red foreground color.
em: ({node, ...props}) => <i style={{color: 'red'}} {...props} />
组件中的键是你用 Markdown 编写的东西的 HTML 等价物(例如h1
for # heading
)†
†通常,在 Markdown 中,那些是:a
, blockquote
, code
, em
, h1
,
h2
, h3
, h4
, h5
, h6
, hr
, img
, li
, ol
, p
, pre
, strong
, 和
ul
。有了remark-gfm
,你也可以使用:del
,input
,table
,tbody
,
td
,th
,thead
,和tr
。添加对新结构的支持的其他备注或重新炒作插件也将与react-markdown
.
传递的道具可能是您所期望的a
:(链接)将获得href
(和title
)道具,以及img
(图像)和src
(和title
)等。还有一些额外的道具被传递。
inline
( boolean?
) — 设置true
为内联代码
className
( string?
) —language-js
使用时设置为```js
ordered
(boolean
) -父是否是ol
或不
checked
( boolean?
) —null
通常,boolean
当使用remark-gfm
的任务列表时
className
( string?
) —task-list-item
使用时设置为remark-gfm
,item1 为任务列表
ol
, ul
depth
( number
) — 祖先列表的数量(所以首先得到0
,等等)
ordered
(boolean
) -无论它是一个ol
与否
className
( string?
) —contains-task-list
使用时设置为remark-gfm
并且列表包含一个或多个任务列表
td
, th
(使用时remark-gfm
)
style
( Object?
) —{textAlign: 'left'}
取决于单元格的对齐方式
isHeader
(boolean
) -不管它是一个th
或不
tr
(使用时remark-gfm
)
isHeader
(boolean
) -无论是在thead
或不
每个组件都会收到一个node
( Object
)。这是原来的hast元素变成了 React 元素。
每个元素都会收到一个key
( string
)。有关更多信息,请参阅React 的文档。
可选地,组件还将收到:
data-sourcepos
( string
) — 见sourcePos
选项
sourcePosition
( Object
) — 见rawSourcePos
选项
index
和siblingCount
( number
) — 见includeElementIndex
选项
target
在a
( string
) — 见linkTarget
选项
react-markdown
默认情况下,使用是安全的。覆盖transformLinkUri
或transformImageUri
不安全的东西会让你面临 XSS 向量。此外,remarkPlugins
和rehypePlugins
你使用,components
你写的可能是不安全的。
为了确保内容是完全安全的,即使在插件做了什么之后,使用rehype-sanitize
. 该插件可让您定义自己的架构,允许和不允许的内容。
– JSX在降价
remark-gfm
— GitHub 风格的降价支持插件
请参阅contributing.md
中remarkjs/.github
的入门方法。查看support.md
获取帮助的方法。
这个项目有一个行为准则。通过与此存储库、组织或社区互动,您同意遵守其条款。
麻省理工学院© Espen Hovlandsdal
项目issue数量: 3
项目贡献人员列表:
johno wooorm
喜欢 (0)
express-useragent中文文档|express-useragent js中文教程|解析
gulp-replace-task中文文档|gulp-replace-task js中文教程|解析
react-intl-redux中文文档|react-intl-redux js中文教程|解析nunjucks-markdown中文文档|nunjucks-markdown js中文教程|解析detective-es6中文文档|detective-es6 js中文教程|解析teaspoon中文文档|teaspoon js中文教程|解析markit中文文档|markit js中文教程|解析ast-util中文文档|ast-util js中文教程|解析markdown-it-attrs中文文档|markdown-it-attrs js中文教程|解析griddle-react中文文档|griddle-react js中文教程|解析