#自定义配置

本页列出 Fluxdown 的公开属性。除 text 外，顶层属性均可省略；类型 BaseBuildConfig、StreamingConfig、Theme、IPluginItem 和 FluxdownRef 都可从 fluxdown 导入。

#text 必选

类型： string

当前完整的 Markdown。收到新片段时，传入累积后的内容；不要只传最后一个片段。

<Fluxdown text="# 你好，Fluxdown" />

#streaming 可选

类型： boolean | StreamingConfig

默认值： false

true 同时开启末尾修复、平滑输出和末尾渐变；false 关闭这三项。传对象可以分别控制，对象中省略的字段默认为 true。

<Fluxdown
  streaming={{
    repairEnding: true,
    smooth: true,
    shad: false,
  }}
  text={text}
/>

连接数据源与结束流的完整过程见流式内容。

#streaming.repairEnding 可选

类型： boolean

默认值： true（streaming 为对象时）

修复仍在生成的末尾语法。设置为 false 时，只关闭末尾修复；build.repair: false 则关闭全部修复。

#streaming.smooth 可选

类型： boolean | SmoothConfig

默认值： true（streaming 为对象时）

让新增内容逐步显示。true 使用内置弹簧调度，并自动选择可用的时钟；false 直接显示已收到的内容。传对象可以指定时钟和调度方式：

<Fluxdown
  streaming={{
    smooth: {
      enabled: true,
      ticker: 'raf',
      scheduler: 'spring',
    },
  }}
  text={text}
/>

#smooth.enabled 可选

类型： boolean

默认值： false

使用 smooth 对象时，显式设为 true 开启平滑输出。关闭后会立即显示当前已收到的内容。

#smooth.ticker 必选

类型： 'raf' | 'interval' | SmoothTickerClass

选择输出节奏的时钟：'raf' 跟随动画帧，'interval' 使用定时器，也可以传自定义时钟类。

#smooth.scheduler 必选

类型： 'spring' | SmoothSchedulerClass

决定每次更新显示多少内容。'spring' 使用内置弹簧调度，也可以传自定义调度类。

通常直接使用 smooth: true 即可。SmoothConfig、SmoothTickerClass 和 SmoothSchedulerClass 从 @fluxdown/core-presets/mapper 导入。

#streaming.shad 可选

类型： boolean | ShadConfig

默认值： true（streaming 为对象时）

为新出现的末尾文字添加渐变。true 使用默认效果，false 关闭效果；传对象可以调整参与渐变的字符数和遮罩宽度：

<Fluxdown
  streaming={{
    shad: {
      enabled: true,
      length: 3,
      maskWidth: 18,
    },
  }}
  text={text}
/>

#shad.enabled 可选

类型： boolean

默认值： true

是否开启末尾渐变。

#shad.length 可选

类型： number

默认值： 2

参与渐变的末尾字符数。小数向下取整，负数和非有限值按 0 处理。

#shad.maskWidth 可选

类型： number

默认值： 15

渐变遮罩宽度，单位为像素。0 隐藏遮罩，负数按 0 处理，非有限值使用默认宽度。

#build 可选

类型： BaseBuildConfig

默认值： {}

选择 Markdown 编译能力。表格、任务列表、删除线、自动链接和普通换行默认可用，以下字段均可省略。

<Fluxdown
  build={{
    tex: true,
    footnote: true,
  }}
  text={text}
/>

Markdown 内的 HTML 会经过标签检查与清理，默认允许 span、u、br、em 和 a。调整方式见 Rehype 插件。

#build.repair 可选

类型： boolean

默认值： true

是否启用语法修复。false 关闭整组修复；仅控制流式末尾时，使用 streaming.repairEnding。

#build.footnote 可选

类型： boolean

默认值： false

是否解析脚注语法，并生成引用与回跳链接。

#build.tex 可选

类型： boolean

默认值： false

是否解析行内与块级公式语法。开启后，内置渲染器会加载公式渲染能力。

#build.indentedCode 可选

类型： boolean

默认值： false

是否解析缩进代码块语法。围栏代码块无需开启此项。

#build.setextHeading 可选

类型： boolean

默认值： false

是否解析用 === 或 --- 作下划线的标题语法。以 # 开头的标题不受影响。

#build.idPrefix 可选

类型： string

默认值： 自动生成

为脚注 ID 指定命名空间。

通常无需设置 idPrefix。手动设置时，应为页面上的不同实例提供不同值，避免脚注链接指向其他内容。

#theme 可选

类型： Theme

默认值： 'light'

支持三种形式：

• 'light' 或 'dark'：使用内置主题。
• PartialThemeConfig：在浅色主题上覆盖需要的 token。
• ['light' | 'dark', PartialThemeConfig]：在指定主题上覆盖 token。

<Fluxdown
  theme={[
    'dark',
    {
      tokens: {
        colors: { accent: '#82d8cf' },
        typography: { fontSans: 'Inter, sans-serif' },
      },
    },
  ]}
  text={text}
/>

tokens 的各组配置都支持局部覆盖：

完整 token 类型为 ThemeTokens，同样从 fluxdown 导入。搭配产品主题的例子见样式指南。

#plugins 可选

类型： IPluginItem | IPluginItem[]

默认值： []

一个对象表示一个插件包；数组组合多个插件包。每个包可以提供以下列表：

列表项可以是插件本身，也可以是 [插件, 选项]。使用 config 时，不需要把选项重复写进各个列表项：

import { CodeHeaderSlotPlugin } from '@fluxdown/react-presets/slot';
import { Fluxdown } from 'fluxdown';

<Fluxdown
  plugins={{
    slots: [CodeHeaderSlotPlugin],
    config: {
      'slot-code-header': { disabled: true },
    },
  }}
  text={text}
/>;

这个例子关闭默认代码工具栏。插件选项中的 disabled: true 可停用插件；priority 设置执行顺序，数值越小越早执行。

config 属于插件包，作用于同一个包里明确列出的插件。其他预设会继续保留。

声明、组合和配置示例见使用与编写插件。

#patches 可选

类型： IPatchItem<ReactNode>[]

默认值： []

用自己的 React 内容替换指定文本，或在某个位置插入内容。适合把提及、引用等文本变成可交互元素。

<Fluxdown
  patches={[
    {
      key: 'person-ada',
      range: [3, 7],
      render: () => <a href="/people/ada">@Ada</a>,
    },
  ]}
  text="欢迎，@Ada。"
/>

#patches[].key 可选

类型： string

默认值： undefined

补丁的稳定标识。

#patches[].range 必选

类型： number | [number, number]

单个数字表示在该位置插入内容；区间表示替换内容，包含起点、不包含终点。

位置按原始字符串索引计算。区间需要落在同一个内容块内，避免跨段落或相互重叠。

#patches[].render 必选

类型： (text?: string) => ReactNode

返回插入或替换的内容，也可以通过 text 读取被替换的文本。

#className 可选

类型： string

默认值： undefined

添加到最外层容器的类名，用于接入应用样式。

<Fluxdown className="conversation-message" text={text} />

#style 可选

类型： CSSProperties

默认值： undefined

最外层容器的 React 内联样式。常用于宽度、布局和与父容器的间距：

<Fluxdown
  style={{
    maxWidth: '72ch',
    marginInline: 'auto',
  }}
  text={text}
/>

内容内部的排版优先使用 theme，组件与交互调整使用插件。

#ref 可选

类型： Ref<FluxdownRef>

默认值： undefined

读取渲染结果的响应式句柄。FluxdownRef 是 IReadableClosure<ReactNode[]>；其 value 提供当前内容与订阅能力，不是 DOM 元素。

import type { FluxdownRef } from 'fluxdown';

import { Fluxdown } from 'fluxdown';
import { useRef } from 'react';

type MessageProps = {
  text: string;
};

export function Message({ text }: MessageProps) {
  const content = useRef<FluxdownRef>(null);

  return <Fluxdown ref={content} text={text} />;
}

普通展示无需使用 ref。Fluxdown 会管理句柄的生命周期；自己建立的订阅需要取消。