pinyin · 开发者必备的知识

## [安装](https://github.com/overtrue/pinyin#%E5%AE%89%E8%A3%85) 使用 Composer 安装: ~~~shell composer require overtrue/pinyin:^5.0 ~~~ ## [使用](https://github.com/overtrue/pinyin#%E4%BD%BF%E7%94%A8) ### [拼音风格](https://github.com/overtrue/pinyin#%E6%8B%BC%E9%9F%B3%E9%A3%8E%E6%A0%BC) 除了获取首字母的方法外，所有方法都支持第二个参数，用于指定拼音的格式，可选值为： * `symbol`（默认）声调符号，例如`pīn yīn` * `none`不输出拼音，例如`pin yin` * `number`末尾数字模式的拼音，例如`pin1 yin1` ### [返回值](https://github.com/overtrue/pinyin#%E8%BF%94%E5%9B%9E%E5%80%BC) 除了`permalink`返回字符串外，其它方法都返回集合类型[`Overtrue\Pinyin\Collection`](https://github.com/overtrue/pinyin/blob/master/src/Collection.php)： ~~~html use Overtrue\Pinyin\Pinyin; $pinyin = Pinyin::sentence('你好，世界'); ~~~ 你可以通过以下方式访问集合内容: ~~~html echo $pinyin; // nǐ hǎo shì jiè // 直接将对象转成字符串 $string = (string) $pinyin; // nǐ hǎo shì jiè $pinyin->toArray(); // ['nǐ', 'hǎo', 'shì', 'jiè'] // 直接使用索引访问 $pinyin[0]; // 'nǐ' // 使用函数遍历 $pinyin->map('ucfirst'); // ['Nǐ', 'Hǎo', 'Shì', 'Jiè'] // 拼接为字符串 $pinyin->join(' '); // 'nǐ hǎo shì jiè' $pinyin->join('-'); // 'nǐ-hǎo-shì-jiè' // 转成 json $pinyin->toJson(); // '["nǐ","hǎo","shì","jiè"]' json_encode($pinyin); // '["nǐ","hǎo","shì","jiè"]' ~~~ ### [文字段落转拼音](https://github.com/overtrue/pinyin#%E6%96%87%E5%AD%97%E6%AE%B5%E8%90%BD%E8%BD%AC%E6%8B%BC%E9%9F%B3) ~~~html use Overtrue\Pinyin\Pinyin; echo Pinyin::sentence('带着希望去旅行，比到达终点更美好'); // dài zhe xī wàng qù lǚ xíng ， bǐ dào dá zhōng diǎn gèng měi hǎo // 去除声调 echo Pinyin::sentence('带着希望去旅行，比到达终点更美好', 'none'); // dai zhe xi wang qu lv xing ， bi dao da zhong dian geng mei hao // 保留所有非汉字字符 echo Pinyin::fullSentence('ル是片假名，π是希腊字母', 'none'); // ル shi pian jia ming ，π shi xi la zi mu ~~~ ### [生成用于链接的拼音字符串](https://github.com/overtrue/pinyin#%E7%94%9F%E6%88%90%E7%94%A8%E4%BA%8E%E9%93%BE%E6%8E%A5%E7%9A%84%E6%8B%BC%E9%9F%B3%E5%AD%97%E7%AC%A6%E4%B8%B2) 通常用于文章链接等，可以使用`permalink`方法获取拼音字符串： ~~~html echo Pinyin::permalink('带着希望去旅行'); // dai-zhe-xi-wang-qu-lyu-xing echo Pinyin::permalink('带着希望去旅行', '.'); // dai.zhe.xi.wang.qu.lyu.xing ~~~ ### [获取首字符字符串](https://github.com/overtrue/pinyin#%E8%8E%B7%E5%8F%96%E9%A6%96%E5%AD%97%E7%AC%A6%E5%AD%97%E7%AC%A6%E4%B8%B2) 通常用于创建搜索用的索引，可以使用`abbr`方法转换： ~~~html Pinyin::abbr('带着希望去旅行'); // ['d', 'z', 'x', 'w', 'q', 'l', 'x'] echo Pinyin::abbr('带着希望去旅行')->join('-'); // d-z-x-w-q-l-x echo Pinyin::abbr('你好2018！')->join(''); // nh2018 echo Pinyin::abbr('Happy New Year! 2018！')->join(''); // HNY2018 ~~~ **姓名首字母** 将首字作为姓氏转换，其余作为普通词语转换： ~~~html Pinyin::nameAbbr('欧阳'); // ['o', 'y'] echo Pinyin::nameAbbr('单单单')->join('-'); // s-d-d ~~~ ### [姓名转换](https://github.com/overtrue/pinyin#%E5%A7%93%E5%90%8D%E8%BD%AC%E6%8D%A2) 姓名的姓的读音有些与普通字不一样，比如 ‘单’ 常见的音为`dan`，而作为姓的时候读`shan`。 ~~~html Pinyin::name('单某某'); // ['shàn', 'mǒu', 'mǒu'] Pinyin::name('单某某', 'none'); // ['shan', 'mou', 'mou'] Pinyin::name('单某某', 'none')->join('-'); // shan-mou-mou ~~~ ### [护照姓名转换](https://github.com/overtrue/pinyin#%E6%8A%A4%E7%85%A7%E5%A7%93%E5%90%8D%E8%BD%AC%E6%8D%A2) 根据国家规定[关于中国护照旅行证上姓名拼音 ü（吕、律、闾、绿、女等）统一拼写为 YU 的提醒](http://sg.china-embassy.gov.cn/lsfw/zghz1/hzzxdt/201501/t20150122_2022198.htm)的规则，将`ü`转换为`yu`： ~~~html Pinyin::passportName('吕小布'); // ['lyu', 'xiao', 'bu'] Pinyin::passportName('女小花'); // ['nyu', 'xiao', 'hua'] Pinyin::passportName('律师'); // ['lyu', 'shi'] ~~~ ### [多音字](https://github.com/overtrue/pinyin#%E5%A4%9A%E9%9F%B3%E5%AD%97) 多音字的返回值为关联数组的集合，默认返回去重后的所有读音： ~~~html $pinyin = Pinyin::polyphones('重庆'); $pinyin['重']; // ["zhòng", "chóng", "tóng"] $pinyin['庆']; // ["qìng"] $pinyin->toArray(); // [ // "重": ["zhòng", "chóng", "tóng"], // "庆": ["qìng"] // ] ~~~ 如果不想要去重，可以数组形式返回： ~~~html $pinyin = Pinyin::polyphones('重庆重庆', Converter::TONE_STYLE_SYMBOL, true); // or $pinyin = Pinyin::polyphonesAsArray('重庆重庆', Converter::TONE_STYLE_SYMBOL); $pinyin->toArray(); // [ // ["重" => ["zhòng", "chóng", "tóng"]], // ["庆" => ["qìng"]], // ["重" => ["zhòng", "chóng", "tóng"]], // ["庆" => ["qìng"]] // ] ~~~ ### [单字转拼音](https://github.com/overtrue/pinyin#%E5%8D%95%E5%AD%97%E8%BD%AC%E6%8B%BC%E9%9F%B3) 和多音字类似，单字的返回值为字符串，多音字将根据该字字频调整得到常用音： ~~~html $pinyin = Pinyin::chars('重庆'); echo $pinyin['重']; // "zhòng" echo $pinyin['庆']; // "qìng" $pinyin->toArray(); // [ // "重": "zhòng", // "庆": "qìng" // ] ~~~ Warning 当单字处理时由于多音字来自词频表中取得常用音，所以在词语环境下可能出现不正确的情况，建议使用多音字处理。更多使用请参考[测试用例](https://github.com/overtrue/pinyin/blob/master/tests/PinyinTest.php)。 ## [v/yu/ü 的问题](https://github.com/overtrue/pinyin#vyu%C3%BC-%E7%9A%84%E9%97%AE%E9%A2%98) 根据国家语言文字工作委员会的规定，`lv`、`lyu`、`lǚ`都是正确的，但是`lv`是最常用的，所以默认使用`lv`，如果你需要使用其他的，可以在初始化时传入： ~~~html echo Pinyin::sentence('旅行'); // lǚ xíng echo Pinyin::sentence('旅行', 'none'); // lv xing echo Pinyin::yuToYu()->sentence('旅行', 'none'); // lyu xing echo Pinyin::yuToU()->sentence('旅行', 'none'); // lu xing echo Pinyin::yuToV()->sentence('旅行', 'none'); ~~~