Android

This is the core dependency for the Android platform. When using PanguText on Android, you need to include this module.

Configure Dependency

You can add this module to your project using the following method.

SweetDependency (Recommended)

Add dependency in your project's SweetDependency configuration file.

libraries:
+  com.highcapable.pangutext:
+    pangutext-android:
+      version: +
+

Configure dependency in your project's build.gradle.kts.

implementation(com.highcapable.pangutext.pangutext.android)
+

Version Catalog

Add dependency in your project's gradle/libs.versions.toml.

[versions]
+pangutext-android = "<version>"
+
+[libraries]
+pangutext-android = { module = "com.highcapable.pangutext:pangutext-android", version.ref = "pangutext-android" }
+

Configure dependency in your project's build.gradle.kts.

implementation(libs.pangutext.android)
+

Please change <version> to the version displayed at the top of this document.

Traditional Method

Configure dependency in your project's build.gradle.kts.

implementation("com.highcapable.pangutext:pangutext-android:<version>")
+

Please change <version> to the version displayed at the top of this document.

Function Introduction

You can view the KDoc click hereopen in new window.

Implementation Principle

PanguText provides two methods for text formatting on the Android platform: SpannableString (does not alter the original text length) and direct insertion of whitespace characters (alters the original text length).

The first method, SpannableString, adds a Span with spacing to the character before the one that needs spacing, changing the text style without altering the string content. The rendering is done by the TextView layer (or manually using TextPaint based on Spanned for layout styling), achieving non-intrusive text styling.

This method also supports processing already styled text (Spanned), such as text created via Html.fromHtml.

However, it is currently experimental and may still have unexpected style errors. You can refer to the Personalized Configuration section below to disable it.

The dynamic application (injection) feature mainly targets the input state of EditText. It sets a custom TextWatcher for EditText to monitor input changes and formats the text from afterTextChanged.

The second method directly inserts whitespace characters after the characters that need spacing. This method alters the original text length and content but does not rely on the TextView layer for rendering. It uses TextPaint to draw the text directly, suitable for all scenarios, but does not support dynamic application (injection).

Unresolved Issues

PanguText may conflict with Material components like TextInputEditText, MaterialAutoCompleteTextView, and TextInputLayout when using setHint, as TextView does not account for Span during measurement. This issue is particularly noticeable in single-line text, and there is no solution yet. Use these components cautiously.

Due to the above issue, calculating the width of a TextView with PanguText style using the View.measure method may also result in errors.

PanguText currently cannot handle continuous characters like underlines or strikethroughs in Spanned text, as the lines will break after adding spacing. It may also cause style errors or fail to apply styles correctly to some special characters. For stability, avoid enabling PanguText for very complex rich text or refer to the Personalized Configuration section to set excludePatterns.

Integrate into Existing Projects

Integrating PanguText into your current project is very easy. You don't need to change much code. Choose your preferred method below to complete the integration.

Inject to LayoutInflater

PanguText supports direct injection of LayoutInflater.Factory2 or creating a LayoutInflater.Factory2 instance for the current Activity to take over the entire view layout inflation. This is the recommended integration method, as it allows for non-intrusive and quick integration without modifying any existing layouts.

The following example

class MainActivity : AppCompatActivity() {
+
+    val binding by lazy { ActivityMainBinding.inflate(layoutInflater) }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        // Inject here.
+        PanguTextFactory2.inject(this)
+        setContentView(binding.root)
+    }
+}
+

Tips

Since LayoutInflater.Factory2 is taken over, recycled layouts like ListView and RecyclerView can also be correctly handled.

After injecting the LayoutInflater instance in the Activity, the following instances attached to the current Context will automatically take effect:

Fragment
Dialog
PopupWindow
Toast (foreground only in higher system versions)

Layouts based on RemoteView will not take effect because they are remote objects and do not use the current Context's LayoutInflater for layout inflation.

If you are using ui-component → AppBindingActivityopen in new window in BetterAndroid, you need to slightly modify the current code.

The following example

class MainActivity : AppBindingActivity<ActivityMainBinding>() {
+
+    override fun onPrepareContentView(savedInstanceState: Bundle?): LayoutInflater {
+        val inflater = super.onPrepareContentView(savedInstanceState)
+        // Inject here.
+        PanguTextFactory2.inject(inflater)
+        return inflater
+    }
+  
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        // Your code here.
+    }
+}
+

If your application does not use AppCompatActivity or ViewBinding, don't worry, you can still use the original method.

The following example

class MainActivity : Activity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        // Inject here.
+        PanguTextFactory2.inject(this)
+        setContentView(R.layout.activity_main)
+    }
+}
+

Tips

PanguTextFactory2 can be used not only with Activity but also injected into any existing LayoutInflater instance. However, please inject it before the LayoutInflater instance is used to inflate the layout, otherwise it will not take effect.

Using the Patching Tool

You can use PanguTextPatcher to patch existing View or ViewGroup instances.

Patch the entire root layout, and PanguTextPatcher will automatically patch all TextView instances or their subclasses under the root layout.

The following example

// Assume you have a root layout.
+val root: ViewGroup
+// Patch the root layout.
+PanguTextPatcher.patch(root)
+

Patch a single View, which is of type TextView or a subclass of TextView.

The following example

// Assume this is your TextView.
+val textView: TextView
+// Patch a single View.
+PanguTextPatcher.patch(textView)
+

Notice

When using PanguTextPatcher in recycled layouts such as RecyclerView, ListView, or ViewPager, you need to patch the itemView in onCreateViewHolder or onBindViewHolder, otherwise it will not take effect.

Manual Injection or Text Formatting

PanguText also supports manual injection, allowing you to inject it into the desired TextView or EditText.

The following example

// Assume this is your TextView.
+val textView: TextView
+// Assume this is your EditText.
+val editText: EditText
+// Inject into existing text.
+textView.injectPanguText()
+editText.injectPanguText()
+// Optionally choose whether to inject Hint (default is true).
+textView.injectPanguText(injectHint = false)
+editText.injectPanguText(injectHint = false)
+// Dynamic injection, re-calling setText will automatically take effect.
+textView.injectRealTimePanguText()
+// Dynamic injection mainly targets the input state of EditText.
+editText.injectRealTimePanguText()
+// Optionally choose whether to inject Hint (default is true).
+textView.injectRealTimePanguText(injectHint = false)
+editText.injectRealTimePanguText(injectHint = false)
+

PanguText also extends the setText method of TextView, allowing you to directly set text with PanguText style.

The following example

// Assume this is your TextView.
+val textView: TextView
+// Set text with PanguText style.
+textView.setTextWithPangu("Xiaoming今年16岁")
+// Set Hint with PanguText style.
+textView.setHintWithPangu("输入Xiaoming的年龄")
+

You can also use the PanguText.format method to directly format text.

The following example

// Assume this is your TextView.
+val textView: TextView
+// Format text using SpannableString method.
+// Requires passing the current TextView's Resources and text size.
+// If the input text is already Spannable,
+// it will return the original object without creating a new SpannableString.
+val text = PanguText.format(textView.resources, textView.textSize, "Xiaoming今年16岁")
+// Set text.
+textView.text = text
+// Directly format text using whitespace characters for insertion.
+// This method adds extra whitespace characters " " (HSP) to the text.
+// The result below will output the string "Xiaoming 今年 16 岁".
+// You can also customize the whitespace character at the end of the method.
+val text = PanguText.format("Xiaoming今年16岁")
+// Set text.
+textView.text = text
+

Tips

The injectPanguText, injectRealTimePanguText, setTextWithPangu, setHintWithPangu, and PanguText.format methods support the config parameter. You can refer to the Personalized Configuration section below.

Custom View

PanguText can also be used with custom View. You can extend your View to AppCompatTextView and override the setText method.

The following example

class MyTextView(context: Context, attrs: AttributeSet? = null) : AppCompatTextView(context, attrs) {
+
+    override fun setText(text: CharSequence?, type: BufferType?) {
+        // Manually inject here.
+        val panguText = text?.let { PanguText.format(resources, textSize, it) }
+        super.setText(panguText, type)
+    }
+}
+

Notice

After injecting PanguText into TextView, if you use android:singleLine="true" in XML layout or TextView.setSingleLine(true) in code along with android:ellipsize="...", this method of setting single-line text may cause unresolvable OBJ characters (truncated by ellipsis) to appear when the text exceeds the screen width, because TextView does not account for Span during measurement, leading to incorrect text width calculation.

The solution is to use android:maxLines="1" in XML layout or TextView.setMaxLines(1) in code instead.

The following example

<TextView
+    android:id="@+id/text"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    android:text="这是一段很长很长长长长长长长长长长长长还有English混入的的文本"
+    android:maxLines="1"
+    android:ellipsize="end" />
+

Personalized Configuration

PanguText supports personalized configuration. You can use the global static instance PanguText.globalConfig to get the global configuration or configure it individually.

The following example

// Get global configuration.
+val config = PanguText.globalConfig
+// Enable or disable the feature.
+config.isEnabled = true
+// Process Spanned text.
+// Processing Spanned text is enabled by default, but this feature is experimental.
+// If issues occur, you can disable it. When disabled, Spanned text will return the original text.
+config.isProcessedSpanned = true
+// Whether to automatically re-measure the text width after processing.
+// Note: After [PanguText] injects text and changes the text,
+// the width of [TextView] will not be calculated automatically.
+// At this time, this feature will call [TextView.setText] to re-execute the measurements,
+// which can fix issues in some dynamic layouts (such as `RecyclerView`) where text width changes each time,
+// but may cause performance issues. You can choose to disable this feature.
+// To prevent unnecessary performance overhead,
+// this feature only takes effect on [TextView] with `maxLines` set to 1 or `singleLine`.
+config.isAutoRemeasureText = true
+// Set patterns to exclude during formatting using regular expressions.
+// For example, exclude all URLs.
+config.excludePatterns.add("https?://\\S+".toRegex())
+// For example, exclude emoji placeholders like "[doge]".
+// If you use [ImageSpan] to display emoji images, you can choose to exclude these placeholders.
+config.excludePatterns.add("\\[.*?]".toRegex())
+// Set the spacing ratio for CJK characters.
+// This determines the final layout effect.
+// It is recommended to keep the default ratio and adjust it according to personal preference.
+config.cjkSpacingRatio = 7f
+

Notice

If you integrated using the Inject to LayoutInflater method, configure PanguText.globalConfig before executing PanguTextFactory2.inject(...), otherwise the configuration will not take effect.

You can also pass the config parameter for personalized configuration when manually injecting or formatting text.

The following example

// Assume this is your TextView.
+val textView: TextView
+// Create a new configuration.
+// You can set [copyFromGlobal] to false to not copy from the global configuration.
+val config = PanguTextConfig(copyFromGlobal = false) {
+    excludePatterns.add("https?://\\S+".toRegex())
+    excludePatterns.add("\\[.*?]".toRegex())
+    cjkSpacingRatio = 7f
+}
+// You can also copy and create a new configuration from any configuration.
+val config2 = config.copy {
+    excludePatterns.clear()
+    excludePatterns.add("https?://\\S+".toRegex())
+    excludePatterns.add("\\[.*?]".toRegex())
+    cjkSpacingRatio = 7f
+}
+// Manually inject and configure.
+textView.injectPanguText(config = config2)
+

If you integrated using the Inject to LayoutInflater method, you can use the following attributes in the XML layout declaration of TextView, EditText, or their subclasses for personalized configuration.

panguText_enabled corresponds to PanguTextConfig.isEnabled
panguText_processedSpanned corresponds to PanguTextConfig.isProcessedSpanned
panguText_autoRemeasureText corresponds to PanguTextConfig.isAutoRemeasureText
panguText_excludePatterns corresponds to PanguTextConfig.excludePatterns, string array, multiple patterns separated by |@|
panguText_cjkSpacingRatio corresponds to PanguTextConfig.cjkSpacingRatio

The following example

<TextView
+    android:id="@+id/text"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    android:text="Xiaoming今年16岁"
+    app:panguText_enabled="true"
+    app:panguText_processedSpanned="true"
+    app:panguText_autoRemeasureText="true"
+    app:panguText_excludePatterns="https?://\\S+;\\[.*?]|@|\\[.*?]"
+    app:panguText_cjkSpacingRatio="7.0" />
+

Notice

Due to issues with Android Studio, the above attributes may not have auto-completion hints. Please complete them manually.

Don't forget to add the declaration xmlns:app="http://schemas.android.com/apk/res-auto".

In custom View, you can extend your View to implement the PanguTextView interface to achieve the same functionality. This feature is also effective for the Using the Patching Tool method.

The following example

class MyTextView(context: Context, attrs: AttributeSet? = null) : AppCompatTextView(context, attrs),
+    PanguTextView {
+
+    override fun configurePanguText(config: PanguTextConfig) {
+        // Configure your [PanguTextConfig].
+    }
+}
+

Notice

The PanguTextView interface takes precedence over attributes used directly in the XML layout. If you use both methods for configuration, the PanguTextView interface configuration will override the XML layout configuration.

Individual configurations will override global configurations, and options not configured will follow the global configuration.

Android

这是 Android 平台的核心依赖，在 Android 平台上使用 PanguText 时，你需要引入此模块。

配置依赖

你可以使用如下方式将此模块添加到你的项目中。

SweetDependency (推荐)

在你的项目 SweetDependency 配置文件中添加依赖。

libraries:
+  com.highcapable.pangutext:
+    pangutext-android:
+      version: +
+

在你的项目 build.gradle.kts 中配置依赖。

implementation(com.highcapable.pangutext.pangutext.android)
+

Version Catalog

在你的项目 gradle/libs.versions.toml 中添加依赖。

[versions]
+pangutext-android = "<version>"
+
+[libraries]
+pangutext-android = { module = "com.highcapable.pangutext:pangutext-android", version.ref = "pangutext-android" }
+

在你的项目 build.gradle.kts 中配置依赖。

implementation(libs.pangutext.android)
+

请将 <version> 修改为此文档顶部显示的版本。

传统方式

在你的项目 build.gradle.kts 中配置依赖。

implementation("com.highcapable.pangutext:pangutext-android:<version>")
+

请将 <version> 修改为此文档顶部显示的版本。

功能介绍

你可以点击这里在新窗口中打开查看 KDoc。

实现原理

PanguText 在 Android 平台有两种方案对文本进行格式化，一种为 SpannableString (不破坏原始文本长度)，另一种则是直接插入空白字符 (破坏原始文本长度)。

第一种方案为 SpannableString，它会在需要增加间距的字符的前一个字符后增加应用了间距的 Span 来实现文本在样式上的改变，而不实际改变字符串的内容，最后交由 TextView 层完成渲染 (或手动使用 TextPaint 基于 Spanned 做布局样式处理)，实现无侵入式为文本设置样式。

第一种方案同样支持直接处理已经应用了样式的文本 (Spanned)，例如通过 Html.fromHtml 创建的文本，但是目前尚处于实验性阶段，可能仍然会出现非预期样式错误问题，你可以参考下方的个性化配置选择禁用它。

动态应用 (注入) 功能主要针对 EditText 的输入状态，它会为 EditText 设置一个自定义的 TextWatcher 来监听输入状态，当输入状态发生变化时，从 afterTextChanged 中获取 Editable 并进行格式化。

第二种方案则是直接插入空白字符，它会直接在需要增加间距的字符后插入空白字符，这种方案会破坏原始文本的长度并且会改变文本内容自身，但是可以不依赖于 TextView 层完成渲染，直接使用 TextPaint 绘制文本即可，适用于所有场景，但不支持动态应用 (注入)。

尚未解决的问题

PanguText 可能会与 Material 组件 TextInputEditText、MaterialAutoCompleteTextView 与 TextInputLayout 结合时在 setHint 效果上产生冲突，因为 TextView 不会在测量时计算文本中的 Span，在单行文本中此类问题尤为明显，暂时还没有解决方案，请谨慎配合此类组件使用。

受制于上述问题，通过 View.measure 方法计算包含了 PanguText 风格的 TextView 宽度时也可能会出现错误。

PanguText 目前不能处理 Spanned 文本中的下划线、删除线这种连续的字符，添加空白间距后线条会中断，并且它可能会在一些特殊字符上发生样式错误或样式没有被正确应用，为了稳定性考虑请尽量不要对非常复杂的富文本启用 PanguText 或参考下方的个性化配置设置 excludePatterns。

集成到现有项目

将 PanguText 集成到你的当前项目中非常容易，你不需要改动过多代码，挑选以下你喜欢的方案进行，即可完成集成。

注入布局装载器 (LayoutInflater)

PanguText 支持直接注入 LayoutInflater.Factory2 或为当前 Activity 创建 LayoutInflater.Factory2 实例以接管整个视图，这是推荐的集成方案，这种方式不需要修改任何现有布局即可实现无侵入式快速集成。

示例如下

class MainActivity : AppCompactActivity() {
+
+    val binding by lazy { ActivityMainBinding.inflate(layoutInflater) }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        // 在这里注入
+        PanguTextFactory2.inject(this)
+        setContentView(binding.root)
+    }
+}
+

小提示

由于接管了 LayoutInflater.Factory2，所以包括类似 ListView、RecyclerView 的回收式布局也能被正确接管。

注入 Activity 中的 LayoutInflater 实例后，以下附属于当前 Context 的实例都会自动生效。

Fragment
Dialog
PopupWindow
Toast (在高版本系统中仅前台)

基于 RemoteView 的布局将无法生效，因为它们是远程对象，不会使用当前 Context 的 LayoutInflater 进行布局装载。

如果你正在使用 BetterAndroid 中的 ui-compoment → AppBindingActivity在新窗口中打开，你需要稍微改动当前代码。

示例如下

class MainActivity : AppBindingActivity<ActivityMainBinding>() {
+
+   override fun onPrepareContentView(savedInstanceState: Bundle?): LayoutInflater {
+       val inflater = super.onPrepareContentView(savedInstanceState)
+       // 在这里注入
+       PanguTextFactory2.inject(inflater)
+       return inflater
+   }
+
+   override fun onCreate(savedInstanceState: Bundle?) {
+       super.onCreate(savedInstanceState)
+       // Your code here.
+   }
+}
+

如果你的应用程序没有使用 AppCompatActivity 也没有使用 ViewBinding，没有关系，你依然可以使用最初的方案进行。

示例如下

class MainActivity : Activity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        // 在这里注入
+        PanguTextFactory2.inject(this)
+        setContentView(R.layout.activity_main)
+    }
+}
+

小提示

PanguTextFactory2 除了可以配合 Activity 使用，它还支持注入到任何现有的 LayoutInflater 实例中，但请在 LayoutInflater 实例被用于装载布局前进行注入，否则将无法生效。

使用修补工具

你可以使用 PanguTextPatcher 修补现有的 View 或 ViewGroup 实例。

修补整个根布局，PanguTextPatcher 会自动修补根布局下的所有 TextView 或继承于其的组件。

示例如下

// 假设你有一个根布局
+val root: ViewGroup
+// 修补根布局
+PanguTextPatcher.patch(root)
+

修补单个 View，类型为 TextView 或继承于 TextView 的组件。

示例如下

// 假设这就是你的 TextView
+val textView: TextView
+// 修补单个 View
+PanguTextPatcher.patch(textView)
+

注意

在 RecyclerView、ListView、ViewPager 等回收式布局中使用 PanguTextPatcher 时，你需要在 onCreateViewHolder 或 onBindViewHolder 中获取到 itemView 后进行修补，否则不会生效。

手动注入或格式化文本

PanguText 同样支持手动注入，你可以在需要的 TextView 或 EditText 上手动进行注入。

示例如下

// 假设这就是你的 TextView
+val textView: TextView
+// 假设这就是你的 EditText
+val editText: EditText
+// 注入到现有文本
+textView.injectPanguText()
+editText.injectPanguText()
+// 可以选择是否同时注入 Hint (默认是)
+textView.injectPanguText(injectHint = false)
+editText.injectPanguText(injectHint = false)
+// 动态注入，重新调用 setText 也会自动生效
+textView.injectRealTimePanguText()
+// 动态注入主要针对于 EditText 的输入状态
+editText.injectRealTimePanguText()
+// 同样可以选择是否同时注入 Hint (默认是)
+textView.injectRealTimePanguText(injectHint = false)
+editText.injectRealTimePanguText(injectHint = false)
+

PanguText 还对 TextView 的 setText 方法进行了扩展，你可以使用如下方式直接设置带有 PanugText 样式的文本。

示例如下

// 假设这就是你的 TextView
+val textView: TextView
+// 设置带有 PanguText 样式的文本
+textView.setTextWithPangu("Xiaoming今年16岁")
+// 设置带有 PanguText 样式的 Hint
+textView.setHintWithPangu("输入Xiaoming的年龄")
+

你还可以使用 PanguText.format 方法直接格式化文本。

示例如下

// 假设这就是你的 TextView
+val textView: TextView
+// 使用 SpannableString 方案格式化文本
+// 需要传入当前 TextView 的 Resources 以及字体大小
+// 如果传入的文本自身为 Spannable 类型，则不会创建新的 SpannableString，而是返回原始对象
+val text = PanguText.format(textView.resources, textView.textSize, "Xiaoming今年16岁")
+// 设置文本
+textView.text = text
+// 直接使用空白字符以插入破坏的方式格式化文本
+// 这个方案会为文本增加额外的空白字符 " " (HSP)
+// 下方的结果会输出字符串 "Xiaoming 今年 16 岁"
+// 你也可以在方法末位自定义要使用的空白字符
+val text = PanguText.format("Xiaoming今年16岁")
+// 设置文本
+textView.text = text
+

小提示

injectPanguText、injectRealTimePanguText、setTextWithPangu、setHintWithPangu、PanguText.format 方法支持 config 参数，你可以参考下方的个性化配置。

自定义 View

PanguText 还可以配合自定义 View 进行使用，你可以将你的 View 继承到 AppCompatTextView 并重写 setText 方法。

示例如下

class MyTextView(context: Context, attrs: AttributeSet? = null) : AppCompatTextView(context, attrs) {
+
+    override fun setText(text: CharSequence?, type: BufferType?) {
+        // 在这里手动进行注入
+        val panguText = text?.let { PanguText.format(resources, textSize, it) }
+        super.setText(panguText, type)
+    }
+}
+

注意

TextView 在注入 PanguText 后，如果你在 XML 布局中使用了 android:singleLine="true" 或在代码中使用了 TextView.setSingleLine(true) 并且配合 android:elipsize="..."，那么这种方式设置单行文本可能会造成文本超出屏幕后其中会中显示出无法解析的 OBJ 字符 (被省略号截断)，因为 TextView 不会在测量时计算文本中的 Span，这会导致文本宽度计算错误。解决方案为在 XML 布局中使用 android:maxLines="1" 或在代码中使用 TextView.setMaxLines(1) 来代替。

示例如下

<TextView
+    android:id="@+id/text"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    android:text="这是一段很长很长长长长长长长长长长长长还有English混入的的文本"
+    android:maxLines="1"
+    android:ellipsize="end" />
+

个性化配置

PanguText 支持个性化配置，你可以使用全局静态实例 PanguText.globalConfig 获取全局配置，或单独进行配置。

示例如下

// 获取全局配置
+val config = PanguText.globalConfig
+// 开关，禁用将使所有功能失效
+config.isEnabled = true
+// 处理 Spanned 文本
+// Spanned 文本处理默认启用，但此功能尚处于实验性阶段，
+// 如果发生问题你可以选择禁用，禁用后遇到 Spanned 文本将返回原始文本
+config.isProcessedSpanned = true
+// 是否要在处理后自动重新测量文本宽度
+// 注意：[PanguText] 注入文本并更改文本后，[TextView] 的宽度将不会自动计算
+// 目前，此功能将调用 [TextView.setText] 重新执行测量结果，
+// 该测量可以在某些动态布局 (例如 `RecyclerView`) 中每次修复文本宽度，
+// 但可能会导致性能问题，你可以选择禁用此功能
+// 为了防止不必要的性能开销，此功能仅在 `maxlines` 设置为 1 或 `singleLine` 的 [TextView] 上生效
+config.isAutoRemeasureText = true
+// 设置在格式化过程中以正则形式定义需要排除的内容
+// 例如排除全部 URL
+config.excludePatterns.add("https?://\\S+".toRegex())
+// 例如排除类似 "[doge]" 的 emoji 占位符，
+// 如果你需要使用 [ImageSpan] 显示 emoji 图片，你可以选择排除这些占位符
+config.excludePatterns.add("\\[.*?]".toRegex())
+// 设置 CJK 空白占位间距比例
+// 这会决定最终的排版效果，建议保持默认比例，然后再以此跟随个人喜好进行调整
+config.cjkSpacingRatio = 7f
+

注意

如果你使用了注入布局装载器的方案进行集成，请在 PanguTextFactory2.inject(...) 执行前配置 PanguText.globalConfig，否则配置将无法生效。

你还可以在手动注入或格式化文本时传入 config 参数以进行个性化配置。

示例如下

// 假设这就是你的 TextView
+val textView: TextView
+// 创建一个新配置
+// 你可以设置 [copyFromGlobal] 为 false 来不从全局配置中复制配置
+val config = PanguTextConfig(copyFromGlobal = false) {
+    excludePatterns.add("https?://\\S+".toRegex())
+    excludePatterns.add("\\[.*?]".toRegex())
+    cjkSpacingRatio = 7f
+}
+// 你还可以从任意一个配置中复制并创建新配置
+val config2 = config.copy {
+    excludePatterns.clear()
+    excludePatterns.add("https?://\\S+".toRegex())
+    excludePatterns.add("\\[.*?]".toRegex())
+    cjkSpacingRatio = 7f
+}
+// 手动注入并配置
+textView.injectPanguText(config = config2)
+

如果你使用了注入布局装载器的方案进行集成，你可以在 TextView、EditText 或继承于它们的 XML 布局声明中使用以下属性来进行个性化配置。

panguText_enabled 对应 PanguTextConfig.isEnabled
panguText_processedSpanned 对应 PanguTextConfig.isProcessedSpanned
panguText_autoRemeasureText 对应 PanguTextConfig.isAutoRemeasureText
panguText_excludePatterns 对应 PanguTextConfig.excludePatterns，字符串数组，多个使用 |@| 分隔
panguText_cjkSpacingRatio 对应 PanguTextConfig.cjkSpacingRatio

示例如下

<TextView
+    android:id="@+id/text"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    android:text="Xiaoming今年16岁"
+    app:panguText_enabled="true"
+    app:panguText_processedSpanned="true"
+    app:panguText_autoRemeasureText="true"
+    app:panguText_excludePatterns="https?://\\S+;\\[.*?]|@|\\[.*?]"
+    app:panguText_cjkSpacingRatio="7.0" />
+

注意

由于 Android Studio 的问题，上述属性可能不会有补全提示，请自行补全。

不要忘记加入声明 xmlns:app="http://schemas.android.com/apk/res-auto"。

在自定义 View 中，你可以将你的 View 继承于 PanguTextView 接口以同样实现上述功能，此功能对使用修补工具方案同样有效。

示例如下

class MyTextView(context: Context, attrs: AttributeSet? = null) : AppCompatTextView(context, attrs),
+    PanguTextView {
+
+    override fun configurePanguText(config: PanguTextConfig) {
+        // 配置你的 [PanguTextConfig]
+    }
+}
+

注意

PanguTextView 接口的优先级将高于直接在 XML 布局中使用的属性，如果你同时使用了这两种方式进行配置，PanguTextView 接口的配置将覆盖 XML 布局中的配置。

单独配置将覆盖全局配置，未配置的选项将跟随全局配置。

404

pangutext-android

Packages

configurePanguText

See also

PanguTextView

Functions

afterTextChanged

beforeTextChanged

PanguTextWatcher

Parameters

Functions

onTextChanged

Package-level declarations

Types

PanguTextConfig

Return

Parameters

See also

Package-level declarations

Functions

injectPanguText

Receiver

Parameters

See also

injectRealTimePanguText

Receiver

Parameters

See also

setHintWithPangu

Receiver

Parameters

See also

setTextWithPangu

Receiver

Parameters

See also

Companion

Functions

inject

Parameters

Parameters

See also

PanguTextFactory2

Parameters

Types

Functions

onCreateView

PanguTextPatcher

Functions

patch

Parameters

Package-level declarations

Types

cjkSpacingRatio

copy

Return

Parameters

excludePatterns

PanguTextConfig

Properties

Functions

isAutoRemeasureText

isEnabled

isProcessedSpanned

format

Return

Parameters

See also

Return

Parameters

See also

globalConfig

PanguText

See also

Properties

Functions

Package-level declarations

Types

# About This Document

About This Document

License

Changelog

pangutext-android

1.0.4 | 2025.08.16 latest

1.0.3 | 2025.08.03 stale

1.0.2 | 2025.03.05 stale

1.0.1 | 2025.02.11 stale

1.0.0 | 2025.02.10 stale

pangutext-compose

Contact Us

Help with Maintenance

Looking Toward the Future

Future Plans

Limitations of SpannableString

Jetpack Compose Plan

R8 & Proguard Obfuscate

Introduction

Background

Effects

Language Requirement

Contribution