writeexcel.rdoc in writeexcel-0.4.1 vs writeexcel.rdoc in writeexcel-0.4.2
- old
+ new
@@ -633,16 +633,15 @@
指定されたセルに数式あるいは関数を書き込みます。
worksheet.write_formula(0, 0, '=$B$3 + B4' )
worksheet.write_formula(1, 0, '=SIN(PI()/4)')
worksheet.write_formula(2, 0, '=SUM(B1:B5)' )
- worksheet.write_formula('A4', '=IF(A3>1,"Yes", "No")' )
+ worksheet.write_formula('A4', '=IF(A3>1,"Yes","No")' )
worksheet.write_formula('A5', '=AVERAGE(1, 2, 3, 4)' )
worksheet.write_formula('A6', '=DATEVALUE("1-Jan-2001")')
-
== ページセットアップメソッド
印刷されたときの書式設定ですね。ヘッダ・フッタやマージンなど。
次のメソッドが用意されています。
@@ -780,6 +779,604 @@
:pattern => 1
}
format1 = workbook.add_format(font) # フォントだけ設定
format2 = workbook.add_format(font, shading) # 両方を設定
+
+===FORMATメソッド
+
+Formatクラスのメソッドの詳細は改めて説明がある。加えて、gem の examples
+ディレクトリの formats.rb を実行して得られる formats.xls には、ほとんど
+すべての書式設定例があるので見ていただきたい。
+
+以下のメソッドがあります。
+
+ set_font
+ set_size
+ set_color
+ set_bold
+ set_italic
+ set_underline
+ set_font_strikeout
+ set_font_script
+ set_font_outline
+ set_font_shadow
+ set_num_format
+ set_locked
+ set_hidden
+ set_align
+ set_rotation
+ set_text_wrap
+ set_text_justlast
+ set_center_across
+ set_indent
+ set_shrink
+ set_pattern
+ set_bg_color
+ set_fg_color
+ set_border
+ set_bottom
+ set_top
+ set_left
+ set_right
+ set_border_color
+ set_bottom_color
+ set_top_color
+ set_left_color
+ set_right_color
+
+これらは、プロパティとして直接指定することもできます。例えば、
+
+ format = workbook.add_format
+ format.set_bold
+
+は、
+
+ format = workbook.add_format(:bold => 1)
+
+と同じことになります。
+
+===色の扱い
+
+エクセルは５６色のカラーパレットを提供しています。WriteExcelでは、８から６３までの
+パレットインデックスを通じてアクセスできます。このインデックスは、フォント、背景色、
+枠線などの色の設定に用いられます。
+
+ format = workbook.add_format(
+ :color => 12, # index for blue
+ :font => 'ＭＳ 明朝',
+ :size => 12,
+ :bold => 1
+ )
+
+よく用いられる色は、色の名前の文字列でも指定できます。文字列の大文字小文字は問いません。
+
+ 'black' => 8
+ 'blue' => 12
+ 'brown' => 16
+ 'cyan' => 15
+ 'gray' => 23
+ 'green' => 17
+ 'lime' => 11
+ 'magenta' => 14
+ 'navy' => 18
+ 'orange' => 53
+ 'pink' => 33
+ 'purple' => 20
+ 'red' => 10
+ 'silver' => 22
+ 'white' => 9
+ 'yellow' => 13
+
+使用例：
+
+ font = workbook.add_format(:color => 'red')
+
+求める色が既定色にない場合は、Workbook#set_custom_colorによりRGB(red green blue)を指定
+してオーバーライドすることができます。
+
+ ferrari = workbook.set_custom_color(40, 216, 12, 12)
+
+ format = workbook.add_format(
+ :bg_color => ferrari,
+ :pattern => 1,
+ :border => 1
+ )
+
+ worksheet.write_blank('A1', format)
+
+以下のリンクが参考になるでしょう。
+
+エクセルのカラーパレットについて詳しく見る。
+http://www.mvps.org/dmcritchie/excel/colors.htm
+
+A decimal RGB chart: http://www.hypersolutions.org/pages/rgbdec.html
+
+A hex RGB chart: : http://www.hypersolutions.org/pages/rgbhex.html
+
+===DATES AND TIME IN EXCEL
+
+エクセルでの日付・時刻について２つの重要なことがあります。
+
+1. エクセルの日付・時刻は正の実数形式である。
+
+2. WriteExcel は、Worksheet#write によって与えられた日付・時刻を表す文字列を
+自動的には日付・時刻データとして変換しない。
+
+この２点について、どのように求められる書式で日付・時刻として表示するのか、
+いくつかのサジェスチョンを以下に示します。
+
+====エクセルの日付・時刻は数値と書式
+
+文字列をWorksheet#writeで書き込んだ場合、それはあくまで文字列です。
+
+ worksheet.write('A1', '02/03/04') # !! Writes a string not a date. !!
+
+エクセルでの日付・時刻にあたるのは実数です。
+"Jan 1 2001 12:30 AM" は、36892.521です。
+
+整数部分はエポックからの日数であり、小数部分は一日のうち経過した時間のパーセンテージ
+です。
+いくつか例を載せます。
+
+ #!/usr/bin/ruby -w
+
+ require 'writeexcel'
+
+ workbook = WriteExcel.new('date_examples.xls')
+ worksheet = workbook.add_worksheet
+
+ worksheet.set_column('A:A', 30) # For extra visibility.
+
+ number = 39506.5
+
+ worksheet.write('A1', number) # 39506.5
+
+ format2 = workbook.add_format(:num_format => 'dd/mm/yy')
+ worksheet.write('A2', number , format2); # 28/02/08
+
+ format3 = workbook.add_format(:num_format => 'mm/dd/yy')
+ worksheet.write('A3', number , format3); # 02/28/08
+
+ format4 = workbook.add_format(:num_format => 'd-m-yyyy')
+ worksheet.write('A4', .number , format4) # 28-2-2008
+
+ format5 = workbook.add_format(:num_format => 'dd/mm/yy hh:mm')
+ worksheet.write('A5', number , format5) # 28/02/08 12:00
+
+ format6 = workbook.add_format(:num_format => 'd mmm yyyy')
+ worksheet.write('A6', number , format6) # 28 Feb 2008
+
+ format7 = workbook.add_format(:num_format => 'mmm d yyyy hh:mm AM/PM')
+ worksheet.write('A7', number , format7) # Feb 28 2008 12:00 PM
+
+====WriteExcel は日付・時刻風の文字列を自動的に日付・時刻には変換しない
+
+WriteExcel は、日付・時刻風の文字列から日付・時刻の実数への変換を自動的には
+行いません。多くの書式があるため、また、解釈ミスを行う可能性があるためです。
+
+例えば、02/03/04 は 2002年3月4日／2004年2月3日／2004年3月2日いずれか判別できません。
+
+ですから、日付を扱うためには本来であれば数値に変換し、書式を指定して渡す必要があります。
+
+しかし、数値に変換するのも大変ですから、ISO8601の形式（yyyy-mm=ddThh:mm:ss.sss)の文字列で
+表し、Worksheet#write_date_timeで書き込む方法が用意されています。
+
+ worksheet.write_date_time('A2', '2001-01-01T12:20', format)
+
+詳しくはWorksheet#write_date_time のドキュメントを参照ください。
+
+ #!/usr/bin/ruby -w
+
+ require 'writeexcel'
+
+ workbook = WriteExcel.new('example.xls')
+ worksheet = workbook.add_worksheet
+
+ # Set the default format for dates.
+ date_format = workbook.add_format(:num_format => 'mmm d yyyy')
+
+ # Increase column width to improve visibility of data.
+ worksheet.set_column('A:C', 20)
+
+ data = [
+ %w(Item Cost Date),
+ %w(Book 10 1/9/2007),
+ %w(Beer 4 12/9/2007),
+ %w(Bed 500 5/10/2007)
+ ]
+
+ # Simulate reading from a data source.
+ row = 0
+
+ data.each do |row_data|
+ col = 0
+ row_data.each do |item|
+
+ # Match dates in the following formats: d/m/yy, d/m/yyyy
+ if item =~ %r[^(\d{1,2})/(\d{1,2})/(\d{4})$]
+ # Change to the date format required by write_date_time().
+ date = sprintf "%4d-%02d-%02dT", $3, $2, $1
+ worksheet.write_date_time(row, col, date, date_format)
+ else
+ # Just plain data
+ worksheet.write(row, col, item)
+ end
+ col += 1
+ end
+ row += 1
+ end
+
+===エクセルにおけるグループとアウトライン
+
+エクセルでは、行や桁をグループ化し、ワンクリックで表示・非表示を行うことができます。
+この昨日はアウトラインと関係があります。
+
+ ------------------------------------------
+ 1 2 3 | | A | B | C | D | ...
+ ------------------------------------------
+ _ | 1 | A | | | | ...
+ | _ | 2 | B | | | | ...
+ | | | 3 | (C) | | | | ...
+ | | | 4 | (D) | | | | ...
+ | - | 5 | E | | | | ...
+ | _ | 6 | F | | | | ...
+ | | | 7 | (G) | | | | ...
+ | | | 8 | (H) | | | | ...
+ | - | 9 | I | | | | ...
+ - | . | ... | ... | ... | ... | ...
+
+レベル２のマイナス記号をクリックすると次のようになります。
+
+ ------------------------------------------
+ 1 2 3 | | A | B | C | D | ...
+ ------------------------------------------
+ _ | 1 | A | | | | ...
+ | | 2 | B | | | | ...
+ | + | 5 | E | | | | ...
+ | | 6 | F | | | | ...
+ | + | 9 | I | | | | ...
+ - | . | ... | ... | ... | ... | ...
+
+さらにレベル１のマイナス記号をクリックすると次のようになります。
+
+ ------------------------------------------
+ 1 2 3 | | A | B | C | D | ...
+ ------------------------------------------
+ | 1 | A | | | | ...
+ + | . | ... | ... | ... | ... | ...
+
+WriteExcel におけるグループ化は、Worksheet#set_row や Worksheet#set_column
+を通じて行うことができます。
+
+ set_row(row, height, format, hidden, level, collapsed)
+ set_column(first_col, last_col, width, format, hidden, level, collapsed)
+
+次の例では、行１と行２、桁ＢからＧまでににアウトラインレベル１を設定しています。
+hidden や format が nil の時は、デフォルトの値が用いられます。
+
+ worksheet.set_row(1, nil, nil, 0, 1)
+ worksheet.set_row(2, nil, nil, 0, 1)
+ worksheet.set_column('B:G', nil, nil, 0, 1)
+
+エクセルではアウトラインレベル７まで用いることができます。ですから、パラメータ level は
+０以上７以下でなければなりません。
+
+行、桁は hidden フラグをセットすることで折りたたむことができます。その場合、
+フラグをセットした行、桁は＋記号が付いて折りたたまれます。
+
+ worksheet.set_row(1, nil, nil, 1, 1)
+ worksheet.set_row(2, nil, nil, 1, 1)
+ worksheet.set_row(3, nil, nil, 0, 0, 1) # Collapsed flag.
+
+ worksheet.set_column('B:G', nil, nil, 1, 1)
+ worksheet.set_column('H:H', nil, nil, 0, 0, 1) # Collapsed flag.
+
+Note: collapsed フラグをセットすることは、OpenOffice.orgやGnumeric との互換性上
+特に重要です。
+
+examplesディレクトリの outline.rb 及び outline_collapsed.rb をご覧ください。
+
+===エクセルのデータ検証（データ-入力規則）
+
+データ検証は、ユーザのセルへの入力データを制限し、ヘルプやワーニングを
+表示するエクセルの機能です。ドロップダウンリストで入力値を制限することもできます。
+
+一定の範囲内の整数に入力値を制限する際に、必要な値についてメッセージを表示し、
+範囲外の時はワーニングを表示するなどの使い方が典型的な使用例でしょう。
+WriteExcel では次のようにします。
+
+ worksheet.data_validation('B3',
+ {
+ :validate => 'integer',
+ :criteria => 'between',
+ :minimum => 1,
+ :maximum => 100,
+ :input_title => '整数値を入力：',
+ :input_message => '1以上100以下',
+ :error_message => 'すいません、もう一度お願いします。'
+ })
+
+データ検証についてさらなる情報は、以下を参照のこと。
+"Description and examples of data validation in Excel":
+ http://support.microsoft.com/kb/211485.
+
+===エクセルの数式と関数
+
+====注意
+
+数式及び関数の実装に際して、いくつか未解決の問題があります。
+
+ 1.数式を書き込むのは、文字列を書き込むのと比べ非常に遅いです。
+ 2.関数内で{1;2;3}といった配列形式の定数は使えません。
+ 3.単項演算子の「-」（マイナス）は、「-1*」と解釈されます。例：-SIN(PI()) => -1*SIN(PI())
+ 4.演算子前後に空白は入れないでください。
+ 5.名前付きレンジは未サポートです。
+ 6.配列数式は未サポートです。
+
+====イントロダクション
+
+数式は、等号で始まる文字列です。
+
+ '=A1+B1'
+ '=AVERAGE(1, 2, 3)'
+
+数式には、数値、文字列、真偽値、セル参照、セル範囲、関数を含むことができます。
+名前付き範囲はまだサポートされていません。
+数式はエクセルで記載するときと同様、セルや関数は大文字にする必要があります。
+
+セルはＡ１形式で表します。桁はＡからＩＶまで（０から２５５まで）。行は１から
+６５５３６までです。
+
+「$」による絶対指定もサポートしています。
+
+ '=A1' # Column and row are relative
+ '=$A1' # Column is absolute and row is relative
+ '=A$1' # Column is relative and row is absolute
+ '=$A$1' # Column and row are absolute
+
+数式では他のシートのセルを参照することもできます。
+
+ '=Sheet2!A1'
+ '=Sheet2!A1:A5'
+ '=Sheet2:Sheet3!A1'
+ '=Sheet2:Sheet3!A1:A5'
+ q{='Test Data'!A1}
+ q{='Test Data1:Test Data2'!A1}
+
+シート参照とセル参照は「!」で区切られます。ワークシート名に空白やコンマ、括弧
+が含まれる場合、シングルクオートで囲う必要があります（上記例の末尾２例参照）。
+他のワークブックに含まれるシートを参照することはできません。
+
+以下にエクセルの数式で使うことができる演算子を示します。
+ほとんど Ruby と同様ですが、異なるものには注記してあります。
+ Arithmetic operators:
+ =====================
+ Operator Meaning Example
+ + Addition 1+2
+ - Subtraction 2-1
+ * Multiplication 2*3
+ / Division 1/4
+ ^ Exponentiation 2^3 # べき乗
+ - Unary minus -(1+2) # -1*(1+2)を解釈される。
+ % Percent (Not modulus) 13% # パーセント。サポートしていない。
+
+ Comparison operators:
+ =====================
+ Operator Meaning Example
+ = Equal to A1 = B1 # ==
+ <> Not equal to A1 <> B1 # !=
+ > Greater than A1 > B1
+ < Less than A1 < B1
+ >= Greater than or equal to A1 >= B1
+ <= Less than or equal to A1 <= B1
+
+ String operator:
+ ================
+ Operator Meaning Example
+ & Concatenation "Hello " & "World!" # 文字列の連結。
+
+ Reference operators:
+ ====================
+ Operator Meaning Example
+ : Range operator A1:A4
+ , Union operator SUM(1, 2+2, B3)
+
+The range and comma operators can have different symbols in non-English
+versions of Excel. These will be supported in a later version of WriteExcel.
+European users of Excel take note:
+
+ worksheet.write('A1', '=SUM(1; 2; 3)') # Wrong!!
+ worksheet.write('A1', '=SUM(1, 2, 3)') # Okay
+
+以下にはExcel5及びWriteExcelでサポートされている関数を示します。
+
+ ABS DB INDIRECT NORMINV SLN
+ ACOS DCOUNT INFO NORMSDIST SLOPE
+ ACOSH DCOUNTA INT NORMSINV SMALL
+ ADDRESS DDB INTERCEPT NOT SQRT
+ AND DEGREES IPMT NOW STANDARDIZE
+ AREAS DEVSQ IRR NPER STDEV
+ ASIN DGET ISBLANK NPV STDEVP
+ ASINH DMAX ISERR ODD STEYX
+ ATAN DMIN ISERROR OFFSET SUBSTITUTE
+ ATAN2 DOLLAR ISLOGICAL OR SUBTOTAL
+ ATANH DPRODUCT ISNA PEARSON SUM
+ AVEDEV DSTDEV ISNONTEXT PERCENTILE SUMIF
+ AVERAGE DSTDEVP ISNUMBER PERCENTRANK SUMPRODUCT
+ BETADIST DSUM ISREF PERMUT SUMSQ
+ BETAINV DVAR ISTEXT PI SUMX2MY2
+ BINOMDIST DVARP KURT PMT SUMX2PY2
+ CALL ERROR.TYPE LARGE POISSON SUMXMY2
+ CEILING EVEN LEFT POWER SYD
+ CELL EXACT LEN PPMT T
+ CHAR EXP LINEST PROB TAN
+ CHIDIST EXPONDIST LN PRODUCT TANH
+ CHIINV FACT LOG PROPER TDIST
+ CHITEST FALSE LOG10 PV TEXT
+ CHOOSE FDIST LOGEST QUARTILE TIME
+ CLEAN FIND LOGINV RADIANS TIMEVALUE
+ CODE FINV LOGNORMDIST RAND TINV
+ COLUMN FISHER LOOKUP RANK TODAY
+ COLUMNS FISHERINV LOWER RATE TRANSPOSE
+ COMBIN FIXED MATCH REGISTER.ID TREND
+ CONCATENATE FLOOR MAX REPLACE TRIM
+ CONFIDENCE FORECAST MDETERM REPT TRIMMEAN
+ CORREL FREQUENCY MEDIAN RIGHT TRUE
+ COS FTEST MID ROMAN TRUNC
+ COSH FV MIN ROUND TTEST
+ COUNT GAMMADIST MINUTE ROUNDDOWN TYPE
+ COUNTA GAMMAINV MINVERSE ROUNDUP UPPER
+ COUNTBLANK GAMMALN MIRR ROW VALUE
+ COUNTIF GEOMEAN MMULT ROWS VAR
+ COVAR GROWTH MOD RSQ VARP
+ CRITBINOM HARMEAN MODE SEARCH VDB
+ DATE HLOOKUP MONTH SECOND VLOOKUP
+ DATEVALUE HOUR N SIGN WEEKDAY
+ DAVERAGE HYPGEOMDIST NA SIN WEIBULL
+ DAY IF NEGBINOMDIST SINH YEAR
+ DAYS360 INDEX NORMDIST SKEW ZTEST
+
+上記数式や関数についての文法はエクセルのヘルプなどを参照ください。
+
+WriteExcel で数式がうまく機能しない場合、以下を確認ください。
+
+ 1.エクセルやGnumeric, OpenOffice.orgでその数式が動くこと。
+ 2.注意の項で示した制限に該当しないこと
+ 3.セル参照や関数名が大文字で記述されていること
+ 4.範囲にはコロンが使われていること A1:A4.
+ 5.引数区切りにはコンマが使われていること SUM(1,2,3).
+ 6.上記で示した関数であること
+
+上記を満たしていて、なおかつ問題がある場合は、
+cxn03651@msj.biglobe.ne.jp にお知らせください。
+
+====数式を使う際のパフォーマンス改善
+
+WriteExcel でたくさんの数式を書き込む場合、とても時間がかかります。
+これは、現在の実装ではそれぞれの数式ごとに解釈されるためです。
+
+しかしながら、以下のように同じような式を書き込んでいるのであれば改善策は
+あります。
+
+ worksheet.write_formula('B1', '=A1 * 3 + 50', format)
+ worksheet.write_formula('B2', '=A2 * 3 + 50', format)
+ ...
+ ...
+ worksheet.write_formula('B99', '=A999 * 3 + 50', format)
+ worksheet.write_formula('B1000', '=A1000 * 3 + 50', format)
+
+この例では、セル参照がA1からA1000まで順に変化しています。
+こういうときは、Wordsheet#store_formulaとWorksheet#repeat_formulaを使って、
+一度解釈したものを再利用することができます。
+
+ formula = worksheet.store_formula('=A1 * 3 + 50')
+
+ (0...1000).each do |row|
+ worksheet.repeat_formula(row, 1, formula, format, 'A1', 'A' + (row +1).to_s)
+ end
+
+とあるマシン上では、これで１０倍早くなりました。
+
+===チャート
+
+====概要（チャート）
+
+WriteExcelでチャートを含むエクセルファイルを作る例です。
+
+ #!/usr/bin/ruby -w
+
+ require 'writeexcel'
+
+ workbook = WriteExcel.new('chart.xls')
+ worksheet = workbook.add_worksheet
+
+ chart = workbook.add_chart(:type => 'Chart::Column')
+
+ # Configure the chart.
+ chart.add_series(
+ :categories => '=Sheet1!$A$2:$A$7',
+ :values => '=Sheet1!$B$2:$B$7'
+ )
+
+ # Add the data to the worksheet the chart refers to.
+ data = [
+ [ 'Category', 2, 3, 4, 5, 6, 7 ],
+ [ 'Value', 1, 4, 5, 2, 1, 5 ]
+ ]
+
+ worksheet.write('A1', data)
+
+ workbook.close
+
+====説明（チャート）
+
+チャートを使う場合、チャートのタイプを指定してWorkbook#add_chartを呼びます。
+
+ chart = workbook.add_chart(:type => 'Chart::Column')
+
+現在サポートされているのは、次の５つ。
+
+ * 'Chart::Column': Creates a column style (histogram) chart. See Column.
+ * 'Chart::Bar': Creates a Bar style (transposed histogram) chart. See Bar.
+ * 'Chart::Line': Creates a Line style chart. See Line.
+ * 'Chart::Area': Creates an Area (filled line) style chart. See Area.
+ * 'Chart::Scatter': Creates an Scatter style chart. See Scatter.
+ * 'Chart::Stock': Creates an Stock style chart. See Stock.
+
+More chart types will be supported in time. See the "TODO" section.
+
+=== チャート名とリンク
+
+Chart#add_series, Chart#set_x_axis, Chart#set_y_axis, Chart#set_title メソッドは
+methods all
+support a name property. In general these names can be either a static
+string or a link to a worksheet cell. If you choose to use the name_formula
+property to specify a link then you should also the name property.
+This isn't strictly required by Excel but some third party applications
+expect it to be present.
+
+ chartl.set_title(
+ :name => 'Year End Results',
+ :name_formula => '=Sheet1!$C$1'
+ )
+
+These links should be used sparingly since they aren't commonly
+used in Excel charts.
+
+=== Chart names and Unicode
+
+The add_series()), set_x_axis(), set_y_axis() and set_title() methods all
+support a name property. These names can be UTF8 strings.
+
+This methodology is explained in the "UNICODE IN EXCEL" section of WriteExcel
+but is semi-deprecated. If you are using Unicode the easiest option is to
+just use UTF8.
+
+=== TODO(Chart)
+
+Charts in WriteExcel are a work in progress. More chart types and
+features will be added in time. Please be patient. Even a small feature
+can take a week or more to implement, test and document.
+
+Features that are on the TODO list and will be added are:
+
+ * Additional chart types. Stock, Pie and Scatter charts are next in line.
+ Send an email if you are interested in other types and they will be
+ added to the queue.
+ * Colours and formatting options. For now you will have to make do
+ with the default Excel colours and formats.
+ * Axis controls, gridlines.
+ * Embedded data in charts for third party application support.
+
+== KNOWN ISSUES(Chart)
+
+ * Currently charts don't contain embedded data from which the charts
+ can be rendered. Excel and most other third party applications ignore
+ this and read the data via the links that have been specified. However,
+ some applications may complain or not render charts correctly. The
+ preview option in Mac OS X is an known example. This will be fixed
+ in a later release.
+ * When there are several charts with titles set in a workbook some of
+ the titles may display at a font size of 10 instead of the default
+ 12 until another chart with the title set is viewed.