getimagesize.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: f8d1e172bd6d11986f0dfeb11756b90c039a39bc Maintainer: HonestQiao Status: ready -->
<!-- CREDITS: mowangjuanzi, Luffy -->
<refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.getimagesize">
 <refnamediv>
  <refname>getimagesize</refname>
  <refpurpose>取得图像大小</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>array</type><type>false</type></type><methodname>getimagesize</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter role="reference">image_info</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>getimagesize</function> 函数将确定任何支持的指定图像文件的大小，并返回尺寸以及文件类型和
   <literal>height/width</literal> 文本字符串，以在标准 <acronym>HTML</acronym> <tag>IMG</tag>
   标签和对应的 <acronym>HTTP</acronym> 内容类型中使用。
  </para>
  <para>
   <function>getimagesize</function> 还可以在 <parameter>image_info</parameter> 参数中返回更多信息。
  </para>
  <caution>
   <para>
    此函数要求 <parameter>filename</parameter> 是有效的图像文件。如果提供的是非图像，可能会错误的识别为图像且函数会成功返回，但数组可能包含无意义的值。
   </para>
   <para>
    不要使用 <function>getimagesize</function> 识别指定的文件是否是有效的图像。请使用专业解决方案，比如
    <link linkend="book.fileinfo">Fileinfo</link> 扩展。
   </para>
  </caution>
  <note>
   <simpara>
    注意 JPC 和 JP2 是具有不同位深度的组件。此外，JP2 文件可能包含有<literal>多个 JPEG 2000
    代码流</literal>，此情况下，<function>getimagesize</function>
    返回此文件顶层中碰到的第一个代码流的值。
   </simpara>
  </note>
  <note>
   <simpara>
    从具有最高比特率的 icon 中检索有关 icon 的信息。
   </simpara>
  </note>
  <note>
   <simpara>
    GIF 图像由一个或多个帧组成，其中每个帧可能只占据图像的一部分。<function>getimagesize</function> 报告的图像大小是整体大小（从逻辑屏幕描述符中读取）。
   </simpara>
  </note>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
       此参数指定希望检索其信息的文件。可以指向本地文件或（配置允许）使用某个<link linkend="wrappers">支持的流</link>的远程文件。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>image_info</parameter></term>
     <listitem>
      <para>
       可选参数允许从图像文件中提取一些扩展信息。目前会将不同的 <acronym>JPG</acronym> APP
       标记作为关联数组返回。一些程序使用这些 APP 标记在图像中嵌入文本信息。
       A very common one is to embed 
       <link xlink:href="&url.iptc;">IPTC</link> information in the APP13 marker.
       You can use the <function>iptcparse</function> function to parse the
       binary APP13 marker into something readable.
      </para>
      <note>
       <para>
        <parameter>image_info</parameter> 仅支持 <acronym>JFIF</acronym> 文件。
       </para>
      </note>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   返回信息最多包含 7 个元素。并非所有图像类型都包含 <literal>channels</literal> 和 <literal>bits</literal> 元素。
  </para>
  <para>
   索引 0 和 1 分别包含图像的宽度和高度。
  </para>
  <note>
   <para>
    一些格式可能没有图像或者包含多个图像。在这种情况下，<function>getimagesize</function>
    可能无法正确确定图像大小。<function>getimagesize</function> 此时会返回的宽高为 0。
   </para>
  </note>
  <note>
   <simpara>
    <function>getimagesize</function> 是独立于任何图像元数据的。
    例如，如果 Exif <literal>Orientation</literal> 标志设置为将图像旋转 90 或 270 度的值，
    索引 0 和 1 被交换，即包含高度和宽度。
   </simpara>
  </note>
  <para>
   索引 2 是表示图像类型的某个 <constant>IMAGETYPE_<replaceable>*</replaceable></constant> 常量。
  </para>
  <para>
   Index 3 is a text string with the correct 
   <literal>height="yyy" width="xxx"</literal> string that can be used
   directly in an <acronym>IMG</acronym> tag.
  </para>
  <para>
   <literal>mime</literal> 是图像对应的 MIME 类型。此信息可用于传递具有正确 HTTP 
   <literal>Content-type</literal> 报头的图像：
   <example>
    <title><function>getimagesize</function> 和 MIME 类型</title>
    <programlisting role="php">
<![CDATA[
<?php
$size = getimagesize($filename);
$fp = fopen($filename, "rb");
if ($size && $fp) {
    header("Content-type: {$size['mime']}");
    fpassthru($fp);
    exit;
} else {
    // error
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <literal>channels</literal> 对 RGB 图片为 3，对 CMYK 图像为 4。
  </para>
  <para>
   <literal>bits</literal> 是每种颜色的位数。
  </para>
  <para>
   对应一些图像类型，<literal>channels</literal> 和 <literal>bits</literal> 值的存在可能会让人困惑。
   As an example, <acronym>GIF</acronym> always uses 3 channels
   per pixel, but the number of bits per pixel cannot be calculated for an
   animated <acronym>GIF</acronym> with a global color table.
  </para>
  <para>
   失败时返回 &false;。
  </para>
 </refsect1>
 
 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   如果无法访问 <parameter>filename</parameter> 图像，<function>getimagesize</function> 将生成 <constant>E_WARNING</constant>
   级别的错误。读取错误时，<function>getimagesize</function> 将生成 <constant>E_NOTICE</constant> 级别的错误。
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>8.2.0</entry>
       <entry>
        现在将正确返回 AVIF 图像的实际尺寸、bits 和 channels；以前，尺寸报告为 <literal>0x0</literal>，并且不会报告 bits 和 channels。
       </entry>
      </row>
      <row>
       <entry>7.1.0</entry>
       <entry>
        新增 WebP 支持。
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>getimagesize</function> 示例</title>
    <programlisting role="php">
<![CDATA[
<?php
list($width, $height, $type, $attr) = getimagesize("img/flag.jpg");
echo "<img src=\"img/flag.jpg\" $attr alt=\"getimagesize() example\" />";
?>
]]>
    </programlisting>
   </example>
   <example>
    <title>getimagesize (URL)</title>
    <programlisting role="php">
<![CDATA[
<?php
$size = getimagesize("http://www.example.com/gifs/logo.gif");

// if the file name has space in it, encode it properly
$size = getimagesize("http://www.example.com/gifs/lo%20go.gif");

?>
]]>
    </programlisting>
   </example>
   <example>
    <title>getimagesize() 返回 IPTC</title>
    <programlisting role="php">
<![CDATA[
<?php
$size = getimagesize("testimg.jpg", $info);
if (isset($info["APP13"])) {
    $iptc = iptcparse($info["APP13"]);
    var_dump($iptc);
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  &note.gd.notrequired;
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><function>image_type_to_mime_type</function></member>
   <member><function>exif_imagetype</function></member>
   <member><function>exif_read_data</function></member>
   <member><function>exif_thumbnail</function></member>
   <member><function>imagesx</function></member>
   <member><function>imagesy</function></member>
  </simplelist>
 </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->