【241216】What I have learnt today

I. val annotatedString = buildAnnotatedString { }

buildAnnotatedString is a function provided by Kotlin to build an AnnotatedString object.
val annotatedString is not defining a function, but defining an immutable variable whose value is built by buildAnnotatedString.
Explain the role of buildAnnotatedString:
buildAnnotatedString is a DSL (domain-specific language) function that can build an AnnotatedString containing text, style, and tags with concise code.
The code in curly braces { } is used to gradually add content, style, and tags.

For example:
val annotatedString = buildAnnotatedString {
append("Normal text ")
withStyle(style = SpanStyle(color = Color.Blue)) {
append("Blue text ")
}
pushStringAnnotation(tag = "URL", annotation = "https://example.com")
append("Clickable text")
pop()
}

val annotatedString = buildAnnotatedString { } 
buildAnnotatedString 是一个 Kotlin 提供的函数，用来构建一个 AnnotatedString 对象。
val annotatedString 并不是在定义一个函数，而是在定义一个不可变变量，其值是由 buildAnnotatedString 构建出来的。
解释一下 buildAnnotatedString 的作用：
buildAnnotatedString 是一个DSL（领域特定语言）函数，可以用简洁的代码构建一个包含文本、样式和标记的 AnnotatedString。
大括号 { } 里的代码，是用来逐步添加内容、样式和标记的。
举个例子：
val annotatedString = buildAnnotatedString {
    append("普通文本 ")
    withStyle(style = SpanStyle(color = Color.Blue)) {
        append("蓝色文本 ")
    }
    pushStringAnnotation(tag = "URL", annotation = "https://example.com")
    append("可点击的文本")
    pop()
}

II.offset 

offset is a parameter in the onClick callback function, representing the index of the click position in the string.
When the user clicks a character in ClickableText, offset returns the position of the character (counting from 0).
Example:
Assume the string is Hello World:
If the letter W is clicked, then offset = 6 (index starts from 0).
For example:
ClickableText(
text = annotatedString,
onClick = { offset ->
println("Click position is: $offset")
}
)
Click the first character of clickable text, and the index position of the click will be output.

offset 是 onClick 回调函数中的参数，代表点击位置在字符串中的索引。
当用户点击 ClickableText 中的某个字符时，offset 会返回该字符的位置（从 0 开始计数）。
示例说明：
假设字符串是 Hello World：
如果点击了字母 W，那么 offset = 6（索引从 0 开始）。
举个例子：
ClickableText(
    text = annotatedString,
    onClick = { offset ->
        println("点击位置是：$offset")
    }
)
点击 可点击的文本 的第一个字符，就会输出点击的索引位置。

III.annotatedString.getStringAnnotations(tag = "URL", start = offset, end = offset)

Method analysis:
getStringAnnotations is a method of AnnotatedString, which is used to get the annotation at a specified position.
Parameter description:
tag: the name of the tag (for example, "URL").
start and end: the text range to be searched.
Here, start = offset and end = offset mean checking the position of a single character.
How it works:
You added a tag in buildAnnotatedString:
pushStringAnnotation(tag = "URL", annotation = "https://example.com")
append("Clickable text")

annotatedString.getStringAnnotations(tag = "URL", start = offset, end = offset)
方法解析：
getStringAnnotations 是 AnnotatedString 的一个方法，用来获取指定位置的标记（Annotation）。
参数说明：
tag：标记的名称（例如 "URL"）。
start 和 end：要搜索的文本范围。
在这里，start = offset 和 end = offset 表示检查单个字符所在的位置。
它的工作原理：
你在 buildAnnotatedString 中添加了一个标记：
pushStringAnnotation(tag = "URL", annotation = "https://example.com")
append("可点击的文本")
 

IV.What does firstOrNull() mean?

getStringAnnotations returns a list because there may be multiple tags at the same position.
firstOrNull() takes the first element in the list (if it exists).
If the list is empty (i.e. no tags are found), it returns null.

firstOrNull() 是什么意思？
getStringAnnotations 返回的是一个列表，因为同一个位置可能存在多个标记。
firstOrNull() 取出列表中的第一个元素（如果存在）。
如果列表为空（即没有找到任何标记），返回 null。

V.What does let { ... } mean?

let is a Kotlin safe call operator that prevents null from causing exceptions.
If firstOrNull() returns a non-null object, the code block in let will be executed.
Inside let, annotation represents the found tag object.

let { ... } 是什么意思？
let 是 Kotlin 的安全调用操作符，避免 null 引发异常。
如果 firstOrNull() 返回了非空的对象，let 中的代码块就会执行。
在 let 内部，annotation 表示找到的标记对象。

VI.

annotatedString.getStringAnnotations(tag = "URL", start = offset, end = offset)
    .firstOrNull()?.let { annotation ->
        println("点击的链接是：${annotation.item}")
    }

Execution steps: Find the tag tag = "URL" at the clicked character position (offset).
If there is a tag at that position, return a list of tags.
Take the first tag from the tag list.
If there is no tag, return null.
If the tag is found, execute the code in let.
annotation.item represents the data attached to the tag (here, https://example.com).
Print the link attached to the tag.

执行步骤：在点击的字符位置（offset）查找标记 tag = "URL"。如果该位置存在标记，返回标记的列表。从标记列表中取第一个标记。如果没有标记，返回 null。如果找到了标记，执行 let 中的代码。annotation.item 表示标记附带的数据（在这里是 https://example.com）。打印出标记中附带的链接。