701 字
4 分钟
Markdown 字段卡片

当若干相关选项同属一个 API 或组件时,用 field-group 把它们排成整齐的卡片。每个示例下面都先给写法(源码),再给渲染效果。

基础组合#

写法

::::field-group
:::field{name="tex"}
@type object
@optional
TeX 解析器配置项。
:::
:::field{name="output"}
@type `'svg' | 'chtml'`
@default `'svg'`
@optional
输出格式,SVG 或通用 HTML。
:::
::::

渲染效果

tex可选object

TeX 解析器配置项。

output可选'svg' | 'chtml'
'svg'

输出格式,SVG 或通用 HTML。

必填 / 可选 / 废弃状态#

必填、可选、废弃状态可混在同一组。默认值与类型分开标注,便于快速扫读。

写法

::::field-group
:::field{name="title"}
@type string
@required
组件的可见标题。该值显示在页面头部,应足够简短以便快速扫读。
:::
:::field{name="disabled"}
@type boolean
@default `false`
@optional
控件是否初始为禁用状态。
:::
:::field{name="locale"}
@type `'en' | 'zh-CN' | 'ja-JP'`
@default `'en'`
@optional
用于格式化日期、数字和无障碍标签的语言区域。
:::
::::

渲染效果

title必填string

组件的可见标题。该值显示在页面头部,应足够简短以便快速扫读。

disabled可选boolean
false

控件是否初始为禁用状态。

locale可选'en' | 'zh-CN' | 'ja-JP'
'en'

用于格式化日期、数字和无障碍标签的语言区域。

富文本描述#

描述是普通 Markdown。元数据行之后仍可用链接、强调、列表和行内代码。

写法

::::field-group
:::field{name="render"}
@type `(value: unknown) => string`
@required
把数据值渲染为最终输出。回调应返回**安全字符串**,可使用 `formatValue` 辅助函数。
- 保持渲染确定性。
- 避免在回调内发起网络请求。
:::
:::field{name="retries"}
@type number
@default `3`
@optional
请求被判定失败前的最大尝试次数。
:::
:::field{name="legacyMode"}
@type boolean
@deprecated
为向后兼容保留。新接入应改用 `compatibility`。
:::
::::

渲染效果

render必填(value: unknown) => string

把数据值渲染为最终输出。回调应返回安全字符串,可使用 formatValue 辅助函数。

  • 保持渲染确定性。
  • 避免在回调内发起网络请求。
retries可选number
3

请求被判定失败前的最大尝试次数。

legacyMode已弃用boolean

为向后兼容保留。新接入应改用 compatibility。

独立字段#

只记录一个选项时,可不包组直接在示例或代码块旁使用单字段。

写法

:::field{name="format"}
@type `'short' | 'long'`
@default `'short'`
@optional
控制结果的格式化方式。
:::

渲染效果

format可选'short' | 'long'
'short'

控制结果的格式化方式。

元数据标签速查#

标签作用渲染表现
@type数据类型代码令牌
@default默认取值代码令牌
@required必填状态徽标
@optional可选状态徽标
@deprecated废弃状态徽标
  • 元数据之后的任何普通 Markdown 都会成为字段描述。
  • 未知的 @标签 会作为描述文本保留,而不是被丢弃。

第 7 篇,共 20 篇本文属于系列

分享文章

生成精美分享图或复制链接,与更多人分享本文。

继续阅读

沿着主题读

基于共同的标签与分类

换条路线

从其他文章中稳定抽取