Skip to content

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 <span class="py result item"></span> 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 <span class="py-chinese-item"></span> 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 <span class="py non Chinese item"></span> tag. (The class of the tag can be customized through the nonChineseClass attribute)
js
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)()(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.

js
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
// 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)()(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.

js
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)()(pīn)(yīn)

API

Function

ts
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:
KeyTypeDescriptionOptional ValuesDefault Value
resultClassstringclass of the outermost <span> tag of Chinese characters and pinyin-py-result-item
pinyinClassstringclass of the outer <rt> tag of Pinyin-py-pinyin-item
chineseClassstringclass of the outer <span> tag of Chinese character-py-chinese-item
wrapNonChinesestringWhether 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/falsefalse
nonChineseClassstringclass of the outer <span> tag of non Chinese character(Only when the value of wrapNonChinese is true, it is work.)-py-non-chinese-item
toneTypestringthe display form of tones in Pinyinsymbol/none/numsymbol