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'); ~~~