factories

feishu.cards.factories

text_card

Python

text_card(content: str, title: str | None = None, template: str = 'blue') -> dict[str, Any]

构造仅含一个 markdown 元素的卡片，并在提供 title 时附带标题栏。

参数：

名称	类型	描述	默认
content	str	markdown 正文内容。	必需
title	str | None	标题栏文案；为 None 时不生成标题栏。	None
template	str	标题栏颜色主题，会经 feishu.cards.validation.validate_template 校验。	'blue'

返回：

类型	描述
dict[str, Any]	卡片 2.0 的字典表示。

飞书文档

卡片 JSON 2.0 结构

示例：

>>> d = text_card("hello", title="Greeting", template="green")
>>> d["header"]["title"], d["header"]["template"]
({'tag': 'plain_text', 'content': 'Greeting'}, 'green')
>>> d["body"]["elements"]
[{'tag': 'markdown', 'content': 'hello'}]
>>> "header" in text_card("hello")
False

源代码位于： feishu/cards/factories.py

def text_card(content: str, title: str | None = None, template: str = "blue") -> dict[str, Any]:
    r"""
    构造仅含一个 markdown 元素的卡片，并在提供 `title` 时附带标题栏。

    Args:
        content: markdown 正文内容。
        title: 标题栏文案；为 `None` 时不生成标题栏。
        template: 标题栏颜色主题，会经 [feishu.cards.validation.validate_template][] 校验。

    Returns:
        卡片 2.0 的字典表示。

    飞书文档:
        [卡片 JSON 2.0 结构](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-structure)

    Examples:
        >>> d = text_card("hello", title="Greeting", template="green")
        >>> d["header"]["title"], d["header"]["template"]
        ({'tag': 'plain_text', 'content': 'Greeting'}, 'green')
        >>> d["body"]["elements"]
        [{'tag': 'markdown', 'content': 'hello'}]
        >>> "header" in text_card("hello")
        False
    """
    card = Card()
    if title is not None:
        card.header(title, template=template)
    card.markdown(content)
    return card.to_dict()

alert_card

Python

alert_card(content: str, title: str, template: str = 'red', buttons: list[dict[str, Any]] | None = None) -> dict[str, Any]

构造含标题栏、markdown 正文，以及可选按钮的告警卡片。

参数：

名称	类型	描述	默认
content	str	markdown 正文内容。	必需
title	str	标题栏文案。	必需
template	str	标题栏颜色主题，默认 red，会经 feishu.cards.validation.validate_template 校验。	'red'
buttons	list[dict[str, Any]] | None	预先构造好的按钮元素列表（如由 feishu.cards.elements.button 生成），依次追加到正文之后。	None

返回：

类型	描述
dict[str, Any]	卡片 2.0 的字典表示。

飞书文档

卡片 JSON 2.0 结构

示例：

>>> from feishu.cards.elements import button
>>> d = alert_card("Heads up", title="Alert", buttons=[button("OK", value={"d": "y"})])
>>> d["header"]["template"]
'red'
>>> [e["tag"] for e in d["body"]["elements"]]
['markdown', 'button']

源代码位于： feishu/cards/factories.py

def alert_card(
    content: str,
    title: str,
    template: str = "red",
    buttons: list[dict[str, Any]] | None = None,
) -> dict[str, Any]:
    r"""
    构造含标题栏、markdown 正文，以及可选按钮的告警卡片。

    Args:
        content: markdown 正文内容。
        title: 标题栏文案。
        template: 标题栏颜色主题，默认 `red`，会经 [feishu.cards.validation.validate_template][] 校验。
        buttons: 预先构造好的按钮元素列表（如由 [feishu.cards.elements.button][] 生成），依次追加到正文之后。

    Returns:
        卡片 2.0 的字典表示。

    飞书文档:
        [卡片 JSON 2.0 结构](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-structure)

    Examples:
        >>> from feishu.cards.elements import button
        >>> d = alert_card("Heads up", title="Alert", buttons=[button("OK", value={"d": "y"})])
        >>> d["header"]["template"]
        'red'
        >>> [e["tag"] for e in d["body"]["elements"]]
        ['markdown', 'button']
    """
    card = Card().header(title, template=template).markdown(content)
    for btn in buttons or []:
        card.add(btn)
    return card.to_dict()

table_card

Python

table_card(headers: list[str], rows: list[list[Any]], title: str | None = None) -> dict[str, Any]

将表头与数据行渲染为 GFM markdown 表格，置于单个 markdown 元素中。

采用稳妥的 markdown 表格实现，而非卡片 2.0 原生 table 组件。单元格中的竖线 | 会被转义，换行符会折叠为空格，以免破坏表格结构。

参数：

名称	类型	描述	默认
headers	list[str]	表头文案列表。	必需
rows	list[list[Any]]	数据行列表，每一行的单元格数必须与 headers 等长。	必需
title	str | None	标题栏文案；为 None 时不生成标题栏。	None

返回：

类型	描述
dict[str, Any]	卡片 2.0 的字典表示。

引发：

类型	描述
ValueError	当某一行的单元格数与 headers 长度不一致时抛出。

飞书文档

富文本组件

示例：

>>> d = table_card(["Name", "Age"], [["Alice", 30], ["Bob", 25]])
>>> print(d["body"]["elements"][0]["content"])
| Name | Age |
| --- | --- |
| Alice | 30 |
| Bob | 25 |
>>> table_card(["A", "B"], [["only-one"]])
Traceback (most recent call last):
...
ValueError: table_card row 0 has 1 cells, expected 2

源代码位于： feishu/cards/factories.py

def table_card(
    headers: list[str],
    rows: list[list[Any]],
    title: str | None = None,
) -> dict[str, Any]:
    r"""
    将表头与数据行渲染为 GFM markdown 表格，置于单个 markdown 元素中。

    采用稳妥的 markdown 表格实现，而非卡片 2.0 原生 `table` 组件。单元格中的竖线 `|`
    会被转义，换行符会折叠为空格，以免破坏表格结构。

    Args:
        headers: 表头文案列表。
        rows: 数据行列表，每一行的单元格数必须与 `headers` 等长。
        title: 标题栏文案；为 `None` 时不生成标题栏。

    Returns:
        卡片 2.0 的字典表示。

    Raises:
        ValueError: 当某一行的单元格数与 `headers` 长度不一致时抛出。

    飞书文档:
        [富文本组件](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-components/content-components/rich-text)

    Examples:
        >>> d = table_card(["Name", "Age"], [["Alice", 30], ["Bob", 25]])
        >>> print(d["body"]["elements"][0]["content"])
        | Name | Age |
        | --- | --- |
        | Alice | 30 |
        | Bob | 25 |
        >>> table_card(["A", "B"], [["only-one"]])
        Traceback (most recent call last):
        ...
        ValueError: table_card row 0 has 1 cells, expected 2
    """
    card = Card()
    if title is not None:
        card.header(title)
    card.markdown(_gfm_table(headers, rows))
    return card.to_dict()