validation

feishu.cards.validation

validate_element_id

Python

validate_element_id(element_id: str) -> str

校验卡片元素的 element_id，合法则原样返回。

规则：长度不超过 20 个字符，以 ASCII 字母开头，其余字符仅可为 [A-Za-z0-9_]。

参数：

名称	类型	描述	默认
element_id	str	待校验的元素 ID。	必需

返回：

类型	描述
str	校验通过的元素 ID（即传入值本身）。

引发：

类型	描述
ValueError	当 element_id 不符合命名规则时抛出。

飞书文档

卡片 JSON 2.0 结构

示例：

>>> validate_element_id("Title_1")
'Title_1'
>>> validate_element_id("1bad")
Traceback (most recent call last):
...
ValueError: invalid element_id '1bad': must be <=20 chars, start with a letter, and contain only [A-Za-z0-9_]

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

def validate_element_id(element_id: str) -> str:
    r"""
    校验卡片元素的 `element_id`，合法则原样返回。

    规则：长度不超过 20 个字符，以 ASCII 字母开头，其余字符仅可为 `[A-Za-z0-9_]`。

    Args:
        element_id: 待校验的元素 ID。

    Returns:
        校验通过的元素 ID（即传入值本身）。

    Raises:
        ValueError: 当 `element_id` 不符合命名规则时抛出。

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

    Examples:
        >>> validate_element_id("Title_1")
        'Title_1'
        >>> validate_element_id("1bad")
        Traceback (most recent call last):
        ...
        ValueError: invalid element_id '1bad': must be <=20 chars, start with a letter, and contain only [A-Za-z0-9_]
    """
    if not _ELEMENT_ID_RE.match(element_id):
        raise ValueError(
            f"invalid element_id {element_id!r}: must be <=20 chars, start with a "
            f"letter, and contain only [A-Za-z0-9_]"
        )
    return element_id

validate_template

Python

validate_template(template: str) -> str

校验卡片标题栏的颜色主题，合法则原样返回。

取值须为已确认的枚举之一（见 [feishu.cards.validation.HEADER_TEMPLATES][]）。

参数：

名称	类型	描述	默认
template	str	待校验的标题栏颜色主题。	必需

返回：

类型	描述
str	校验通过的颜色主题（即传入值本身）。

引发：

类型	描述
ValueError	当 template 不在已确认的枚举范围内时抛出。

飞书文档

标题组件

示例：

>>> validate_template("blue")
'blue'
>>> try:
...     validate_template("rainbow")
... except ValueError as exc:
...     print(str(exc).startswith("invalid header template 'rainbow'"))
True

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

def validate_template(template: str) -> str:
    r"""
    校验卡片标题栏的颜色主题，合法则原样返回。

    取值须为已确认的枚举之一（见 [feishu.cards.validation.HEADER_TEMPLATES][]）。

    Args:
        template: 待校验的标题栏颜色主题。

    Returns:
        校验通过的颜色主题（即传入值本身）。

    Raises:
        ValueError: 当 `template` 不在已确认的枚举范围内时抛出。

    飞书文档:
        [标题组件](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-components/containers/title)

    Examples:
        >>> validate_template("blue")
        'blue'
        >>> try:
        ...     validate_template("rainbow")
        ... except ValueError as exc:
        ...     print(str(exc).startswith("invalid header template 'rainbow'"))
        True
    """
    if template not in HEADER_TEMPLATES:
        raise ValueError(f"invalid header template {template!r}: expected one of {sorted(HEADER_TEMPLATES)}")
    return template

clamp_spacing

Python

clamp_spacing(value: int) -> int

将间距/边距整数裁剪到文档约定的 [-99, 99] 区间内。

参数：

名称	类型	描述	默认
value	int	待裁剪的间距整数。	必需

返回：

类型	描述
int	裁剪到 [-99, 99] 区间后的整数。

引发：

类型	描述
TypeError	当 value 不是 int（或为 bool）时抛出。

飞书文档

布局组件

示例：

>>> clamp_spacing(50)
50
>>> clamp_spacing(200)
99
>>> clamp_spacing(-100)
-99

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

def clamp_spacing(value: int) -> int:
    r"""
    将间距/边距整数裁剪到文档约定的 `[-99, 99]` 区间内。

    Args:
        value: 待裁剪的间距整数。

    Returns:
        裁剪到 `[-99, 99]` 区间后的整数。

    Raises:
        TypeError: 当 `value` 不是 `int`（或为 `bool`）时抛出。

    飞书文档:
        [布局组件](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-json-v2-components/containers/column-set)

    Examples:
        >>> clamp_spacing(50)
        50
        >>> clamp_spacing(200)
        99
        >>> clamp_spacing(-100)
        -99
    """
    if isinstance(value, bool) or not isinstance(value, int):
        raise TypeError(f"spacing must be an int, got {type(value).__name__}")
    return max(_SPACING_MIN, min(_SPACING_MAX, value))