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 解析器配置项。
'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
用于格式化日期、数字和无障碍标签的语言区域。:::
::::渲染效果
组件的可见标题。该值显示在页面头部,应足够简短以便快速扫读。
false控件是否初始为禁用状态。
'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`。:::
::::渲染效果
把数据值渲染为最终输出。回调应返回安全字符串,可使用 formatValue 辅助函数。
- 保持渲染确定性。
- 避免在回调内发起网络请求。
3请求被判定失败前的最大尝试次数。
为向后兼容保留。新接入应改用 compatibility。
独立字段
只记录一个选项时,可不包组直接在示例或代码块旁使用单字段。
写法
:::field{name="format"}@type `'short' | 'long'`@default `'short'`@optional
控制结果的格式化方式。:::渲染效果
'short'控制结果的格式化方式。
元数据标签速查
| 标签 | 作用 | 渲染表现 |
|---|---|---|
@type | 数据类型 | 代码令牌 |
@default | 默认取值 | 代码令牌 |
@required | 必填 | 状态徽标 |
@optional | 可选 | 状态徽标 |
@deprecated | 废弃 | 状态徽标 |
- 元数据之后的任何普通 Markdown 都会成为字段描述。
- 未知的
@标签会作为描述文本保留,而不是被丢弃。
Shirone 操作指南
连载中分享文章
生成精美分享图或复制链接,与更多人分享本文。
继续阅读
换条路线
从其他文章中稳定抽取