HOME > さらに使いこなす > ATOKダイレクト API > ATOK 2013 for Windows向け（プラグイン作成）
ATOK 2013 for WindowsATOKダイレクト API プラグイン作成手順
共通事項
Perl 、Ruby 、Python を用いてプラグインを作成するには
- スクリプトファイル（ Perl またはRuby 、Python で作成。UTF-8 で記述すること。）
- プラグインの名前などを記述する、XML 形式の情報ファイル
を用意する必要があります。
ATOK ダイレクトで検索を実行した場合、入力中の文字列をプラグインで受け取ることができます。
スクリプトプラグインでは、入力中の文字列に対応する候補情報（候補表記、コメント、ツールチップ候補とその種類）を生成し、出力することができます。
Perlスクリプトプラグイン
Perlで記述したプラグインを作成する場合、そのスクリプトファイルに記述しなければならない情報は、以下の通りです。
ソース記述例
#################################################
#
# Perlモジュール用のプラグインインターフェイス
#
# ※このテキストは必ずUTF-8で記述すること
# 扱う文字列は全てUTF-8前提であるとする
#
#################################################
package Atok_plugin;
#################################################
# 宣言
use strict;
use utf8;
#################################################
#
# 取得処理を実行する
# ・設定した候補を返すことが可能
# ・最大で100個の候補を返すことができる
# ・候補には、
# １．表記
# ２．コメント（プレーンテキストかXHTML）
# ３．ツールチップ（確定文字列かURLジャンプ文字列とそのエイリアス文字列）
# を設定できる
# ・何もセットしなかった場合、処理結果は何もないと判断される
# ・引数で渡される情報に含まれる文字列は、全てUTF8フラグが付いている
# ・返す情報に含める文字列は必ずUTF8にする必要がある
# （UTF8フラグは付いていなくても問題ない）
sub run_process
{
my( $a_request_data ) = @_;
my %result_data;
my @candidate_array;
push( @candidate_array , { 'hyoki' => "候補1" } );
push( @candidate_array , { 'hyoki' => "候補2" ,
'comment' => "コメント(候補2)" } );
# コメントとして返すXHTMLを定義
# （UTF-8のXHTMLとして指定する必要がある）
my $comment_xhtml = <<"END_OF_STRING";
<?xml version="1.0" encoding="UTF-8" ?>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ja" lang="ja">
<head><title>AtokDirect</title></head>
<body>XHTMLコメント<b style="color: #ff0000">(候補3)</b></body>
</html>
END_OF_STRING
push( @candidate_array , { 'hyoki' => "候補3" ,
'comment_xhtml' => $comment_xhtml } );
push( @candidate_array , {
'hyoki' => "通知された表記：" . $a_request_data->{ 'composition_string' } ,
'comment' => "コメント(" . $a_request_data->{ 'composition_string' } . ")" ,
'alternative' => "確定文字(" . $a_request_data->{ 'composition_string' } . ")" ,
'alternative_type' => 'definite_string' } );
push( @candidate_array , { 'hyoki' => "ATOK.comを開く1" ,
'alternative' => "http://www.atok.com/" ,
'alternative_type' => 'url_jump_string' } );
push( @candidate_array , { 'hyoki' =>"ATOK.comを開く2" ,
'alternative' => "http://www.atok.com/" ,
'alternative_alias'=> "ATOK.comを既定のブラウザで開く",
'alternative_type' => 'url_jump_string' } );
$result_data{ 'candidate' } = \@candidate_array;
return( %result_data );
}
#################################################
1; # 重要：モジュールは必ず真と解釈される値を返さなければならない
※「Atok_plugin」パッケージ内に「run_process」を実装する必要があります。
サブルーチン、パッケージ、引数
- サブルーチン名
- run_process
- パッケージ名
- Atok_plugin
- 引数
- 「run_process 」の引数で受け取るオブジェクトはハッシュであり、その構造は以下の通りです。
（『文字列』は全てUTF-8 で通知され、UTF8 フラグが付いています）
| キー | 種類 | 値 |
|---|---|---|
| composition_string | 文字列 | 入力中の文字列 |
| proxy_name | 文字列 | プロキシサーバー名
|
| proxy_port | 文字列 | プロキシボート番号
|
| proxy_username | 文字列 | プロキシ認証で使用するユーザ名
|
| proxy_password | 文字列 | プロキシ認証で使用するパスワード
|
処理結果の格納
プラグインの処理結果として返すオブジェクトはハッシュであり、その構造は以下の通りです。
| キー | 種類 | 値 |
|---|---|---|
| candidate | 配列 | 候補として設定する内容を格納します。 |
「candidate」で表される配列の個々の内容はハッシュであり、その構造は以下の通りです。
（『文字列』は全てUTF-8 で指定します。UTF-8 フラグは付いていなくてもかまいません）
| キー | 種類 | 値 |
|---|---|---|
| hyoki | 文字列 | 候補文字列
|
| comment | 文字列 | 候補に対応するコメント文字列（テキスト）
|
| comment_xhtml | 文字列 | 候補に対応するコメント文字列（ XHTML）
|
| alternative | 文字列 | 候補に対応するコメント文字列（XHTML）
|
| alternative_type | 文字列 | 候補に対応するツールチップの種類を表す文字列 以下のいずれかを設定します。
|
| alternative_alias | 文字列 | 実際にツールチップに表示する文字列
|
※文字列が最大値を超える場合、超過した文字列は破棄します。
※URL文字列についてはhttp:// から始まらない場合や最大値を超える場合はツー ルチップ文字列は使用しません。
戻り値
処理結果を格納して返すオブジェクト
（結果なしの場合は空のオブジェクトを返します）
Rubyスクリプトプラグイン
ソース記述例
Rubyで記述したプラグインを作成する場合、そのスクリプトファイルに記述しなければならない情報は、以下の通りとなります。
#! /usr/bin/ruby -Ku
#################################################
#
# ATOKダイレクトRubyスクリプトモジュールインターフェイス
#
# ※このテキストは必ずUTF-8で記述すること
# 扱う文字列は全てUTF-8前提であるとする
#
#################################################
module Atok_plugin
#################################################
# 取得処理を実行する
# ・設定した候補を返すことが可能
# ・最大で100個の候補を返すことができる
# ・候補には、
# １．表記
# ２．コメント（プレーンテキストかXHTML）
# ３．ツールチップ（確定文字列かURLジャンプ文字列とそのエイリアス文字列）
# を設定できる
# ・何もセットしなかった場合、処理結果は何もないと判断される
# ・引数で渡される情報に含まれる文字列は、全てUTF-8である
# ・返す情報に含める文字列は必ずUTF-8にする必要がある
def run_process( a_request_data )
result_data = Hash.new
candidate_array = Array.new
candidate_array.push( { 'hyoki' => "候補1" } )
candidate_array.push( { 'hyoki' => "候補2" ,
'comment' => "コメント（候補2）" } )
# コメントとして返すXHTMLを定義
# （UTF-8のXHTMLとして指定する必要がある）
comment_xhtml = <<END_OF_STRING
<?xml version="1.0" encoding="UTF-8" ?>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ja" lang="ja">
<head><title>AtokDirect</title></head>
<body>XHTMLコメント<b style="color: #ff0000">(候補3)</b></body>
</html>
END_OF_STRING
candidate_array.push( { 'hyoki' => "候補3" ,
'comment_xhtml' => comment_xhtml } )
candidate_array.push( {
'hyoki' => "通知された表記：" + a_request_data[ 'composition_string' ] ,
'comment' => "コメント(" + a_request_data[ 'composition_string' ] + ")" ,
'alternative'=> "確定文字(" + a_request_data[ 'composition_string' ] + ")" ,
'alternative_type'=> "definite_string" } )
candidate_array.push( { 'hyoki' => "ATOK.comを開く1" ,
'alternative' => "http://www.atok.com/" ,
'alternative_type' => "url_jump_string" } )
candidate_array.push( { 'hyoki' => "ATOK.comを開く2" ,
'alternative' => "http://www.atok.com/" ,
'alternative_alias'=> "ATOK.comを既定のブラウザで開く",
'alternative_type' => "url_jump_string" } )
result_data[ 'candidate' ] = candidate_array
result_data
end
#################################################
end
※「Atok_plugin 」モジュール内に「run_process 」を実装する必要があります。
メソッド、モジュール、引数
- メソッド名
- run_process
- モジュール名
- Atok_plugin
- 引数
- 「run_process 」の引数で受け取るオブジェクトはHashであり、その構造は以下の通りです。
（『String 』は全てUTF-8で通知されます）
| キー | 種類 | 値 |
|---|---|---|
| composition_string | String | 入力中の文字列 |
| proxy_name | String | プロキシサーバ名
|
| proxy_port | String | プロキシポート番号
|
| proxy_username | String | プロキシ認証で使用するユーザ名
|
| proxy_password | String | プロキシ認証で使用するパスワード
|
処理結果の格納
プラグインの処理結果として返すオブジェクトはHashであり、その構造は以下の通りです 。
| キー | 種類 | 値 |
|---|---|---|
| candidate | Array | 候補として設定する内容を格納します。 |
「candidate」で表される配列の個々の内容はHashであり、その構造は以下の通りです。
（『String 』は全てUTF-8で指定する必要があります。）
| キー | 種類 | 値 |
|---|---|---|
| hyoki | String | 候補文字列
|
| comment | String | 候補に対応するコメント文字列
|
| comment_xhtml | String | 候補に対応するコメント文字列（XHTML）
|
| alternative | String | 候補に対応するツールチップ文字列
|
| alternative_type | String | 候補に対応するツールチップの種類を表す文字列 以下のいずれかを設定します。
|
| alternative_alias | String | 実際にツールチップに表示する文字列
|
※文字列が最大値を超える場合、超過した文字列は破棄します。
※URL 文字列についてはhttp:// から始まらない場合や最大値を超える場合はツールチップ文字列は使用しません。
戻り値
処理結果を格納して返すオブジェクト
（結果なしの場合は空のオブジェクトを返します）
Pythonスクリプトプラグイン
ソース記述例
Python で記述したプラグインを作成する場合、そのスクリプトファイルに記述しなければならない情報は、以下の通りとなります。
#! /usr/bin/env python
# coding:utf-8
#################################################
#
# Pythonモジュール用のプラグインインターフェイス
#
# ※このテキストは必ずUTF-8で記述すること
# 扱う文字列は全てUTF-8前提であるとする
#
#################################################
#################################################
# 取得処理を実行する
# ・設定した候補を返すことが可能
# ・最大で100個の候補を返すことができる
# ・候補には、
# １．表記
# ２．コメント（プレーンテキストかXHTML）
# ３．ツールチップ（確定文字列かURLジャンプ文字列とそのエイリアス文字列）
# を設定できる
# ・何もセットしなかった場合、処理結果は何もないと判断される
# ・引数で渡される情報に含まれる文字列は、全てunicodeである
# ・返す情報に含める文字列は必ずunicodeにする必要がある
def atok_plugin_run_process( a_request_data ):
result_data = {}
candidate_array = []
candidate_array.append( { 'hyoki' : u"候補1" } )
candidate_array.append( { 'hyoki' : u"候補2" ,
'comment' : u"コメント(候補2)" } )
# コメントとして返すXHTMLを定義
# （unicode文字列で作成するが、記述はUTF-8のXHTMLとして指定する必要がある）
comment_xhtml1 = u'''<?xml version="1.0" encoding="UTF-8" ?>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ja" lang="ja">
<head><title>AtokDirect</title></head>
<body>XHTMLコメント<b style="color: #ff0000">(候補3)</b></body>
</html>'''
candidate_array.append( { 'hyoki' : u"候補3" ,
'comment_xhtml' : comment_xhtml1 } )
candidate_array.append( {
'hyoki' : u"通知された表記：" + a_request_data[ 'composition_string' ] ,
'comment' : u"コメント(" + a_request_data[ 'composition_string' ] + u")" ,
'alternative' : u"確定文字(" + a_request_data[ 'composition_string' ] + u")" ,
'alternative_type' : u"definite_string" } )
candidate_array.append( { 'hyoki' : u"ATOK.comを開く1" ,
'alternative' : u"http://www.atok.com/" ,
'alternative_type' : u"url_jump_string" } )
candidate_array.append( { 'hyoki' : u"ATOK.comを開く2" ,
'alternative' : u"http://www.atok.com/" ,
'alternative_alias':u"ATOK.comを既定のブラウザで開く" ,
'alternative_type' : u"url_jump_string" } )
result_data[ 'candidate' ] = candidate_array
return result_data
※「atok_plugin_run_process 」を実装する必要があります。
関数名、引数
- 関数名
- atok_plugin_run_process
- 引数
- 「atok_plugin_run_process 」の引数で受け取るオブジェクトはdict であり、その構造は以下の通りです。
| キー | 種類 | 値 |
|---|---|---|
| composition_string | unicode | 入力中の文字列 |
| proxy_name | unicode | プロキシサーバ名
|
| proxy_port | unicode | プロキシポート番号
|
| proxy_username | unicode | プロキシ認証で使用するユーザ名
|
| proxy_password | unicode | プロキシ認証で使用するパスワード
|
処理結果の格納
プラグインの処理結果として返すオブジェクトはdict であり、その構造は以下の通りです。
| キー | 種類 | 値 |
|---|---|---|
| candidate | list | 候補として設定する内容を格納します。 |
「candidate 」で表される配列の個々の内容はHash であり、その構造は以下の通りです。
| キー | 種類 | 値 |
|---|---|---|
| hyoki | unicode | 候補文字列
|
| comment | unicode | 候補に対応するコメント文字列
|
| comment_xhtml | unicode | 候補に対応するコメント文字列（XHTML）
|
| alternative | unicode | 候補に対応するツールチップ文字列
|
| alternative_type | unicode | 候補に対応するツールチップの種類を表す文字列 以下のいずれかを設定します。
|
| alternative_alias | unicode | 実際にツールチップに表示する文字列
|
※文字列が最大値を超える場合、超過した文字列は破棄します。
※URL 文字列についてはhttp:// から始まらない場合や最大値を超える場合はツー ルチップ文字列は使用しません。
戻り値
処理結果を格納して返すオブジェクト
（結果なしの場合は空のオブジェクトを返します）
XHTML コメントの記述について
ATOK 2010 以降のバージョンでは、候補に対応するコメントを、HTML 表示することができます。 処理結果を格納する際に、comment_xhtml にXHTML 形式（ XHTML1.0 ）でコメントを設定します。
使用可能な要素について
いくつかの要素については、使用できないなどの制限が存在します。 また、属性については、無視されるものもあります。
使用可能な要素
html , body , div , span , h1 , h2 , h3 , h4 , h5 , h6 , p , br , blockquote , q , cite , em ,
strong , dfn , abbr , acronym , sup , sub , pre , code , var , kbd , samp , ins , del , bdo ,
ruby , rb , rt , rp , rbc , rtc , hr , tt , i , b , big , small , u , strike , s , font , basefont ,
center , img , map , ul , ol , li , dl , dt , dd , dir , menu , table , caption , tr , th , td ,
thead , tfoot , tbody , colgroup , col
制限付きで使用可能な要素
a , area
上記要素については、href 属性が「http 」で始まっている必要があります。
使用できない要素
script 、iframe など、使用可能な要素として記載した要素以外はすべて無視されます。
指定方法について
有効なXHTML1.0 として処理できる形で、comment_xhtml に設定します。 実際のATOK ダイレクト解説表示では、設定されたXHTML のbody 要素以下を使用します。
例：
<?xml version="1.0" encoding="UTF-8" ?>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ja" lang="ja">
<head>○○○○</head>
<body>●●●●●●</body>
</html>
なお、body 要素の属性を記述した場合、その属性値は無視されます。
ATOK ダイレクト解説に「正常なデータとして認識できません」と表示される
設定したXHTML が正常に解析できなかった場合、ATOK ダイレクト解説に「正常なデータとして認識できません」と表示されます。
設定したXHTML 文書が正確であるか確認ください。
情報ファイル
プラグインの情報（プラグインの名前、解説、コピーライト、およびバージョン）を記述する XML ファイルを準備します。
情報ファイルのファイル名はスクリプトファイル名と同名のXML ファイル（スクリプトファイ ルの拡張子をのぞいた部分＋拡張子XML のファイル）となります。
記述例
スクリプトファイルがplugin_sample.rb の場合、
情報ファイル名はplugin_sample.xml 。
<?xml version="1.0" encoding="UTF-8" ?>
<plugin_info>
<name>プラグインの名前</name>
<name_short>プラグインの省略名</name_short>
<description>プラグインの解説</description>
<copyright>プラグインのコピーライト</copyright>
<major_version>1</major_version>
<minor_version>0</minor_version>
</plugin_info>
タグの解説
情報ファイルのタグは、以下の内容を示します。
- plugin_info
- root タグ
- name
- プラグインの名前
- 最大64 文字
- name_short
- プラグインの省略名（候補ウィンドウに表示する名称）
- 最大16 文字
- 設定しない場合、name に設定した名前の先頭から16 文字を使用します。
- description
- プラグインの解説
- 最大256 文字
- copyright
- プラグインのコピーライト
- 最大64 文字
- major_version
- プラグインのメジャーバージョン
- 0 〜 100 （半角）
- minor_version
- プラグインのマイナーバージョン
- 0 〜 100 （半角）
※文字列が最大値を超える場合、超過した文字列は破棄します。
