html v3.15.0+

Use html API to get a HTML string of Chinese characters and Pinyin in the format of ''.

Example

Basic Use

The returned value of html api is a HTML string：

The outermost layer of each Chinese character and Pinyin is wrapped by a  tag. (the class of the tag can be customized through the resultClass attribute)
The inner layer is wrapped with <ruby></ruby> to display Chinese characters and Pinyin.
The Chinese character part is wrapped by a  tag. (the class of the tag can be customized through the chineseClass attribute)
The Pinyin part is wrapped by a <rt class="py-pinyin-item"></rt> tag. (the class of the tag can be customized through the pinyinClass attribute)
By default, non Chinese character isn't be wrapped. By setting the value of the wrapNonChinese attribute to true, non Chinese character part will be wrapped by a  tag. (The class of the tag can be customized through the nonChineseClass attribute)

import { html } from 'pinyin-pro';

const htmlString = html('汉语拼音');

/*
<span class="py-result-item">
  <ruby>
    <span class="py-chinese-item">汉</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">hàn</rt>
    <rp>)</rp>
  </ruby>
</span>
<span class="py-result-item">
  <ruby>
    <span class="py-chinese-item">语</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">yǔ</rt>
    <rp>)</rp>
  </ruby>
</span>
<span class="py-result-item">
  <ruby>
    <span class="py-chinese-item">拼</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">pīn</rt>
    <rp>)</rp>
  </ruby>
</span>
<span class="py-result-item">
  <ruby>
    <span class="py-chinese-item">音</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">yīn</rt>
    <rp>)</rp>
  </ruby>
</span>
*/

import { html } from 'pinyin-pro';

const htmlString = html('汉语拼音');

/*
<span class="py-result-item">
  <ruby>
    <span class="py-chinese-item">汉</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">hàn</rt>
    <rp>)</rp>
  </ruby>
</span>
<span class="py-result-item">
  <ruby>
    <span class="py-chinese-item">语</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">yǔ</rt>
    <rp>)</rp>
  </ruby>
</span>
<span class="py-result-item">
  <ruby>
    <span class="py-chinese-item">拼</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">pīn</rt>
    <rp>)</rp>
  </ruby>
</span>
<span class="py-result-item">
  <ruby>
    <span class="py-chinese-item">音</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">yīn</rt>
    <rp>)</rp>
  </ruby>
</span>
*/

The preview of the htmlString in the browser is as follows:

汉(hàn)语(yǔ)，拼(pīn)音(yīn)

Without Tone

When set the value of the toneType attribute to none, the Pinyin in the returned value has no tone.

import { html } from 'pinyin-pro';

const htmlString = html('汉语拼音', { toneType: 'none' });

/*
<span class="py-result-item">
  <ruby>
    <span class="py-chinese-item">汉</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">han</rt>
    <rp>)</rp>
  </ruby>
</span>
<span class="py-result-item">
  <ruby>
    <span class="py-chinese-item">语</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">yu</rt>
    <rp>)</rp>
  </ruby>
</span>
<span class="py-result-item">
  <ruby>
    <span class="py-chinese-item">拼</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">pin</rt>
    <rp>)</rp>
  </ruby>
</span>
<span class="py-result-item">
  <ruby>
    <span class="py-chinese-item">音</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">yin</rt>
    <rp>)</rp>
  </ruby>
</span>
*/

import { html } from 'pinyin-pro';

const htmlString = html('汉语拼音', { toneType: 'none' });

/*
<span class="py-result-item">
  <ruby>
    <span class="py-chinese-item">汉</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">han</rt>
    <rp>)</rp>
  </ruby>
</span>
<span class="py-result-item">
  <ruby>
    <span class="py-chinese-item">语</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">yu</rt>
    <rp>)</rp>
  </ruby>
</span>
<span class="py-result-item">
  <ruby>
    <span class="py-chinese-item">拼</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">pin</rt>
    <rp>)</rp>
  </ruby>
</span>
<span class="py-result-item">
  <ruby>
    <span class="py-chinese-item">音</span>
    <rp>(</rp>
    <rt class="py-pinyin-item">yin</rt>
    <rp>)</rp>
  </ruby>
</span>
*/

The preview of the above code in the browser is as follows:

汉(han)语(yu)拼(pin)音(yin)

Custom Style

You can control the specific style by using the class in the returned value of html api. In the following example, we let the Chinese character part in blue and the Pinyin part in red.

// js
import { html } from 'pinyin-pro';

const htmlString = html('汉语拼音');

// js
import { html } from 'pinyin-pro';

const htmlString = html('汉语拼音');

css

/* css */
.py-chinese-item {
  color: blue;
}
.py-pinyin-item {
  color: red;
}

/* css */
.py-chinese-item {
  color: blue;
}
.py-pinyin-item {
  color: red;
}

The preview of the above code in the browser is as follows:

汉(hàn)语(yǔ) ，拼(pīn)音(yīn)

Custom Classes of Designated Words

You can apply individual styles to specific characters through the customClassMap parameter. For example, in the following example, the "汉" part is in red, and the "音" part is in blue.

import { html } from 'pinyin-pro';

const htmlString = html('汉语拼音', {
  customClassMap: {
    'red-item': ['汉'],
    'blue-item': ['音'],
  },
});

/*
<span class="py-result-item red-item">
	<ruby>
		<span class="py-chinese-item">汉</span>
		<rp>(</rp>
		<rt class="py-pinyin-item">hàn</rt>
		<rp>)</rp>
	</ruby>
</span>
<span class="py-result-item">
	<ruby>
		<span class="py-chinese-item">语</span>
		<rp>(</rp>
		<rt class="py-pinyin-item">yǔ</rt>
		<rp>)</rp>
	</ruby>
</span>
<span class="py-result-item">
	<ruby>
		<span class="py-chinese-item">拼</span>
		<rp>(</rp>
		<rt class="py-pinyin-item">pīn</rt>
		<rp>)</rp>
	</ruby>
</span>
<span class="py-result-item blue-item">
	<ruby>
		<span class="py-chinese-item">音</span>
		<rp>(</rp>
		<rt class="py-pinyin-item">yīn</rt>
		<rp>)</rp>
	</ruby>
</span>
*/

import { html } from 'pinyin-pro';

const htmlString = html('汉语拼音', {
  customClassMap: {
    'red-item': ['汉'],
    'blue-item': ['音'],
  },
});

/*
<span class="py-result-item red-item">
	<ruby>
		<span class="py-chinese-item">汉</span>
		<rp>(</rp>
		<rt class="py-pinyin-item">hàn</rt>
		<rp>)</rp>
	</ruby>
</span>
<span class="py-result-item">
	<ruby>
		<span class="py-chinese-item">语</span>
		<rp>(</rp>
		<rt class="py-pinyin-item">yǔ</rt>
		<rp>)</rp>
	</ruby>
</span>
<span class="py-result-item">
	<ruby>
		<span class="py-chinese-item">拼</span>
		<rp>(</rp>
		<rt class="py-pinyin-item">pīn</rt>
		<rp>)</rp>
	</ruby>
</span>
<span class="py-result-item blue-item">
	<ruby>
		<span class="py-chinese-item">音</span>
		<rp>(</rp>
		<rt class="py-pinyin-item">yīn</rt>
		<rp>)</rp>
	</ruby>
</span>
*/

css

/* css */
.red-item {
  color: red;
}
.blue-item {
  color: blue;
}

/* css */
.red-item {
  color: red;
}
.blue-item {
  color: blue;
}

The preview of the above code in the browser is as follows:

汉(hàn)语(yǔ)拼(pīn)音(yīn)

API

Function

import { customPinyin } from 'pinyin-pro';

interface HtmlOptions {
  resultClass?: string;
  pinyinClass?: string;
  chineseClass?: string;
  wrapNonChinese?: boolean;
  nonChineseClass?: string;
  tone?: boolean;
  rp?: boolean; // v3.24.2+  Whether to output <rp>(</rp> and <rp>)</rp> tags
}

function html(text: string, options?: HtmlOptions): string {}

import { customPinyin } from 'pinyin-pro';

interface HtmlOptions {
  resultClass?: string;
  pinyinClass?: string;
  chineseClass?: string;
  wrapNonChinese?: boolean;
  nonChineseClass?: string;
  tone?: boolean;
  rp?: boolean; // v3.24.2+  Whether to output <rp>(</rp> and <rp>)</rp> tags
}

function html(text: string, options?: HtmlOptions): string {}

Parameters

text (required): string, the Chinese character string to convert.
options (optional): object, the configuration related to the return value, more specific information is shown in the table below：

Key	Type	Description	Optional Values	Default Value
resultClass	string	class of the outermost `<span>` tag of Chinese characters and pinyin	-	py-result-item
pinyinClass	string	class of the outer `<rt>` tag of Pinyin	-	py-pinyin-item
chineseClass	string	class of the outer `<span>` tag of Chinese character	-	py-chinese-item
wrapNonChinese	string	Whether use `<span>` to wrap non Chinese characters. If you want to do some custom style processing for non Chinese characters, it is recommended to set it to `true`; If the input text parameter is also an HTML string, it is recommended to set it to `false` to prevent affecting the structure of the text.	`true/false`	false
nonChineseClass	string	class of the outer `<span>` tag of non Chinese character(Only when the value of `wrapNonChinese` is `true`, it is work.)	-	py-non-chinese-item
toneType	string	the display form of tones in Pinyin	`symbol/none/num`	symbol

html v3.15.0+ ​

Example ​

Basic Use ​

Without Tone ​

Custom Style ​

Custom Classes of Designated Words ​

API ​

Function ​

Parameters ​

html v3.15.0+

Example

Basic Use

Without Tone

Custom Style

Custom Classes of Designated Words

API

Function

Parameters