---
source_url: https://docs.dolphindb.cn/zh/funcs/s/stringFormat.html
fetched_at: 2026-05-19T09:40:42Z
category: funcs
title: stringFormat
sha1: a37b492a18b2c85d8891440f9a45c0f01a64e25d
---

# stringFormat

## 语法

`stringFormat(format, [args...])`

## 详情

对字符串进行格式化处理，即将用户传入的值按指定的格式进行处理后填充到字符串中。在占位符内部，可以通过格式符指定进制格式、字段宽度、精度、对齐方式等选项，以便对输出进行更精确的控制。

表一：占位符支持的数据类型列表

| 类型 | 占位符(%数据类型符号) | args 示例 |
| --- | --- | --- |
| BOOL | %b | 1b, 0b, true, false |
| CHAR | %c | 'a', 97c |
| SHORT | %h | 122h |
| 十进制整数（INT） | %i | 21 |
| 八进制整数 | %o | 31 |
| 十六进制整数（小写） | %x | 2f |
| 十六进制整数（大写） | %X | 2F |
| LONG | %l | 25l |
| DATE | %d | 2022.01.01 |
| MONTH | %M | 2022.05M |
| TIME | %t | 13:00:10.706 |
| MINUTE | %m | 13:30m |
| SECOND | %s | 13:30:10 |
| DATETIME | %D | 2012.06.13 13:30:10, 2012.06.13T13:30:10 |
| TIMESTAMP | %T | 2012.06.13 13:30:10.008, 2012.06.13T13:30:10.008 |
| NANOTIME | %n | 13:30:10.008007006 |
| NANOTIMESTAMP | %N | 2012.06.13 13:30:10.008007006, 2012.06.13T13:30:10.008007006 |
| FLOAT | %f | 2.1f |
| DOUBLE | %F | 2.1 |
| SYMBOL | %S | symbol(["aaa","bbb"]) |
| STRING | %W | "Hello" |
| ANY（元组） | %A | (1, 45, 'sah') |

注意：若字符串包含 "%" ，则须通过百分号进行转义，即写为 "%%" 。

在占位符内部（即在`%`与数据类型符号之间）插入一个或多个格式化操作符，对输出格式进行控制，书写形式为
`%[(var)][#][±][0][m/*][.][n/*]数据类型符号`。

表二：以小数点为分隔，下表解释小数点前的部分支持的符号：

| 符号 | 功能 | 用法示例 |
| --- | --- | --- |
| m （一个正整数） | 支持在 %f, %F, %W 中使用。- 当占位符类型是 f 或 F 时，表示输出字符串的**最小**总宽度，默认使用空格填充宽度。 当 m 小于浮点数实际位数时，输出完整的浮点数（保留至小数点后六位）；当 m 大于浮点数实际位数时，默认填充空格。- 当占位符类型是 W 时，表示输出字符串的**最小**位数：当 m 小于字符串长度时，输出完整的字符串；当 m 大于字符串长度时，默认填充空格。默认对齐方式为右对齐。 | `stringFormat("%10f", pi)`输出：`··3.141593` `stringFormat("%2f", 12345.0)`输出：`12345.000000``stringFormat("%10W", "6chars")`输出：`····6chars` |
| \* | 与 m 功能类似，通过参数（*args*）指定输出字符串的宽度。在对应的 *args* 中指定具体宽度数值，形式为一个元组：`(宽度值，格式化字符串)`。 | 定义宽度：`stringFormat("%*f", (10,pi))`输出：`··3.141593` |
| 0 | 当宽度不足时，在输出的字符串前填充“0”来实现指定宽度（左对齐时，从右边开始填充）。若不指定，则使用空格填充。 | `stringFormat("%010f", pi)`输出：`003.141593` |
| - | 左对齐，仅适用于数值类型。若不指定该符号，则默认为右对齐。 | `stringFormat("%-10.3f", pi)`输出：`3.142` |
| + | 在正数前显示加号（+）。 | `stringFormat('%+f', pi)`输出：`+3.141593` |
| (var) | 映射变量，var 只能是字典形式。不可与其他操作符混用。 | `employee = {"name":"Lisa Mill", "year":2010} stringFormat("%(name)W joined the company in %(year)i", employee)`输出：`Lisa Mill joined the company in 2010` |
| # | 在八进制数前显示 “0o”；在十六进制前显示 ”0x“ （当数据类型符号为 “x“时）或者 “0X”（当数据类型符号为 “X” 时）。 | `stringFormat("%#o", 33)`输出：`0o41``stringFormat("%#X", 33)`输出：`0X21` |

表三：小数点后的部分支持的符号（**仅支持在 %f, %F 和 %W 中使用**）：

| 符号 | 功能 | 用法示例 |
| --- | --- | --- |
| n（一个正整数） | - 当占位符类型是 f 或 F 时，表示小数点后保留位数。若 n 小于浮点数的小数位数，则会将浮点数四舍五入至指定位数；若该数字大于浮点数的小数位数，则会补零对齐。- 当占位符类型是 W 时，表示保留字符串位数。n 小于字符串长度时对字符串截断，大于字符串长度时不补充。 | `stringFormat("%10.5f", pi)`输出：`···3.14159` `stringFormat('%10.3f' , 3.1)`输出：`·····3.100``stringFormat("%2.10W", "6chars")`输出：`6chars` |
| \* | 与 n 功能类似，在对应的 *args* 中指定输出字符串的小数点后的位数，形式为一个元组：`([宽度], [精度值], 格式化字符串的值)`。 | 定义小数点后位数：`stringFormat("%.*f", (5,pi))`输出：`3.14159`同时定义宽度与小数点位数：`stringFormat("%0*.*f", (10,5,pi))`输出：`···3.14159` |

## 参数

**format** 包含0个或多个占位符的字符串。

**args...** 可选参数，1个或多个填入格式化字符串的值。若指定，则其数量和数据类型必须与 *format*
中的占位符的数量和类型一致。若不指定，则直接输出 *format*。

## 返回值

STRING 类型标量。

## 例子

```dolphindb
stringFormat("date: %d, time: %t", 2022.12.01, 10:12:45.065)
```

输出返回：date: 2022.12.01, time: 10:12:45.065

```dolphindb
stringFormat("Students account for %i%% of our customers.", 50)
```

输出返回：Students account for 50% of our customers.

```dolphindb
t = datetime(now())
stringFormat("The current time is %D.", t)
```

输出返回：The current time is 2023.01.02T20:36:03.

```dolphindb
a = 7.596
stringFormat("%-+10.5f", a)
```

输出返回：+7.59600

```dolphindb
stringFormat("%010.3f", a)
```

输出返回：000007.596

```dolphindb
product = {"item":"Eggs", "price_per_unit":2}
stringFormat("%(item)W: $ %(price_per_unit)i", product)
```

输出返回：Eggs: $ 2
